UV Documentation MCP Server

UV 文档 MCP 服务

一个 MCP 服务，通过标准化 API 提供对 UV 文档的程序化访问。此服务现采用现代化的分层资源结构，将高层级文档章节和详细的命令文档（包括子章节）分别作为独立的 MCP 资源公开。工具已精简，许多文档查询通过资源层处理。

链接

• UV 文档
• MCP Python SDK

快速开始

1. 要求：
   确保已安装 Python 3.13+（为兼容 MCP SDK，最低版本为 3.10）。

2. 克隆仓库：

   git clone https://github.com/StevenBtw/uv-docs-mcp.git
   cd uv-docs-mcp
   

3. 设置虚拟环境并安装依赖项：

   python3.13 -m venv env
   source env/bin/activate   # On Windows use: env\\Scripts\\activate
   pip install -e .
   

4. 运行服务：

   uv run uv-docs
   

   （如果使用 Claude Desktop 或其他 MCP 客户端，请相应调整配置。）

架构

此服务采用模块化分层设计，清晰划分各项职责：

flowchart TD
    Client[MCP Client] --> Server[Server Layer]
    Server --> Resources[Resource Layer]
    Server --> Tools[Tools Layer]
    Server --> Prompts[Prompts Layer]
    
    Resources --> Cache[Cache System]
    Tools --> Cache

• 资源层：
  通过 uv-docs:// 方案的 URI 提供 UV 文档。资源按层级组织：

  • 第 1 层： 基础章节（例如，uv-docs://cli、uv-docs://settings、uv-docs://resolver）
  • 第 2 层： 单个命令（例如，uv-docs://cli/uv-run、uv-docs://cli/uv-cache）
  • 第 3 层： 命令子章节（例如，uv-docs://cli/uv-cache/uv-cache-dir）

• 工具层：
  提供用于与缓存交互并执行实时搜索的操作命令。

  • update_cache： 如果实时版本有变化，则更新文档缓存。
  • search_documentation： 通过实时查询执行搜索 UV 文档。

• 提示词层：
  提供提示词模板，供 AI 助手生成文档摘要（例如，summarize-docs 提示词）。

组件

资源

通过 uv-docs:// URI 方案访问资源，资源提供完整的文档层级。例如：

• 基础章节：
  uv-docs://cli 返回所有 CLI 命令的列表。

• 命令层级：
  uv-docs://cli/uv-cache 返回 uv cache 命令的元数据，包括可用的文档章节。

• 子章节层级：
  uv-docs://cli/uv-cache/uv-cache-dir 返回“uv cache dir”章节的详细文档内容。

每个资源都会返回包含详细元数据的 JSON 数据，并在请求时提供完整的文档内容。这种细粒度划分使 MCP 客户端和 AI 助手能够只查询所需信息。

工具

可用工具已精简：

1. update_cache
   • 用途： 如果实时版本已更改，则更新文档缓存。
   • 输入：

     {
       "force": false
     }
     

2. search_documentation
   • 用途： 实时搜索 UV 文档。
   • 输入：

     {
       "query": "search query"
     }
     

提示词

此服务提供适用于常见文档任务的预置提示词模板：

• summarize-docs：
  生成 UV 文档章节的摘要。
  可选参数：

  {
    "section": "cli|settings|resolver"
  }
  

  如果未指定章节，则会生成所有章节的摘要。

安装与配置

MCP 服务配置

对于 Claude Desktop 或其他系统，请相应修改 MCP 服务设置：

开发/未发布配置

{
  "mcpServers": {
    "uv-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/steven/Git/MCP/uv-docs",
        "run",
        "uv-docs"
      ]
    }
  }
}

已发布配置

{
  "mcpServers": {
    "uv-docs": {
      "command": "uvx",
      "args": [
        "uv-docs"
      ]
    }
  }
}

调试与检查

如需详细调试，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /Users/steven/Git/MCP/uv-docs run uv-docs

缓存

该服务实现了版本感知缓存系统，以优化文档检索：

• 初始化： 缓存会在启动时自动初始化。
• 版本检查： 将实时文档版本与缓存版本进行比较。
• 分段缓存： 每个文档章节（例如 CLI、设置、解析器）都会单独缓存。
• 手动更新： 必要时使用 update_cache 工具。

开发

项目结构

uv-docs/
├── src/
│   └── uv_docs/
│       ├── __init__.py
│       ├── server.py         # Server setup and routing
│       ├── resources.py      # Resource handling and MCP resource interface
│       ├── cache.py          # Version-aware cache system
│       ├── prompts.py        # Prompt templates for documentation tasks
│       └── tools.py          # Consolidated tool implementations (update_cache, search_documentation)
├── pyproject.toml            # Project configuration
└── README.md                # Project overview (this file)

构建与发布

1. 同步依赖项和锁文件：

   uv sync
   

2. 构建软件包分发文件：

   uv build
   

3. 发布到 PyPI：

   uv publish
   

注意： 通过以下方式设置 PyPI 凭据：

• 令牌：--token 或环境变量 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

为获得最佳调试体验，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /Users/steven/Git/MCP/uv-docs run uv-docs

Inspector 会显示一个用于基于浏览器进行调试的 URL。

缓存

该服务实现了版本感知缓存系统：

• 在服务启动时初始化缓存
• 对照实时文档进行版本检查
• 版本变更时自动更新
• 通过 update_cache 工具手动更新
• 每个文档章节单独缓存