RTFD (Read The F g Docs)

RTFD Logo RTFD（阅读F\*\*\*\*\*\*g文档）MCP服务器

   ](https://www.python.org/downloads/) 

](https://github.com/aserper/rtfd) ](https://github.com/aserper/rtfd/fork)

RTFD（阅读F\*\*\*\*\*\*g文档）MCP服务器充当大型语言模型（LLM）和实时文档之间的桥梁。它允许编码代理查询包存储库，如PyPI、npm、crates.io、GoDocs、DockerHub、GitHub和Google Cloud Platform（GCP），以检索最新的文档和上下文。

此服务器解决了一个常见问题，即LLM会产生API幻觉或提供过时的代码示例，因为它们的训练数据已有数月或数年的历史。通过让代理访问实际文档，RTFD确保生成的代码是准确的，并遵循当前的最佳实践。

⚠️ 安全警告

安全警告：此MCP服务器允许代理访问来自外部源（GitHub、PyPI等）的未经验证的代码和内容。这带来了重大风险，包括 间接快速注射 以及恶意代码执行的可能性，特别是在自主或“YOLO”模式下运行时。 使用风险自负。 维护人员对使用此工具造成的任何损坏或安全隐患不承担任何责任。 您可以通过配置特定的环境变量来限制功能，从而降低这些风险。例如，设置 RTFD_FETCH=false 禁用所有内容获取工具（仅允许元数据查找），以及 VERIFIED_BY_PYPI=true 将Python包文档限制为仅包含经过PyPI验证的源代码。请参阅 配置 有关更多详细信息，请参阅第节。

为什么要使用RTFD？

• 准确度： 代理可以访问库的最新文档，确保他们使用正确的特定于版本的API，并避免使用不推荐的方法。
• 情境感知： 服务器不只是获取原始文本转储，而是提取关键部分，如安装说明、快速启动指南和API引用，从而为代理提供所需的内容。
• 隐私： 与基于云的文档服务不同，RTFD完全在本地计算机上运行。您的查询被直接发送到源（中间没有服务器，不需要API密钥等），您访问的文档永远不会离开您的系统，确保完全的隐私和数据收集。
• 支持的来源： PyPI（Python）、npm（JavaScript/TypeScript）、crates.io（Rust）、GoDocs（Go）、Zig-docs、DockerHub、GitHub容器注册表（GHCR）、GitHub存储库和谷歌云平台（GCP）。

用例

RTFD在以下场景中有所帮助：

• 重构旧代码：获取当前值 pandas 用于查找已弃用方法及其替换的文档。LLM没有猜测发生了什么变化，而是阅读了实际的升级指南。

• 不熟悉的图书馆：集成一个你从未见过的Rust机箱？直接从文档中查找确切的版本、功能标志和示例，而不是从一般模式中猜测API。

• 培训中断后的图书馆：使用LLM训练数据结束后发布的库？从GitHub获取实际的README和代码示例，这样LLM就可以编写正确的用法，而不是产生幻觉的API。

• Docker优化：优化Dockerfile时，请查看官方 python:3.11-slim 图像，以准确查看包含哪些包和操作系统层，而不是做出假设。

• 依赖性审计：检查PyPI、npm和crates.io，了解所有依赖项的可用更新。LLM可以看到最新版本，并且可以生成审计报告，而无需手动访问每个注册表。

Dependency audit example

特性

• 文档内容获取： 从PyPI、npm和GitHub检索实际文档内容（README和关键部分），而不仅仅是URL。
• 智能截面提取： 自动区分优先级并提取相关部分，如“安装”、“使用”和“API参考”，以减少噪音。
• 格式转换： 自动将reStructuredText和HTML转换为Markdown，以实现一致的格式，并使LLM更容易使用。
• 多源搜索： 聚合来自PyPI、npm、crates.io、GoDocs、Zig-docs、DockerHub、GHCR、GitHub和GCP的结果。
• GitHub存储库浏览： 浏览存储库文件树(list_repo_contents, get_repo_tree)并读取源代码文件(get_file_content)直接。
• GitHub软件包（GHCR）： 列出软件包并获取任何GitHub用户或组织的版本，以找到正确的图像标签。
• PyPI验证： 可选安全功能(VERIFIED_BY_PYPI)以确保在获取文档之前由PyPI验证包。
• 智能GCP搜索： 结合本地服务映射的混合搜索方法 cloud.google.com 搜索以查找任何Google Cloud服务的文档。
• 可插拔架构： 通过创建单个提供程序模块，可以轻松添加新的文档提供程序。
• 容错能力： 一个提供程序中的故障不会导致服务器崩溃；该系统被设计为优雅地降级。

安装

Claude代码插件（适用于Claude代码用户）

分两步将RTFD安装为Claude Code插件：

# Step 1: Add the RTFD marketplace
claude plugin marketplace add aserper/RTFD

# Step 2: Install the plugin
claude plugin install rtfd-mcp@rtfd-marketplace

有关详细的配置选项和安装替代方案，请参阅 塞子.md.

来自PyPI（推荐）

pip install rtfd-mcp

或与 uv:

uv pip install rtfd-mcp

来源

克隆存储库并安装：

git clone https://github.com/aserper/RTFD.git
cd RTFD
uv sync --extra dev

Docker（GHCR）

您可以直接从GitHub容器注册表运行RTFD，而无需在本地安装Python或依赖项。

docker run -i --rm \
  -e GITHUB_AUTH=token \
  -e GITHUB_TOKEN=your_token_here \
  ghcr.io/aserper/rtfd:latest

可用标签：

• :latest -稳定版本（新版本更新）
• :edge -开发构建（推送到main的更新）
• :vX.X.X -特定版本标签

快速入门

RTFD是一个MCP服务器，需要在您选择的AI代理中进行配置。

1.安装RTFD

pip install rtfd-mcp
# or with uv:
uv pip install rtfd-mcp

2.配置您的代理

克劳德代码

最简单方法（推荐）： 使用Claude Code插件市场：

# Step 1: Add the RTFD marketplace
claude plugin marketplace add aserper/RTFD

# Step 2: Install the plugin
claude plugin install rtfd-mcp@rtfd-marketplace

替代方法：

使用以下命令手动将RTFD添加为MCP服务器，以自动将其添加到您的配置中：

# Using GITHUB_TOKEN for authentication (default)
claude mcp add rtfd -- command="rtfd" --env GITHUB_AUTH=token --env GITHUB_TOKEN=your_token_here --env RTFD_FETCH=true

# Or using GitHub CLI for authentication
claude mcp add rtfd -- command="rtfd" --env GITHUB_AUTH=cli --env RTFD_FETCH=true

# Or using both methods with fallback
claude mcp add rtfd -- command="rtfd" --env GITHUB_AUTH=auto --env GITHUB_TOKEN=your_token_here --env RTFD_FETCH=true

# Or using Docker
claude mcp add rtfd -- type=docker -- image=ghcr.io/aserper/rtfd:latest --env GITHUB_AUTH=token --env GITHUB_TOKEN=your_token_here

或手动编辑 ~/.claude.json:

{
  "mcpServers": {
    "rtfd": {
      "command": "rtfd",
      "env": {
        "GITHUB_AUTH": "token", // Options: "token", "cli", "auto", or "disabled"
        "GITHUB_TOKEN": "your_token_here",
        "RTFD_FETCH": "true"
      }
    }
  }
}

光标

1. 首选 设置 > 光标设置 > MCP服务器
2. 点击 “添加新的MCP服务器”
3. 姓名： rtfd
4. 类型： stdio
5. 命令： rtfd
6. 添加环境变量： GITHUB_AUTH = token （选项： token, cli, auto, disabled)
7. 添加环境变量： GITHUB_TOKEN = your_token_here
8. 添加环境变量： RTFD_FETCH = true

或手动编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "rtfd": {
      "command": "rtfd",
      "env": {
        "GITHUB_AUTH": "token", // Options: "token", "cli", "auto", or "disabled"
        "GITHUB_TOKEN": "your_token_here",
        "RTFD_FETCH": "true"
      }
    }
  }
}

帆板运动

1. 打开 设置 > 高级设置 > 模型上下文协议
2. 编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "rtfd": {
      "command": "rtfd",
      "env": {
        "GITHUB_AUTH": "token", // Options: "token", "cli", "auto", or "disabled"
        "GITHUB_TOKEN": "your_token_here",
        "RTFD_FETCH": "true"
      }
    }
  }
}

Gemini CLI

编辑 ~/.gemini/settings.json:

{
  "mcpServers": {
    "rtfd": {
      "command": "rtfd",
      "env": {
        "GITHUB_AUTH": "token", // Options: "token", "cli", "auto", or "disabled"
        "GITHUB_TOKEN": "your_token_here",
        "RTFD_FETCH": "true"
      }
    }
  }
}

法典

编辑 ~/.codex/config.toml:

[mcpServers.rtfd]
command = "rtfd"
[mcpServers.rtfd.env]
GITHUB_AUTH = "token" # Options: "token", "cli", "auto", or "disabled"
GITHUB_TOKEN = "your_token_here"
RTFD_FETCH = "true"

3.验证

问你的经纪人： *“你们有什么工具？”* 或 *“搜索有关pandas的文档”*.

MCP检验员测试

MCP检查器工具允许您直接测试RTFD MCP服务器，而不需要IDE或代理集成。这对开发和调试很有用。

安装

# Install the MCP Inspector tool globally
npm install -g @modelcontextprotocol/inspector

用法

# Run RTFD with the MCP Inspector
npx @modelcontextprotocol/inspector rtfd

# If you need to pass environment variables
npx @modelcontextprotocol/inspector rtfd -e GITHUB_AUTH=auto

检查器工具将打开一个交互式终端，您可以在其中直接调用RTFD工具并查看它们的响应。

配置

RTFD可以使用以下环境变量进行配置：

延迟加载的令牌优化

RTFD为多个提供商提供了33个工具。默认情况下，所有工具描述都加载到上下文中，消耗约10-15K令牌。您可以使用 defer_loading 功能。

运作原理

defer_loading 是一个 客户端配置 该标记将工具标记为可发现但最初未加载。当LLM需要延迟工具时，它会按需加载。RTFD提供层分类和配置生成器来帮助您进行配置。

工具层级分类

结果：始终加载2个工具，延迟31个工具（代币减少约93%）

配置生成器CLI

RTFD包括一个CLI工具，用于生成优化的配置：

# Generate Claude Desktop configuration
rtfd-config --format claude-desktop

# Generate with custom defer tiers (e.g., only defer tiers 4-6)
rtfd-config --format claude-desktop --defer-tiers 4,5,6

# View tier summary
rtfd-config --format summary

# List all tools with tier info
rtfd-config --format tools

Claude桌面配置示例

{
  "mcpServers": {
    "rtfd": {
      "command": "uvx",
      "args": ["rtfd-mcp"],
      "type": "mcp_toolset",
      "default_config": {"defer_loading": true},
      "configs": {
        "search_library_docs": {"defer_loading": false},
        "github_repo_search": {"defer_loading": false}
      }
    }
  }
}

此配置使两个最重要的工具始终处于加载状态，同时推迟其他所有操作。

编程式访问

您可以通过编程方式访问层信息：

from RTFD.config_generator import (
    get_all_tools_with_tiers,
    get_tools_by_tier,
    generate_claude_desktop_config,
)

# Get all tools with their tier info
tools = get_all_tools_with_tiers()
print(tools["search_library_docs"])  # {'tier': 1, 'defer_recommended': False, 'category': 'search'}

# Get tools organized by tier
by_tier = get_tools_by_tier()
print(by_tier[1])  # ['github_repo_search', 'search_library_docs']

# Generate config programmatically
config = generate_claude_desktop_config(defer_tiers=[3, 4, 5, 6])

发布和版本控制

对于维护人员，请参阅 贡献.md 用于自动发布过程。

可用工具

所有工具响应均以JSON格式返回。

聚合器

• search_library_docs(library, limit=5)：跨所有提供者（PyPI、npm、crates.io、GoDocs、GCP、GitHub）的组合查找。注意：Zig和DockerHub是通过专用工具访问的。

缓存管理

• get_cache_info()：获取缓存统计信息，包括条目计数、数据库大小和位置。
• get_cache_entries()：获取所有缓存项目的详细信息，包括年龄、大小和内容预览。

文档内容获取

• fetch_pypi_docs(package, max_bytes=20480)：从PyPI获取Python包文档。
• fetch_npm_docs(package, max_bytes=20480)：获取npm包文档。
• fetch_godocs_docs(package, max_bytes=20480)：从godocs.io获取Go包文档（例如“github.com/gorilla/mux”）。
• fetch_gcp_service_docs(service, max_bytes=20480)：从docs.Cloud.Google.com获取谷歌云平台服务文档（例如“存储”、“计算”、“bigquery”）。
• fetch_github_readme(repo, max_bytes=20480)：从GitHub存储库获取README（格式：“owner/repo”）。
• fetch_docker_image_docs(image, max_bytes=20480)：从DockerHub获取Docker镜像文档和描述（例如，“nginx”、“postgres”、“user/image”）。
• fetch_dockerfile(image)：通过解析GitHub链接的描述来获取Docker镜像的Dockerfile（尽最大努力）。

元数据提供程序

• pypi_metadata(package)：获取Python包元数据。
• npm_metadata(package)：获取JavaScript包元数据。
• crates_metadata(crate)：获取Rust crate元数据。
• search_crates(query, limit=5)：搜索Rust板条箱。
• godocs_metadata(package)：检索Go包文档。
• search_gcp_services(query, limit=5)：按名称或关键字搜索谷歌云平台服务（例如，“存储”、“计算”、“大查询”）。
• zig_docs(query)：搜索Zig文档。
• docker_image_metadata(image)：获取DockerHub Docker镜像元数据（星号、pulls、描述等）。
• search_docker_images(query, limit=5)：在DockerHub上搜索Docker镜像。
• github_repo_search(query, limit=5, language="Python")：搜索GitHub存储库。
• github_code_search(query, repo=None, limit=5)：在GitHub上搜索代码。
• list_github_packages(owner, package_type="container")：列出用户或组织的GitHub包。
• get_package_versions(owner, package_type, package_name)：获取特定GitHub包的版本。
• list_repo_contents(repo, path="")：列出GitHub存储库中目录的内容（格式：“owner/repo”）。
• get_file_content(repo, path, max_bytes=102400)：从GitHub存储库获取特定文件的内容。
• get_repo_tree(repo, recursive=False, max_items=1000)：获取GitHub存储库的完整文件树。
• get_commit_diff(repo, base, head)：获取两个提交、分支或标签之间的差异。

LogScale（Humio）查询语言

• search_logscale_docs(query, limit=10)：在LogScale查询语言文档中搜索语法主题、函数和运算符。
• list_logscale_functions(category=None)：按类别（聚合、字符串、数学、正则表达式等）列出LogScale函数，或在未指定类别时列出所有类别。
• logscale_syntax(topic, max_bytes=20480)：获取主题的详细语法文档（过滤器、运算符、字段、正则表达式、时间、宏等）。
• logscale_function(function_name, max_bytes=20480)：获取特定LogScale函数的文档（例如，“regex”、“splitString”、“array:append”）。

提供商特定注意事项

GCP（谷歌云平台）

• 服务发现： 使用本地服务映射（20+公共服务），直接搜索 cloud.google.com （用于一般查询），以及GitHub API搜索googleapis/googleapis存储库。
• 文件来源： 通过抓取docs.cloud.google.com并转换为Markdown来获取文档。
• GitHub身份验证： 使用配置 GITHUB_AUTH 环境变量。选项包括 token （默认）， cli, auto，或 disabled.
• GitHub令牌： 可选，但推荐。没有a GITHUB_TOKEN，GitHub API搜索限制为每小时60个请求。使用令牌后，限制将增加到5000个请求/小时。
• 支持的服务： 云存储、计算引擎、BigQuery、云功能、云运行、发布/订阅、Firestore、GKE、应用引擎、云视觉、云语音、IAM、秘密管理器等。
• 服务名称格式： 接受各种格式（例如，GKE的“存储”、“云存储”、”云存储“、”kubernetes“、”k8s“）。

对数刻度（Humio）

• 文件来源： 从以下位置获取文档 LogScale库.
• 语法主题： 注释、过滤器、运算符、字段、用户输入、条件、数组、表达式、用户函数、函数调用、时间、时区、相对时间、宏、正则表达式、正则表达式语法、正则表达式标志和正则表达式引擎。
• 功能类别： 聚合、数组、比较、条件、数据操作、事件、过滤器、格式化、地理位置、哈希、连接、数学、网络、解析、正则表达式、安全性、统计、字符串、时间日期和小部件。
• 无需身份验证： 所有文件均可公开查阅。

其他供应商

• 令牌计数： 默认情况下禁用。集 RTFD_TRACK_TOKENS=true 查看Claude Code日志中的令牌统计信息。
• 速率限制： crates.io提供程序遵守每秒1个请求的限制。
• 依赖关系： mcp, httpx, beautifulsoup4, markdownify, docutils, tiktoken.

建筑

• 入口点： src/RTFD/server.py 包含主搜索编排工具。特定于提供商的工具 src/RTFD/providers/.
• 框架： 用途 mcp.server.fastmcp.FastMCP 声明工具并通过stdio运行服务器。
• HTTP层： httpx.AsyncClient 与共享 _http_client() 应用超时、重定向和用户代理标头的工厂。
• 数据模型： 响应是简单的字典，便于在MCP上进行序列化。
• 序列化： 工具响应使用 serialize_response_with_meta() 从 utils.py.
• 令牌计数： 可选令牌统计信息 meta 字段（默认情况下禁用）。启用 RTFD_TRACK_TOKENS=true.

序列化和令牌计数

工具响应由以下人员处理 serialize_response_with_meta() 在 utils.py:

• 令牌统计： 当 RTFD_TRACK_TOKENS=true，响应包括 _meta 带有令牌计数的字段(tokens_json, tokens_sent, bytes_json).
• 令牌计数： 用途 tiktoken 图书馆与 cl100k_base 编码（与Claude模型兼容）。
• 零成本元数据： 令牌统计信息显示在 _meta 领域 CallToolResult，这在Claude Code的特殊元数据日志中可见，但不会发送到LLM，花费0个令牌。

令牌高效工具描述

RTFD使用紧凑、结构化的MCP工具描述格式，以最大限度地减少令牌消耗，同时保持语义清晰。如果29个工具暴露在LLM中，详细的描述每次上下文加载将消耗约6000多个令牌。优化后的格式将其减少到约1500个令牌——a 减少75%.

设计原则

1. 简短摘要 -工具功能的一行描述
2. 结构化元数据 - When:, Args:, Ex: 便于解析的格式
3. 内联示例 -具有实际值的紧凑参数示例
4. 交叉引用 - See also: 用于相关工具，而不是冗长的解释
5. 无冗余 -避免描述响应格式（LLM查看实际响应）

示例格式

"""
{One-line summary}. For related usage, see other_tool.

When: {brief condition}
Args: param="example_value", param2=default_value
Ex: tool_name("arg") → brief result description
"""

此格式为LLM提供了以下所需的信息：

• 理解 何时使用该工具
• 呼叫 具有正确参数的工具
• 解释 响应代表什么

有关编写工具描述的指南，请参阅 CONTRIBUTING.md中的工具描述指南.

可扩展性与发展

添加提供商

RTFD服务器使用模块化架构。供应商位于 src/RTFD/providers/ 并实施 BaseProvider 界面。服务器重新启动时，会自动发现并注册新的提供程序。

要添加自定义提供程序，请执行以下操作：

1. 在中创建新文件 src/RTFD/providers/.
2. 定义用以下方式装饰的异步函数 @mcp.tool().
3. 确保工具归还 CallToolResult 使用 serialize_response_with_meta(result_data).

开发笔记

• 依赖关系： 声明于 pyproject.toml （Python 3.10+）。
• 测试： 使用 pytest 运行测试套件。
• 环境： 如果您更改环境敏感设置（例如。， GITHUB_TOKEN)，重新启动 rtfd 过程。