Content
# Agentic TODO-List with MCP Architecture
> A production-grade task management application demonstrating AI orchestration through the Model Context Protocol (MCP)
## 🎯 Overview
This project showcases an intelligent TODO-list application that integrates AI capabilities using the **Model Context Protocol (MCP)**. The architecture features a central orchestrator coordinating two specialized MCP servers, separating execution logic (PHP) from knowledge/context logic (Python).
### Key Features
- **AI-Powered Task Management:** Natural language interface for managing tasks
- **MCP Architecture:** Native implementation of Model Context Protocol in PHP 8.5 and Python 3.14
- **Smart Orchestration:** LangGraph-based agent for intelligent decision-making
- **Complete Traceability:** Transaction logging with correlation IDs for full observability
- **Microservices Design:** Containerized services with shared SQLite database
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Laravel Frontend │
│ (Web UI + REST API) │
└──────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Python AI Orchestrator (LangGraph) │
│ │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Router │───▶│ Observer │───▶│ Executor │ │
│ └─────────┘ └──────────┘ └──────────┘ │
└───────┬─────────────────────────────────┬───────────────────┘
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ MCP Server Python │ │ MCP Server PHP │
│ (Knowledge Layer) │ │ (Action Layer) │
│ │ │ │
│ - tasks_context │ │ - task_crud │
│ - smart_prioritizer │ │ - app_navigator │
└──────────┬───────────┘ └──────────┬───────────┘
│ │
└─────────────┬───────────────┘
▼
┌───────────────┐
│ SQLite DB │
│ (Shared) │
└───────────────┘
```
## 🚀 Quick Start
### Prerequisites
- Docker and Docker Compose
- OpenAI API Key or Anthropic API Key (for AI features)
### Installation
1. **Clone the repository:**
```bash
git clone <repository-url>
cd mcp-demo
```
2. **Configure environment variables:**
```bash
cp .env.example .env
# Edit .env and add your API keys:
# OPENAI_API_KEY=your_key_here
# ANTHROPIC_API_KEY=your_key_here
```
3. **Start the services:**
```bash
./start.sh # Start all services
```
4. **Access the application:**
- Web UI: http://localhost:8000
- AI Dashboard: http://localhost:8000/admin/dashboard
- AI Logs: http://localhost:8000/admin/ai-logs
- AI Orchestrator: http://localhost:8080
- MCP Server: http://localhost:8081
### Management Scripts
```bash
./start.sh # Start all services
./stop.sh # Stop all services
./logs.sh # View logs (all services)
./rebuild.sh # Rebuild and restart
./test.sh # Run Laravel + Python tests inside Docker
./reset-db.sh # Reset database (⚠️ deletes data)
```
`db-init` is a one-shot initialization container. Seeing it as `Exited (0)` after startup is expected.
### Manual Setup (Without Docker)
See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed instructions.
## 📚 Tech Stack
### Laravel Service (PHP 8.5)
- **Framework:** Laravel 13
- **Database:** SQLite (shared)
- **MCP Server:** Native PHP implementation (stdio + HTTP bridge for Docker orchestration)
- **Tools:** `task_crud`, `app_navigator`
### Python Orchestrator (Python 3.14)
- **Framework:** FastAPI 0.135.3
- **AI:** LangGraph, LangChain
- **MCP Server:** Native Python implementation
- **Resources:** `db://tasks_context`
- **Prompts:** `smart_prioritizer`
### Infrastructure
- **Database:** SQLite with WAL mode
- **Communication:** MCP (stdio/HTTP), REST API
- **Containerization:** Docker Compose
- **Logging:** Structured JSON with correlation IDs
## 📖 Documentation
- **[Specification](docs/plan/specs.md)** - Complete project specification
- **[Implementation Plan](docs/plan/implementation-plan.md)** - Detailed implementation roadmap
- **[Deployment Guide](DEPLOYMENT.md)** - Docker deployment and operations
- **[Frontend Documentation](services/laravel-app/FRONTEND.md)** - UI components and features
- **[Observability](services/laravel-app/OBSERVABILITY.md)** - Monitoring and logging
- **[Laravel MCP Server](services/laravel-app/IMPLEMENTATION.md)** - PHP action layer
- **[Python MCP Server](services/python-orchestrator/IMPLEMENTATION_MCP.md)** - Knowledge layer
- **[Orchestrator](services/python-orchestrator/IMPLEMENTATION_ORCHESTRATOR.md)** - LangGraph workflow
## 🎤 Presentation Slides
The MCP, agents, and skills presentation sources live in `docs/presentacion/`.
Use the Dockerized Marp CLI wrapper to export the deck without installing Marp locally:
```bash
./slides.sh docs/presentacion/mcp-agents-skills-slides.md --html
```
You can replace `--html` with `--pdf` or `--pptx` depending on the format you need.
## 🎮 Usage Examples
### Chat Interface
```bash
User: "Create a task to review the documentation"
AI: Task created! I've added "Review the documentation" to your pending tasks.
User: "Show me what I need to do today"
AI: You have 3 pending tasks:
1. Review the documentation
2. Update the README
3. Write unit tests
Based on complexity and time, I recommend starting with updating the README.
User: "Take me to the task list"
AI: *Automatically redirects to /tasks*
```
### REST API
```bash
# Send a natural language command
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"message": "Create a task for database optimization"}'
# Response includes correlation_id for tracing
{
"response": {
"content": "Task created successfully",
"action": "task_created",
"task_id": 42
},
"correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
## 🔍 Observability
### Transaction Monitoring
Access the transaction log at `/admin/ai-logs` to:
- View all AI interactions with timestamps
- Filter by correlation ID to trace a complete request flow
- Inspect request/response JSON payloads
- Analyze performance metrics (tokens, latency)
### Correlation IDs
Every user request generates a unique correlation ID that propagates through:
1. Laravel frontend
2. Python orchestrator
3. MCP PHP server
4. MCP Python server
This enables complete end-to-end tracing of all AI operations.
## 🧪 Testing
```bash
# Run all tests inside Docker
./test.sh
# Run live E2E checks too (/api/chat + CRUD over MCP HTTP)
./test.sh --with-e2e
# Or run services separately inside Docker
docker compose -f docker/docker-compose.yml exec -T service-app ./vendor/bin/phpunit
docker compose -f docker/docker-compose.yml exec -T service-ai pytest tests --cov=. --cov-report=term-missing
```
## 📁 Project Structure
```
mcp-demo/
├── services/
│ ├── laravel-app/ # Laravel 13 + MCP Server PHP
│ ├── python-orchestrator/ # FastAPI + LangGraph + MCP Server Python
│ └── shared/
│ └── database/ # Shared SQLite database
├── docker/
│ ├── laravel.Dockerfile
│ ├── python.Dockerfile
│ └── docker-compose.yml
├── docs/
│ ├── plan/ # Specifications and planning
│ └── api/ # API documentation
├── start.sh # Quick start script
├── stop.sh # Stop all services
└── README.md
```
## 🛠️ Development
### Adding a New MCP Tool (PHP)
1. Create tool class in `services/laravel-app/app/Mcp/Tools/`
2. Register in MCP server tool list
3. Implement `execute()` method
4. Add tests
### Adding a New MCP Resource (Python)
1. Create resource in `services/python-orchestrator/mcp_server/resources/`
2. Register in resource handler
3. Return formatted context for LLM
4. Add tests
### Modifying the Orchestrator Flow
Edit the LangGraph definition in `services/python-orchestrator/orchestrator/graph.py`
## 🤝 Contributing
This is a demonstration project showcasing MCP architecture patterns. Feel free to use it as a reference for your own implementations.
## 🔗 Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
- [Laravel Documentation](https://laravel.com/docs)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
## 🐛 Troubleshooting
### `db-init` appears as exited
```bash
docker compose -f docker/docker-compose.yml ps
```
This is expected after successful database initialization.
### Database locked error
```bash
# Ensure WAL mode is enabled
sqlite3 services/shared/database/app.db "PRAGMA journal_mode=WAL;"
```
### MCP server not responding
```bash
# Check service logs
./logs.sh service-app # or service-ai
```
### `/api/chat` times out on write actions
```bash
./rebuild.sh
```
The Docker setup relies on the Laravel MCP HTTP bridge at `/api/mcp` and on concurrent PHP built-in server workers.
### Permission issues with SQLite
```bash
# Fix permissions on shared database
chmod 666 services/shared/database/app.db
```
## 📧 Support
For questions or issues, please refer to the documentation in the `docs/` directory.
---
**Built with ❤️ to demonstrate AI orchestration with MCP**
