Moxie Docs

访问 Moxie Docs

Moxie Docs — MCP 与 Agent 工具

Moxie Docs 的模型上下文协议（MCP）服务、Moxie Docs 安装到你仓库中的 Agent 技能，以及将这些功能整合起来的 moxie-docs 命令行工具——npx moxie-docs setup。

本仓库也是 moxie-docs npm 包的开源所在地：一个设置命令行工具，以及可供导入的 MCP 接口（工具目录、提示词、服务元数据和技能渲染器）。托管服务、索引流水线和生成的文档仍保留在私有的 Moxie Docs 服务中。

Moxie Docs 会为已连接的 GitHub 仓库建立索引并持续维护其文档——生成文档、发现惯例、跟踪文档缺失和偏差，并创建拉取请求，让文档与代码保持同步。MCP 服务会向编码 Agent（Claude Code、Cursor、VS Code、Codex，以及任何支持 MCP 的客户端）提供这些实时上下文，让它们的工作以你的仓库实际做法为依据，并在代码变更时及时更新文档。

• 网站 / 仪表板： https://moxiedocs.com
• MCP 服务的用户文档： https://moxiedocs.com/mcp
• MCP 端点： https://moxiedocs.com/api/mcp

本仓库仅包含文档和分发资源。托管服务、索引流水线以及你各个仓库的文档均不存储于此。

---

目录

• 快速开始
• 命令行工具
• MCP 服务
  • 连接
  • 身份验证
  • 客户端配置
  • 工具
  • 提示词
• Claude 插件
• 技能
  • moxie-docs 技能
  • Moxie Docs 安装到你仓库中的内容
• 作为库使用
• 查找服务
• 发现端点
• 许可证

---

快速开始

最快的方式——在你的仓库目录中运行：

npx moxie-docs setup

此命令会让你登录（在浏览器中进行 OAuth），为编辑器写入 MCP 配置，安装 moxie-docs 技能和 AGENTS.md 指南，并验证连接。之后，你的 Agent 会在编辑前通过 moxie.get_ai_context 读取实时上下文，并提出文档更新建议，这些更新会进入同一个 PR。

想手动操作？先在 https://moxiedocs.com 连接一个仓库，然后通过配置块将服务添加到你的 Agent。

---

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 服务。

---

MCP 服务

连接

传输方式	Streamable HTTP MCP
端点	https://moxiedocs.com/api/mcp
协议版本	2025-06-18
代码仓库选择	工具接受可选的 repository 参数（owner/name，例如 acme/app）。只有当令牌适用于多个代码仓库且没有单一默认值时，才必须提供此参数。匹配不区分大小写。

所有写入工具都只会生成提案——Moxie Docs 会返回文件路径和内容，供你（Agent）写入自己的分支。Moxie Docs 绝不会通过 MCP 直接编辑你的代码仓库，也不会进行合并。读取操作返回精简且附带引用的上下文，而不是原始代码转储。

认证

Bearer 令牌（现已提供）。 在控制面板中创建令牌，并将其作为标头发送：

Authorization: Bearer <MOXIE_TOKEN>

Moxie Docs 仅存储令牌哈希（另加一份加密副本，以便你查看令牌）、前缀、访问范围和上次使用时间戳。你可以随时在控制面板中查看、轮换或撤销令牌。

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

这两种认证方式都映射到相同的令牌模型，因此都可以使用相同的工具。你可以在控制面板中查看和撤销已连接的应用程序。

客户端配置

大多数 Agent 都支持通过 URL 和标头连接远程 MCP 服务。将 <MOXIE_TOKEN> 替换为控制面板中的令牌。

Claude Code — .mcp.json（或 claude mcp add）：

{
  "mcpServers": {
    "moxie-docs": {
      "url": "https://moxiedocs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <MOXIE_TOKEN>"
      }
    }
  }
}

Cursor — .cursor/mcp.json：

{
  "mcpServers": {
    "moxie-docs": {
      "url": "https://moxiedocs.com/api/mcp",
      "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" }
    }
  }
}

VS Code — .vscode/mcp.json：

{
  "servers": {
    "moxie-docs": {
      "type": "http",
      "url": "https://moxiedocs.com/api/mcp",
      "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" }
    }
  }
}

不要将令牌纳入源代码管理。如果客户端支持，请引用环境变量；否则，只将令牌粘贴到本地且未跟踪的配置中。

工具

• moxie.get_ai_context：编辑前的精简简报：仓库状态、已验证的命令、主要约定、待解决的问题和团队备注。请先阅读。
• moxie.get_doc_impact：根据你即将修改（以及删除）的路径，返回与这些路径的证据重叠的约定、问题和现有文档。
• moxie.get_api_context：根据你即将接触的路径，返回这些路径对应的 API 端点的结构化上下文：方法、路径、架构和已知使用方。
• moxie.review_change：打开 PR 前对更改进行自我审查；返回按严重程度排序的约定违规、过时文档、未记录的功能表面和失效引用列表。
• moxie.get_conventions：发现的编码约定，按类别分组，并附带置信度评分、Agent 指引和源文件引用。
• 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 Docs 跟踪文档；返回要在分支中删除的路径。

工具	用途
moxie.get_ai_context	编辑前的精简简报：仓库状态、已验证的命令、主要约定、待解决的问题和团队备注。请先阅读。
moxie.get_doc_impact	根据你即将修改（以及删除）的路径，返回与这些路径的证据重叠的约定、问题和现有文档，并标记全新或未记录的功能表面。
moxie.get_api_context	根据你即将接触的路径，返回这些路径对应的 API 端点的结构化上下文：方法、路径、架构和已知使用方／功能。
moxie.review_change	打开 PR 前对更改进行自我审查；返回按严重程度排序的评估（干净／有警告／必须修复），涵盖约定违规、过时文档、未记录的功能表面和失效引用。
moxie.get_conventions	发现的编码约定，按类别分组，并附带置信度评分、Agent 指引和源文件引用。
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 Docs 跟踪文档；返回要在分支中删除的路径。

提示词

该服务还提供 MCP 提示词，用于编排常见工作流：

提示词	用途
document-this-change	对已更改的路径执行文档影响检查，并引导你提出文档更新建议，使其与代码更改一并进入同一个 PR。
fix-stale-docs	查找仓库中尚未解决的文档缺口和内容偏差问题，并通过 Moxie Docs 进行修复。
review-before-finalize	在打开 PR 前，使用 Moxie Docs 的防护机制检查差异，以发现约定违规、过时文档、未记录的功能表面和失效引用。

---

Claude 插件

对于 Claude Code 和 Claude Cowork，此仓库同时也是一个插件市场——只需一条命令，就能同时添加 Moxie Docs 连接器和技能。此插件包含：

• moxie-docs MCP 服务（上文的远程端点），已配置为让客户端在首次使用时自行进行 OAuth 登录——无需粘贴或提交令牌；以及
• moxie-docs 技能，让编辑后记录文档的工作流在安装插件后立即可用。

在 Claude Code（或 Cowork）中安装：

/plugin marketplace add Jackalope-Dev/Moxie-Docs-MCP
/plugin install moxie-docs@moxie-docs

第一条命令会将此仓库注册为插件市场；第二条命令会从中安装 moxie-docs 插件。首次使用 Moxie Docs 工具时，客户端会打开浏览器进行登录，然后即可使用上文的工具和提示词。之后可使用 /plugin marketplace update moxie-docs 更新，使用 /plugin uninstall moxie-docs@moxie-docs 卸载。

更偏好静态令牌，或使用不支持插件的客户端？请改用客户端配置代码块或 CLI——插件、CLI 和手动编写的配置最终都会指向同一服务，并采用相同的身份验证模型。

插件清单位于 .claude-plugin/，服务入口位于 .mcp.json。

---

技能

Agent Skills 是一些小型的触发式指令文件，用于教会 Agent 何时以及如何使用某项能力。Moxie Docs 发布了一项名为 moxie-docs 的技能，可将 Agent 接入编辑后记录文档的工作流。

moxie-docs 技能

规范版技能位于此仓库的 skills/moxie-docs/SKILL.md，也可从网站获取（附有已发布的 SHA-256 摘要）：

https://moxiedocs.com/.well-known/agent-skills/moxie-docs/SKILL.md

它会指示 Agent 在编辑前读取实时上下文（get_ai_context、get_doc_impact），遵循仓库实际采用的约定和已验证的命令，并提议更新或移除文档，使其与代码更改在同一个 PR 中提交——绝不编造凑数的文档。

Moxie Docs 会在你的仓库中安装什么

Moxie Docs 连接到仓库时，会创建一个 “添加 Moxie Docs Agent 指引” PR，其中包含三个可自我修复、确定性的文件（仅在内容发生偏差或仓库重命名时重新生成，不会在每次索引时反复变动）：

文件	用途
AGENTS.md	简短的常驻指引块（位于 / 标记之间），告知任何 Agent 使用 MCP 服务和 moxie-docs 技能。标记以外由人工添加的内容会予以保留。参见 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 的仓库专属版本：工作流完全相同，并内置你的 owner/name，以便多仓库令牌能指向正确的仓库。Moxie Docs 写入的所有内容都是确定性的，不包含易变数据——实时约定和命令始终来自 MCP 服务，而非已提交的文件。

---

Cursor 规则

Moxie Docs 为 Cursor AI Agent 模式发布原生 Cursor 规则文件（.mdc）。规范版规则位于此仓库的 rules/moxie-docs.mdc，可添加到你的仓库中的 .cursor/rules/moxie-docs.mdc，也可通过 cursor.directory 导入。

---

用作库

此包还导出了开源 MCP 接口——与后端无关的契约——因此你可以基于 Moxie Docs 构建工具，而无需依赖私有服务。它不包含任何机密信息或服务端逻辑。

import {
  moxieMcpTools,            // the tool catalog (names, descriptions, input schemas, annotations)
  moxieMcpPrompts,          // the document-this-change / fix-stale-docs prompt descriptors
  moxieMcpServerInfo,       // { name, version }
  moxieMcpProtocolVersion,  // "2025-06-18"
  moxieMcpCapabilities,
  buildMoxieMcpServerCard,  // full /.well-known/mcp/server-card.json document
  moxieMcpServerCard,       // canonical server card (tools + prompts included)
  moxieMcpPublicMethods,    // ["initialize", "tools/list", "prompts/list", "resources/list", "resources/read"]
  renderSkillMarkdown,      // ({ repository }) => the moxie-docs SKILL.md for a repo
  renderAgentsGuidanceBlock,// ({ repository }) => the AGENTS.md guidance block
  moxieDocsSkillMarkdown,   // the canonical published skill, as a string
  MOXIE_MCP_ENDPOINT,       // "https://moxiedocs.com/api/mcp"
  MOXIE_SITE_URL,
} from "moxie-docs";

它不包含：工具处理程序、索引／文档生成流水线、AI／向量搜索、数据库层或令牌存储——这些仍由托管的 Moxie Docs 服务提供。

---

查找服务

Moxie Docs 在 MCP 客户端和目录中的名称如下：

位置	标识符／链接
官方 MCP 注册表	io.github.Jackalope-Dev/moxie-docs — 搜索 moxie-docs
Smithery	smithery.ai/servers/jackalope-digital/moxie-docs（徽章见上方）
Glama	glama.ai/mcp/servers/Jackalope-Dev/Moxie-Docs-MCP
LobeHub Marketplace	lobehub.com/mcp/jackalope-dev-moxie-docs-mcp
npm CLI	moxie-docs — npx moxie-docs setup

此仓库中的 server.json 包含托管端点的机器可读注册表元数据。

发现端点

Moxie Docs 提供了一组小型机器可发现接口，方便 Agent 和爬虫找到该服务：

端点	提供的内容
/.well-known/mcp/server-card.json	MCP 服务卡片：serverInfo、协议版本、传输方式、功能、完整的 tools／prompts 目录，以及 publicMethods（未经身份验证的列表）。
/.well-known/api-catalog	RFC 9727 目录，链接到服务卡片和面向用户的文档。
/.well-known/agent-skills/index.json	Agent Skills 发现索引（技能及 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 © Jackalope Dev。此仓库中的内容（文档、技能文件和模板）均为开源内容。托管的 Moxie Docs 服务、索引流水线和生成的文档不属于此仓库。