Model Context Protocol (MCP) Server

Model Context Protocol (MCP) 服务

一个模块化的 Model Context Protocol 服务，为 AI 服务提供多种传输选项和动态服务选择。采用 SOLID 原则构建，便于维护和扩展。

功能

• 多种 AI 服务：支持 Claude、OpenAI 和模拟服务
• 动态服务选择：可针对每个请求选择 AI 服务
• 多种传输方式：
  • stdio：用于命令行调用和脚本编写
  • TCP：用于基于网络的应用程序
  • WebSocket：用于 Web 浏览器和实时应用程序
• JSON-RPC 2.0：符合规范的接口，确保交互可预测
• 模块化架构：便于扩展新的服务和传输方式
• 环境配置：通过 .env 文件轻松设置
• 流式传输支持：为支持的传输方式提供实时响应流

仓库结构

basic-mcp-server/
├── .env                      # Environment configuration
├── .gitignore                # Git ignore rules
├── README.md                 # Project documentation
├── examples/                 # Example clients
│   ├── example_client.py     # Command-line client example
│   └── websocket_client.html # Browser WebSocket client
├── mcp_server.py             # Main entry point
└── mcp_server/               # Core package
    ├── config/               # Configuration management
    │   ├── settings.py       # Environment and settings handling
    │   └── __init__.py
    ├── core/                 # Core server logic
    │   ├── server.py         # Main server implementation
    │   └── __init__.py
    ├── handlers/             # Method handlers
    │   ├── base_handlers.py  # Standard MCP handlers
    │   ├── system_handlers.py # System info handlers
    │   └── __init__.py
    ├── models/               # Data models
    │   ├── json_rpc.py       # JSON-RPC data structures
    │   └── __init__.py
    ├── services/             # AI service implementations
    │   ├── claude_service.py # Anthropic Claude API
    │   ├── openai_service.py # OpenAI API
    │   └── __init__.py       # Service registry
    ├── transports/           # Communication protocols
    │   ├── base.py           # Transport interfaces
    │   ├── websocket.py      # WebSocket implementation
    │   └── __init__.py
    └── __init__.py

安装

1. 克隆仓库：

   git clone https://github.com/shaswata56/basic-mcp-server.git
   cd basic-mcp-server
   

2. 创建虚拟环境并安装依赖：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -e .
   

3. 编辑 .env 文件，使用你的 API 密钥和设置配置环境。

配置

环境变量

可使用 .env 文件中的环境变量配置服务：

变量	描述	默认值
AI_SERVICE_TYPE	要使用的默认 AI 服务（"claude"、"openai"、"mock"）	"claude"
SECRETS_FILE	包含 API 密钥的 JSON 文件路径	None
ANTHROPIC_API_KEY	你的 Anthropic API 密钥	None
OPENAI_API_KEY	你的 OpenAI API 密钥	None
MCP_SERVER_NAME	服务名称	"ai-mcp-server"
MCP_SERVER_VERSION	服务版本	"1.0.0"
MCP_TRANSPORT_TYPE	传输类型（"stdio"、"tcp" 或 "websocket"）	"stdio"
MCP_TCP_HOST	TCP/WebSocket 主机地址	"127.0.0.1"
MCP_TCP_PORT	TCP 服务端口	9000
MCP_WS_PORT	WebSocket 服务端口	8765
MCP_WS_PATH	WebSocket 服务路径	"/"
MCP_WS_ORIGINS	允许的源列表，以逗号分隔	None（允许全部）
CLAUDE_DEFAULT_MODEL	默认 Claude 模型	"claude-3-opus-20240229"
CLAUDE_DEFAULT_MAX_TOKENS	Claude 的默认最大 token 数	4096
CLAUDE_DEFAULT_TEMPERATURE	Claude 的默认温度	0.7
OPENAI_DEFAULT_MODEL	默认 OpenAI 模型	"gpt-4o"
OPENAI_DEFAULT_MAX_TOKENS	OpenAI 的默认最大 token 数	1024
OPENAI_DEFAULT_TEMPERATURE	OpenAI 的默认温度	0.7

| EMBEDDINGS_3_LARGE_API_URL | text-embedding-3-large 的 Azure 端点 | None | | EMBEDDINGS_3_LARGE_API_KEY | text-embedding-3-large 的 API 密钥 | None | | EMBEDDINGS_3_SMALL_API_URL | text-embedding-3-small 的 Azure 端点 | None | | EMBEDDINGS_3_SMALL_API_KEY | text-embedding-3-small 的 API 密钥 | None | | AZURE_OPENAI_EMBEDDING_DEPLOYMENT | Embedding 的 Azure 部署名称 | <model name> | | QDRANT_URL | Qdrant 服务的 URL（使用 :memory: 可在内存中运行） | None | | QDRANT_API_KEY | Qdrant Cloud 的 API 密钥 | None |

未提供 Embedding API 凭据时，服务会生成确定性的模拟 Embedding，以便在不使用外部服务的情况下进行测试。

对于生产环境部署，请将 QDRANT_URL 配置为指向专用 Qdrant 服务。与默认的内存模式相比，使用远程服务可提供持久化存储并提升向量搜索性能。

可选变量 SECRETS_FILE 允许你将 API 密钥存储在 JSON 文件中，而不是环境变量中。未设置相应环境变量时，将使用密钥文件中定义的值。如果密钥值是数组，每次请求该密钥时，服务都会轮换使用其中的值，从而实现简单的密钥轮换策略。

使用方法

运行服务

标准 stdio 模式

python mcp_server.py

TCP 服务模式

python mcp_server.py --tcp --host 127.0.0.1 --port 9000

WebSocket 服务模式

python mcp_server.py --websocket --host 127.0.0.1 --port 8765 --ws-path /

命令行选项

usage: mcp_server.py [-h] [--tcp | --websocket] [--host HOST] [--port PORT]
                     [--ws-path WS_PATH] [--service-type {claude,openai,mock}]
                     [--claude-api-key CLAUDE_API_KEY]
                     [--openai-api-key OPENAI_API_KEY]
                     [--qdrant-url QDRANT_URL]
                     [--qdrant-api-key QDRANT_API_KEY] [--mock]
                     [--log-level {DEBUG,INFO,WARNING,ERROR}]
                     [--env-file ENV_FILE]

AI MCP Server with JSON-RPC

options:
  -h, --help            show this help message and exit
  --log-level {DEBUG,INFO,WARNING,ERROR}
                        Logging level
  --env-file ENV_FILE   Path to .env file (default: .env in project root)

Transport Options:
  --tcp                 Run as TCP server
  --websocket           Run as WebSocket server
  --host HOST           Host to bind server
  --port PORT           Port for server
  --ws-path WS_PATH     URL path for WebSocket server (default: /)

AI Service Options:
  --service-type {claude,openai,mock}
                        AI service to use
  --claude-api-key CLAUDE_API_KEY
                        Anthropic API key
  --openai-api-key OPENAI_API_KEY
                          OpenAI API key
  --qdrant-url QDRANT_URL
                          Qdrant server URL
  --qdrant-api-key QDRANT_API_KEY
                          Qdrant API key
  --mock                Use mock AI service (for testing)

客户端示例

命令行客户端

examples/example_client.py 提供了一种与服务器交互的简单方式：

# Initialize connection
python examples/example_client.py initialize

# List available tools
python examples/example_client.py list-tools

# Echo text
python examples/example_client.py echo "Hello, world!"

# Calculate expression
python examples/example_client.py calculate "2 + 3 * 4"

# Ask AI with dynamic service selection
python examples/example_client.py ask "What is the capital of France?" --service claude

# System information
python examples/example_client.py system-info

WebSocket 浏览器客户端

对于 WebSocket 传输，请在浏览器中打开 examples/websocket_client.html：

1. 输入 WebSocket URL（例如，ws://localhost:8765/）
2. 点击“连接”
3. 使用界面向服务器发送请求

JSON-RPC 接口

统一 AI 消息请求

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "ai/message",
    "arguments": {
      "prompt": "What is the capital of France?",
      "service_name": "claude"  // Optional: "claude", "openai", "mock" or omit for default
    }
  },
  "id": 1
}

特定服务的请求（用于向后兼容）

Claude：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "claude/message",
    "arguments": {
      "prompt": "What is the capital of France?"
    }
  },
  "id": 2
}

OpenAI：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "openai/message",
    "arguments": {
      "prompt": "What is the capital of France?"
    }
  },
  "id": 3
}

可用方法

方法	描述
initialize	初始化服务器连接
tools/list	列出可用工具
tools/call	使用参数调用工具
resources/list	列出可用资源
resources/read	读取资源
system/info	获取系统信息
system/health	检查系统运行状况

扩展服务器

添加新的方法处理器

1. 在 handlers 目录中创建一个实现 HandlerInterface 的新处理器类
2. 在 AIMCPServerApp.initialize() 方法中注册它

添加新的 AI 服务

1. 在 services 目录中创建一个实现 AIServiceInterface 的新服务类
2. 将其添加到 create_ai_services_from_config() 中的服务注册表

添加新的传输方式

1. 在 transports 目录中创建一个继承 Transport 类的新传输类
2. 更新主函数以使用新的传输方式

WebSocket 和负载均衡器

在此服务器前使用 TLS/SSL 终止型负载均衡器（如 AWS ELB）时：

• 客户端使用安全 WebSocket（wss://）连接负载均衡器
• 负载均衡器负责 TLS/SSL 终止
• 负载均衡器使用普通 WebSocket（ws://）将流量转发到 MCP 服务
• 无需在应用程序本身实现 WSS

性能注意事项

处理非常大的代码仓库，尤其是 C# 项目时，可能会产生大量数据库操作。 如果遇到 MongoDB 性能问题，请考虑批量插入或采用其他存储策略。

许可证

MIT 许可证

致谢

• Anthropic 提供的 Claude API
• OpenAI API
• JSON-RPC 2.0 规范
• WebSockets 协议