wiki-skills

A local MCP connector that lets Claude search, read, create, and edit pages in the ok-wiki knowledge base.

It runs as a child process of the Claude client on the same machine as ok-wiki, speaks MCP over stdio, and reaches the wiki over HTTP with an API key that never enters the model's context.

Status: documentation first. The architecture is specified and the upstream API is mapped; src/ is not yet implemented. Start at docs/architecture.md.

What it can do

• Search and read — full-text search, fetch a page by path or id, list pages by tag or recency

• Create and edit — create markdown pages; patch an existing page's content, title, description, tags, or published state

• History — list a page's revisions, fetch a specific version, restore a page to an earlier one

• Tags — list and autocomplete the wiki's existing tag vocabulary

• Assets — upload a file and get back a ready-to-paste markdown reference; list assets and create folders

Related MCP server: requarks-wiki-mcp

What it deliberately cannot do

No moving, renaming, or deleting pages. Those break inbound links or lose content, and a mistyped path is exactly the error a model makes. Do them in the ok-wiki UI. The boundary is enforced twice — the tools don't exist, and the API key's group withholds delete:pages and manage:pages. Reasoning: docs/adr/0005.

Also out of scope: comments, navigation, users and groups, theming, and administrative operations.

Quickstart

1. Build

cd /home/obe/wiki-skills
npm install
npm run build          # MCP registration points at dist/index.js, not src/

2. Enable the ok-wiki API

In the wiki: Administration → API Access → enable. Without this, every request is rejected with "API is disabled. You must enable it from the Administration Area first."

3. Mint a scoped API key

Create a group for the connector granting exactly:

read:pages, read:source, write:pages, read:history, read:assets, write:assets, manage:pages

Grant them in both the group's global permissions and its page rules — the wiki checks both layers. manage:pages looks like more than a reader needs, but the wiki's single-page resolvers require it: without it, page lookups fail with "You are not authorized to view this page" even though listing works (docs/ok-wiki-api.md §4).

Then Administration → API Access → New API Key, bound to that group.

read:source is the one that fails quietly if you forget it — pages come back with a null body instead of an error. Use a dedicated key so it can be revoked independently and so wiki history distinguishes agent edits from human ones. Details: docs/ok-wiki-api.md §2.

4. Register with Claude Code

claude mcp add wiki \
  --env WIKI_BASE_URL=http://localhost:3000 \
  --env WIKI_API_KEY=<your-api-key> \
  -- node /home/obe/wiki-skills/dist/index.js

Or, to share it with a project via .mcp.json:

{
  "mcpServers": {
    "wiki": {
      "command": "node",
      "args": ["/home/obe/wiki-skills/dist/index.js"],
      "env": {
        "WIKI_BASE_URL": "http://localhost:3000",
        "WIKI_API_KEY": "${WIKI_API_KEY}"
      }
    }
  }
}

Prefer the ${VAR} form in any file you might commit — don't put the key in version control.

5. Verify

Run /mcp in Claude Code and confirm wiki is connected with its tools listed. Then ask for something read-only, like "search the wiki for onboarding", to exercise wiki_search_pages.

Configuration

Documentation

If you read only one thing before writing code, make it docs/adr/0004: ok-wiki's pages.update is a full replace, not a patch, and a naive implementation silently unpublishes pages and drops their tags.

Troubleshooting

License

MIT