MCP-Orchestrator by abialemuel - MCP Server

MCP Proxy Server

A FastMCP-based proxy server that provides access to MCP services through the Model Context Protocol. Built with FastMCP for native MCP support.

🚀 Features

Native MCP Protocol: Full MCP support with multiple transports (SSE, STDIO, HTTP)
Multi-Server Support: Connect to multiple MCP servers simultaneously
Multiple Transport Options: Choose the best transport for your use case
Enhanced Logging: Context-aware logging and debugging
Type Safety: Built-in validation and error handling
Clean Architecture: Pure FastMCP implementation without unnecessary API layers

📦 Installation

# Clone and install
git clone <repository-url>
cd tlkm-mcp
pip install .

# For development
pip install -e ".[dev]"

⚙️ Configuration

Create a .env file:

# MCP Servers (JSON format)
MCP_SERVERS='{"server-name": "https://your-mcp-server.com"}'

# Authentication tokens (JSON format)  
MCP_SERVER_TOKENS='{"server-name": "your-api-key"}'

# Server settings
HOST=0.0.0.0
PORT=8000

🏃‍♂️ Running

Choose Transport

# Server-Sent Events (default, for web clients like GitHub Copilot)
python run_server.py --transport sse

# Standard I/O (for command-line tools)
python run_server.py --transport stdio

# HTTP streaming (for custom implementations)  
python run_server.py --transport http

🔌 GitHub Copilot Integration

Add to your .vscode/mcp.json:

{
    "servers": {
        "mcp-proxy": {
            "url": "http://localhost:8000/sse"
        }
    }
}

Then start the server:

python run_server.py --transport sse

🔧 Available Tools

Core MCP Operations

list_all_tools - List all available tools from connected servers
call_mcp_tool - Call any tool on connected MCP servers (main interface)
get_server_status - Check status of all connected servers
reinitialize_servers - Restart all server connections
list_all_resources - List available resources from all servers
read_resource - Read specific resources by server and URI
list_all_prompts - List available prompts from all servers
get_prompt - Execute prompts with arguments

Server Tools (accessed via call_mcp_tool)

When you call call_mcp_tool, tools are automatically prefixed with server names:

server-name_tool1 - Tools are prefixed with server names
server-name_tool2 - Use the call_mcp_tool interface to access them
server-name_search - Each server provides its own set of tools

💻 Usage

FastMCP Client Example

from fastmcp import Client
import asyncio

async def use_mcp_services():
    async with Client("http://localhost:8000") as client:
        # First, list all available tools
        tools_result = await client.call_tool("list_all_tools", {})
        print("Available tools:", tools_result)
        
        # Call a specific service (tools are prefixed with server name)
        result = await client.call_tool("call_mcp_tool", {
            "name": "server-name_tool-name",
            "arguments": {"query": "Your query here"}
        })
        print("Response:", result)

asyncio.run(use_mcp_services())

GitHub Copilot Usage

Once configured in .vscode/mcp.json, you can directly ask GitHub Copilot:

"What tools are available?"
"Call the search function with my query"

The tools will be automatically called with your natural language queries.

Command Line (STDIO)

# Start server in STDIO mode
python run_server.py --transport stdio

# Connect with MCP client tools or other MCP-compatible applications

📚 Resources & Prompts

Resources

config://servers - View configured MCP servers
config://status - Current server status

Prompts

Available prompts depend on connected servers
Use list_all_prompts to see what's available

🏗️ Architecture

┌─────────────────┐
│   MCP Client    │
│ (GitHub Copilot)│
└─────────┬───────┘
          │ MCP Protocol (SSE/STDIO/HTTP)
          │
┌─────────▼─────────┐
│  FastMCP Server   │
│  (Proxy Server)   │
└─────────┬─────────┘
          │
┌─────────▼─────────┐
│  Proxy Manager    │
└─────────┬─────────┘
          │
┌─────────▼─────────┐
│   External MCP    │
│     Servers       │
└───────────────────┘

🛠️ Development

Quick Start

# Setup development environment
make dev-setup

# Start for GitHub Copilot
make copilot

# Start for MCP Inspector
make inspector

# Run tests
make test

# Code quality
make quality

Available Make Commands

make help           # Show all available commands
make run            # Run with SSE transport (default)
make run-sse        # Run with SSE transport
make run-http       # Run with HTTP transport  
make run-stdio      # Run with STDIO transport
make test           # Run tests
make format         # Format code
make lint           # Lint code
make docker         # Build and run Docker

🧪 Testing

# Test FastMCP functionality
python test_fastmcp.py

# Test server endpoints (requires running server)
python test_mcp_server.py

# Use MCP Inspector for interactive testing
python run_server.py --transport http
# Then open MCP Inspector and connect to http://localhost:8000/mcp

🐳 Docker

# Build and run with Docker
make docker

# Or manually:
docker build -t mcp-proxy-server .
docker run -p 8000:8000 --env-file .env mcp-proxy-server

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test your changes
Submit a pull request