MCP Server (mcp-tools)

MCP 服务（mcp-tools）

此项目包含一个通用 MCP 服务，旨在通过模型上下文协议（MCP）使用标准输入/标准输出与 AI Agent 通信，并为其提供工具。

提供的工具

服务目前提供以下工具，可通过 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 编排。

1. 进入项目目录： 确保你位于_此_项目（mcp-server）的根目录。

   cd /path/to/mcp-server
   

2. 安装依赖（包括开发/测试依赖）： 如果本地虚拟环境（.venv）不存在，此命令会创建该环境，并使用 uv 安装所有必要的软件包。

   make install-dev
   

3. 运行测试并生成覆盖率报告：

   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%（已覆盖核心逻辑；未测试状态检查中的部分边界情况）

4. 检查代码并格式化： 使用 ruff 检查代码错误，并按照项目标准格式化代码。

   make lint
   

5. 运行服务（手动）： 服务通过标准输入/标准输出进行监听。

   make run
   

   （注意：手动交互需要发送格式正确的 JSON-RPC 消息；调用 call_tool 前，需先发送 initialize 和 initialized。）

6. 清理： 删除虚拟环境和缓存文件。

   make clean
   

Cursor MCP 集成（Linux）

此服务可通过在 ~/.cursor/mcp.json 中使用以下全局配置，集成为 Cursor 的 MCP 工具（你可能需要创建此文件或目录）：

{
  "mcpServers": {
    "local-link-checker": {
      "name": "Local Link Checker", // Name displayed in Cursor
      "type": "command",
      // Use the absolute path to the python executable within THIS project's venv
      "command": "/absolute/path/to/mcp-server/.venv/bin/python",
      "args": [
        "-m", // Run module
        "mcp_server.server" // The server module to run
      ]
      // Optional: Define the working directory if needed (usually handled by -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 方法。

添加新工具

1. 在 handle_list_tools（src/mcp_server/server.py）中定义工具的架构。
2. 在 handle_call_tool（src/mcp_server/server.py）中新增 elif name == "your-tool-name": 代码块，实现工具逻辑。
   • 根据需要，在 src/mcp_server/tools/ 下的单独文件中创建辅助函数。
   • 在 tests/ 中为辅助函数添加单元测试。
3. 在 pyproject.toml 中添加任何新依赖项。
4. 如果添加了新的 仅供测试使用 的依赖项，请更新 Makefile 中的 install-dev 目标（基础依赖项应通过 install-dev 中的 uv sync 处理）。
5. 更新此 README。

贡献

欢迎贡献！请遵循标准编码规范，并在提交拉取请求前确保测试通过（make test）。

许可证

[在此指定你的许可证]