https://github.com/jonmatum/mcp-dual-interface-demo
Demonstrates dual-interface architecture: same business logic powering both traditional web apps and MCP servers for AI tools
https://github.com/jonmatum/mcp-dual-interface-demo
ai-integration aws demo-project docker dual-interface dynamodb fastapi full-stack kiro-cli mcp model-context-protocol react shared-business-logic tailwindcss
Last synced: 5 months ago
JSON representation
Demonstrates dual-interface architecture: same business logic powering both traditional web apps and MCP servers for AI tools
- Host: GitHub
- URL: https://github.com/jonmatum/mcp-dual-interface-demo
- Owner: jonmatum
- License: mit
- Created: 2025-12-14T17:23:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-14T18:08:49.000Z (6 months ago)
- Last Synced: 2025-12-17T03:39:51.918Z (6 months ago)
- Topics: ai-integration, aws, demo-project, docker, dual-interface, dynamodb, fastapi, full-stack, kiro-cli, mcp, model-context-protocol, react, shared-business-logic, tailwindcss
- Language: TypeScript
- Homepage:
- Size: 77.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MCP Dual Interface Demo
A 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.
## What This Demonstrates
This project showcases a **dual-interface architecture** where the same business logic powers both:
- **Traditional Web App**: React frontend + FastAPI REST API
- **AI Integration**: MCP server for Kiro CLI and other AI tools
Both interfaces access the same DynamoDB database directly, demonstrating how to build AI-ready applications without architectural compromises.
## Key Innovation
Instead of building separate systems for humans and AI, this stack shows how to:
- Share business logic between REST APIs and MCP servers
- Maintain loose coupling with direct database access
- Scale each interface independently
- Avoid cascading failures between services
```mermaid
graph TB
subgraph "Human Interface"
A[React Frontend] --> B[FastAPI REST API]
end
subgraph "AI Interface"
C[Kiro CLI] --> D[MCP Server stdio]
end
subgraph "Shared Layer"
E[Shared Business Logic
todo_service.py]
end
subgraph "Data Layer"
F[(DynamoDB)]
end
B --> E
D --> E
E --> F
style E fill:#e1f5fe
style F fill:#f3e5f5
```
**Key Principles**:
- Loose coupling: Services access DynamoDB directly
- Shared code: Common business logic in `shared/` module
- Independent scaling: Each service can scale separately
- No cascading failures: Services don't depend on each other
## Stack
- **Backend API**: FastAPI + Python 3.11
- **MCP Server**: Python MCP SDK (stdio transport)
- **Frontend**: React 19 + TypeScript + Vite + Tailwind CSS
- **Database**: DynamoDB Local
- **Shared Logic**: Python module used by both services
- **Testing**: Vitest
- **Orchestration**: Docker Compose
## Quick Start
```bash
# One command to start everything
make start
# Or step by step:
make build
make up
make init-db
```
## Services
- Frontend: http://localhost:5173
- Backend API: http://localhost:8002
- DynamoDB Admin: http://localhost:8001
- DynamoDB Local: http://localhost:8000
- MCP Server: stdio (connect via Kiro)
## Usage
### Manual Testing (Frontend)
Visit http://localhost:5173 to create, update, and delete todos via the web UI.
### AI Testing (Kiro + MCP)
Add to your Kiro config (`~/.config/kiro/mcp_config.json`):
```json
{
"mcpServers": {
"todo-server": {
"command": "docker",
"args": ["exec", "-i", "mcp-server", "python", "server.py"]
}
}
}
```
Then use Kiro to interact with todos:
- "Create a todo: Buy groceries"
- "List all todos"
- "Mark todo X as completed"
### Development
**Add new features**:
1. Update `shared/todo_service.py` with business logic
2. Add REST endpoint in `backend/main.py`
3. Add MCP tool in `mcp-server/server.py`
4. Both services use the same shared logic
**Run tests**:
```bash
make test
```
## Project Structure
```
mcp-dual-interface-demo/
├── shared/ # Shared business logic
│ ├── db.py # DynamoDB client
│ ├── todo_service.py # Todo operations
│ └── init_db.py # Table initialization
├── backend/ # FastAPI REST API
├── mcp-server/ # MCP server for Kiro
├── frontend/ # React app
├── docker-compose.yml
├── Makefile
└── mcp-config.json # Kiro MCP configuration
```
## AWS Deployment
This architecture maps directly to AWS services:
- **DynamoDB Local** → **DynamoDB**
- **FastAPI** → **Lambda + API Gateway** or **ECS/Fargate**
- **MCP Server** → **Lambda** or **ECS Task**
- **Frontend** → **S3 + CloudFront** or **Amplify**
- **Shared Logic** → **Lambda Layer** or **shared package**
All services maintain direct DynamoDB access with no inter-service dependencies.