MCP 服务器

MCP Server (mcp-tools)

danfmaia

开发者工具

访问服务器

README

MCP 服务器 (mcp-tools)

本项目包含一个通用的 MCP 服务器，旨在为 AI 代理提供工具，通过 stdin/stdout 使用模型上下文协议 (MCP) 进行通信。

提供的工具

服务器目前提供以下工具，可以通过 call_tool 端点调用：

`check_markdown_link_file`

描述: 检查单个指定 Markdown 文件中的 HTTP/HTTPS 链接。
参数:
- file_path (字符串, 必需): Markdown 文件的路径（相对于项目根目录或绝对路径）。
arguments 示例:
```
{
  "file_path": "docs/usage.md"
}
```
输出: 文本报告，详细说明文件中找到的链接的状态（总数、有效、损坏、错误）。

`check_markdown_link_files`

描述: 检查提供的 Markdown 文件列表中的 HTTP/HTTPS 链接。
参数:
- file_paths (字符串列表, 必需): Markdown 文件路径的列表（相对于项目根目录或绝对路径）。

arguments 示例:

{
  "file_paths": [
    "README.md",
    "docs/requirements/link_checker_tool_enhancements_reqs.md"
  ]
}

输出: 汇总的文本报告，总结所有已处理文件的链接状态。

`check_markdown_link_directory`

描述: 递归扫描指定目录中的 *.md 文件，并检查其中的 HTTP/HTTPS 链接。
参数:
- directory_path (字符串, 必需): 要扫描的目录的路径。
arguments 示例:
```
{
  "directory_path": "docs/"
}
```
输出: 汇总的文本报告，总结目录中找到的所有 Markdown 文件的链接状态。

`check_markdown_links_project`

描述: 扫描整个项目中的 *.md 文件，排除根目录 .gitignore 文件中列出的文件，并检查剩余文件中的 HTTP/HTTPS 链接。
参数: 无。
arguments 示例:
```
{}
```
输出: 汇总的文本报告，总结项目中找到的所有已处理 Markdown 文件的链接状态（遵循 .gitignore）。

设置 & 使用 (使用 Makefile)

本项目使用 uv 进行环境和依赖管理，并通过 Makefile 进行编排。

导航到项目目录: 确保您位于_此_项目 (mcp-server) 的根目录中。
```
cd /path/to/mcp-server
```
安装依赖项（包括开发/测试）: 如果本地虚拟环境 (.venv) 不存在，此命令将创建它，并使用 uv 安装所有必需的软件包。
```
make install-dev
```
运行测试 & 覆盖率:
```
make test
```
此命令使用 pytest 运行所有单元测试，并使用 coverage.py 生成代码覆盖率报告。
- 测试运行配置为如果总覆盖率降至 85% 以下则失败（请参阅 Makefile）。
- 截至 2025-04-04，覆盖率状态为：
  - 总体：85%
  - src/mcp_server/server.py: 81% (主要处理程序已覆盖；main 循环未测试)
  - src/mcp_server/tools/link_checker.py: 89% (核心逻辑已覆盖；状态检查中的一些边缘情况未测试)
Lint & 格式化代码: 使用 ruff 检查 linting 错误并根据项目标准格式化代码。
```
make lint
```
运行服务器（手动）: 服务器监听 stdin/stdout。
```
make run
```
(注意：手动交互需要发送正确构建的 JSON-RPC 消息，包括 initialize 和 initialized，然后再发送 call_tool。)
清理: 删除虚拟环境和缓存文件。
```
make clean
```

Cursor MCP 集成 (Linux)

可以使用 ~/.cursor/mcp.json 中的以下全局配置将此服务器作为 MCP 工具集成到 Cursor 中（您可能需要创建此文件/目录）：

{
  "mcpServers": {
    "local-link-checker": {
      "name": "Local Link Checker", // Cursor 中显示的名称
      "type": "command",
      // 使用此项目 venv 中 python 可执行文件的绝对路径
      "command": "/absolute/path/to/mcp-server/.venv/bin/python",
      "args": [
        "-m", // 运行模块
        "mcp_server.server" // 要运行的服务器模块
      ]
      // 可选：如果需要，定义工作目录（通常由 -m 处理）
      // "cwd": "/absolute/path/to/mcp-server"
    }
  }
}

集成的重要说明：

绝对路径： 您必须将 /absolute/path/to/mcp-server 替换为系统上此项目目录的正确绝对路径。
虚拟环境： 此配置假定您已首先运行 make install-dev 以创建 .venv 并在该项目目录中安装依赖项。
工作目录 & 文件路径： 通过 python -m 运行时，服务器的工作目录通常是项目根目录 (/absolute/path/to/mcp-server)。因此，在调用该工具时（例如，@Local Link Checker），file_path 参数应相对于此项目根目录（例如，对于根目录中的文件，file_path: test_links.md）或绝对路径。
重启 Cursor： 添加或修改 ~/.cursor/mcp.json 后，您必须重启 Cursor 才能使更改生效。

之前使用不同方法（如 uv run 或 shell 包装器）的集成尝试失败，原因是 Cursor 在 Linux 上的进程执行环境存在问题。使用项目自己的虚拟环境的直接 python -m 方法是被证明有效的配置。

添加新工具

在 handle_list_tools (src/mcp_server/server.py) 中定义工具的 schema。
在 handle_call_tool (src/mcp_server/server.py) 中的一个新的 elif name == "your-tool-name": 块下实现工具的逻辑。
- 根据需要在 src/mcp_server/tools/ 下的单独文件中创建辅助函数。
- 在 tests/ 中为辅助函数添加单元测试。
将任何新依赖项添加到 pyproject.toml。
如果添加了新的_仅测试_依赖项，请更新 Makefile 中的 install-dev 目标（基本依赖项应由 install-dev 中的 uv sync 处理）。
更新此 README。