outline-doc-mcp

v0.1.0

Published

20 days ago

Local stdio MCP for Outline interface document collaboration.

Downloads

112

0High
0Medium
0Low

zhoupb01

OutlineDoc MCP

把 Outline 里的接口文档树接成一个本地 stdio MCP 服务。接入 MCP 客户端后，你可以直接把 Outline 当成一个可读写的接口文档工具来用。

它只做一件事：围绕 OUTLINE_ROOT_PARENT_ID 下面的那棵文档树，提供稳定、严格、可脚本化的读写能力。

能做什么

列出根目录下的目录
列出某个目录下的接口文档
在整棵受管子树里搜索接口文档
精确读取单篇文档
新建、更新、删除接口文档

约定的 Outline 结构

它假设你的 Outline 文档树长这样：

OUTLINE_ROOT_PARENT_ID
├── 用户管理
│   ├── GET /job/v1/users/{id} - 获取用户详情
│   └── POST /job/v1/users - 创建用户
└── 订单管理
    └── GET /job/v1/orders/{id} - 获取订单详情

也就是：

根节点下一层是目录
目录下一层是接口文档
只认这两层
更深层嵌套文档不在受管范围内

安装

要求：

Node.js >= 20

临时运行：

OUTLINE_BASE_URL="https://outline.example.com/api" \
OUTLINE_API_KEY="ol_api_xxx" \
OUTLINE_ROOT_PARENT_ID="doc_xxx" \
npx outline-doc-mcp

这是一个 stdio MCP server，不是面向终端交互的普通 CLI；如果缺少必要环境变量，进程会在启动时直接失败。

安装到项目里：

npm install outline-doc-mcp

配置

环境变量

| 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | OUTLINE_BASE_URL | 是 | - | Outline API 地址，例如 https://outline.example.com/api | | OUTLINE_API_KEY | 是 | - | Outline API Token | | OUTLINE_ROOT_PARENT_ID | 是 | - | 受管子树根文档 ID | | OUTLINE_TIMEOUT_MS | 否 | 15000 | 请求超时毫秒数 | | OUTLINE_DEFAULT_PAGE_SIZE | 否 | 50 | 列表和搜索单次请求使用的分页大小 | | OUTLINE_STRICT_MODE | 否 | true | 当前版本会读取并校验该值，但整体行为仍保持严格模式 |

示例：

export OUTLINE_BASE_URL="https://outline.example.com/api"
export OUTLINE_API_KEY="ol_api_xxx"
export OUTLINE_ROOT_PARENT_ID="doc_xxx"
export OUTLINE_TIMEOUT_MS="15000"
export OUTLINE_DEFAULT_PAGE_SIZE="50"
export OUTLINE_STRICT_MODE="true"

快速接入 MCP 客户端

把它注册成一个 stdio MCP 服务即可：

{
  "mcpServers": {
    "outline-doc-mcp": {
      "command": "npx",
      "args": ["outline-doc-mcp"],
      "env": {
        "OUTLINE_BASE_URL": "https://outline.example.com/api",
        "OUTLINE_API_KEY": "ol_api_xxx",
        "OUTLINE_ROOT_PARENT_ID": "doc_xxx"
      }
    }
  }
}

如果你的客户端不适合用 npx，先安装到本地项目或全局环境，再直接调用 outline-doc-mcp 可执行文件。

提供的 MCP Tools

| Tool | 作用 | 关键参数 | | --- | --- | --- | | list_directories | 列出受管根节点下一层目录 | 无 | | list_documents | 列出接口文档 | directory?、query? | | search_documents | 先搜索，再过滤出受管子树内的接口文档 | keyword | | get_document | 读取单篇文档 | document_id，或 title + directory | | create_document | 创建接口文档 | directory、title、content | | update_document | 更新文档内容 | document_id、content | | delete_document | 删除文档 | document_id |

Tool 行为说明

`list_directories`

返回根节点下一层目录
返回字段：id、name

`list_documents`

directory 不传时，会跨所有目录聚合结果
query 只做标题包含过滤
返回字段：id、title、directory、updated_at

`search_documents`

先调用 Outline 搜索，再过滤出受管子树中的接口文档
返回字段：id、title、directory、updated_at

`get_document`

如果提供 document_id，会优先按 document_id 读取
如果不提供 document_id，则必须同时提供 title 和 directory
返回字段：id、title、directory、content、updated_at

`create_document`

目录不存在时会先自动创建目录
新建目录和新建文档都会直接发布
同一目录下标题重复会直接报错
返回字段：id、title、directory

`update_document`

只接受 document_id + content
返回字段：id、updated

`delete_document`

只接受 document_id
返回字段：id、deleted、mode
当前 mode 固定为 soft

使用约束

这个服务默认偏严格，不帮你“猜”：

请求参数是严格校验的，多余字段会直接报错
旧字段名不会兼容，比如 domain、version
目录名匹配是精确匹配
get_document 里的标题匹配是精确匹配
list_documents 里的 query 是标题包含匹配
请求到目录文档本身会报错
请求到更深层嵌套文档也会报错
同名目录或同目录下同名文档导致歧义时会报错

已知限制

当前版本故意不做这些事：

版本管理
历史回放
元数据体系
domain 模型
CHANGELOG
major/minor/patch
本地数据库
OAuth
远程网关

另外还有两个明确限制：

当前不会自动翻页；目录列表、目录下文档列表、搜索结果都受 OUTLINE_DEFAULT_PAGE_SIZE 约束
search_documents 不是由 Outline 侧限定在受管子树内，而是先全局搜索，再把结果过滤到受管子树
它只适合管理一棵由当前服务独占的接口文档子树，不适合拿去兼容通用 Outline 信息架构

本地开发

npm run dev
npm run build
npm test

代码入口：

src/cli.ts
src/server.ts
src/treeService.ts
src/outlineClient.ts
src/config.ts

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme