DocsMint

DocsMint MCP 服务

为 AI Agent 提供持久的项目知识。通过混合检索、重排、GraphRAG 和范围限定的访问权限，搜索、阅读、创建和整理文档。

**推荐使用 DocsMint Cloud：**通过 Streamable HTTP 连接到 https://docsmint.com/mcp。无需部署服务。如需高级自托管设置，请运行自己的 DocsMint API，并使用自己的 API 密钥连接 docsmint-mcp stdio 桥接程序。该桥接程序随 @hiai-gg/docsmint 一同发布，包中还包含 TypeScript SDK 和 CLI。

选项 A — DocsMint Cloud（推荐）

从连接 DocsMint Cloud开始。无需自托管服务或本地 MCP 进程。

1. 注册或登录现有的 DocsMint 账户。
2. 选择工作区，并确认套餐包含托管 MCP。
3. 对于支持 OAuth 的客户端，请在浏览器中授权，并同意访问工作区和明确指定的权限范围。对于 API 密钥客户端，请在已通过身份验证的界面中创建 MCP/API 凭据；优先选择绑定工作区或限定类别的访问权限。
4. 选择 MCP 客户端并按照其连接说明操作。
5. 使用 initialize 和允许的工具调用验证连接。

支持 OAuth 的客户端使用相同的托管 URL。未经身份验证的请求会返回 401，并附带指向 /.well-known/oauth-protected-resource/mcp 的 WWW-Authenticate 链接。该资源元数据指向 /.well-known/oauth-authorization-server。当前托管授权和客户端连接方式详见 DocsMint Cloud 设置指南。

当前授权元数据公布的响应类型为 code，仅支持 authorization_code 授权类型，不支持令牌端点客户端身份验证，并要求使用 S256 的 PKCE。令牌端点会交换授权码，但不会签发或接受刷新令牌。

授权使用你现有的 DocsMint 账户，并通过浏览器同意流程完成，采用授权码授权类型和必需的 PKCE S256。用户同意后，访问权限将绑定到所选工作区、可选类别以及请求的 mcp:read、mcp:edit 和 mcp:write 权限范围。不透明的不记名令牌绑定到托管 MCP 资源，有效期为一小时，并可在浏览器界面中撤销。不会签发刷新令牌；过期后请重新授权。这是 DocsMint Cloud 的功能，并非由 stdio npm 桥接程序安装的 OAuth 服务端。

API 密钥客户端通过 Authorization: Bearer <key> 连接到 https://docsmint.com/mcp。凭据的创建、修改和撤销由浏览器会话管理：MCP/API 凭据无法创建或提升凭据权限。

export HIAI_DOCS_API_KEY="your-global-or-category-key"

codex mcp add docsmint \
  --url https://docsmint.com/mcp \
  --bearer-token-env-var HIAI_DOCS_API_KEY

通用 HTTP 客户端应使用 Authorization: Bearer <key> 连接到 https://docsmint.com/mcp。绑定工作区的密钥无需额外请求头；未绑定的密钥可以提供文档所述的 X-Docsmint-Workspace slug。

选项 B — 自托管 stdio 桥接程序（高级）

已发布的 MCP 二进制文件会连接到已运行的 DocsMint API。安装该包并不会部署 DocsMint 本身。

请先运行 DocsMint，在其已通过身份验证的浏览器界面中创建 API 密钥，将 HIAI_DOCS_URL 设置为部署的 API URL，并将 HIAI_DOCS_API_KEY 设置为该密钥，然后启动 stdio 桥接程序。不要使用 /api/health URL 作为 MCP 端点。桥接程序使用该不记名 API 密钥向你自己的 DocsMint API 进行身份验证；它不会安装或公开 DocsMint Cloud OAuth 授权服务端。

使用 Bun 运行

bunx --package @hiai-gg/docsmint docsmint-mcp

使用 NPX 运行

npx --yes --package @hiai-gg/docsmint docsmint-mcp

从本地检出版本运行

git clone https://github.com/HiAi-gg/docsmint.git
cd docsmint
bun install --frozen-lockfile
bun run packages/mcp-server/src/index.ts

这三种方式都会运行来自 @hiai-gg/docsmint 的同一个 stdio 服务。

客户端配置

{
  "mcpServers": {
    "docsmint": {
      "command": "npx",
      "args": ["--yes", "--package", "@hiai-gg/docsmint", "docsmint-mcp"],
      "env": {
        "HIAI_DOCS_URL": "http://localhost:50700",
        "HIAI_DOCS_API_KEY": "your-global-or-category-key"
      }
    }
  }
}

HIAI_DOCS_URL 默认为 http://localhost:50700。可选的 API 密钥会作为不记名令牌发送。对于绑定类别的 Agent，优先使用类别密钥；对于受信任的全局所有者自动化，优先使用全局密钥。类别的 read、edit 和 write 权限范围彼此独立，并非层级关系；请配置所公开工具所需的权限组合。

Glama 服务列表

如需提交到 Glama MCP 服务目录，请提交这个来自 DocsMint 仓库的开源 stdio 桥接程序。 使用上方的 NPX 命令启动（执行已发布的二进制文件必须安装 Bun）。将 HIAI_DOCS_URL 设置为已运行且可访问的 DocsMint API 的 URL，并将 HIAI_DOCS_API_KEY 设置为具有工具所需权限的密钥。对于可用的托管 Glama 进程，这两个值都是必需的：默认的 localhost URL 指向 Glama 自身的环境，而不是你的 API。 即使没有 API 访问权限，该进程仍可公布工具、提示词和资源，但文档操作需要可访问的 API 和有效密钥。Glama 的托管连接器使用 DocsMint Cloud（地址为 https://docsmint.com/mcp），属于单独的列表。

MCP 功能

工具

DocsMint 提供 22 个 MCP 工具。原有的 31 项操作仍可使用；分组工具需要明确指定 mode、view、kind 或 action，以免 Agent 混淆浏览与搜索、恢复版本与恢复回收站内容，或可撤销删除与永久清除。不会公布第二套或旧版工具目录。迁移会调用旧工具名称的 MCP 客户端时，请使用与其匹配版本的可自托管桥接程序或 Cloud 端点。

根据资源和意图选择工具。save_* 用于创建或更新单个文档、文件夹、类别或标签；delete_* 则按照文档说明的规则移除单个资源。对于单个文档，优先使用匹配的单文档工具。多个已明确选定的文档需要执行相同的归类、标记、移入回收站、恢复或索引操作时，请使用 batch_documents。为兼容自动化，它接受一个 ID，但会按顺序执行，并可能返回部分成功。它不会发现 ID、执行任意更新、恢复版本或永久清除。 只读浏览、图谱探索、版本历史、回收站检查和索引状态仍是各自独立的意图，不会增加并行的 CRUD 工具集。 create_snapshot 使用 create，因为快照是新的不可变历史条目；它无法像 save_* 资源那样更新现有快照。

• find_documents：使用 mode=list 按文件夹／标签 UUID 浏览，或使用 mode=search 按文本／标签名称进行混合搜索。
• read_document：使用 view=detail 读取内容和元数据，使用 view=markdown 导出 Markdown，或使用 view=versions 列出修订和快照。
• save_document：使用 action=create 创建文档，或使用 action=update 修改现有文档。省略的修改字段保持不变；将位置设为 null 可清除该位置。API 会强制应用有效类别并安排索引。
• delete_document：将文档移至回收站，不清除其内容或版本。
• list_workspace_structure：使用 kind=folders|categories|tags 列出文件夹、类别或标签；文件夹可选择接受 parentId。
• save_folder：使用 action=create 创建，或使用 action=update 重命名、移动或重新排序；元数据变更会排队等待重新索引。
• delete_folder：移除文件夹，并按照 API 的解除关联规则保留其中的文档。
• save_category：使用 action=create 创建，或使用 action=update 重命名／重新排序；需要完整工作区写入权限。
• delete_category：移除类别并解除其文档的关联；需要完整工作区写入权限。
• save_tag：使用 action=create 创建，或使用 action=update 重命名／更改颜色；需要完整工作区写入权限。
• delete_tag：删除标签及其分配关系，但不删除文档。
• set_document_tag：使用 action=add 分配标签，或使用 action=remove 取消分配；需要对文档具有编辑权限。
• create_snapshot：保存当前文档内容的命名版本。
• restore_document_version：恢复通过 read_document(view=versions) 选定的修订或快照中的内容；将该文档的 UUID 作为 documentId 传入。
• explore_graph：使用 mode=neighbors 遍历单个文档，或使用 mode=search 按种子 ID 对关系排序。
• get_document_index_status：检查索引状态，但不启动任务。
• refresh_document_index：检查状态后，显式排队进行异步重试。
• list_trash：列出当前活动范围内可见的软删除文档。
• restore_trashed_document：恢复软删除文档；此操作不会恢复较早的版本。
• permanently_delete_document：根据用户的明确请求，永久清除已在回收站中的文档。
• batch_documents：对 1–25 个明确指定的文档 ID 应用一项操作：移动、设置类别、添加／移除一个标签、移至回收站、恢复或刷新索引。处理多个 ID 时优先使用此工具；处理单个 ID 时使用对应的单文档工具。结果会指出每个 ID 的成功或失败情况；可能出现部分成功。此工具不会永久清除文档。
• get_workspace_item：按 UUID 读取一个可见的文件夹、类别或标签。类别和标签从完整的权限过滤列表中选取；无法访问的 ID 会报告为未找到。

分组工具在文本和结构化 MCP 内容中均返回 { "operation": "<selected variant>", "result": ... }。 其他工具保留其原有的结果格式。 从版本 0.10.0 开始的 31 项到 20 项迁移如下：

之前的工具	当前工具和选择器
search_documents、list_documents	find_documents，使用 `mode=search
get_document、export_document、get_version_history	read_document，使用 `view=detail
create_document、update_document	save_document，使用 `action=create
list_folders、list_categories、list_tags	list_workspace_structure，使用 `kind=folders
create_folder、update_folder	save_folder，使用 `action=create
create_category、update_category	save_category，使用 `action=create
create_tag、update_tag	save_tag，使用 `action=create
add_tag_to_document、remove_tag_from_document	set_document_tag，使用 `action=add
get_related_documents、search_knowledge_graph	explore_graph，使用 `mode=neighbors
delete_document、delete_folder、delete_category、delete_tag、create_snapshot、restore_document_version、get_document_index_status、refresh_document_index、list_trash、restore_trashed_document、permanently_delete_document	名称和行为不变

生命周期权限

操作	所需权限	影响
删除文档	其有效类别中的 write 权限	软删除至回收站；内容和版本历史仍会保留。
删除文件夹	其有效类别中的 write 权限	移除文件夹；直接子文件夹和文档会解除关联，而不会被删除。
删除类别	工作区完整 write 权限	解除类别关联；保留内容并将其加入重新索引队列。类别密钥不能执行此操作。
恢复版本	对文档具有 edit 权限	备份当前内容，恢复所选版本的内容，并将其加入索引队列。不会更改标题或位置。
创建、更新或删除标签	工作区完整 write 权限	管理工作区标签目录；类别密钥不能执行此操作。
分配或移除文档标签	对文档具有 edit 权限	更改单个文档的标签关联，并将其加入元数据重新索引队列。
更新文件夹	其有效类别中的 write 权限	按照 API 的范围规则重命名或移动文件夹；将其加入元数据重新索引队列。
更新类别	工作区完整 write 权限	重命名类别或调整类别顺序；类别密钥不能执行此操作。
列出回收站	当前范围内的 read 权限	显示密钥可见的软删除文档。
恢复回收站中的文档	其有效类别中的 write 权限	将软删除的文档恢复到活动文档库。
永久删除文档	其有效类别中的 write 权限	不可逆地清除已在回收站中的文档，包括版本历史。
批量文档操作	与所选单文档操作相同的权限，逐个 ID 检查	按顺序执行且非原子；某个项目被拒绝不会授权或取消其他项目。身份验证和速率限制失败会停止剩余调用。

请使用列表/历史工具返回的 UUID。快照是带有标签的版本： 将其版本 ID 传给 restore_document_version。请使用 restore_trashed_document 恢复回收站中的文档。生命周期工具会声明破坏性注释；授权由 REST API 执行， 而非由这些仅供参考的客户端提示执行。请求失败时会返回带有 REST 状态的 MCP isError； 绝不会确认未成功的删除操作。

提示词

• organize_workspace：使用 DocsMint 类别和文件夹，规划安全的文档整理方案。
• research_workspace：使用混合搜索、GraphRAG 和重排功能研究问题，并引用文档 ID。

资源

• docsmint://guide/editor：编辑器使用指南。
• docsmint://guide/search：搜索、GraphRAG 和重排指南。
• docsmint://workspace/catalog：实时的限定范围工作区目录。

技能

• docsmint-document-manager： 通过 DocsMint 的 MCP 工具创建、整理、编辑和研究 DocsMint 文档。

工具和 REST 路由

分组选择器映射到相同的已记录 REST 操作；stdio 桥接本身不实现数据库或认证服务器。端点详情请参阅机器可读的 REST 合约和上方的操作映射。

提示词和资源

该服务提供 organize_workspace 和 research_workspace 提示词。MCP 客户端还可以通过以下资源附加编辑器规则、检索规则和实时限定范围的工作区目录：

• docsmint://guide/editor
• docsmint://guide/search
• docsmint://workspace/catalog

仓库提供了可复用的 docsmint-document-manager 技能。其中记录了 API 和 UI 所使用的相同工作区/类别权限、多语言检索流程、编辑器规则和索引生命周期。

工作区密钥可以管理其实时工作区角色所允许的完整文档域。类别密钥仅限于其绑定的类别及其文件夹和文档，以及明确授予的 read、edit 和 write 权限。类别密钥无法创建类别，也无法通过文档、文件夹、图谱、标签或索引操作越权访问其所属类别之外的内容。

该服务不管理或披露密钥；这些端点需要 Better Auth 浏览器会话。MCP 错误会保留后端 HTTP 状态码和消息，且不会暴露凭据。

开发

cd packages/mcp-server
bun run test
bun run typecheck
bun run dev