MCPilot

# MCPilot - MCP Gateway A powerful, FastAPI-based gateway for the Model Context Protocol (MCP), designed to unify and scale your AI toolchain. ## ✅ Current Status MCPilot is now **fully functional** with the following working features: ### ✅ Working Features - **FastAPI Gateway Server** - Running on http://localhost:8000/docs - **Admin Dashboard** - Beautiful web UI at http://localhost:8000 - **REST API Endpoints** - Full CRUD operations via /api/v1/* - **API Wrapper System** - Convert REST APIs to MCP tools (tested with JSONPlaceholder) - **Configuration Management** - Environment-based settings - **Transport Framework** - Ready for HTTP, WebSocket, SSE, stdio - **Modular Architecture** - Clean separation of concerns - **Interactive Documentation** - OpenAPI/Swagger UI at /docs ### 🔄 In Progress - **MCP Server Federation** - Basic framework ready, needs MCP client integration fixes - **WebSocket Real-time Communication** - Framework ready - **Admin UI Management** - Backend ready, frontend interactions needed ### 🧪 Tested Examples The API wrapper successfully converts REST APIs to MCP tools: ```python # Example: JSONPlaceholder API → MCP Tool result = await gateway.call_tool( "api:jsonplaceholder:get_user", {"user_id": "1"} ) # Returns: Full user data from REST API ``` --- 1. **Federation of multiple MCP servers** into one unified endpoint 2. **REST API and function wrapping** as virtual MCP-compliant tools 3. **Multiple transport support**: HTTP/JSON-RPC, WebSocket, SSE, and stdio 4. **Centralized tools, prompts, and resources** with full JSON-Schema validation 5. **Admin UI** with built-in auth, observability, and transport layers ## 📁 Project Structure ``` src/mcpilot/ ├── main.py # FastAPI application entry point ├── config.py # Configuration management ├── gateway.py # Core MCP federation logic ├── api.py # REST API endpoints ├── admin.py # Admin management endpoints ├── transports.py # Transport layer implementations ├── api_wrapper.py # REST API to MCP tool wrapper ├── middleware.py # Request/response middleware └── server.py # Original MCP server implementation ``` ## 🛠️ Installation ### Prerequisites - Python 3.10 or higher - uv package manager (recommended) or pip ### Install Dependencies ```bash # Using uv (recommended) uv sync # Or using pip pip install -e . ``` ## 🚀 Quick Start ### 1. Start the Gateway Server ```bash # Run the FastAPI server uv run python -m mcpilot.main # Or using uvicorn directly uvicorn mcpilot.main:app --reload --host 0.0.0.0 --port 8000 ``` ### 2. Access the Admin UI Open your browser to `http://localhost:8000` to access the admin dashboard. ### 3. API Documentation - OpenAPI/Swagger UI: `http://localhost:8000/docs` - ReDoc: `http://localhost:8000/redoc` ## 🔧 Configuration MCPilot can be configured via environment variables or a `.env` file: ```env # Server Configuration MCPILOT_HOST=0.0.0.0 MCPILOT_PORT=8000 MCPILOT_DEBUG=false # CORS Settings MCPILOT_CORS_ORIGINS=["*"] # Logging MCPILOT_LOG_LEVEL=INFO ``` ### Adding MCP Servers Configure MCP servers via the admin API or by setting up the configuration: ```python from mcpilot.config import MCPServerConfig server_config = MCPServerConfig( name="my-server", type="stdio", command="python", args=["-m", "my_mcp_server"], enabled=True ) ``` ### Adding API Wrappers Convert REST APIs to MCP tools: ```python from mcpilot.config import APIWrapperConfig api_config = APIWrapperConfig( name="my-api", base_url="https://api.example.com", auth_type="bearer", auth_config={"token": "your-token"}, endpoints=[ { "name": "get_user", "method": "GET", "path": "/users/{user_id}", "description": "Get user information", "path_params": [ {"name": "user_id", "type": "string", "required": True} ] } ] ) ``` ## 📖 API Endpoints ### Core MCP Operations - `GET /api/v1/tools` - List all available tools - `POST /api/v1/tools/call` - Call a tool - `GET /api/v1/prompts` - List all available prompts - `POST /api/v1/prompts/get` - Get a prompt - `GET /api/v1/resources` - List all available resources - `POST /api/v1/resources/read` - Read a resource ### Admin Operations - `GET /admin/servers` - List MCP servers - `POST /admin/servers` - Add new MCP server - `PUT /admin/servers/{name}` - Update MCP server - `DELETE /admin/servers/{name}` - Remove MCP server - `GET /admin/api-wrappers` - List API wrappers - `POST /admin/api-wrappers` - Add new API wrapper ### Health & Monitoring - `GET /health` - Health check endpoint - `GET /api/v1/status` - Gateway and server status - `GET /admin/metrics` - System metrics ## 🔌 WebSocket Support Connect to the WebSocket endpoint for real-time MCP communication: ```javascript const ws = new WebSocket('ws://localhost:8000/api/v1/ws'); // Send MCP JSON-RPC message ws.send(JSON.stringify({ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} })); ``` ## 🧪 Development ### Running in Development Mode ```bash # Install development dependencies uv sync --dev # Run with auto-reload uvicorn mcpilot.main:app --reload --host 0.0.0.0 --port 8000 ``` ### Testing ```bash # Run tests (when implemented) uv run pytest # Type checking uv run mypy src/mcpilot ``` ## 📄 License This project is licensed under the MIT License. ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. --- ## Original MCP Server Components MCPilot also includes the original MCP server functionality for development and testing: ### Resources The server implements a simple note storage system with: - Custom note:// URI scheme for accessing individual notes - Each note resource has a name, description and text/plain mimetype ### Prompts The server provides a single prompt: - summarize-notes: Creates summaries of all stored notes - Optional "style" argument to control detail level (brief/detailed) - Generates prompt combining all current notes with style preference ### Tools The server implements one tool: - add-note: Adds a new note to the server - Takes "name" and "content" as required string arguments - Updates server state and notifies clients of resource changes ## Configuration [TODO: Add configuration details specific to your implementation] ## Quickstart ### Install #### Claude Desktop On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json` On Windows: `%APPDATA%/Claude/claude_desktop_config.json` <details> <summary>Development/Unpublished Servers Configuration</summary> ``` "mcpServers": { "MCPilot": { "command": "uv", "args": [ "--directory", "C:\Users\ary7s\OneDrive\Desktop\MCPilot", "run", "MCPilot" ] } } ``` </details> <details> <summary>Published Servers Configuration</summary> ``` "mcpServers": { "MCPilot": { "command": "uvx", "args": [ "MCPilot" ] } } ``` </details> ## Development ### Building and Publishing To prepare the package for distribution: 1. Sync dependencies and update lockfile: ```bash uv sync ``` 2. Build package distributions: ```bash uv build ``` This will create source and wheel distributions in the `dist/` directory. 3. Publish to PyPI: ```bash uv publish ``` Note: You'll need to set PyPI credentials via environment variables or command flags: - Token: `--token` or `UV_PUBLISH_TOKEN` - Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD` ### Debugging Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command: ```bash npx @modelcontextprotocol/inspector uv --directory C:\Users\ary7s\OneDrive\Desktop\MCPilot run mcpilot ``` Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.