Moxie-Docs-MCP

<p align="center"> <img src="https://moxiedocs.com/moxie-fox.svg" alt="Moxie 文档" width="120" /> <br /> <a href="https://moxiedocs.com">访问 Moxie 文档</a> </p> # Moxie 文档 — MCP 与 Agent 工具 [](https://www.npmjs.com/package/moxie-docs) [](https://smithery.ai/servers/caden/moxie-docs) **Moxie 文档**模型上下文协议（MCP）服务器、Moxie 安装到您的仓库的代理**技能**，以及将所有这些连接起来的 **`moxie-docs` CLI** — `npx moxie-docs setup`。 该仓库也是 **`moxie-docs` npm 包**的开源主页：一个设置 CLI 加上 MCP **接口**（工具目录、提示、服务器元数据和技能渲染器），您可以导入。托管服务器、索引管道和生成的文档保留在私有 Moxie 服务中。 Moxie 文档索引连接的 GitHub 仓库，并保持其文档更新 — 生成文档、发现约定、跟踪文档空白和漂移，并打开拉取请求以保持文档与代码同步。MCP 服务器向编码代理（Claude Code、Cursor、VS Code、Codex 和任何支持 MCP 的客户端）公开该实时上下文，以便他们在工作中依据 *您的* 仓库实际执行的操作 — 并在他们更改代码时保持文档更新。 - **网站 / 控制台：** https://moxiedocs.com - **MCP 服务器的人类文档：** https://moxiedocs.com/mcp - **MCP 端点：** `https://moxiedocs.com/api/mcp` 该仓库仅包含文档和分发资产。托管服务器、索引管道和您的仓库文档不存储在此处。 --- ## 目录 - [快速开始](#快速开始) - [CLI](#cli) - [MCP 服务器](#mcp-服务器) - [连接](#连接) - [身份验证](#身份验证) - [客户端配置](#客户端配置) - [工具](#工具) - [提示](#提示) - [技能](#技能) - [`moxie-docs` 技能](#moxie-docs-技能) - [Moxie 安装到您的仓库](#moxie-安装到您的仓库) - [用作库](#用作库) - [查找服务器](#查找服务器) - [发现端点](#发现端点) - [许可证](#许可证) --- ## 快速开始 从您的仓库目录开始的最快方式： ```bash npx moxie-docs setup ``` 这会为您登录（浏览器中的 OAuth）、编写编辑器的 MCP 配置、安装 `moxie-docs` 技能 + `AGENTS.md` 指南，并验证连接。之后，您的代理在编辑之前会读取实时上下文 `moxie.get_ai_context`，并提出文档更新，这些更新会落在同一个 PR 中。 您更喜欢手动操作吗？在 https://moxiedocs.com 上连接一个仓库，然后使用配置块将服务器添加到您的代理中。 --- ## CLI `moxie-docs` CLI（Node ≥ 18，无运行时依赖）设置和管理连接。运行它时使用 `npx moxie-docs <command>` 或全局安装 (`npm i -g moxie-docs`)。 | 命令 | 执行操作 | | --- | --- | | `moxie-docs setup` | 端到端：登录、配置您的 MCP 客户端、安装技能 + `AGENTS.md` 块并进行烟雾测试。 | | `moxie-docs login` | 通过浏览器（OAuth 2.1 + PKCE）登录并将凭证存储在 `~/.moxie-docs/` 中。 | | `moxie-docs status` | 显示您的作用域、连接的仓库和可用的工具数量。 | | `moxie-docs config <client>` | 将 `moxie-docs` 服务器条目写入客户端配置（`claude-code`、`cursor` 或 `vscode`）。 | | `moxie-docs install-skill` | 在当前仓库中安装 `moxie-docs` 技能和 `AGENTS.md` 指南。 | | `moxie-docs logout` | 删除存储的凭证。 | 有用的标志： `--client <name>`、 `--token <dashboard-token>`、 `--repo owner/name`、 `--no-browser`、 `--yes`。 **身份验证如何编写。** 默认情况下，`setup`/`config` 编写一个 **仅限 URL** 的服务器条目，并让您的编辑器在首次使用时执行自己的 OAuth 登录 — 因此您提交的配置中没有任何内容过期。CLI 的浏览器登录（用于 `status` 和设置烟雾测试）存储一个短期令牌和一个刷新令牌在 `~/.moxie-docs/` 下（文件模式 `0600`）；它 **从不** 编写到客户端配置中。如果您想固定一个静态的 `Authorization` 头，请使用 `--token` 传递一个长寿命的仪表板令牌，CLI 将其写入。CLI 从不记录令牌值，并且如果它无法安全解析客户端配置，则拒绝覆盖它。 --- ## MCP 服务器 ### 连接 | | | | --- | --- | | **传输** | 可流式 HTTP MCP | | **端点** | `https://moxiedocs.com/api/mcp` | | **协议版本** | `2025-06-18` | | **仓库选择** | 工具接受一个可选的 `repository` 参数（`owner/name`，例如 `acme/app`）。仅当令牌服务多个仓库且没有单一的默认应用时，才需要它。匹配不区分大小写。 | 所有写入工具都是 **提议** — Moxie 返回文件路径和内容，供您（代理）写入到您自己的分支中。Moxie 永远不会直接通过 MCP 编辑您的仓库，永远不会合并。读取返回紧凑的、基于引用的上下文，而不是原始代码转储。 ### 身份验证 **Bearer 令牌（今日可用）。** 在仪表板上创建令牌并将其作为头部发送： ``` Authorization: Bearer <MOXIE_TOKEN> ``` Moxie 只存储令牌哈希（以及加密副本，以便您能够揭示它）、前缀、作用域和上次使用时间戳。您可以在任何时候从仪表板上揭示、轮换或撤销令牌。 **OAuth 2.1 登录（适用于支持它的客户端）。** 实现 OAuth 授权流的 MCP 客户端可以通过浏览器登录而不是粘贴令牌 — 客户端发现服务器的 OAuth 元数据、动态注册自身（RFC 7591）并通过授权码 + PKCE 流获得令牌。发现文档： - 受保护的资源元数据： `https://moxiedocs.com/.well-known/oauth-protected-resource` - 授权服务器元数据： `https://moxiedocs.com/.well-known/oauth-authorization-server` 两种身份验证路径都解析为相同的令牌模型，因此任一方法都适用于相同的工具。连接的应用程序可以从仪表板审查和撤销。 ### 客户端配置 大多数代理接受带有 URL 和头部的远程 MCP 服务器。用仪表板上的令牌替换 `<MOXIE_TOKEN>`。 **Claude Code** — `.mcp.json`（或 `claude mcp add`）： ```json { "mcpServers": { "moxie-docs": { "url": "https://moxiedocs.com/api/mcp", "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" } } } } ``` **Cursor** — `.cursor/mcp.json`： ```json { "mcpServers": { "moxie-docs": { "url": "https://moxiedocs.com/api/mcp", "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" } } } } ``` **VS Code** — `.vscode/mcp.json`： ```json { "servers": { "moxie-docs": { "type": "http", "url": "https://moxiedocs.com/api/mcp", "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" } } } } ``` > 将令牌排除在源代码控制之外。在客户端支持的情况下，引用环境变量或仅将令牌粘贴到本地、未跟踪的配置中。 ### 工具 所有工具均为只读工具，除了两个 `propose_*` 工具，它们返回一个提议，供代理应用于其自己的分支。 | 工具 | 用途 | | --- | --- | | `moxie.get_ai_context` | 紧凑的编辑前简报：仓库状态、已验证命令、顶级约定、开放空白、团队笔记。先阅读此内容。 | | `moxie.get_doc_impact` | 给定您即将更改的路径（以及您正在删除的路径），返回约定、空白和现有文档的证据重叠 — 并标记新的/未记录的表面。 | | `moxie.get_conventions` | 按类别分组的已发现编码约定，具有置信度评分、代理指导和源文件引用。 | | `moxie.search_docs` | 对生成的文档、约定、空白和 AI 上下文进行语义和关键字搜索。 | | `moxie.get_doc_gaps` | 未解决的文档空白，具有严重性和相关路径。 | | `moxie.get_documentation_opportunities` | 推荐的文档工作：缺少的文档、漂移修复和 PR 模板。 | | `moxie.get_documentation_patterns` | 仓库如何组织和维护其文档（新文档属于哪里）。 | | `moxie.list_docs` | 每份生成文档的分页、按章节分组的目录。 | | `moxie.propose_doc_update` | 在当前更改中添加或更新文档；返回目标路径 + Markdown 以写入您的分支。 | | `moxie.propose_doc_removal` | 删除更改使过时的 Moxie 跟踪文档；返回要在您的分支中删除的路径。 | ### 提示 服务器还公开 MCP 提示，脚本化常见工作流： | 提示 | 用途 | | --- | --- | | `document-this-change` | 对更改的路径运行文档影响检查，并引导您提出文档更新，以便它们落在同一个 PR 中。 | | `fix-stale-docs` | 查找仓库的开放文档空白和漂移机会，并通过 Moxie 修复它们。 | --- ## 技能 [代理技能](https://github.com/cloudflare/agent-skills-discovery-rfc) 是小型触发指令文件，用于教导代理 **何时** 和 **如何** 使用功能。Moxie 发布一项技能 `moxie-docs`，它将代理连接到编辑-然后-文档工作流。 ### `moxie-docs` 技能 规范技能位于此仓库中的 [`skills/moxie-docs/SKILL.md`](skills/moxie-docs/SKILL.md)，也从网站（带有已发布的 SHA-256 摘要）提供： ``` https://moxiedocs.com/.well-known/agent-skills/moxie-docs/SKILL.md ``` 它告诉代理在编辑之前读取实时上下文（`get_ai_context`、`get_doc_impact`），遵循仓库的实际约定和已验证命令，并提出文档更新/删除，这些更新/删除会落在 **同一个 PR** 中 — 永远不会发明填充文档。 ### Moxie 安装到您的仓库 当 Moxie 连接仓库时，它会打开一个 **"添加 Moxie 代理指导"** PR，添加三个自我修复、确定性文件（仅在它们漂移或仓库重命名时重新生成 — 绝不因每次索引而更改）： | 文件 | 用途 | | --- | --- | | `AGENTS.md` | 一个简短的、始终开启的指针块（在 `<!-- moxie-docs:start -->` / `<!-- moxie-docs:end -->` 标记之间），告诉任何代理使用 MCP 服务器和 `moxie-docs` 技能。人类添加的内容在标记之外被保留。参见 [`templates/AGENTS.md`](templates/AGENTS.md)。 | | `.claude/skills/moxie-docs/SKILL.md` | 用于 Claude Code 的仓库特定 `moxie-docs` 技能。 | | `.agents/skills/moxie-docs/SKILL.md` | 适用于 `.agents` 感知客户端的相同技能。 | 安装的技能是仓库特定的 [`skills/moxie-docs/SKILL.md`](skills/moxie-docs/SKILL.md) 变体：相同的流程，具有您的 `owner/name` 嵌入，以便多仓库令牌定位到正确的仓库。Moxie 编写的每个内容都是确定性的，不包含易逝的数据 — 实时约定和命令始终来自 MCP 服务器，而不是提交的文件。 --- ## 用作库 该包还导出了开放源代码的 MCP **接口** — 独立于后端的合约 — 因此您可以针对 Moxie 构建工具，而无需依赖私有服务器。它不携带秘密，也没有服务器逻辑。 ```ts import { moxieMcpTools, // 工具目录（名称、描述、输入模式、注释） moxieMcpPrompts, // document-this-change / fix-stale-docs 提示描述符 moxieMcpServerInfo, // { name, version } moxieMcpProtocolVersion, // "2025-06-18" moxieMcpCapabilities, buildMoxieMcpServerCard, // 完整的 /.well-known/mcp/server-card.json 文档 moxieMcpServerCard, // 规范服务器卡（包括工具 + 提示） moxieMcpPublicMethods, // ["initialize", "tools/list", "prompts/list"] renderSkillMarkdown, // ({ repository }) => 仓库的 moxie-docs SKILL.md renderAgentsGuidanceBlock,// ({ repository }) => AGENTS.md 指导块 moxieDocsSkillMarkdown, // 规范发布的技能，作为字符串 MOXIE_MCP_ENDPOINT, // "https://moxiedocs.com/api/mcp" MOXIE_SITE_URL, } from "moxie-docs"; ``` 它 **不包括**：工具处理程序、索引/文档生成管道、AI/向量搜索、数据库层或令牌存储 — 这些仍保留在托管的 Moxie 服务中。 --- ## 查找服务器 Moxie 文档在 MCP 客户端和目录下以以下名称列出： | 位置 | 标识符 / 链接 | | --- | --- | | **官方 MCP 注册表** | [`io.github.Jackalope-Dev/moxie-docs`](https://registry.modelcontextprotocol.io/) — 搜索 `moxie-docs` | | **Smithery** | [smithery.ai/servers/caden/moxie-docs](https://smithery.ai/servers/caden/moxie-docs) （上面的徽章） | | **npm CLI** | [`moxie-docs`](https://www.npmjs.com/package/moxie-docs) — `npx moxie-docs setup` | 托管端点的机器可读注册表元数据位于此仓库中的 [`server.json`](server.json)。 ## 发现端点 Moxie 公开了一个小的机器可发现的表面，以便代理和爬虫可以找到服务器： | 端点 | 提供内容 | | --- | --- | | `/.well-known/mcp/server-card.json` | MCP 服务器卡：`serverInfo`、协议版本、传输、功能、完整的 `tools`/`prompts` 目录和 `publicMethods`（未经身份验证的列表）。 | | `/.well-known/api-catalog` | RFC 9727 目录，链接到服务器卡和人类文档。 | | `/.well-known/agent-skills/index.json` | 代理技能发现索引（技能 + SHA-256 摘要）。 | | `/.well-known/agent-skills/moxie-docs/SKILL.md` | 公布的 `moxie-docs` 技能。 | | `/.well-known/oauth-protected-resource` | OAuth 受保护资源元数据（RFC 9728）。 | | `/.well-known/oauth-authorization-server` | OAuth 授权服务器元数据（RFC 8414）。 | --- ## 许可证 [MIT](LICENSE) © Jackalope Dev. 此仓库的内容（文档、技能文件和模板）是开源的。托管的 Moxie 文档服务、索引管道和生成的文档不是此仓库的一部分。