MCP 工具

这是一个自定义的模型上下文协议（MCP）服务器实现，为 Claude Desktop 和其他大语言模型（LLM）客户端提供了文件系统和命令执行工具。

什么是模型上下文协议？

模型上下文协议（MCP）是一个开放协议，它标准化了应用程序如何向大语言模型（LLMs）提供上下文。就像 USB-C 端口提供了一种连接设备到各种外设的标准方式一样，MCP 提供了一种将 AI 模型与不同数据源和工具连接起来的标准方式。

此项目实现了一个带有多个有用工具的 FastMCP 服务器，这些工具使 Claude 及其他 LLMs 能够与您的本地文件系统交互并执行命令。它通过定义良好的工具接口以受控的方式扩展了 LLMs 的能力，使其能够访问本地系统。

MCP 的主要优势

• 标准化集成：MCP 提供了越来越多的预构建集成，您的 LLM 可以直接接入
• 供应商灵活性：轻松切换 LLM 提供商和供应商（Claude、GPT-4o、Gemini 等）
• 安全性：在您的基础设施内保护数据的最佳实践
• 工具暴露：封装现有工具，并让它们对任何兼容 MCP 的 LLM 客户端可见

功能

MCP 服务器提供了以下文件系统和命令执行工具：

• execute_shell_command：执行 shell 命令并获取 stdout/stderr 结果
• show_file：查看文件内容，可选指定行范围
• search_in_file：使用正则表达式在文件中搜索模式
• edit_file：通过字符串替换和行操作精确修改文件
• write_file：写入或追加内容到文件

MCP 架构

MCP 遵循客户端-服务器架构：

• 主机：启动连接的 LLM 应用程序（如 Claude Desktop 或 IDE）
• 客户端：在主机应用程序内部维护与服务器的一对一连接
• 服务器：向客户端提供上下文、工具和提示（本项目实现了服务器）

先决条件

• Python 3.10 或更高版本
• 一个兼容 MCP 的客户端（Claude Desktop 或任何支持 MCP 的其他客户端）

安装

1. 安装 uv
2. 克隆此仓库或下载源代码
3. 运行 uv run mcp install 以安装 MCP 服务器
4. 运行 which uv 获取 uv 可执行文件的绝对路径
5. 在 Claude Desktop 中更新您的 MCP 服务器配置，以使用 uv 可执行文件的绝对路径

我的 MCP 服务器配置如下所示：

{
  "globalShortcut": "",
  "mcpServers": {
    "zbigniew-mcp": {
      "command": "/Users/zbigniewtomanek/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "marker-pdf",
        "mcp",
        "run",
        "/Users/zbigniewtomanek/PycharmProjects/my-mcp-tools/server.py"
      ]
    }
  }
}

使用方法

从 Claude Desktop 连接

1. 打开 Claude Desktop
2. 使用标识符 "zbigniew-mcp" 连接到 MCP 服务器

注意：虽然此实现重点在于 Claude Desktop，但 MCP 设计为与任何兼容 MCP 的工具或 LLM 客户端兼容，从而在实现和集成方面提供了灵活性。

可用工具

execute_shell_command

使用参数列表安全地执行 shell 命令：

execute_shell_command(["ls", "-la"])
execute_shell_command(["grep", "-r", "TODO", "./src"])
execute_shell_command(["python", "analysis.py", "--input", "data.csv"])
execute_shell_command(["uname", "-a"])

show_file

查看文件内容，并可选指定行范围：

show_file("/path/to/file.txt")
show_file("/path/to/file.txt", num_lines=10)
show_file("/path/to/file.txt", start_line=5, num_lines=10)

search_in_file

使用正则表达式在文件中搜索模式：

search_in_file("/path/to/script.py", r"def\s+\w+\s*\(")
search_in_file("/path/to/code.py", r"#\s*TODO", case_sensitive=False)

edit_file

对文件进行精确修改：

# Replace text
edit_file("config.json", replacements={"\"debug\": false": "\"debug\": true"})

# Insert at line 5
edit_file("script.py", line_operations=[{"operation": "insert", "line": 5, "content": "# New comment"}])

# Delete lines 10-15
edit_file("file.txt", line_operations=[{"operation": "delete", "start_line": 10, "end_line": 15}])

# Replace line 20
edit_file("file.txt", line_operations=[{"operation": "replace", "line": 20, "content": "Updated content"}])

write_file

向文件写入或追加内容：

# Overwrite file
write_file("/path/to/file.txt", "New content")

# Append to file
write_file("/path/to/log.txt", "Log entry", mode="a")

fetch_page

获取网页内容并将其转换为 PDF（需要安装 chromium），然后使用本地 LLM 将其解析为 markdown：

fetch_page("https://example.com")

传输机制

MCP 支持多种客户端与服务器之间的通信传输方法：

• 标准输入/输出 (stdio): 使用标准输入/输出进行通信，适用于本地进程
• 服务器发送事件 (SSE): 通过 HTTP POST 请求实现从客户端到服务器的通信，并支持服务器到客户端的流式传输

此实现使用了一个通过文本输入/输出进行通信的本地 MCP 服务器。

通过自定义工具扩展

你可以轻松地通过添加带有 @mcp.tool 装饰器的新工具来扩展这个 MCP 服务器。按照 server.py 中的模式创建新的工具，以向你的 LLM 客户端暴露额外的功能。

相关项目

• langchain-mcp-adapters: 使用 LangChain 与 MCP
• MCP-Bridge: 将 MCP 工具映射到 OpenAI 的格式

安全注意事项

MCP 服务器使 Claude 能够访问您的本地系统。请注意以下几点：

• 该服务器将以您的用户身份执行 shell 命令
• 它可以读取、写入和修改您系统上的文件
• 如果安全是关注点，请考虑限制对特定目录的访问