使用说明

模型上下文协议（MCP）服务器

用于AI服务的模块化模型上下文协议服务器，具有多种传输选项和动态服务选择。基于SOLID原则构建，具有可维护性和可扩展性。

特性

多种AI服务：支持Claude、OpenAI和模拟服务
动态服务选择：根据请求选择AI服务
多个传输:
- 标准：用于命令行使用和脚本编写
- 传输控制协议：适用于基于网络的应用程序
- 双向通信：适用于网络浏览器和实时应用程序
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

安装

克隆存储库：

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

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

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

通过编辑来配置您的环境 .env 使用API密钥和设置创建文件。

配置

环境变量

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

变量	描述	默认值
`AI_SERVICE_TYPE`	要使用的默认AI服务（“claude”、“openai”、“mock”）	“claud”
`SECRETS_FILE`	带有API机密的JSON文件的路径	无
`ANTHROPIC_API_KEY`	您的Anthropic API密钥	无
`OPENAI_API_KEY`	您的OpenAI API密钥	无
`MCP_SERVER_NAME`	服务器名称	“ai-mcp服务器”
`MCP_SERVER_VERSION`	服务器版本	“1.0.0”
`MCP_TRANSPORT_TYPE`	传输类型（“stdio”、“tcp”或“websocket”）	“stdio
`MCP_TCP_HOST`	TCP/Webocket主机地址	“127.0.0.1”
`MCP_TCP_PORT`	TCP服务器端口	9000
`MCP_WS_PORT`	WebSocket服务器端口	8765
`MCP_WS_PATH`	WebSocket服务器路径	“/”
`MCP_WS_ORIGINS`	逗号分隔的允许来源列表	无（全部允许）
`CLAUDE_DEFAULT_MODEL`	默认克劳德模型	“克劳德3-opus-20240229”
`CLAUDE_DEFAULT_MAX_TOKENS`	Claude的默认最大令牌	4096
`CLAUDE_DEFAULT_TEMPERATURE`	克劳德的默认温度	0.7
`OPENAI_DEFAULT_MODEL`	默认OpenAI模型	“gpt-4o”
`OPENAI_DEFAULT_MAX_TOKENS`	OpenAI的默认最大令牌	1024
`OPENAI_DEFAULT_TEMPERATURE`	OpenAI的默认温度	0.7

当没有提供嵌入API凭据时，服务器将生成确定性模拟嵌入，以便在没有外部环境的情况下进行测试服务。

对于生产部署，请配置 QDRANT_URL 指向一个专用 Qdrant服务器。使用远程服务器提供持久存储并改进与默认内存模式相比，矢量搜索性能。

可选 SECRETS_FILE 变量允许您将API密钥存储在JSON中文件而不是环境变量。secrets文件中定义的值为当没有设置相应的环境变量时使用。如果秘密值为一个数组，每次键被调用时，服务器都会遍历这些值根据要求，实现了简单的按键轮换策略。

用法

运行服务器

标准标准模式

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 在浏览器中：

输入WebSocket URL（例如。， ws://localhost:8765/)
点击“连接”
使用该接口向服务器发送请求

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
}

服务特定请求（为了向后兼容性）

克劳德：

{
  "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`	检查系统运行状况

扩展服务器

添加新方法处理程序

创建一个新的处理程序类，实现 HandlerInterface 在handlers目录中
在 AIMCPServerApp.initialize() 方法

添加新的AI服务

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

添加新传输

创建一个新的传输类，扩展 Transport 传输目录中的类
更新主功能以使用您的新交通工具

WebSocket和负载均衡器

在此服务器前使用TLS/SSL端接负载平衡器（如AWS ELB）时：

客户端使用安全的WebSockets连接到负载均衡器(wss://)
负载平衡器处理TLS/SSL终止
负载均衡器使用常规WebSockets将流量转发到MCP服务器(ws://)
无需在应用程序本身中实现WSS

性能注意事项

处理非常大的存储库，特别是C#项目，可以生成许多数据库操作。如果遇到MongoDB的性能问题，请考虑批处理插入或使用替代存储策略。

许可证

MIT许可证

AI服务协议服务器

使用说明

模型上下文协议（MCP）服务器

特性

存储库结构

安装

配置

环境变量

用法

运行服务器

标准标准模式

TCP服务器模式

WebSocket服务器模式

命令行选项

客户示例

命令行客户端

Websocket浏览器客户端

JSON-RPC接口

统一AI消息请求

服务特定请求（为了向后兼容性）

可用方法

扩展服务器

添加新方法处理程序

添加新的AI服务

添加新传输

WebSocket和负载均衡器

性能注意事项

许可证

致谢

使用说明

模型上下文协议（MCP）服务器

特性

存储库结构

安装

配置

环境变量

用法

运行服务器

标准标准模式

TCP服务器模式

WebSocket服务器模式

命令行选项

客户示例

命令行客户端

Websocket浏览器客户端

JSON-RPC接口

统一AI消息请求

服务特定请求（为了向后兼容性）

可用方法

扩展服务器

添加新方法处理程序

添加新的AI服务

添加新传输

WebSocket和负载均衡器

性能注意事项

许可证

致谢

相关 MCP

模型推理协议服务

JSON-RPC服务

CLI工具MCP服务器

ChatGPT服务器应用

以太坊RPC MPC服务器

WinDbg调试服务器