FixYourDocs

@fixyourdocs/mcp-server

Model Context Protocol（MCP）服务，提供单个工具 — file_doc_feedback — 让任何 MCP 客户端（Claude Desktop、Cursor、Codex、 Gemini CLI，等等）在遇到损坏、错误、过时、缺失、不清晰或 其他无用的文档时，向 FixYourDocs 中心 hub.fixyourdocs.io 提交 结构化的文档反馈报告。

如果文档所有者安装了 FixYourDocs 集成，报告会转发为其仓库中的 GitHub Issue。不回传数据，也不进行遥测 — 只有在 Agent 明确调用工具时，服务才会联系中心。

• 文档： docs.fixyourdocs.io/mcp/
• 规范： Docs Feedback Protocol v0
• SDK： @fixyourdocs/sdk
• 问题 / 贡献： https://github.com/fixyourdocs/fixyourdocs

安装

该服务设计为通过 npx 运行，因此通常无需直接安装 — MCP 客户端会按需启动它：

npx -y @fixyourdocs/mcp-server

它使用标准的 MCP stdio 传输。除非你想指定其他中心，否则无需配置（参见下文的环境变量）。

客户端配置

每种 MCP 客户端都有自己的配置文件，但格式相同：包含 command + args 的命名服务条目。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "fixyourdocs": {
      "command": "npx",
      "args": ["-y", "@fixyourdocs/mcp-server"]
    }
  }
}

重启 Claude Desktop。工具列表中应该会出现 file_doc_feedback 工具。

Cursor

编辑 ~/.cursor/mcp.json（或工作区中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "fixyourdocs": {
      "command": "npx",
      "args": ["-y", "@fixyourdocs/mcp-server"]
    }
  }
}

Codex / OpenAI Codex CLI

编辑 ~/.codex/config.toml：

[mcp_servers.fixyourdocs]
command = "npx"
args = ["-y", "@fixyourdocs/mcp-server"]

mcp-inspector（用于验证）

npx @modelcontextprotocol/inspector npx -y @fixyourdocs/mcp-server

检查器 UI 会列出 file_doc_feedback，接受示例报告，并显示中心返回的 { id }。

工具：file_doc_feedback

输入

与 v0 规范中的 Report 信封格式一致：

字段	类型	必填	说明
doc_url	字符串	是	出现问题的文档页面 URL。最多 2048 个字符。
agent.name	字符串	是	小写 kebab-case 标识符，例如 claude-code、cursor、codex。最多 64 个字符。
agent.version	字符串	否	可选的 Agent 版本字符串。
agent.vendor	字符串	否	可选的供应商 / 发布者，例如 Anthropic。
report.kind	枚举	是	以下之一：broken、incorrect、outdated、missing、unclear、other。
report.summary	字符串	是	单行描述，≤ 280 个字符。
report.details	字符串	否	可选的详细描述。≤ 8000 个字符。
report.suggested_fix	字符串	否	可选的具体建议。≤ 4000 个字符。

输出

{
  "id": "01ABCDEF0123456789ABCDEFGH"
}

id 是中心返回的 ULID — 用于确认幂等性的标识符，不是可用于获取内容的句柄。公共 API 上的报告仅支持写入：没有检索端点，报告内容只能通过中心转发至 GitHub Issue 后传达给文档所有者。

行为

• MCP 服务会先根据 v0 词法约束验证输入（URL 解析、Agent 名称模式、摘要长度），然后再联系中枢。验证错误会以 MCP isError: true 结果返回，并附带人类可读的说明。
• 对于 201 Created（新提交）或 200 OK（幂等重复提交），工具都会返回 { id }——Agent 无需区分两者，中枢不会重复创建问题。
• 对于 429 rate_limited、5xx 或任何网络错误，工具会原样呈现错误。客户端应将此类错误视为暂时性错误，并使用相同的负载重试（中枢会根据正文内容去重）。

环境变量

变量	默认值	用途
FIXYOURDOCS_HUB_URL	https://hub.fixyourdocs.io	覆盖中枢基础 URL。适用于测试／自托管。

隐私

• 无遥测，不会向外发送数据。 仅当 Agent 显式调用工具时，服务才会发起出站网络请求。不会发送分析数据、版本检查 ping 或诊断信息。
• 报告负载仅包含 Agent 提供的字段（文档 URL、Agent 身份、类型、摘要、可选的详细信息和建议修复方案）。不会附加进程环境、文件路径或系统标识符。

许可证

Apache-2.0。参见 LICENSE。