Updation MCP

# Updation MCP Local Server **Production-grade Model Context Protocol (MCP) server with LLM-agnostic architecture** ## 🌟 Key Features - ✅ **LLM-Agnostic**: Seamlessly switch between OpenAI, Claude, Gemini, or Azure OpenAI - ✅ **Production-Ready**: Structured logging, metrics, error handling, and observability - ✅ **Scalable**: Redis-backed state management for horizontal scaling - ✅ **Secure**: RBAC, rate limiting, input validation, and secret management - ✅ **Modular**: Auto-discovery tool architecture for easy extensibility - ✅ **Type-Safe**: Full Pydantic validation throughout - ✅ **Resilient**: Circuit breakers, retries, and graceful degradation ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ FastAPI Web Chat API │ │ (Port 8002) │ └────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LLM Orchestrator │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ LLM Provider Abstraction Layer │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ OpenAI │ │ Claude │ │ Gemini │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ └────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ MCP Server (Port 8050) │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Auto-Discovery Tool Registry │ │ │ │ ├── User Tools (subscriptions, bookings, etc.) │ │ │ │ ├── Organization Tools (locations, resources) │ │ │ │ └── Payment Tools │ │ │ └──────────────────────────────────────────────────────┘ │ └────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ External Services │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Updation API │ │ Redis │ │ Prometheus │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 🚀 Quick Start ### 1. Prerequisites - **Python 3.11+** - **Redis** (required for conversation memory - see setup below) - **UV package manager** (recommended) or pip ### 2. Installation ```bash # Clone or navigate to project cd /Users/saimanvithmacbookair/Desktop/Updation_MCP_Local # Create virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -e . # Or with UV (faster) uv pip install -e . ``` ### 3. Install Redis (Mac M2) **Redis is required for conversation memory to work!** ```bash # Install Redis via Homebrew brew install redis # Start Redis (background service) brew services start redis # Verify it's running redis-cli ping # Should return: PONG ``` **See `REDIS_SETUP.md` for detailed instructions and troubleshooting.** ### 4. Configuration ```bash # Copy environment template cp .env.example .env # Edit .env with your actual values nano .env # or use your favorite editor ``` **Required settings:** ```bash # LLM Provider LLM_PROVIDER=openai OPENAI_API_KEY=your-key-here # Laravel API UPDATION_API_BASE_URL=http://127.0.0.1:8000/api # Redis (should already be correct) REDIS_ENABLED=true REDIS_URL=redis://localhost:6379/0 # Enable auto-reload for development (optional) WEB_CHAT_RELOAD=true # Auto-restart on code changes ``` ### 5. Run the Services **Terminal 1: MCP Server** ```bash source .venv/bin/activate python -m src.mcp_server.server ``` **Terminal 2: Web Chat API (with auto-reload)** ```bash source .venv/bin/activate python -m src.web_chat.main ``` **Note:** With `WEB_CHAT_RELOAD=true`, Terminal 2 will auto-restart when you edit code! # Terminal 3 (optional): Start metrics server python -m src.observability.metrics_server ``` ### 6. Test the Setup **Quick health check:** ```bash curl http://localhost:8002/health ``` **Test chat with Bearer token:** ```bash # Replace with your actual Laravel token TOKEN="11836|UAc9YiEKc9zO9MvNHKQqY9WwdkxW7qQyw3mqyNK5" curl -X POST http://localhost:8002/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"message": "What can I do?"}' ``` **Test conversation memory:** ```bash # First message curl -X POST http://localhost:8002/chat \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"message": "My name is John"}' # Second message (should remember) curl -X POST http://localhost:8002/chat \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"message": "What is my name?"}' ``` **Expected:** AI should respond "Your name is John" ✅ **Check cache stats:** ```bash # User cache (Bearer tokens) curl http://localhost:8002/cache/stats # Redis conversation keys redis-cli keys "conversation:*" ``` **See `BEARER_TOKEN_AUTH.md` for complete API documentation.** ## 📁 Project Structure ``` Updation_MCP_Local/ ├── src/ │ ├── config/ # Configuration management │ │ ├── __init__.py │ │ └── settings.py # Pydantic settings with validation │ │ │ ├── core/ # Core shared utilities │ │ ├── __init__.py │ │ ├── envelope.py # Standard response envelope │ │ ├── exceptions.py # Custom exceptions │ │ └── security.py # RBAC and auth helpers │ │ │ ├── llm/ # LLM abstraction layer │ │ ├── __init__.py │ │ ├── base.py # Abstract base provider │ │ ├── openai.py # OpenAI implementation │ │ ├── anthropic.py # Claude implementation │ │ ├── google.py # Gemini implementation │ │ └── factory.py # Provider factory │ │ │ ├── mcp_server/ # MCP server implementation │ │ ├── __init__.py │ │ ├── server.py # Main MCP server │ │ └── tools/ # Tool modules │ │ ├── __init__.py # Auto-discovery │ │ ├── users/ # User-related tools │ │ ├── organizations/ # Org-related tools │ │ └── payments/ # Payment tools │ │ │ ├── orchestrator/ # LLM orchestration │ │ ├── __init__.py │ │ ├── client.py # MCP client wrapper │ │ ├── processor.py # Query processing logic │ │ └── policy.py # RBAC policies │ │ │ ├── web_chat/ # FastAPI web interface │ │ ├── __init__.py │ │ ├── main.py # FastAPI app │ │ ├── routes/ # API routes │ │ ├── middleware/ # Custom middleware │ │ └── dependencies.py # FastAPI dependencies │ │ │ ├── observability/ # Logging, metrics, tracing │ │ ├── __init__.py │ │ ├── logging.py # Structured logging setup │ │ ├── metrics.py # Prometheus metrics │ │ └── tracing.py # Distributed tracing │ │ │ └── storage/ # State management │ ├── __init__.py │ ├── redis_client.py # Redis wrapper │ └── memory.py # In-memory fallback │ ├── tests/ # Test suite │ ├── unit/ │ ├── integration/ │ └── e2e/ │ ├── scripts/ # Utility scripts │ ├── setup_redis.sh │ └── health_check.sh │ ├── .env.example # Environment template ├── .gitignore ├── pyproject.toml # Dependencies ├── README.md └── docker-compose.yml # Local development stack ``` ## 🔧 Configuration All configuration is managed through environment variables (see `.env.example`). ### Switching LLM Providers Simply change the `LLM_PROVIDER` environment variable: ```bash # Use OpenAI LLM_PROVIDER=openai OPENAI_API_KEY=sk-... # Use Claude LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-... # Use Gemini LLM_PROVIDER=google GOOGLE_API_KEY=... ``` No code changes required! The system automatically routes to the correct provider. ## 🛠️ Development ### Running Tests ```bash # Install dev dependencies pip install -e ".[dev]" # Run all tests pytest # Run with coverage pytest --cov=src --cov-report=html # Run specific test file pytest tests/unit/test_llm_providers.py ``` ### Code Quality ```bash # Format code ruff format . # Lint ruff check . # Type checking mypy src/ ``` ## 📊 Monitoring ### Metrics Prometheus metrics available at `http://localhost:9090/metrics`: - `mcp_requests_total` - Total requests by tool and status - `mcp_request_duration_seconds` - Request latency histogram - `mcp_active_connections` - Current active connections - `llm_api_calls_total` - LLM API calls by provider - `llm_tokens_used_total` - Token usage tracking ### Logs Structured JSON logs with trace IDs for correlation: ```json { "timestamp": "2024-01-15T10:30:00Z", "level": "info", "event": "tool_executed", "tool_name": "get_user_subscriptions", "user_id": 123, "duration_ms": 245, "trace_id": "abc-123-def" } ``` ## 🔒 Security - **RBAC**: Role-based access control for all tools - **Rate Limiting**: Per-user and global rate limits - **Input Validation**: Pydantic schemas for all inputs - **Secret Management**: Never log or expose API keys - **CORS**: Configurable allowed origins - **HTTPS**: Enforce HTTPS in production ## 🚢 Deployment ### Docker ```bash docker build -t updation-mcp:latest . docker run -p 8050:8050 -p 8002:8002 --env-file .env updation-mcp:latest ``` ### Docker Compose ```bash docker-compose up -d ``` ## 📝 Adding New Tools 1. Create tool module in `src/mcp_server/tools/your_domain/` 2. Implement `tool.py` with `register(mcp)` function 3. Add schemas in `schemas.py` 4. Add business logic in `service.py` 5. Auto-discovery handles the rest! Example: ```python # src/mcp_server/tools/your_domain/tool.py from mcp.server.fastmcp import FastMCP def register(mcp: FastMCP) -> None: @mcp.tool() async def your_tool(param: str): \"\"\"Tool description for LLM.\"\"\" return {"result": "data"} ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes with tests 4. Run quality checks: `ruff check . && pytest` 5. Submit a pull request ## 📄 License [Your License Here] ## 🆘 Support For issues or questions: - GitHub Issues: [Your Repo] - Email: [Your Email] - Docs: [Your Docs URL]