outline-mcp

Сервер MCP только для чтения для Outline. Предоставляет агенту поиск и доступ на чтение к вашей вики — без записи, по замыслу.

Зачем

API Outline — это плоская RPC-поверхность: каждая конечная точка — это POST {base}/api/<method> с JSON-телом и Bearer-токеном. Такая единообразность означает, что полезный MCP-сервер — это одна функция запроса плюс курируемый список инструментов. Этот пакет намеренно мал: нет зависимостей времени выполнения, кроме MCP SDK и zod, и полный контроль над описаниями инструментов и формой вывода, которые определяют, выберет ли агент правильный инструмент.

Сервер только для чтения: в коде нет ни одного пути создания, обновления, перемещения или архивирования.

Related MCP server: outline-mcp

Инструменты

get_document принимает полный URL, голый urlId или UUID. urlId — это [A-Za-z0-9]{10,15} — слаг без допустимого суффикса идентификатора отклоняется локально, потому что API отвечает 400 validation_error.

Требования

• Node 18 или новее (использует встроенный fetch; без нативных зависимостей).

• Экземпляр Outline — самостоятельный хостинг или Outline.com.

Начало работы

git clone https://github.com/minhquan2904/outline-mcp.git
cd outline-mcp
npm ci

Получение API-ключа

В Outline: Settings → API & Apps → New API key. Значение начинается с ol_api_ и содержит 38 буквенно-цифровых символов.

Установка двух переменных окружения

export OUTLINE_API_URL=https://your-outline-instance
export OUTLINE_API_KEY=ol_api_…
node index.js

Конфигурация

Сервер читает ровно две переменные окружения:

Claude Code — mcp.json (проект) или .mcp.json (пользователь):

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Примечание: Claude Desktop не раскрывает ссылки ${VAR} в этом файле — вставьте ключ буквально, не пишите "${OUTLINE_API_KEY}".

Любой другой MCP-клиент (Zed, Cline или что-либо, говорящее на протоколе MCP stdio) — та же форма: запустите node /path/to/outline-mcp/index.js с двумя переменными в его окружении.

Как это работает

flowchart LR
    CC[Claude Code / any MCP client]
    OM[outline-mcp<br/>Node 18+, stdio server]
    O[Outline instance]
    F[format.js<br/>parse ref · truncate · render]
    C[client.js<br/>timeout · error map · 429 retry]

    CC -->|stdio| OM
    OM -->|"POST /api/{method} · Bearer ol_api_…"| O
    OM -.-> F
    OM -.-> C

Сервер никогда не проверяет учетные данные при запуске. Сервер, который завершает работу при загрузке, отображается в клиенте как «не удалось подключиться» без объяснения причин; вместо этого он запускается, перечисляет свои инструменты, и каждый вызов возвращает сообщение с указанием отсутствующей переменной.

Разработка

npm ci
npm test          # unit tests, fully offline (fetch is stubbed)
npm run smoke     # every tool against a real instance; no-ops without credentials

npm run smoke требует OUTLINE_API_URL + OUTLINE_API_KEY, указывающих на работающий экземпляр; без них он выводит строку «smoke skipped» и завершается с кодом 0. См. CONTRIBUTING.md о том, как добавить инструмент.

Ограничения

• Только для чтения по замыслу. Нет создания, обновления, перемещения, архивирования или записи комментариев.

• Вложения не разрешаются. Встроенные изображения и файлы остаются в виде ссылок /api/attachments.redirect?id=… в markdown; они не загрузятся для агента, читающего текст.

• Нет упреждающего сигнала ограничения скорости. Экземпляр не возвращает заголовки RateLimit-*. При 429 клиент соблюдает Retry-After (максимум 10 секунд) и повторяет попытку ровно один раз, затем сообщает об ошибке.

• Длинные документы обрезаются до maxChars (по умолчанию 40 000) с маркером, указывающим истинную общую длину.

Безопасность

API-ключ передается только в заголовке Authorization исходящих запросов. Любое сообщение об ошибке, покидающее клиент, проходит через этап редактирования, который заменяет ключ на ol_api_***, и ничто на пути ключа (транспорт stdio или журнал stderr) никогда не выводит сам ключ. Если ваш экземпляр Outline поддерживает ключи с ограниченной областью действия, предпочтите ключ с областью только для чтения для этого сервера.

Лицензия

MIT — см. LICENSE для полного текста.