将 Mintlify 用作代码库的知识图谱

代码库知识图谱是一个描述你代码的 Mintlify 项目：每个仓库做什么、对外暴露什么，以及各仓库之间如何相互依赖。Agent 在修改代码之前会通过 MCP 查询它。你不需要已有的文档，也不需要迁移。设置只需三步：

使用 Mintlify agent 或你自己的编码 agent 生成初始知识图谱。
设置自动化以保持其最新。
通过 MCP 使用知识图谱。

本页示例中的仓库、pull request 和回答均为示例数据。

先决条件

一个已连接到 Git 仓库的 Mintlify 项目。这个中心（hub）仓库用于存放知识图谱，初始时可以为空。请参见快速开始。
在中心仓库以及你想要编写文档的每个源仓库上安装 Mintlify GitHub 应用。
使用自定义自动化需要 Enterprise 计划。
Mintlify agent，或 Claude Code、Codex、Cursor 等编码 agent。

若要将知识图谱设为私有，请设置身份验证。之后，搜索 MCP 服务器会要求每位用户登录。

规划结构

将所有仓库放在同一个中心项目中，这样 agent 只需查询一个 MCP 服务器，页面也可以跨仓库互相链接。为每个仓库设置单独的分组，并另设一个概览部分。

docs.json

{
  "navigation": {
    "groups": [
      {
        "group": "Overview",
        "pages": ["index", "architecture", "glossary"]
      },
      {
        "group": "Web app",
        "pages": ["repos/web-app/index", "repos/web-app/local-development", "repos/web-app/routing"]
      },
      {
        "group": "API service",
        "pages": ["repos/api-service/index", "repos/api-service/endpoints", "repos/api-service/data-model"]
      },
      {
        "group": "API gateway",
        "pages": ["repos/api-gateway/index", "repos/api-gateway/auth"]
      }
    ]
  }
}

每个仓库部分都应涵盖 agent 在修改代码前需要了解的内容：该仓库做什么、由谁负责、对外暴露的端点或事件、它调用了什么以及被什么调用、关键数据模型，以及如何运行和测试它。先从几个有代表性的仓库开始，例如一个前端、一个后端和一个共享服务，然后再添加其余仓库。

第 1 步：生成初始知识图谱

让 agent 阅读你的源代码，并将第一批页面写入中心仓库。你可以使用 Mintlify agent，也可以克隆仓库并运行你自己的编码 agent。

Mintlify agent
克隆并推送

Mintlify agent 可以读取任何已安装 Mintlify GitHub 应用的仓库，因此你无需克隆任何内容。

连接你的源仓库

在你想要编写文档的每个源仓库上安装 Mintlify GitHub 应用。请参见将仓库连接为上下文。

为一个仓库生成文档

在你的控制台或 Slack 中打开 agent，并指明源仓库、目标文件夹以及要编写的页面。

Example prompt

Read the source code in the your-org/api-service repository and write
documentation for it in repos/api-service/.

Create these pages:
- index.mdx: what the service does, who owns it, and how it fits into the
  rest of the system
- endpoints.mdx: every HTTP endpoint with method, path, parameters, and
  response shape, based on the route definitions
- data-model.mdx: the main models and database tables
- local-development.mdx: how to install, run, and test the service

For each page, list the other repositories this service calls or is called
by, and link to their pages under repos/.

Only document what you can confirm from the code. If something is unclear,
leave a TODO comment instead of guessing.

Add the new pages to docs.json in a group named "API service".

Agent 会在中心仓库中打开一个 pull request。审查它，并修正 agent 弄错的任何内容。

对每个仓库重复此操作

对你的其他仓库重复此操作，然后让 agent 编写概览页面。

Example prompt

Read every page under repos/ and write architecture.mdx. Describe how the
repositories depend on each other, which services call which, and how a
request moves through the system. Link to the repository pages for details.

合并 pull request

Pull request 合并后，Mintlify 会部署知识图谱，并为搜索和 MCP 建立索引。

在本地克隆上运行 Claude Code、Codex 或 Cursor，然后将页面推送到中心仓库。

设置你的编码 agent

将中心仓库和源仓库克隆到同一个父目录中。

mkdir knowledge-graph && cd knowledge-graph
git clone https://github.com/your-org/docs-hub.git
git clone https://github.com/your-org/web-app.git
git clone https://github.com/your-org/api-service.git
git clone https://github.com/your-org/api-gateway.git

在中心仓库中运行 mint agent setup，以安装 Mintlify skill 并连接管理 MCP 服务器。

cd docs-hub
mint agent setup

为一个仓库生成文档

在父目录中启动你的 agent，并指明源仓库、目标文件夹以及要编写的页面。

Example prompt

Read the source code in ../api-service and write documentation for it in
docs-hub/repos/api-service/.

Create these pages:
- index.mdx: what the service does, who owns it, and how it fits into the
  rest of the system
- endpoints.mdx: every HTTP endpoint with method, path, parameters, and
  response shape, based on the route definitions
- data-model.mdx: the main models and database tables
- local-development.mdx: how to install, run, and test the service

For each page, list the other repositories this service calls or is called
by, and link to their pages under docs-hub/repos/.

Only document what you can confirm from the code. If something is unclear,
leave a TODO comment instead of guessing.

Add the new pages to docs-hub/docs.json in a group named "API service".

审查输出内容，修正 agent 弄错的任何地方，然后在中心仓库中运行 mint dev 预览页面。

对每个仓库重复此操作

对你的其他仓库重复此操作，然后让 agent 编写概览页面。

Example prompt

Read every page under docs-hub/repos/ and write docs-hub/architecture.mdx.
Describe how the repositories depend on each other, which services call
which, and how a request moves through the system. Link to the repository
pages for details.

推送到中心仓库

提交页面，将其推送到中心仓库，并打开一个 pull request。合并后，Mintlify 会部署知识图谱，并为搜索和 MCP 建立索引。

git checkout -b initial-knowledge-graph
git add repos architecture.mdx docs.json
git commit -m "Add initial knowledge graph"
git push -u origin initial-knowledge-graph

将效果良好的提示词保存为中心仓库中的自定义 skill 或 AGENTS.md 文件。之后任何添加新仓库的人都会得到相同的页面结构。

第 2 步：保持知识图谱最新

创建一个使用代码变更触发器的自定义自动化，这样每当源仓库中有 pull request 合并时，agent 就会更新中心项目。

创建自动化

打开你的 Automations 设置。
点击 New automation。
选择 Code change 触发器。
为你在第 1 步中编写了文档的每个源仓库点击 Add repo。一个自动化最多可以监听 50 个仓库。

筛选触发器

在每个仓库卡片的 Show advanced options 下，将 Listening to changes in 设置为源代码路径（例如 src/**），并使用 Excluding PRs from 跳过机器人。请参见筛选代码变更触发器。

编写指令

告诉 agent 各仓库如何对应到中心页面，以及需要更改什么。

Example instructions

1. Read the merged pull request diff from the trigger repository.
2. Find the matching folder under /repos/ in this project. The folder name
   matches the repository name.
3. Identify changes to endpoints, events, data models, dependencies on
   other repositories, or setup steps.
4. Update the affected pages in that folder. If the change affects how
   repositories depend on each other, also update /architecture.mdx.
5. If the pull request doesn't change anything the documentation covers,
   make no changes.
6. Open a pull request that lists the pages you changed and links to the
   source pull request.

选择更新模式

先从 Modify and wait for review 开始，该模式会打开一个 pull request，并将源变更的作者指派为审查者。当结果稳定后，再切换到 Update and merge changes。如果启用了分支保护，请参见配置自动合并。

测试自动化

保存并手动运行，然后查看运行历史并完善指令。

此模拟器使用的自动化监听三个示例仓库中的 src/**，并排除 dependabot[bot]。之后若要添加仓库，请按第 1 步生成其页面，然后将其添加到触发器中。每次更新了中心项目的运行都会消耗积分，未做任何更改的运行则免费。对于繁忙的仓库，计划触发器可以将多次合并批量合并为一次运行。请参见控制积分用量。

该估算假设每次合并都会更改已有文档覆盖的代码，因此实际用量可能更低。

第 3 步：通过 MCP 使用知识图谱

每个项目在你站点 URL 的 /mcp 路径下都有一个托管的搜索 MCP 服务器。如果启用了身份验证，请使用 /authed/mcp，并先启用经过身份验证的 MCP。

Claude Code
Codex
Cursor

claude mcp add --transport http knowledge-graph https://docs.your-company.com/mcp

codex mcp add knowledge-graph --url https://docs.your-company.com/mcp

将服务器添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以用于所有项目。

.cursor/mcp.json

{
  "mcpServers": {
    "knowledge-graph": {
      "url": "https://docs.your-company.com/mcp"
    }
  }
}

有关其他客户端，请参见使用你的 MCP 服务器。若要让 agent 无需提示即可主动查询它，请在每个源仓库的 CLAUDE.md、AGENTS.md 或 Cursor 规则文件中添加一行说明。

AGENTS.md

Before changing code that calls another service or repository, search the
knowledge-graph MCP server for that service. Use its documented endpoints,
data models, and conventions instead of guessing.

以下展示了 agent 如何使用 MCP 工具来回答有关你代码的问题：当 agent 发现错误的页面时，可以使用反馈工具进行报告。报告会显示在你的反馈控制台中。

后续步骤

自动化

了解触发器类型、更新模式和使用限制。

搜索 MCP 服务器

为你的 MCP 服务器配置索引、身份验证和客户端凭据。

Skills

通过 skill 文件教会 agent 如何使用你的知识图谱。

身份验证

将知识图谱的访问权限限制在你的团队内。

概览

AI

API 文档

最佳实践

Git

使用场景

将 Mintlify 用作代码库的知识图谱

先决条件

规划结构

第 1 步：生成初始知识图谱

第 2 步：保持知识图谱最新

第 3 步：通过 MCP 使用知识图谱

后续步骤

自动化

搜索 MCP 服务器

Skills

身份验证

​先决条件

​规划结构

​第 1 步：生成初始知识图谱

​第 2 步：保持知识图谱最新

​第 3 步：通过 MCP 使用知识图谱

​后续步骤

自动化

搜索 MCP 服务器

Skills

身份验证

先决条件

规划结构

第 1 步：生成初始知识图谱

第 2 步：保持知识图谱最新

第 3 步：通过 MCP 使用知识图谱

后续步骤