AI导哈

模型上下文协议服务器

一个基于Python的模型上下文协议(MCP)服务器概念验证，提供工具和资源供AI助手和其他MCP客户端访问。

  • by ranit532
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ranit532/MCP-server

使用说明

MCP服务器POC

使用Python和现代技术的模型上下文协议（MCP）服务器的前沿概念验证（POC）实现。该服务器提供AI助手和其他MCP客户端可以访问的工具和资源。

🏗️ 建筑

MCP服务器遵循模块化架构，关注点明确分离：

graph TB
    subgraph "Client Layer"
        AI[AI Assistant/Client]
        CLI[CLI Client]
    end
    
    subgraph "Transport Layer"
        STDIO[STDIO Transport]
        HTTP[HTTP Transport - Future]
    end
    
    subgraph "MCP Server Core"
        SERVER[MCP Server Instance]
        HANDLER[Request Handler]
        TOOLS[Tools Registry]
        RESOURCES[Resources Registry]
    end
    
    subgraph "Tool Implementations"
        CALC[Calculate Tool]
        FETCH[Fetch URL Tool]
        SYSINFO[System Info Tool]
        PROCESS[Process Data Tool]
        FILE[File Operations Tool]
    end
    
    subgraph "Resource Providers"
        FILE_RES[File Resources]
        CONFIG_RES[Config Resources]
    end
    
    subgraph "External Services"
        HTTP_API[HTTP APIs]
        FILE_SYS[File System]
    end
    
    AI --> STDIO
    CLI --> STDIO
    STDIO --> SERVER
    SERVER --> HANDLER
    HANDLER --> TOOLS
    HANDLER --> RESOURCES
    TOOLS --> CALC
    TOOLS --> FETCH
    TOOLS --> SYSINFO
    TOOLS --> PROCESS
    TOOLS --> FILE
    RESOURCES --> FILE_RES
    RESOURCES --> CONFIG_RES
    FETCH --> HTTP_API
    FILE --> FILE_SYS
    FILE_RES --> FILE_SYS

工作流程图

sequenceDiagram
    participant Client
    participant Transport
    participant Server
    participant Tool
    participant Resource
    
    Client->>Transport: Initialize Connection
    Transport->>Server: Connection Established
    Client->>Server: List Tools Request
    Server->>Client: Tools List Response
    Client->>Server: List Resources Request
    Server->>Client: Resources List Response
    Client->>Server: Call Tool Request
    Server->>Tool: Execute Tool
    Tool->>Server: Tool Result
    Server->>Client: Tool Response
    Client->>Server: Read Resource Request
    Server->>Resource: Fetch Resource
    Resource->>Server: Resource Data
    Server->>Client: Resource Response

🚀 特性

  • 现代Python堆栈：使用Python 3.10+和异步/等待模式构建
  • 类型安全：Pydantic模型的完整类型提示
  • 高性能：用途 uvloop 增强异步性能
  • 综合工具：展示各种功能的多个示例工具
  • 资源管理：文件和配置资源提供程序
  • 测试：带pytest的完整测试套件
  • 配置：基于环境的配置管理

📋 先决条件

  • Python 3.10或更高版本
  • pip或诗意的包装管理
  • Git（用于克隆存储库）

🛠️ 安装

步骤1：克隆存储库

git clone <repository-url>
cd MCP-server

第二步：创建虚拟环境

# Using venv
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Or using conda
conda create -n mcp-server python=3.10
conda activate mcp-server

步骤3：安装依赖项

# Using pip
pip install -r requirements.txt

# For development (includes testing tools)
pip install -r requirements-dev.txt

# Or using poetry (if you prefer)
poetry install

步骤4：配置环境

# Copy example environment file
cp .env.example .env

# Edit .env file with your settings (optional)
# nano .env

🧪 测试

运行所有测试

pytest

运行覆盖率测试

pytest --cov=src --cov-report=html

运行特定测试

pytest tests/test_server.py::test_calculate_tool -v

🎯 用法

运行服务器

方法1：直接执行Python

python -m src.server

方法2：使用脚本

python scripts/run_server.py

方法3：作为一个模块

python -m src.server

客户端使用示例

运行示例客户端以查看服务器的运行情况：

python examples/example_client.py

可用工具

服务器提供以下工具：

  1. 计算：执行数学计算

    • 输入： {"expression": "2 + 2"}
    • 输出：计算结果

  2. fetch_url：从URL获取内容

    • 输入： {"url": "https://example.com", "method": "GET"}
    • 输出：HTTP响应内容

  3. get_system_info：获取系统信息

    • 输入： {}
    • 输出：系统详细信息和环境变量

  4. 进程数据：处理和转换数据

    • 输入： {"data": "hello", "operation": "uppercase"}
    • 操作： reverse, uppercase, lowercase, count

  5. write_file：将内容写入文件

    • 输入： {"filepath": "output.txt", "content": "Hello World"}
    • 输出：确认消息

可用资源

  1. 示例文件: file://example.txt -示例文件资源
  2. 服务器配置: config://server-config -当前服务器配置

📁 项目结构

MCP-server/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server implementation
│   └── config.py            # Configuration management
├── tests/
│   ├── __init__.py
│   └── test_server.py       # Unit tests
├── examples/
│   └── example_client.py    # Example client implementation
├── scripts/
│   └── run_server.py        # Server runner script
├── .env.example             # Example environment configuration
├── .gitignore               # Git ignore rules
├── pyproject.toml           # Project metadata and dependencies
├── pytest.ini              # Pytest configuration
├── requirements.txt         # Production dependencies
├── requirements-dev.txt     # Development dependencies
└── README.md               # This file

🔧 配置

可以使用环境变量配置服务器：

  • MCP_SERVER_NAME：服务器名称（默认值： mcp-server-poc)
  • MCP_SERVER_VERSION：服务器版本（默认值： 0.1.0)
  • LOG_LEVEL：日志记录级别（默认值： INFO)
  • ENABLE_METRICS：启用指标收集（默认值： true)

🧩 技术栈

  • MCP-SDK：Python官方模型上下文协议SDK
  • 派丹蒂克：数据验证和设置管理
  • httpx：现代异步HTTP客户端
  • 异步文件：异步文件操作
  • uvloop：高性能事件循环
  • pytest：测试框架
  • python dotenv：环境变量管理

🔍 发展

代码格式化

# Format code with black
black src/ tests/ examples/

# Lint with ruff
ruff check src/ tests/

# Type checking with mypy
mypy src/

添加新工具

  1. 在中添加工具定义 list_tools() 函数
  2. 在中实现工具逻辑 call_tool() 函数
  3. 在中添加测试 tests/test_server.py

例子：

# In list_tools()
Tool(
    name="my_new_tool",
    description="Description of my tool",
    inputSchema={
        "type": "object",
        "properties": {
            "param": {"type": "string"}
        },
        "required": ["param"]
    }
)

# In call_tool()
elif name == "my_new_tool":
    param = arguments.get("param")
    # Your tool logic here
    return [TextContent(type="text", text=f"Result: {result}")]

🐛 故障排除

常见问题

  1. 导入错误：确保安装了所有依赖项

    pip install -r requirements.txt

  2. Python 版本：确保使用Python 3.10+

    python --version

  3. 虚拟环境：确保虚拟环境已激活

    source venv/bin/activate

  4. 权限错误：检查写入操作的文件权限

📝 许可证

有关详细信息，请参阅LICENSE文件。

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

📚 额外资源

🎉 后续步骤

  • 添加更复杂的工具（数据库查询、API集成）
  • 实施身份验证和授权
  • 添加指标和监控
  • 支持流式响应
  • WebSocket传输支持
  • 资源缓存和优化

备注：这是一个POC项目。对于生产用途，考虑添加：

  • 正确的错误处理和记录
  • 安全措施（身份验证、输入验证）
  • 速率限制
  • 综合监控
  • 文档生成
  • CI/CD管道

相关 MCP