本地 MCP 服务器

一个模块化、生产就绪的模型上下文协议 (MCP) 服务器，为 LangGraph 代理和其他 MCP 客户端提供计算器和文件操作工具。

功能特性

• 18 个工具：10 个计算器工具 + 8 个文件操作工具
• 异步支持：完全的异步/等待支持，优化性能
• 沙箱安全：文件操作限制在工作区目录内
• 可配置：基于 YAML 的配置，支持环境变量覆盖
• 日志记录：多级日志记录，支持轮转（文件 + 控制台）
• 类型安全：完整的类型注解和验证
• 模块化：易于添加新的工具类别

架构

local_mcp_server/
├── src/
│   ├── server.py              # MCP 服务器实现
│   ├── config.py              # 配置管理
│   ├── logger.py              # 日志设置
│   └── tools/
│       ├── base.py            # 工具注册和 @tool 装饰器
│       ├── calculator/        # 10 个计算工具
│       │   ├── basic.py       # 加、减、乘、除
│       │   └── advanced.py    # 幂、平方根、对数、正弦、余弦、正切
│       └── file_ops/          # 8 个文件操作工具
│           ├── read.py        # 读取、按行读取、检查存在、列表
│           └── write.py       # 写入、追加、创建、删除
├── config/
│   └── default.yaml           # 默认配置
├── workspace/                 # 文件操作沙箱
├── logs/                      # 服务器日志
└── examples/
    ├── test_client.py         # 简单 MCP 客户端测试
    └── langgraph_integration.py  # LangGraph 集成示例

工具

计算器工具（10 个）

基本操作：

• calculator_add：两数相加
• calculator_subtract：两数相减
• calculator_multiply：两数相乘
• calculator_divide：两数相除（含零检查）

高级操作：

• calculator_power：计算 base^exponent
• calculator_sqrt：计算平方根（验证非负数）
• calculator_log：计算对数（支持自定义底数）
• calculator_sin：计算正弦（角度/弧度）
• calculator_cos：计算余弦（角度/弧度）
• calculator_tan：计算正切（角度/弧度）

文件操作工具（8 个）

读取操作：

• file_read：读取完整文件内容
• file_read_lines：读取文件的特定行
• file_exists：检查文件是否存在
• file_list：列出文件（支持 glob 模式）

写入操作：

• file_write：写入/覆盖文件内容
• file_append：追加内容到文件
• file_create：创建新文件（如存在则失败）
• file_delete：删除文件

安全特性：

• 仅接受相对路径（相对于工作区）
• 沙箱强制执行（所有路径必须在工作区内）
• 路径遍历防护
• 文件扩展名过滤
• 文件大小限制（默认：10MB）

安装

1. 安装依赖

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Windows 系统：venv\Scripts\activate

# 安装依赖
pip install mcp aiofiles pyyaml

或使用项目安装：

pip install -e .

2. 配置（可选）

复制并自定义配置：

cp config/default.yaml config/config.yaml
# 编辑 config/config.yaml 以设置您的首选项

或使用环境变量：

export MCP_LOG_LEVEL=DEBUG
export MCP_WORKSPACE_ROOT=./workspace
export MCP_DEBUG=true

使用方法

运行服务器

服务器使用 stdio 传输进行通信：

# 直接运行
python src/server.py

# 或作为模块运行
python -m src

服务器将：

1. 从 config/default.yaml 加载配置（如果存在 config/config.yaml 也会加载）
2. 初始化日志到 logs/mcp_server.log
3. 从 tools/ 模块注册所有工具
4. 开始监听 stdin/stdout 的 MCP 消息

使用简单客户端测试

测试所有工具而无需 LangGraph：

python examples/test_client.py

这将：

• 连接到 MCP 服务器
• 列出所有可用工具
• 测试计算器操作（加、除、平方根、正弦）
• 测试文件操作（写入、读取、列表、存在）
• 测试错误处理

与 LangGraph 集成

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def use_mcp_tools():
    # 连接到 MCP 服务器
    server_params = StdioServerParameters(
        command="python",
        args=["src/server.py"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 列出可用工具
            tools = await session.list_tools()

            # 调用工具
            result = await session.call_tool(
                "calculator_add",
                {"a": 10, "b": 5}
            )
            print(result.content[0].text)
            # 输出：{"result": 15.0, "operation": "add", "operands": {"a": 10, "b": 5}}

asyncio.run(use_mcp_tools())

完整示例请参见 examples/langgraph_integration.py。

配置

配置文件（config/default.yaml）

server:
  name: "Local MCP Server"
  version: "1.0.0"
  debug: false

file_operations:
  workspace_root: "./workspace"
  enable_sandbox: true
  max_file_size: 10  # MB
  blocked_extensions: [".exe", ".dll", ".so"]
  default_encoding: "utf-8"

logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
  file: "./logs/mcp_server.log"
  console_output: true

环境变量

• MCP_CONFIG_PATH：用户配置文件路径
• MCP_LOG_LEVEL：覆盖日志级别（DEBUG、INFO 等）
• MCP_WORKSPACE_ROOT：覆盖工作区根目录
• MCP_DEBUG：启用调试模式（true/false）

工具返回格式

所有工具返回结构化的 JSON：

计算器工具：

{
  "result": 15.0,
  "operation": "add",
  "operands": {"a": 10, "b": 5}
}

文件读取：

{
  "content": "文件内容在这里...",
  "metadata": {
    "size_bytes": 1024,
    "encoding": "utf-8",
    "line_count": 50,
    "path": "test.txt"
  }
}

文件写入：

{
  "success": true,
  "bytes_written": 1024,
  "path": "output.txt",
  "operation": "write"
}

错误：

{
  "error": "不能除以零"
}

添加新工具

1. 在 src/tools/your_category/ 中创建新模块
2. 使用 @tool 装饰器：

from ..base import tool

@tool(
    name="your_tool_name",
    description="工具的功能描述",
    input_schema={
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "参数描述"}
        },
        "required": ["param1"]
    }
)
async def your_tool_function(param1: str) -> dict:
    """工具实现。"""
    return {"result": "success"}

3. 在 src/tools/__init__.py 中导入模块
4. 重启服务器

日志记录

日志写入到：

• 文件：logs/mcp_server.log（支持轮转）
• 控制台：stderr（如果 console_output: true）

注意：stdout 保留用于 MCP 协议通信。

日志级别：

• DEBUG：详细调试信息（工具参数、结果）
• INFO：一般操作（工具调用、文件操作）
• WARNING：警告（验证失败、非关键错误）
• ERROR：错误（操作失败、异常）
• CRITICAL：严重故障（服务器崩溃）

启用调试模式：

export MCP_DEBUG=true
# 或编辑 config/config.yaml：debug: true

安全注意事项

文件操作安全

1. 沙箱：所有文件路径必须在 workspace_root 内
2. 路径验证：拒绝绝对路径，防止 .. 遍历
3. 扩展名过滤：默认阻止危险扩展名
4. 大小限制：文件默认限制为 10MB
5. 仅相对路径：LLM 提供相对路径，如 data/input.txt

最佳实践

• 以最小权限运行服务器
• 定期检查 workspace/ 内容
• 根据您的用例自定义 blocked_extensions
• 设置适当的 max_file_size 限制
• 启用日志记录以监控操作

故障排除

服务器无法启动

• 检查 Python 版本（需要 Python 3.10+）
• 验证所有依赖已安装：pip install mcp aiofiles pyyaml
• 检查 logs/mcp_server.log 中的日志

工具未找到

• 验证工具模块已在 src/tools/__init__.py 中导入
• 检查工具是否使用 @tool 装饰器注册
• 添加新工具后重启服务器

文件操作错误

• 验证路径是相对的（不是绝对路径）
• 检查路径是否在工作区内：config.workspace_root
• 验证文件权限
• 检查文件大小是否超过 max_file_size 限制

路径验证错误

• 使用正斜杠：data/file.txt（不是 data\file.txt）
• 不要使用 .. 或绝对路径
• 确保文件扩展名未被阻止

开发

运行测试

# 使用简单客户端测试
python examples/test_client.py

# 使用 LangGraph 测试（需要 API 密钥）
export ANTHROPIC_API_KEY=your_key_here
python examples/langgraph_integration.py

项目结构

• src/server.py：MCP 服务器实现
• src/config.py：配置加载和验证
• src/logger.py：日志设置
• src/tools/base.py：工具注册表和装饰器
• src/tools/calculator/：计算器工具
• src/tools/file_ops/：文件操作工具

许可证

MIT 许可证 - 随意使用和修改您的项目。

贡献

欢迎贡献！要添加新工具：

1. 遵循 src/tools/ 中的模块化结构
2. 使用 @tool 装饰器
3. 添加全面的错误处理
4. 更新此 README

支持

如有问题或疑问：

1. 查看故障排除部分
2. 查看 logs/mcp_server.log 中的日志
3. 启用调试模式以获取详细输出
4. 查看 MCP 文档：https://modelcontextprotocol.io

---

使用 Anthropic 的 MCP（模型上下文协议）构建