内容
# Outline MCP 服务器
MCP（模型上下文协议）服务器，用于将 Outline 与 MCP 客户端集成。它允许兼容的助手或代理通过其 API 查询、搜索和管理 Outline 实例的文档。
## 用途
该服务器作为 MCP 客户端和 Outline 之间的桥梁。配置完成后，客户端可以调用工具来读取内部文档、搜索内容、创建笔记、更新文档和查询集合。
典型用例：
- 从 AI 助手查询 Outline 的知识库。
- 在不离开 MCP 客户端的情况下搜索内部文档。
- 从自动化流程中以 Markdown 格式创建或更新文档。
- 将 Outline 用作代理的可编辑文档存储。
## 功能
- 按 ID 读取文档。
- 在 Outline 文档中搜索文本。
- 列出文档，可选按集合过滤。
- 使用 Markdown 内容创建文档。
- 更新标题、内容和发布状态。
- 删除文档。
- 列出集合。
- 查询特定集合的信息。
- 默认使用 `stdio` 进行 MCP 传输，适用于本地客户端。
- 可选使用 Streamable HTTP 传输，适用于远程部署。
- 只读模式，隐藏写入工具。
- Outline 的 HTTP 超时和有界重试。
## 要求
- Node.js `>=18`。
- 可通过 URL 访问的 Outline 实例。
- 具有足够权限的 Outline API 令牌。
## 快速安装（使用 npx）
使用 `npx` 在 MCP 客户端上直接配置的最简单方法：
```json
{
"mcpServers": {
"outline": {
"command": "npx",
"args": ["-y", "getoutline-mcp-server"],
"env": {
"OUTLINE_BASE_URL": "https://your-outline-instance.com",
"OUTLINE_API_KEY": "your-api-token"
}
}
}
}
```
## 从源代码安装
```bash
npm install
npm run build
npm start
```
用于开发：
```bash
npm run dev
```
用于自动重新编译：
```bash
npm run watch
```
## 配置
服务器从环境变量中读取配置：
```bash
OUTLINE_BASE_URL=https://your-outline-instance.com
OUTLINE_API_KEY=your-api-token
OUTLINE_READ_ONLY=false
MCP_TRANSPORT=stdio
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp
OUTLINE_MAX_RETRIES=2
OUTLINE_RETRY_BASE_DELAY_MS=100
# OUTLINE_HTTP_TIMEOUT_MS=10000
```
可用变量：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `OUTLINE_BASE_URL` | 必需 | Outline 实例的基本 URL。 |
| `OUTLINE_API_KEY` | 必需 | Outline API 令牌。不在日志中打印。 |
| `OUTLINE_READ_ONLY` | `false` | 如果为 `true`，则不注册 `outline_create_document`、`outline_update_document` 和 `outline_delete_document`。 |
| `MCP_TRANSPORT` | `stdio` | MCP 传输：`stdio` 或 `http`。无效值会导致启动失败。 |
| `MCP_HTTP_HOST` | `127.0.0.1` | Streamable HTTP 的监听主机。仅当部署正确保护时，才使用 `0.0.0.0`。 |
| `MCP_HTTP_PORT` | `3000` | 当 `MCP_TRANSPORT=http` 时的 HTTP 端口。 |
| `MCP_HTTP_PATH` | `/mcp` | MCP 的 HTTP 路径。必须以 `/` 开头。 |
| `OUTLINE_MAX_RETRIES` | `2` | 对于 `429`、`5xx` 和暂时性网络错误，每个端点的最大重试次数。使用 `0` 禁用。 |
| `OUTLINE_RETRY_BASE_DELAY_MS` | `100` | 有界退避重试之间的基本延迟。 |
| `OUTLINE_HTTP_TIMEOUT_MS` | 无 | Axios 的可选超时毫秒数。 |
### 只读模式
使用 `OUTLINE_READ_ONLY=true` 时，服务器不会在 `tools/list` 上公开写入工具。隐藏的工具包括 `outline_create_document`、`outline_update_document` 和 `outline_delete_document`。
即使启用此模式，也请始终使用具有最小读取权限的 Outline 令牌。
### Streamable HTTP 传输
`stdio` 仍然是默认传输，不需要配置 HTTP 变量。要通过 Streamable HTTP 公开服务器：
```bash
MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp
npm start
```
端点在 `http://127.0.0.1:3000/mcp` 上使用 MCP SDK 的 Streamable HTTP 传输。如果您需要从本地机器外部公开它，请将 `MCP_HTTP_HOST` 更改为例如 `0.0.0.0`，并从网络或反向代理保护访问。
此更改不会向 HTTP 端点添加自己的身份验证。在生产中，仅在受信任的网络、VPN、具有身份验证的反向代理、防火墙规则或等效控件后面发布。
### 超时和重试
Outline 客户端可以重试暂时性错误：`429`、`500`、`502`、`503`、`504`、`ECONNRESET`、`ETIMEDOUT` 和 `ECONNABORTED`。不会重试永久性错误，如 `400`、`401` 或 `403`。
配置 `OUTLINE_MAX_RETRIES=0` 以禁用重试。仅当您要对 Outline 的 HTTP 调用强制实施显式超时时，才定义 `OUTLINE_HTTP_TIMEOUT_MS`。
### 如何获取 Outline 令牌
1. 登录到您的 Outline 实例。
2. 打开 `设置`。
3. 进入 `API 令牌`。
4. 创建一个新的令牌。
5. 将该值用作 `OUTLINE_API_KEY`。
建议：为您的用例创建具有必要最小权限的令牌。
## 在 MCP 客户端上的配置
### 使用 npx 的本地客户端
```json
{
"mcpServers": {
"outline": {
"command": "npx",
"args": ["-y", "getoutline-mcp-server"],
"env": {
"OUTLINE_BASE_URL": "https://your-outline-instance.com",
"OUTLINE_API_KEY": "your-api-token"
}
}
}
}
```
### 从此存储库使用本地客户端
首先编译项目：
```bash
npm run build
```
然后将客户端指向编译后的文件：
```json
{
"mcpServers": {
"outline": {
"command": "node",
"args": ["/absolute/path/to/outline-mcp-server/dist/index.js"],
"env": {
"OUTLINE_BASE_URL": "https://your-outline-instance.com",
"OUTLINE_API_KEY": "your-api-token"
}
}
}
}
```
在 Windows 上，使用有效的绝对路径，例如：
```json
"args": ["D:/work/outline-mcp-server/dist/index.js"]
```
### OpenCode
OpenCode 使用与其他 MCP 客户端不同的配置格式：命令作为单个数组，进程变量放在 `environment` 中，而不是 `env`。
`C:\Users\gbaso\.config\opencode\opencode.json` 示例：
```json
{
"mcp": {
"outline": {
"type": "local",
"command": [
"node",
"D:/work/outline-mcp-server/dist/index.js"
],
"enabled": true,
"environment": {
"OUTLINE_BASE_URL": "https://your-outline-instance.com",
"OUTLINE_API_KEY": "your-api-token"
}
}
}
}
```
如果在 OpenCode 中使用 `env`，服务器可能会在没有 `OUTLINE_BASE_URL` 和 `OUTLINE_API_KEY` 的情况下启动，启动时失败，并在日志中显示为 `server unavailable key=outline type=local status=failed`。
Windows 上的 OpenCode 日志位于：
```text
C:\Users\gbaso\.local\share\opencode\log\opencode.log
```
修改 `opencode.json` 后，重启 OpenCode。MCP 配置在启动时加载，不会热重载。
## 可用工具
### `outline_get_document`
按 ID 获取文档。
参数：
- `id`：文档 ID。
示例：
```json
{
"name": "outline_get_document",
"arguments": {
"id": "document-id"
}
}
```
### `outline_search_documents`
在 Outline 中搜索文档。
参数：
- `query`：搜索文本。
- `limit`：最大结果数。默认为 `25`，最大 `100`。
示例：
```json
{
"name": "outline_search_documents",
"arguments": {
"query": "项目文档",
"limit": 10
}
}
```
### `outline_list_documents`
列出文档，可选按集合过滤。
参数：
- `collectionId`：可选的集合 ID。
- `limit`：最大结果数。默认为 `25`，最大 `100`。
### `outline_create_document`
使用 Markdown 内容创建文档。
参数：
- `title`：文档标题。
- `text`：Markdown 内容。
- `collectionId`：可选的集合 ID。
- `parentDocumentId`：可选的父文档 ID。
- `publish`：是否立即发布。默认为 `false`。
示例：
```json
{
"name": "outline_create_document",
"arguments": {
"title": "项目计划",
"text": "# 计划\n\n文档的初始内容。",
"collectionId": "collection-id",
"publish": true
}
}
```
### `outline_update_document`
更新现有文档。
参数：
- `id`：文档 ID。
- `title`：新的标题，可选。
- `text`：新的 Markdown 内容，可选。
- `publish`：更改发布状态，可选。
### `outline_delete_document`
按 ID 删除文档。
参数：
- `id`：文档 ID。
### `outline_list_collections`
列出所有可用集合。
不需要参数。
### `outline_get_collection`
按 ID 获取集合信息。
参数：
- `id`：集合 ID。
## 开发
主结构：
```text
src/
├── index.ts # MCP 服务器和工具注册
└── outline-client.ts # Outline API 的 HTTP 客户端
```
可用脚本：
- `npm run build`：在 `dist/` 中编译 TypeScript。
- `npm test`：在没有真实 Outline 凭证的情况下运行 Vitest 测试套件。
- `npm run test:coverage`：运行测试，覆盖率至少为 85%。
- `npm start`：运行 `dist/index.js`。
- `npm run dev`：编译并运行服务器。
- `npm run watch`：检测更改时重新编译。
## 安全
- 不要在提交、日志或公共文档中包含 `OUTLINE_API_KEY`。
- 使用环境变量或 MCP 客户端的机密系统。
- 如果客户端只需要读取，请避免具有过多权限的令牌。
- 请谨慎使用写入或删除工具：服务器可以修改您的 Outline 实例。
- 如果使用 `MCP_TRANSPORT=http`，请用外部控件保护端点；服务器不实现自己的 HTTP 身份验证。
## 当前限制
- 不实现速率限制；如果您进行多次调用，请依赖 Outline 的限制。
- Outline 的响应作为 API JSON 返回，具有务实的 TypeScript 类型，但没有详尽的运行时字段验证。
- HTTP 传输是无状态的；它不会添加持久会话或自己的身份验证。
## 许可证
MIT。查看 `LICENSE` 以获取更多详细信息。
