npm package: @insightsuen/outline
Description: MCP server for reading Outline / self-hosted wiki documents
Latest version: 0.2.1

# outline MCP Server

通过 MCP 协议读写自托管 [Outline](https://www.getoutline.com/) / doutline 知识库，支持集合浏览、文档列表、文档读取、全文搜索、创建与更新文档。

## 使用方式

### 1. npx 安装 — 使用默认环境变量

| 环境变量 | 必填 | 说明 |
|---------|------|------|
| `OUTLINE_URL` | ✅ | Outline 实例地址，如 `https://docs.example.com` |
| `OUTLINE_API_KEY` | ✅ | API Key，在 Outline 设置 → API tokens 中创建 |

在 MCP 客户端（Cursor / Claude Desktop）的配置文件中：

```json
{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "@insightsuen/outline@latest"],
      "env": {
        "OUTLINE_URL": "https://your-outline.example.com",
        "OUTLINE_API_KEY": "ol_api_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

不想明文写在配置文件中？在 `~/.zshrc` 里 `export` 环境变量，然后省略 `env` 字段，子进程会自动继承：

```json
{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "@insightsuen/outline@latest"]
    }
  }
}
```

---

### 2. npx 安装 — CLI 参数直传

适合临时测试，直接在 `args` 中传入值：

```json
{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y", "@insightsuen/outline@latest",
        "--url=https://your-outline.example.com",
        "--api-key=ol_api_xxxxxxxxxxxxxxxx"
      ]
    }
  }
}
```

---

### 3. npx 安装 — 指定自定义环境变量名

凭证已存储在其他变量名下时，通过 `--*-env` 参数指定读取哪个变量：

```json
{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y", "@insightsuen/outline@latest",
        "--url-env=MY_WIKI_URL",
        "--api-key-env=MY_WIKI_TOKEN"
      ]
    }
  }
}
```

凭证配置方式总览：

| 凭证 | 默认环境变量 | CLI 直传 | 指定环境变量 |
|------|------------|---------|------------|
| 实例地址 | `OUTLINE_URL` | `--url=xxx` | `--url-env=VAR` |
| API Key | `OUTLINE_API_KEY` | `--api-key=xxx` | `--api-key-env=VAR` |

---

### 4. 开发模式（从源码构建）

适合本地开发调试，或在生产实例旁边并联一个开发实例。

**第一步：构建**

```bash
# 在项目根目录执行
pnpm install
pnpm --filter @insightsuen/outline build
```

**第二步：在 MCP 客户端中注册本地构建产物**

凭证可以通过环境变量、CLI 直传或指定变量名三种方式传入（与生产版相同）：

```json
{
  "mcpServers": {
    "insight-outline-dev": {
      "command": "node",
      "args": [
        "/path/to/Insight-MCP/servers/outline/dist/index.js",
        "--url=https://your-outline.example.com",
        "--api-key-env=OUTLINE_API_KEY"
      ]
    }
  }
}
```

> 使用不同的 key 名（如 `insight-outline-dev`）可与生产实例（`insight-outline`）并存，两者互不干扰。

**热重载开发**：修改源码后重新构建即可，无需重启 MCP 客户端（重新发起对话会重新加载）：

```bash
pnpm --filter @insightsuen/outline dev   # 监听文件变化，自动编译
```

## 可用工具

### `outline-list-collections`

列出所有可访问的集合（Collection），支持分页。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `limit` | number | 否 | 每页返回数量，默认 25，最大 100 |
| `offset` | number | 否 | 分页偏移量，默认 0 |

---

### `outline-list-documents`

列出文档，支持按集合或父文档过滤，支持分页。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `collectionId` | string | 否 | 按集合 ID 过滤（从 `outline-list-collections` 获取） |
| `parentDocumentId` | string | 否 | 按父文档 ID 过滤，列出子文档 |
| `limit` | number | 否 | 每页返回数量，默认 25，最大 100 |
| `offset` | number | 否 | 分页偏移量，默认 0 |

---

### `outline-get-document`

读取单个文档的完整内容，返回 Markdown 格式正文及元信息。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | ✅ | 文档 ID（UUID）或 URL slug |

---

### `outline-search-documents`

全文搜索文档，返回匹配结果、摘要片段和相关度排名。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | ✅ | 搜索关键字 |
| `collectionId` | string | 否 | 限定搜索范围到指定集合 |
| `limit` | number | 否 | 返回结果数量，默认 10，最大 100 |

---

### `outline-create-document`

在知识库中创建新文档。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | string | ✅ | 文档标题 |
| `text` | string | 否 | 文档正文，Markdown 格式，不传则创建空文档 |
| `collectionId` | string | 条件必填 | 所属集合 ID；与 `parentDocumentId` 至少提供一个 |
| `parentDocumentId` | string | 条件必填 | 父文档 ID，创建为子文档；与 `collectionId` 至少提供一个 |
| `publish` | boolean | 否 | 是否立即发布，默认 `true` |

---

### `outline-update-document`

更新已有文档，支持三种模式：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | ✅ | 文档 ID（UUID）或 URL slug |
| `mode` | `replace` \| `append` \| `prepend` | 否 | 更新模式，默认 `replace` |
| `title` | string | 否 | 新标题，不传则保持原标题 |
| `text` | string | 条件必填 | 要写入的 Markdown 内容；仅更新标题时可不传 |

**模式说明：**

| mode | 行为 |
|------|------|
| `replace`（默认） | 用 `text` 整体替换文档正文 |
| `append` | 将 `text` 追加到文档末尾（使用 Outline API 原生支持） |
| `prepend` | 将 `text` 插入到文档开头（先拉取当前正文再拼接回写） |

## 发布到 npm

在 `servers/outline` 目录下构建并发布：

```bash
# 1. 登录 npm
npm login
npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN

pnpm run build
npm publish --access public
```

发布后验证：

```bash
npm info @insightsuen/outline
```

升级版本时，先修改 `servers/outline/package.json` 中的 `version` 字段，再重新发布：

```bash
# 也可以用 npm version 自动修改版本号并打 git tag
npm version patch   # 0.1.0 → 0.1.1（修复）
npm version minor   # 0.1.0 → 0.2.0（新功能）
npm version major   # 0.1.0 → 1.0.0（破坏性变更）

npm publish --access public
```