使用说明

MCP服务器-独立模型上下文协议服务器

一个自包含的、配置驱动的模型上下文协议（MCP）服务器，用于向Claude和GPT-4等LLM公开工具和API。

概述

这是一个 完全独立 MCP服务器：

在端口8001上运行
用途 基于YAML的配置 用于工具定义（无需更改代码！）
支持 多种连接器类型 （HTTP，可为其他人扩展）
提供 丰富的法学硕士背景 对于每个工具
有 零耦合 后端服务
启用 动态工具发现 和注册

快速开始

1.安装依赖项

pip install -r requirements.txt

2.运行服务器

python -m uvicorn mcp_http_server:app --reload --port 8001

服务器将在以下位置可用： http://localhost:8001

3.验证工具是否已装载

# List all tools
curl http://localhost:8001/mcp/tools

# Get LLM context for a specific tool
curl http://localhost:8001/mcp/tools/{tool_id}/context

# Get complete schema for all tools
curl http://localhost:8001/mcp/schema

项目结构

mcp-server/
├── mcp/
│   ├── __init__.py                    # Package initialization
│   ├── core/
│   │   ├── __init__.py                # Core exports
│   │   ├── types.py                   # Type definitions with LLM context
│   │   ├── registry.py                # Tool registry & config loading
│   │   ├── connector.py               # Base connector interface
│   │   └── executor.py                # Tool executor & connector factory
│   ├── connectors/
│   │   ├── __init__.py                # Connector exports
│   │   └── http_connector.py          # HTTP REST connector
│   └── config/
│       └── tools.yaml                 # Master configuration
├── projects/
│   └── map_data/
│       └── config.yaml                # Map data tools definition
├── mcp_http_server.py                 # FastAPI HTTP server
├── requirements.txt                   # Python dependencies
└── README.md                          # This file

配置文件

主配置(`mcp/config/tools.yaml`)

控制全局设置和项目注册：

全局超时和缓存设置
项目定义和连接器配置
内置工具（例如system_health）
工具别名和类别

项目配置(`projects/map_data/config.yaml`)

定义特定项目的所有工具：

11井、钻机、钻井、存储、地质数据的地图数据工具
带验证的完整参数定义
LLM上下文的用例和示例
依赖关系和利率限制

API终点

所有端点都是 动态的 -没有硬编码的工具路线！

系统

获取 / -服务器信息
获取 /health -系统健康状况

工具管理

获取 /mcp/tools -列出所有工具
获取 /mcp/tools/{tool_id} -获取工具详细信息
获取 /mcp/tools/{tool_id}/context -获取工具的LLM上下文

模式和执行

获取 /mcp/schema -所有工具的完整架构（用于LLM上下文）
发布 /mcp/call-tool -执行任何带有参数的工具

请求示例

# List all tools
curl http://localhost:8001/mcp/tools

# Get tool details
curl http://localhost:8001/mcp/tools/get_wells

# Get LLM context
curl http://localhost:8001/mcp/tools/get_wells/context

# Execute a tool
curl -X POST http://localhost:8001/mcp/call-tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "get_wells",
    "parameters": {
      "limit": 10,
      "status": "Active"
    }
  }'

添加新工具

选项1：添加到现有项目

编辑 projects/map_data/config.yaml 并添加工具定义：

- id: "new_tool_id"
  name: "new_tool_name"
  category: "category_name"
  description: "Short description"
  long_description: |
    Longer description for LLM understanding...
  
  use_cases:
    - "Use case 1"
    - "Use case 2"
  
  parameters:
    - name: "param1"
      type: "string"
      description: "Parameter description"
      required: true
      examples: ["example1", "example2"]
  
  handler:
    type: "http"
    method: "GET"
    path: "/api/v1/endpoint"
    query_params:
      param1: "param1"
  
  examples:
    - description: "Example usage"
      parameters:
        param1: "value"
      expected_output_description: "What to expect"
      use_case: "Why you'd use this"
      business_value: "Business impact"
  
  related_tools: ["other_tool_id"]
  rate_limit: 100
  cache_ttl: 300

重新启动服务器-新工具会自动加载！

选项2：创建新项目

创建目录： projects/my_project/
创建 projects/my_project/config.yaml 用你的工具
注册 mcp/config/tools.yaml:

projects:
  - name: "my_project"
    description: "My project description"
    config_file: "projects/my_project/config.yaml"
    connector_type: "http"
    connector_config:
      base_url: "http://your-api-url:port"

重新启动服务器-所有新的项目工具都可用！

连接器类型

HTTP连接器（默认）

对于REST API。支持：

路径、查询和正文参数
承载令牌身份验证
参数验证
错误处理

配置：

connector_type: "http"
connector_config:
  base_url: "http://localhost:8000"
  timeout: 30
  headers:
    Content-Type: "application/json"
  auth_type: "bearer"  # Optional
  auth_config:
    token: "your-token"

添加自定义连接器

在中创建类 mcp/connectors/ 延伸 BaseConnector
实施 execute() 和 validate_config() 方法
注册 mcp/core/executor.py 连接器工厂
在YAML配置中使用

参数验证

工具支持丰富的参数定义，包括：

类型验证：字符串、整数、布尔值、数字、数组、对象
枚举：限制为特定值
范围验证：数字的最小值/最大值
必需/可选：根据需要标记参数
默认值：提供合理的默认值
帮助文本：指导LLM使用参数
例子：显示典型值
依赖项：注明相关字段

例子：

parameters:
  - name: "status"
    type: "string"
    required: false
    validation:
      enum: ["Active", "Inactive", "Suspended"]
    examples: ["Active", "Inactive"]
    help_text: "Filter by well status"

LLM背景

每个工具都为LLM提供了丰富的上下文：

curl http://localhost:8001/mcp/tools/get_wells/context

退货：

完整的工具描述和详细描述
所有用例和实际示例
带验证规则的参数描述
输出格式和预期结果
跨工具工作流的相关工具
业务价值和影响指标

缓存

工具支持可配置缓存：

cache_ttl: 300  # Cache for 5 minutes
rate_limit: 100  # 100 requests per time window

缓存键包括工具ID和精度参数。

错误处理

服务器提供详细的错误响应：

参数验证错误，并显示有用消息
带有调试信息的连接器错误
超时和速率限制违规
文件路径信息配置错误

发展

以开发模式运行

python -m uvicorn mcp_http_server:app --reload --port 8001

配置文件的更改会被检测到并自动重新加载。

在生产中运行

python -m uvicorn mcp_http_server:app --host 0.0.0.0 --port 8001 --workers 4

调试

检查服务器运行状况和连接器状态：

curl http://localhost:8001/health

# With detailed metrics
curl http://localhost:8001/health?detailed=true

查看配置加载问题和执行详细信息的日志。

配置验证

工具在启动时经过验证，用于：

所需配置部分
参数类型一致性
处理程序配置完整性
连接器可用性

验证错误会以清晰的消息和文件位置报告。

扩展系统

自定义处理程序

创建特定于项目的处理函数：

# In projects/my_project/handlers.py
async def my_handler(params):
    return {"result": "value"}

YAML中的引用：

handler:
  type: "custom"
  function: "projects.my_project.handlers.my_handler"

中间件和钩子

通过FastAPI中间件在中添加身份验证、日志记录或监控 mcp_http_server.py.

多连接器工作流

为同一项目使用多个连接器：

不同工具的不同端点
可靠性备用连接器
跨后端的负载平衡

测试

单元测试

# Run tests (create tests/ directory with pytest files)
pytest tests/

集成测试

对正在运行的服务器进行测试：

# In one terminal
python -m uvicorn mcp_http_server:app --port 8001

# In another
python scripts/test_tools.py

性能注意事项

缓存：启用常用工具
速率限制：保护后端服务
超时：防止挂起请求
分页：对大型结果集使用限制/跳过
工人流程：在生产中使用多名工人

安全

认证：配置连接器身份验证
速率限制：按工具配置
参数验证：防止注射攻击
跨域资源共享：如果需要，在FastAPI中配置
超文本传输安全协议：在生产环境中使用反向代理（nginx等）

故障排除

仅加载1个工具，而不是11个

问题：仅加载注册表 system_health 工具

解决方案：检查配置文件路径：

验证 mcp/config/tools.yaml 存在
验证 projects/map_data/config.yaml 存在
检查注册表调试日志
确保从工作目录解析路径

工具未执行

问题：工具调用失败，连接器错误

解决方案:

检查后端服务是否正在运行（localhost:8000）
验证连接器配置（base_url、auth）
直接测试后端端点： curl http://localhost:8000/api/v1/wells
检查服务器日志以了解详细错误

配置未重新加载

问题：不会显示对YAML的更改