outline-openspec-mcp

A Model Context Protocol (MCP) stdio server that exposes the Outline wiki API as MCP tools, generated from the official Outline OpenAPI specification.

Built with FastMCP and TypeScript. Every operation in spec3.json (108+ endpoints — documents, collections, comments, users, groups, attachments, search, …) is registered as an MCP tool with a typed input schema derived from the OpenAPI request body.

Features

• Stdio transport — works out of the box with Claude Desktop, Continue, Cline, and any other MCP-compatible client.
• Auto-generated tools — one MCP tool per OpenAPI operation, with names matching the operation's operationId (e.g. documentsCreate, documentsInfo, collectionsList).
• Typed inputs — JSON Schema from the spec is converted to Zod, including $ref resolution, enums, formats, oneOf/anyOf/allOf, and nullable.
• Self-hosted Outline — point at any Outline instance via OUTLINE_API_URL.
• Zero post-install steps — the spec is bundled with the package.

Quick start (npx)

You only need an Outline API token.

OUTLINE_API_TOKEN=ol_api_xxx npx -y @drunkcoding/outline-openspec-mcp

The process talks MCP over stdio — point an MCP client at it.

Configure in an MCP client

Claude Desktop / Cline / Continue / generic MCP client

Add an entry to your MCP servers configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "@drunkcoding/outline-openspec-mcp"],
      "env": {
        "OUTLINE_API_TOKEN": "ol_api_xxx"
      }
    }
  }
}

For a self-hosted Outline instance, override the base URL:

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "@drunkcoding/outline-openspec-mcp"],
      "env": {
        "OUTLINE_API_TOKEN": "ol_api_xxx",
        "OUTLINE_API_URL": "https://wiki.example.com/api"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | | ------------------- | -------- | --------------------------------------------------------------------------------------------- | | OUTLINE_API_TOKEN | yes | Bearer token used for Authorization: Bearer <token> on every Outline API request. | | OUTLINE_API_URL | no | Base URL of the Outline API. Defaults to https://app.getoutline.com/api. No trailing slash. |

Tool naming

Tool names are taken directly from the operationId field in spec3.json. Examples:

| MCP tool name | Outline endpoint | Description | | ----------------- | ------------------------ | -------------------------- | | documentsList | POST /documents.list | List documents | | documentsInfo | POST /documents.info | Get a single document | | documentsCreate | POST /documents.create | Create a document | | documentsUpdate | POST /documents.update | Update a document | | documentsSearch | POST /documents.search | Full-text search documents | | collectionsList | POST /collections.list | List collections | | usersInfo | POST /users.info | Get a single user |

The tool description includes the original HTTP method/path and OpenAPI tags, so MCP clients can present them with full context. Each tool's input schema is the OpenAPI request body for that operation; the response is returned to the caller as raw JSON text (the body of Outline's response).

Local development

git clone https://github.com/baoduy/outline-openspec-mcp.git
cd outline-openspec-mcp
npm install
npm run build
OUTLINE_API_TOKEN=ol_api_xxx node dist/index.js

The server logs startup information to stderr and uses stdout exclusively for MCP JSON-RPC traffic, so it can be safely piped to a client.

Testing

Unit tests use Vitest and mock the Outline API with MSW — handlers are generated from the bundled OpenAPI spec, following the MSW + OpenAPI pattern.

npm test            # run once
npm run test:watch  # watch mode

Tests cover the JSON Schema → Zod converter, tool registration from the spec, and end-to-end tool execution (HTTP request shape, Authorization header, error handling for missing token / non-2xx / network failures) — all without any real network calls.

Project layout

src/
  index.ts             # FastMCP server: loads spec, registers a tool per operation
  jsonSchemaToZod.ts   # Minimal OpenAPI 3.0 JSON Schema -> Zod converter
spec/
  spec3.json           # Outline OpenAPI spec (bundled, sourced from outline/openapi)
tests/
  jsonSchemaToZod.test.ts  # Converter unit tests
  server.test.ts           # Tool registration + execution tests (MSW-mocked API)
  mocks.ts                 # MSW handler factory built from the OpenAPI spec

Updating the bundled spec

The Outline API spec evolves; to refresh it run:

curl -fsSL -o spec/spec3.json \
  https://raw.githubusercontent.com/outline/openapi/main/spec3.json
npm run build

No code changes are needed — tools are generated dynamically from the spec at startup.

Publishing

Releases are automated by .github/workflows/npm-publish.yaml, which mirrors the ShareWorkflows npm-publish pattern:

1. On every push to main (or via manual workflow_dispatch), paulhatch/semantic-version computes the next MAJOR.MINOR.PATCH from the commit history ((MAJOR) / (MINOR) markers in commit messages bump the corresponding component; otherwise patch).
2. The workflow installs deps, runs npm test, runs npm run build, and npm versions package.json to the calculated version (without committing or tagging locally).
3. It creates a GitHub Release vX.Y.Z (with auto-generated release notes) and runs npm publish --access public.

Required secret: NPM_TOKEN — an npm automation token with publish rights, configured in repository Settings → Secrets and variables → Actions.

A separate ci.yaml workflow runs npm test + npm run build on pull requests and feature branches.

Manual publish

npm version patch        # or minor / major
npm publish --access public

prepublishOnly runs the TypeScript build, and files in package.json ships only dist/, spec/spec3.json, README.md, and LICENSE.

License

MIT — see LICENSE.

The bundled spec/spec3.json file is © Outline and distributed under the license of the outline/openapi repository.