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:
   pip install -r requirements.txt
2. Configure OpenAI (Optional):
   export OPENAI_API_KEY="your-openai-api-key-here"
3. Seed the database:
   python -m app.seed
4. Start the server:
   uvicorn app.main:app --reload
5. Get an access token:
   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:
   # 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

Enhanced Agent Usage

Dynamic Discovery Mode (Recommended)

Static Configuration Mode

Enhanced Agent Demo

Experience the full capabilities:

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:

Features: Real-time chat, streaming responses, command system, tab completion

Web Interface:

Features: Modern web UI, MCP database authentication, real-time messaging

Feature Demo:

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

Container Deployment

Infrastructure

The terraform/ directory provides AWS deployment configuration:

• ECR Repository: Container image storage
• Fargate Service: Serverless container deployment
• Load Balancer: High availability and scaling

Documentation

• Enhanced Agent Guide - Comprehensive agent capabilities and usage
• Architecture Overview - System design and patterns
• OpenAPI Docs: Available at /docs when server is running

Project Structure

The MCP discovery file is available at model_context.yaml for static configuration.