{"id":38721890,"url":"https://github.com/jonmatum/mcp-dual-interface-demo","last_synced_at":"2026-01-17T11:09:59.340Z","repository":{"id":328678730,"uuid":"1116347851","full_name":"jonmatum/mcp-dual-interface-demo","owner":"jonmatum","description":"Demonstrates dual-interface architecture: same business logic powering both traditional web apps and MCP servers for AI tools","archived":false,"fork":false,"pushed_at":"2025-12-14T18:08:49.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-17T03:39:51.918Z","etag":null,"topics":["ai-integration","aws","demo-project","docker","dual-interface","dynamodb","fastapi","full-stack","kiro-cli","mcp","model-context-protocol","react","shared-business-logic","tailwindcss"],"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/jonmatum.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-12-14T17:23:49.000Z","updated_at":"2025-12-14T18:30:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jonmatum/mcp-dual-interface-demo","commit_stats":null,"previous_names":["jonmatum/mcp-dual-interface-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jonmatum/mcp-dual-interface-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fmcp-dual-interface-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fmcp-dual-interface-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fmcp-dual-interface-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fmcp-dual-interface-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonmatum","download_url":"https://codeload.github.com/jonmatum/mcp-dual-interface-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fmcp-dual-interface-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28506613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T10:25:30.148Z","status":"ssl_error","status_checked_at":"2026-01-17T10:25:29.718Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai-integration","aws","demo-project","docker","dual-interface","dynamodb","fastapi","full-stack","kiro-cli","mcp","model-context-protocol","react","shared-business-logic","tailwindcss"],"created_at":"2026-01-17T11:09:58.673Z","updated_at":"2026-01-17T11:09:59.321Z","avatar_url":"https://github.com/jonmatum.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Dual Interface Demo\n\nA complete demonstration of dual-interface architecture that shows how to build MCP servers alongside traditional web applications using shared business logic and AWS Well-Architected principles.\n\n## What This Demonstrates\n\nThis project showcases a **dual-interface architecture** where the same business logic powers both:\n- **Traditional Web App**: React frontend + FastAPI REST API\n- **AI Integration**: MCP server for Kiro CLI and other AI tools\n\nBoth interfaces access the same DynamoDB database directly, demonstrating how to build AI-ready applications without architectural compromises.\n\n## Key Innovation\n\nInstead of building separate systems for humans and AI, this stack shows how to:\n- Share business logic between REST APIs and MCP servers\n- Maintain loose coupling with direct database access\n- Scale each interface independently\n- Avoid cascading failures between services\n\n```mermaid\ngraph TB\n    subgraph \"Human Interface\"\n        A[React Frontend] --\u003e B[FastAPI REST API]\n    end\n    \n    subgraph \"AI Interface\"\n        C[Kiro CLI] --\u003e D[MCP Server stdio]\n    end\n    \n    subgraph \"Shared Layer\"\n        E[Shared Business Logic\u003cbr/\u003etodo_service.py]\n    end\n    \n    subgraph \"Data Layer\"\n        F[(DynamoDB)]\n    end\n    \n    B --\u003e E\n    D --\u003e E\n    E --\u003e F\n    \n    style E fill:#e1f5fe\n    style F fill:#f3e5f5\n```\n\n**Key Principles**:\n- Loose coupling: Services access DynamoDB directly\n- Shared code: Common business logic in `shared/` module\n- Independent scaling: Each service can scale separately\n- No cascading failures: Services don't depend on each other\n\n## Stack\n\n- **Backend API**: FastAPI + Python 3.11\n- **MCP Server**: Python MCP SDK (stdio transport)\n- **Frontend**: React 19 + TypeScript + Vite + Tailwind CSS\n- **Database**: DynamoDB Local\n- **Shared Logic**: Python module used by both services\n- **Testing**: Vitest\n- **Orchestration**: Docker Compose\n\n## Quick Start\n\n```bash\n# One command to start everything\nmake start\n\n# Or step by step:\nmake build\nmake up\nmake init-db\n```\n\n## Services\n\n- Frontend: http://localhost:5173\n- Backend API: http://localhost:8002\n- DynamoDB Admin: http://localhost:8001\n- DynamoDB Local: http://localhost:8000\n- MCP Server: stdio (connect via Kiro)\n\n## Usage\n\n### Manual Testing (Frontend)\nVisit http://localhost:5173 to create, update, and delete todos via the web UI.\n\n### AI Testing (Kiro + MCP)\n\nAdd to your Kiro config (`~/.config/kiro/mcp_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"todo-server\": {\n      \"command\": \"docker\",\n      \"args\": [\"exec\", \"-i\", \"mcp-server\", \"python\", \"server.py\"]\n    }\n  }\n}\n```\n\nThen use Kiro to interact with todos:\n- \"Create a todo: Buy groceries\"\n- \"List all todos\"\n- \"Mark todo X as completed\"\n\n### Development\n\n**Add new features**:\n1. Update `shared/todo_service.py` with business logic\n2. Add REST endpoint in `backend/main.py`\n3. Add MCP tool in `mcp-server/server.py`\n4. Both services use the same shared logic\n\n**Run tests**:\n```bash\nmake test\n```\n\n## Project Structure\n\n```\nmcp-dual-interface-demo/\n├── shared/              # Shared business logic\n│   ├── db.py           # DynamoDB client\n│   ├── todo_service.py # Todo operations\n│   └── init_db.py      # Table initialization\n├── backend/            # FastAPI REST API\n├── mcp-server/         # MCP server for Kiro\n├── frontend/           # React app\n├── docker-compose.yml\n├── Makefile\n└── mcp-config.json     # Kiro MCP configuration\n```\n\n## AWS Deployment\n\nThis architecture maps directly to AWS services:\n\n- **DynamoDB Local** → **DynamoDB**\n- **FastAPI** → **Lambda + API Gateway** or **ECS/Fargate**\n- **MCP Server** → **Lambda** or **ECS Task**\n- **Frontend** → **S3 + CloudFront** or **Amplify**\n- **Shared Logic** → **Lambda Layer** or **shared package**\n\nAll services maintain direct DynamoDB access with no inter-service dependencies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonmatum%2Fmcp-dual-interface-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonmatum%2Fmcp-dual-interface-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonmatum%2Fmcp-dual-interface-demo/lists"}