MCP Server

# MCP Proof of Concept This repository contains a sophisticated Model Context Protocol (MCP) server implemented with **FastAPI**. The project demonstrates advanced API design patterns including OAuth2 authentication, dynamic API discovery, and comprehensive herd management capabilities that can be deployed to AWS Fargate. ## Features ### 🔐 Authentication & Security - **OAuth2 with JWT**: Bearer token authentication system - **User Management**: Built-in user database with role-based access - **Protected Endpoints**: Secure API operations requiring authentication - **Development Mode**: Backwards compatibility with simple token authentication ### 🔍 Enhanced MCP Agent - **Dynamic API Discovery**: Automatically discovers endpoints from OpenAPI metadata - **Universal Operation Support**: Execute any discovered API operation - **Fallback Compatibility**: Graceful degradation to static YAML configuration - **10x More Operations**: Comprehensive endpoint coverage vs static configuration ### 🤖 OpenAI Integration - **GPT-4o-mini Model**: Fast, cost-effective AI powered by OpenAI's latest mini model - **Intelligent Conversations**: Natural language interface with advanced reasoning - **Smart MCP Operations**: AI understands user intent and executes appropriate MCP operations - **Conversational Context**: Maintains conversation history for better interactions - **Model Flexibility**: Switch between GPT-4o-mini, GPT-4o, and other models - **API Endpoints**: RESTful endpoints for chat and intelligent query capabilities ### 💬 Interactive Interfaces - **Interactive CLI**: Full-featured command-line interface with streaming responses - **Web Interface**: Modern web-based chat interface for browser interaction - **Unified Database**: Both interfaces use the same MCP database and authentication - **Session Management**: User-specific conversation saving and restoration - **Real-time Streaming**: Live response streaming for immediate feedback - **Tab Completion**: Smart completion for commands and tool names ### 📊 Comprehensive API - **CRUD Operations**: Full herd management (Create, Read, Update, Delete) - **Search & Filtering**: Search herds by name with flexible parameters - **Pagination**: Efficient data retrieval with skip/limit controls - **Statistics**: Real-time herd analytics and reporting - **Health Monitoring**: System health checks and database status ### 🚀 Advanced Operations - **MCP Execute**: Protected operation execution endpoint - **Broadcast System**: Message broadcasting to connected clients - **Model Listing**: Available MCP models and capabilities - **Real-time Analytics**: Live system statistics and performance metrics ## Quick Start 1. **Install dependencies:** ```bash pip install -r requirements.txt ``` 2. **Configure OpenAI (Optional):** ```bash export OPENAI_API_KEY="your-openai-api-key-here" ``` 3. **Seed the database:** ```bash python -m app.seed ``` 4. **Start the server:** ```bash uvicorn app.main:app --reload ``` 5. **Get an access token:** ```bash curl -X POST "http://localhost:8000/api/v1/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=johndoe&password=secret" ``` 6. **Try the interactive agents:** ```bash # Interactive CLI (uses MCP database authentication) python interactive_agent.py # Web interface (in separate terminal, same database) python web_interface.py # Visit http://localhost:8080 and login with johndoe/secret # Demo all features python demo_agent_usage.py # Test unified database access python test_unified_database.py ``` The database path can be configured via the `DATABASE_PATH` environment variable. If not set, it defaults to `mcp.db` in the working directory. ## AI Model Configuration The system now uses **GPT-4o-mini** as the default model for optimal performance and cost: ### 🤖 **Current Model**: GPT-4o-mini - **Performance**: ~2x faster than GPT-4 for most tasks - **Cost**: Significantly lower cost per token - **Quality**: High-quality responses for interactive chat and MCP operations - **Availability**: Latest OpenAI model with improved efficiency ### 🔄 **Model Switching** - **CLI**: Use `/model <name>` to switch models - **Available models**: gpt-4o-mini, gpt-4o, gpt-4-turbo, gpt-3.5-turbo - **Session persistent**: Model choice saves across CLI sessions - **Web interface**: Uses gpt-4o-mini by default ### 💡 **Model Recommendations** - **gpt-4o-mini**: Best for interactive chat and general tasks (default) - **gpt-4o**: Use for complex reasoning tasks - **gpt-3.5-turbo**: Fallback for basic interactions ## Unified Database System Both the CLI and web interfaces now use the **same MCP database** for authentication and operations: ### 🔑 **Shared Authentication** - Both interfaces authenticate against the same user database - Same JWT token system for both CLI and web - Consistent user management across interfaces ### 💾 **Database Consistency** - **User accounts**: Shared between CLI and web interface - **MCP operations**: Both use identical API endpoints - **Tool discovery**: Same tool set available in both interfaces - **Conversation history**: Interface-specific but user-isolated ### 🔄 **Cross-Interface Benefits** - Login with `johndoe/secret` or `alice/wonderland` in both interfaces - MCP operations executed through web interface affect same database as CLI - Consistent tool availability and functionality - Unified session management per user ## Authentication ### Available Users - **johndoe** / **secret** - Active user account - **alice** / **wonderland** - Active user account ### OAuth2 Flow ```bash # Get access token curl -X POST "http://localhost:8000/api/v1/token" \ -d "username=johndoe&password=secret" # Use token in requests curl -H "Authorization: Bearer YOUR_TOKEN" \ "http://localhost:8000/api/v1/herd" ``` ## Enhanced Agent Usage ### Dynamic Discovery Mode (Recommended) ```bash # List all dynamically discovered operations python -m agent http://localhost:8000 --list-tools # Execute any operation with parameters python -m agent http://localhost:8000 --execute health_check_api_v1_health_get --token YOUR_TOKEN # Create new herd python -m agent http://localhost:8000 --execute create_herd_api_v1_herd_post \ --params '{"name": "New Farm", "location": "Colorado"}' --token YOUR_TOKEN ``` ### Static Configuration Mode ```bash # Traditional static configuration python -m agent http://localhost:8000 --token YOUR_TOKEN ``` ### Enhanced Agent Demo Experience the full capabilities: ```bash python demo_enhanced_agent.py ``` This demonstrates: - Dynamic vs static discovery comparison - All available operations execution - Error handling and fallback mechanisms - Real-time herd management operations ### Interactive Agent Demos Experience the AI-powered interactive agents: **CLI Interface:** ```bash python interactive_agent.py # Default: GPT-4o-mini model # Use /model gpt-4o to switch models ``` Features: Real-time chat, streaming responses, command system, tab completion **Web Interface:** ```bash python web_interface.py # Visit http://localhost:8080 # Login with johndoe/secret or alice/wonderland # Uses GPT-4o-mini by default ``` Features: Modern web UI, MCP database authentication, real-time messaging **Feature Demo:** ```bash python demo_agent_usage.py ``` This demonstrates: - OpenAI integration and chat capabilities - Intelligent MCP operation execution - Natural language query processing - API endpoint usage examples ## API Operations ### Core Herd Management - `GET /api/v1/herd` - List herds with pagination - `POST /api/v1/herd` - Create new herd - `GET /api/v1/herd/{id}` - Get specific herd - `PUT /api/v1/herd/{id}` - Update herd - `DELETE /api/v1/herd/{id}` - Delete herd ### Advanced Features - `GET /api/v1/herd/search/name` - Search herds by name - `GET /api/v1/herd/stats` - Get herd statistics - `GET /api/v1/health` - System health check ### Protected MCP Operations - `POST /api/v1/mcp/execute` - Execute MCP operations - `POST /api/v1/mcp/broadcast` - Broadcast messages - `GET /api/v1/mcp/models` - List available models ### OpenAI Agent Endpoints - `POST /api/v1/agent/chat` - Direct chat with OpenAI agent - `POST /api/v1/agent/query` - Intelligent MCP queries with natural language - `GET /api/v1/agent/capabilities` - Agent capabilities and configuration - `GET /api/v1/agent/tools` - Available MCP tools - `GET /api/v1/agent/status` - Agent operational status ### Authentication Endpoints - `POST /api/v1/token` - OAuth2 token login - `GET /api/v1/users/me` - Current user info - `GET /api/v1/users/me/profile` - Detailed profile ## Testing ```bash # Run all tests pytest -q # Run specific test files pytest tests/test_agent.py -v pytest tests/test_list_herd.py -v ``` ## Container Deployment ```bash # Build container docker build -t mcp . # Run container docker run -p 8000:80 mcp ``` ## Infrastructure The `terraform/` directory provides AWS deployment configuration: - **ECR Repository**: Container image storage - **Fargate Service**: Serverless container deployment - **Load Balancer**: High availability and scaling ```bash cd terraform terraform init terraform plan terraform apply ``` ## Documentation - **[Enhanced Agent Guide](ENHANCED_AGENT.md)** - Comprehensive agent capabilities and usage - **[Architecture Overview](ARCHITECTURE.md)** - System design and patterns - **OpenAPI Docs**: Available at `/docs` when server is running ## Project Structure ``` ├── app/ # FastAPI application │ ├── api/v1/endpoints/ # API route handlers │ ├── core/ # Configuration and security │ ├── models.py # Database models │ ├── schemas.py # Pydantic schemas │ └── services/ # Business logic ├── agent/ # Enhanced MCP agent ├── tests/ # Test suite ├── terraform/ # AWS infrastructure └── demo_enhanced_agent.py # Full capabilities demo ``` The MCP discovery file is available at `model_context.yaml` for static configuration.