UV 文档 MCP 服务器

这是一个提供通过标准化API访问UV文档的MCP服务器。该服务器现在利用现代分层资源结构，将高层次文档部分和详细命令文档（包括子部分）作为单独的MCP资源进行暴露。工具已经简化，许多文档查询通过资源层处理。

链接

• UV 文档
• MCP Python SDK

快速开始

1. 需求：
   确保安装了Python 3.13+（最低版本3.10以兼容MCP SDK）。

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   # 在Windows上使用：env\\Scripts\\activate
   pip install -e .
   

4. 运行服务器：

   uv run uv-docs
   

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

架构

服务器采用模块化和分层设计，明确分离关注点：

flowchart TD
    客户端[MCP 客户端] --> 服务器[服务器层]
    服务器 --> 资源[资源层]
    服务器 --> 工具[工具层]
    服务器 --> 提示[提示层]
    
    资源 --> 缓存[缓存系统]
    工具 --> 缓存

• 资源层：
  通过带有方案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）

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

  • 更新缓存： 如果实时版本有变化，则更新文档缓存。
  • 搜索文档： 使用实时查询执行搜索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. 更新缓存
   • 目的： 如果实时版本发生变化，则更新文档缓存。
   • 输入：

     {
       "force": false
     }
     

2. 搜索文档
   • 目的： 对UV文档执行实时搜索。
   • 输入：

     {
       "query": "搜索查询"
     }
     

提示

服务器提供了预构建的提示模板，用于常见的文档任务：

• 总结文档：
  创建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 检查器：

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         # 服务器设置和路由
│       ├── resources.py      # 资源处理和MCP资源接口
│       ├── cache.py          # 版本感知的缓存系统
│       ├── prompts.py        # 文档任务的提示模板
│       └── tools.py          # 工具的整合实现（update_cache, search_documentation）
├── pyproject.toml            # 项目配置
└── README.md                # 项目概述（此文件）

构建与发布

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

   uv sync
   

2. 构建包分布：

   uv build
   

3. 发布到PyPI：

   uv publish
   

注意： 设置PyPI凭证通过：

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

调试

为了最佳的调试体验，使用MCP 检查器：

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

检查器将显示一个基于浏览器的调试URL。

缓存

服务器实现了一个版本感知的缓存系统：

• 缓存在服务器启动时初始化
• 与实时文档进行版本检查
• 当版本更改时自动更新
• 通过update_cache工具手动更新
• 每个文档部分分别缓存