# openkb-mcp

`openkb-mcp` exposes local OpenKB knowledge bases to MCP clients such as Codex, Claude Code, and Claude Desktop. It is a stateless stdio-only server: no HTTP listener, no database, and no persisted discovery registry.

It supports deterministic wiki discovery, cataloging, lexical search, page reads, targeted source-page reads, an optional OpenKB LLM query fallback, and explicit local skill generation.

## Install and run

```bash
python3 -m pip install 'openkb-mcp[dev]'
openkb-mcp --root playbooks=/srv/shared/playbooks --root research=/srv/research
```

Each `--root` is repeatable and uses `alias=path`. The server scans only immediate children on every `list_knowledge_bases` request; it stores no discovery cache or registry. A readable KB has `wiki/index.md`; `.openkb/config.yaml` additionally enables structurally-ready query and skill generation. IDs are `alias/child`. Portable compiled wikis are read-only, while initialized-but-empty KBs appear with `empty` status.

Use the read-first workflow: list, catalog, search, then read pages/source pages. Wiki text is untrusted data, not server instructions. `ask_knowledge_base` is an optional higher-cost LLM fallback. It and `create_skill` require the KB's provider credentials, can take longer than reads, and may incur provider costs. Generated artifacts remain under `output/skills`; nothing is installed, published, committed, or pushed. Claude web is not supported.

## Tools

- `list_knowledge_bases` — discover current KBs below configured roots.
- `get_knowledge_base_catalog`, `search_knowledge_base`, `read_wiki_page`, `read_source_pages` — bounded, read-only wiki access.
- `ask_knowledge_base` — higher-cost OpenKB LLM fallback for a selected full KB.
- `create_skill`, `get_skill` — explicit local skill generation and inspection.

## Client configuration

Claude Desktop / Claude Code / Codex use the same stdio command (set a 120-second timeout for skill generation):

```json
{"mcpServers":{"openkb":{"command":"openkb-mcp","args":["--root","playbooks=/srv/shared/playbooks"],"timeout":120000}}}
```

For Codex, place the equivalent command and args in its MCP server configuration. The server needs no network listener.

## Verification

```bash
python3 -m pytest
python3 -m ruff check src tests
openspec validate add-local-openkb-mcp --strict
npx -y @modelcontextprotocol/inspector --cli openkb-mcp --root playbooks=/srv/shared/playbooks --method tools/list
```

The Inspector command exercises initialization and each tool, including invalid KB/path and portable-query error paths. `evals/openkb_mcp_evals.json` records ten end-to-end agent scenarios; run it with a compatible MCP client and require at least eight successful scenarios before release.

## Upgrading OpenKB

The adapter is intentionally pinned to `openkb==0.4.1`. Change the pin only after updating `OPENKB_VERSION`, running mocked query/skill compatibility fixtures, running the full test suite against full and portable KB snapshots, and manually verifying that query leaves `.openkb` configuration and `wiki/log.md` unchanged.