MCP智能代理路由

git clone https://github.com/yourusername/mcp-relay.git
cd mcp-relay

uv venv
source .venv/bin/activate  # On Unix/macOS
# .venv\Scripts\activate  # On Windows

uv sync

uv pip install -e .

# Start the server
mcp-relay

# Or with uvicorn for development
uvicorn mcp_relay.main:app --reload

POST /api/tools/discover

{
  "query": "I need to perform calculations",
  "tags": ["math", "calculation"],
  "limit": 5
}

{
  "tools": [
    {
      "tool_id": "calculator",
      "name": "Calculator",
      "description": "Perform mathematical calculations",
      "score": 0.95,
      "matched_tags": ["math", "calculation"],
      "estimated_tokens": 50
    }
  ],
  "query_id": "uuid",
  "timestamp": "2024-01-01T00:00:00"
}

POST /api/tools/provision

{
  "tool_ids": ["calculator", "web-search"],
  "max_tools": 3
}

{
  "tools": [
    {
      "name": "Calculator",
      "description": "Perform mathematical calculations",
      "parameters": { "type": "object", "properties": {...} },
      "token_count": 50
    }
  ],
  "metadata": {
    "total_tokens": 150,
    "gating_applied": true
  }
}

# Make sure the server is running first
mcp-relay

# In another terminal, run the interactive demo
python demo.py

# Test the server endpoints
python test_server.py

import httpx
import asyncio

async def find_math_tools():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/api/tools/discover",
            json={
                "query": "I need to solve equations",
                "tags": ["math"],
                "limit": 3
            }
        )
        tools = response.json()["tools"]
        print(f"Found {len(tools)} relevant tools")
        for tool in tools:
            print(f"- {tool['name']}: {tool['score']:.3f}")

asyncio.run(find_math_tools())

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_relay

# Run specific test files
pytest tests/test_discovery_service.py -v

# Run integration tests
pytest tests/test_integration.py -v

# Allow access from specific LAN IPs
export ALLOWED_MCP_HOSTS="localhost,127.0.0.1,192.168.1.100,192.168.1.101"

# Allow access from custom hostname
export ALLOWED_MCP_HOSTS="localhost,127.0.0.1,myserver.local,app.internal"

# Docker example
docker run -p 8000:8000 \
  -e ALLOWED_MCP_HOSTS="localhost,127.0.0.1,192.168.1.100" \
  mcp-relay

{
  "docs-http": {
    "url": "http://localhost:8844/mcp",
    "transport": "streamable-http",
    "headers": {
      "Authorization": "Bearer example"
    }
  },
  "legacy-sse": {
    "url": "http://localhost:9000/mcp",
    "transport": "sse"
  }
}

# Build the image
docker build -t mcp-relay .

# Prepare persistent data directory (config/logs/storage live here)
mkdir -p data/config data/logs data/storage
cp config/mcp-servers.toml data/config/mcp-servers.toml

# Run on CPU (single bind mount handles config, logs, and storage)
docker run --rm -p 8000:8000 \
  -v $(pwd)/data:/data \
  -e MCP_DATA_DIR=/data \
  mcp-relay

# Enable GPU embeddings (requires NVIDIA Container Toolkit)
docker run --rm -p 8000:8000 --gpus all \
  -v $(pwd)/data:/data \
  -e MCP_DATA_DIR=/data \
  -e MCP_RELAY_ENCODER_DEVICE=cuda:0 \
  mcp-relay

# Customize environment (optional)
cat <<'EOF' > .env
MCP_DATA_VOLUME=./data
MCP_DATA_DIR=/data
MCP_RELAY_ENCODER_DEVICE=cpu  # set to cuda:0 after installing NVIDIA toolkit
MCP_RELAY_SKIP_BOOTSTRAP=0
EOF

docker compose --env-file .env up --build

mcp-relay/
├── src/
│   └── mcp_relay/
│       ├── __init__.py
│       ├── main.py              # FastAPI application
│       ├── api/
│       │   ├── models.py        # Pydantic models
│       │   ├── tools.py         # Tool management endpoints
│       │   └── mcp.py           # MCP server endpoints
│       ├── models/
│       │   └── tool.py          # Domain models
│       └── services/
│           ├── discovery.py     # Semantic search
│           ├── gating.py        # Tool selection logic
│           └── repository.py    # Tool storage
├── tests/
│   ├── test_*.py               # Test files
│   └── test_integration.py     # Integration tests
├── demo.py                     # Interactive demo
├── test_server.py              # Manual testing script
└── pyproject.toml              # Project configuration

# 1. Clear existing demo tools
DELETE /api/tools/clear

# 2. Register tools from your MCP servers
POST /api/tools/register
{
  "id": "exa_research_paper_search",
  "name": "research_paper_search",
  "description": "Search across 100M+ research papers with full text access",
  "tags": ["search", "research", "academic"],
  "estimated_tokens": 250,
  "server": "exa",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "numResults": {"type": "number", "default": 5}
    },
    "required": ["query"]
  }
}

# User: "Add this Slack MCP server to mcp relay"
# AI: Connects to server, discovers tools, and registers everything

POST /api/mcp/ai/register-server
{
  "server_name": "slack",
  "config": {
    "command": "npx",
    "args": ["@slack/mcp-server"],
    "env": {"SLACK_TOKEN": "xoxb-..."}
  },
  "tools": [
    // AI provides all discovered tools with metadata
  ]
}

# Result: Slack server + all tools registered and ready for use

# Format code
black .

# Run linter
ruff check . --fix

# Type checking
mypy .

# Run all checks
black . && ruff check . --fix && mypy . && pytest

Tool(
    id="my-tool",
    name="My Tool",
    description="Description for semantic search",
    tags=["category", "function"],
    estimated_tokens=100,
    parameters={
        "type": "object",
        "properties": {...},
        "required": [...]
    }
)