{"id":42854963,"url":"https://github.com/dheavy/mcp-demo","last_synced_at":"2026-01-30T12:18:16.607Z","repository":{"id":314920755,"uuid":"1057315149","full_name":"dheavy/mcp-demo","owner":"dheavy","description":"A comprehensive demonstration of the Model Context Protocol (MCP) implemented in Next.js with TypeScript, featuring both HTTP and real-time WebSocket communication, authentication, and a modern web interface.","archived":false,"fork":false,"pushed_at":"2025-09-15T15:41:59.000Z","size":131,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-15T17:41:06.335Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dheavy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T15:02:58.000Z","updated_at":"2025-09-15T15:42:02.000Z","dependencies_parsed_at":"2025-09-15T17:41:07.815Z","dependency_job_id":"b1075572-1111-4a53-b08a-5d5e08bd8cb7","html_url":"https://github.com/dheavy/mcp-demo","commit_stats":null,"previous_names":["dheavy/mcp-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dheavy/mcp-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dheavy%2Fmcp-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dheavy%2Fmcp-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dheavy%2Fmcp-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dheavy%2Fmcp-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dheavy","download_url":"https://codeload.github.com/dheavy/mcp-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dheavy%2Fmcp-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28912671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T12:13:43.263Z","status":"ssl_error","status_checked_at":"2026-01-30T12:13:22.389Z","response_time":66,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-30T12:18:15.842Z","updated_at":"2026-01-30T12:18:16.602Z","avatar_url":"https://github.com/dheavy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Assistant Hub - MCP Demo\n\nA comprehensive demonstration of the **Model Context Protocol (MCP)** implemented in Next.js with TypeScript, featuring both HTTP and real-time WebSocket communication, authentication, and a modern web interface.\n\n## Features\n\n### Core MCP implementation\n\n- **9 MCP tools**: Echo, time, weather, filesystem operations, web search, database queries\n- **7 MCP resources**: Documentation, API specs, configuration files\n- **Full MCP protocol support**: Tools, resources, and proper error handling\n- **TypeScript integration**: Complete type safety throughout\n\n### Dual communication modes\n\n- **HTTP MCP client**: Traditional request/response pattern\n- **Real-time WebSocket client**: Live communication with instant updates\n- **Tab-based interface**: Easy switching between communication modes\n\n### Authentication \u0026 security\n\n- **JWT-based authentication**: Secure user sessions\n- **Role-based access control**: Admin and user roles\n- **HTTP-only cookies**: Secure token storage\n- **Protected routes**: Authentication middleware\n\n### Real-time features\n\n- **Live tool execution**: Real-time status tracking\n- **Instant resource access**: Immediate resource reading\n- **Connection monitoring**: WebSocket connection status\n- **Automatic reconnection**: Resilient connection handling\n- **Execution history**: Timestamped operation logs\n\n### Database \u0026 storage\n\n- **SQLite integration**: Local database with sample data\n- **Safe file operations**: Restricted filesystem access\n- **Mock external APIs**: Weather and web search services\n\n## 🛠️ Tech stack\n\n- **Framework**: Next.js 15.5.3 with App Router\n- **Language**: TypeScript\n- **Styling**: Tailwind CSS\n- **Database**: SQLite with better-sqlite3\n- **Authentication**: JWT with bcryptjs\n- **WebSocket**: ws library\n- **MCP SDK**: @modelcontextprotocol/sdk\n\n## Installation\n\n1. **Clone the repository**:\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd mcp-demo\n   ```\n\n2. **Install dependencies**:\n\n   ```bash\n   npm install\n   ```\n\n3. **Start the development server**:\n\n   ```bash\n   npm run dev\n   ```\n\n4. **Open your browser**:\n   Navigate to [http://localhost:3000](http://localhost:3000)\n\n## 🎯 Usage\n\n### Getting started\n\n1. **Register/Login**: Create an account or use existing credentials\n2. **Choose interface**: Switch between HTTP and WebSocket clients\n3. **Execute tools**: Try different MCP tools with real-time feedback\n4. **Read resources**: Access documentation and configuration files\n\n### Available tools\n\n- **echo**: Echo back messages\n- **get_time**: Get current timestamp\n- **get_weather**: Mock weather information\n- **list_files**: Browse project files safely\n- **read_file**: Read file contents with size limits\n- **web_search**: Mock web search results\n- **db_query**: Execute SQL SELECT queries\n- **db_schema**: View database schema\n- **db_samples**: Get sample database queries\n\n### Available resources\n\n- **MCP overview**: Introduction to Model Context Protocol\n- **Tool development guide**: How to create MCP tools\n- **Best practices**: Security and performance guidelines\n- **API documentation**: Weather and database endpoints\n- **Configuration**: Server settings and tool registry\n\n## 🔧 Development\n\n### Project structure\n\n```\nsrc/\n├── app/                    # Next.js App Router\n│   ├── api/               # API routes\n│   │   ├── auth/          # Authentication endpoints\n│   │   ├── mcp/           # MCP HTTP endpoints\n│   │   └── ws/            # WebSocket stats\n│   ├── layout.tsx         # Root layout with auth provider\n│   └── page.tsx           # Main application page\n├── components/            # React components\n│   ├── AuthForm.tsx       # Login/register forms\n│   └── RealtimeMCPClient.tsx # WebSocket client\n├── contexts/              # React contexts\n│   └── AuthContext.tsx    # Authentication state\n├── hooks/                 # Custom React hooks\n│   └── useWebSocket.ts    # WebSocket connection hook\n├── lib/                   # Utility libraries\n│   ├── auth.ts            # Authentication utilities\n│   ├── database.ts        # Database setup\n│   ├── middleware.ts      # Route protection\n│   └── websocket-server.ts # WebSocket server\n└── mcp-server/            # MCP implementation\n    ├── tools/             # MCP tools\n    ├── resources/         # MCP resources\n    ├── server.ts          # MCP server\n    └── types.ts           # TypeScript definitions\n```\n\n### Key files\n\n- **`server.ts`**: Custom Next.js server with WebSocket support\n- **`src/lib/websocket-server.ts`**: WebSocket server implementation\n- **`src/hooks/useWebSocket.ts`**: React WebSocket hook\n- **`src/mcp-server/`**: Complete MCP server implementation\n\n### Adding new tools\n\n1. Create a new tool file in `src/mcp-server/tools/`\n2. Implement the tool with proper input validation\n3. Register the tool in the tools index\n4. The tool will automatically appear in both HTTP and WebSocket clients\n\n### Adding new resources\n\n1. Add resource definition in `src/mcp-server/resources/index.ts`\n2. Implement content provider in `src/mcp-server/resources/content.ts`\n3. Resources will be available in both communication modes\n\n## Security features\n\n- **Input validation**: All tool inputs are validated\n- **Path security**: Filesystem operations are restricted to project directory\n- **SQL injection protection**: Database queries are limited to SELECT statements\n- **Authentication required**: All MCP operations require valid authentication\n- **Role-based access**: Different permissions for admin and user roles\n\n## 🌐 API endpoints\n\n### Authentication\n\n- `POST /api/auth/register` - User registration\n- `POST /api/auth/login` - User login\n- `POST /api/auth/logout` - User logout\n- `GET /api/auth/me` - Get current user\n\n### MCP HTTP\n\n- `GET /api/mcp` - Server status\n- `POST /api/mcp` - MCP method calls (tools/list, resources/list, etc.)\n\n### WebSocket\n\n- `ws://localhost:3000/ws/mcp` - WebSocket MCP connection\n- `GET /api/ws/stats` - WebSocket connection statistics\n\n## Deployment\n\n### Local development\n\n```bash\n# Standard Next.js development (Vercel-compatible)\nnpm run dev\n\n# Full development with WebSocket support\nnpm run dev:full\n```\n\n### Production build\n\n```bash\nnpm run build\nnpm start\n```\n\n### Vercel deployment\n\n1. **Connect to Vercel**:\n\n   ```bash\n   npx vercel\n   ```\n\n2. **Set environment variables** in Vercel dashboard:\n\n   - `JWT_SECRET`: Secret key for JWT tokens\n   - `NODE_ENV`: Set to `production`\n\n3. **Deploy**:\n   ```bash\n   npx vercel --prod\n   ```\n\n**⚠️ Important**: WebSocket functionality is not available on Vercel. The app automatically detects Vercel and disables WebSocket features. See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed deployment information.\n\n### Environment variables\n\n- `JWT_SECRET`: Secret key for JWT tokens (default: development key)\n- `PORT`: Server port (default: 3000)\n- `NODE_ENV`: Environment mode\n\n## 📚 Learning resources\n\nThis demo covers:\n\n- **MCP protocol**: Complete implementation of Model Context Protocol\n- **Tool development**: Creating and registering MCP tools\n- **Resource management**: Handling MCP resources and content\n- **Authentication**: JWT-based auth with role-based access\n- **WebSocket integration**: Real-time communication patterns\n- **Database operations**: SQLite integration with MCP\n- **Security best practices**: Input validation and access control\n- **Modern React patterns**: Hooks, contexts, and TypeScript\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification\n- [Next.js](https://nextjs.org/) for the excellent React framework\n- [Tailwind CSS](https://tailwindcss.com/) for the utility-first CSS framework\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdheavy%2Fmcp-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdheavy%2Fmcp-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdheavy%2Fmcp-demo/lists"}