内容
# MCP 工具
自定义的模型上下文协议（MCP）服务器实现，提供文件系统和命令执行工具，供 Claude Desktop 和其他 LLM 客户端使用。
## 什么是模型上下文协议？
模型上下文协议（MCP）是一种开放协议，标准化了应用程序如何为大型语言模型（LLM）提供上下文。就像 USB-C 接口提供了一种标准化的方式，将设备连接到各种外设一样，MCP 提供了一种标准化的方式，将 AI 模型连接到不同的数据源和工具。
该项目实现了具有多个实用工具的 FastMCP 服务器，使 Claude 和其他 LLM 能够与本地文件系统交互并执行命令。它通过定义良好的工具接口，以受控的方式扩展了 LLM 的功能，实现了本地系统访问。
## MCP 的主要优势
- **标准化集成**：MCP 提供了一系列预建的集成，您的 LLM 可以直接使用
- **供应商灵活性**：轻松在 LLM 提供商和供应商之间切换（Claude、GPT-4o、Gemini 等）
- **安全性**：在您的基础设施内保护数据的最佳实践
- **工具暴露**：封装现有工具，使其可供任何与 MCP 兼容的 LLM 客户端访问
## 功能
MCP 服务器提供以下文件系统和命令执行工具：
- **执行 shell 命令**：执行 shell 命令并获取 stdout/stderr 结果
- **显示文件**：查看文件内容，可选指定行范围
- **搜索文件**：使用正则表达式在文件中搜索模式
- **编辑文件**：对文件进行精确修改，包括字符串替换和行操作
- **写入文件**：写入或追加文件内容
## MCP 架构
MCP 遵循客户端-服务器架构：
- **主机**：LLM 应用程序（如 Claude Desktop 或 IDE），发起连接
- **客户端**：与服务器保持 1:1 连接，位于主机应用程序内
- **服务器**：向客户端提供上下文、工具和提示（该项目实现了服务器）
## 先决条件
- Python 3.10 或更高版本
- 与 MCP 兼容的客户端（Claude Desktop 或其他支持 MCP 的客户端）
## 安装
1. [安装 uv](https://docs.astral.sh/uv/getting-started/installation/)
2. 克隆此仓库或下载源代码
3. 运行 `uv run mcp install` 安装 MCP 服务器
4. 运行 `which uv` 获取 `uv` 可执行文件的绝对路径
5. 在 Claude Desktop 中更新 MCP 服务器配置，使用 `uv` 可执行文件的绝对路径
我的 MCP 服务器配置如下：
```json
{
"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 设计为与任何兼容的工具或 LLM 客户端兼容，提供灵活的实现和集成。
## 可用工具
### 执行 shell 命令
使用参数列表安全地执行 shell 命令：
```python
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"])
```
### 显示文件
查看文件内容，可选指定行范围：
```python
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)
```
### 搜索文件
使用正则表达式在文件中搜索模式：
```python
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)
```
### 编辑文件
对文件进行精确修改：
```python
# 替换文本
edit_file("config.json", replacements={"\"debug\": false": "\"debug\": true"})
# 在第 5 行插入
edit_file("script.py", line_operations=[{"operation": "insert", "line": 5, "content": "# 新注释"}])
# 删除第 10-15 行
edit_file("file.txt", line_operations=[{"operation": "delete", "start_line": 10, "end_line": 15}])
# 替换第 20 行
edit_file("file.txt", line_operations=[{"operation": "replace", "line": 20, "content": "更新内容"}])
```
### 写入文件
写入或追加文件内容：
```python
# 覆盖文件
write_file("/path/to/file.txt", "新内容")
# 追加到文件
write_file("/path/to/log.txt", "日志条目", mode="a")
```
### 获取页面
获取网页内容到 PDF（需要安装 chromium），然后使用本地 LLM 解析为 markdown：
```python
fetch_page("https://example.com")
```
## 传输机制
MCP 支持客户端和服务器之间的多种传输方法：
- **标准输入/输出（stdio）**：使用标准输入/输出进行通信，适用于本地进程
- **服务器发送事件（SSE）**：使用 HTTP POST 请求实现服务器到客户端的流式传输，适用于客户端到服务器的通信
此实现使用通过文本输入/输出进行通信的本地 MCP 服务器。
## 使用自己的工具扩展
您可以通过添加新的工具，使用 `@mcp.tool` 装饰器轻松扩展此 MCP 服务器。遵循 `server.py` 中的模式创建新的工具，向您的 LLM 客户端公开额外的功能。
## 相关项目
- [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters)：将 MCP 与 LangChain 结合使用
- [MCP-Bridge](https://github.com/SecretiveShell/MCP-Bridge)：将 MCP 工具映射到 OpenAI 的格式
## 安全考虑
MCP 服务器为 Claude 提供对本地系统的访问。请注意以下几点：
- 服务器以您的用户身份执行 shell 命令
- 它可以读取、写入和修改系统上的文件
- 如果安全是关注点，请考虑限制对特定目录的访问
MCP 市场