ai-wiki-mcp

A small, wiki-aware MCP server over the ai-wiki/ markdown knowledge base. It replaces the Obsidian + cyanheads/obsidian-mcp-server stack: agents (Claude Code, Hermes, Open WebUI) operate the wiki over a single streamable-HTTP MCP endpoint, while the files stay plain markdown on disk.

Why a purpose-built server instead of a generic filesystem MCP:

• Structured search — recovers the frontmatter querying Obsidian's dataview gave us (lost on leaving Obsidian).
• Schema-validated writes — frontmatter crosses the wire as JSON and is emitted as real YAML; the old "['a','b']" array-mangling bug is impossible by construction.
• Server-side lint — one wiki_lint call runs every structural check instead of dozens of agent round-trips.

Tools

Tool	Purpose
wiki_list	directory snapshot of notes (optional frontmatter)
wiki_read	read a note; full | map | section projections
wiki_search	full-text (ripgrep) and/or structured frontmatter filter
wiki_write	create/overwrite a note with validated, structured frontmatter
wiki_edit	surgical body edit (replace_section/append/replace_text); frontmatter untouched
wiki_set_frontmatter	structured frontmatter mutation; taxonomy-checked tags
wiki_lint	all structural checks server-side; pure read
wiki_archive	move a page to _archive/; report inbound links to fix

Structured search filter DSL

{"type": "concept"}                  # scalar equality
{"confidence": ["high", "medium"]}   # scalar membership
{"tags.contains": "domain/ai"}       # list contains
{"tags.contains_any": [...]}         # list intersects
{"tags.contains_all": [...]}         # list superset
{"missing": ["sources"]}             # keys absent
{"present": ["contested"]}           # keys present

Schema

Validation is driven by <wiki>/.schema.yaml (see .schema.yaml.example), the machine-readable source of truth for frontmatter rules and the tag taxonomy. The human-readable ai-wiki/SCHEMA.md is kept in sync (a wiki_lint drift check guards this). The file is stat-reloaded on change, so adding a domain takes effect without a restart. With no .schema.yaml, validation degrades to warn-not-block.

Configuration

Env	Default	Meaning
WIKI_ROOT	/wiki	wiki tree root (bind-mounted)
AI_WIKI_MCP_HOST	0.0.0.0	bind host
AI_WIKI_MCP_PORT	3010	port; endpoint path is /mcp

Metrics

Prometheus metrics are served unauthenticated at GET /metrics on the same AI_WIKI_MCP_PORT as /mcp (no extra port to expose). They cover per-tool call counts/latency/errors plus scrape-time wiki state — file count and size by layer, wikilink totals, broken/ambiguous/orphan links, and lint findings by severity. All metric names are prefixed ai_wiki_mcp_. The wiki gauges are recomputed on each scrape, so keep the scrape interval at 15s or longer.

Web UI

A read-only viewer is served at GET /app on the same AI_WIKI_MCP_PORT as /mcp (no extra port to expose; / redirects to /app/). It gives a navigable file tree, a force-directed link graph (nodes sized by wikilink degree, broken/orphan markers), search (client-side fuzzy jump + server full-text and the frontmatter filter DSL), click-through [[wikilink]] navigation, and markdown rendering with a render⇄source toggle. It is a no-build vanilla-JS SPA reading a small JSON API (/app/api/{tree,page,graph,index,search,stats}); third-party libraries are vendored under static/vendor/ so it works offline. Read-only: no write/edit endpoints are exposed.

Develop

uv sync
uv run pytest          # offline against tests/fixtures/wiki
uv run ruff check src tests
uv run ai-wiki-mcp     # serve (set WIKI_ROOT first)

Docker: docker build -t ai-wiki-mcp . then run with -v <wiki>:/wiki.

Releasing

Versioning is semver, single-sourced from [project].version in pyproject.toml.

• Every PR must bump the version (major/minor/patch). The version-check workflow fails a PR unless its pyproject.toml version is a valid X.Y.Z strictly greater than main's, so each merge produces a fresh tag. Bump with an edit + uv lock.
• Merging to main runs the release job (after lint + tests pass): it builds the image, publishes it to the Gitea container registry, and pushes a vX.Y.Z git tag.

Published image (Gitea built-in registry, direct endpoint):

docker pull 192.168.10.32:3000/jhonnold/ai-wiki-mcp:<version>   # or :latest
docker run --rm -p 3010:3010 -v <wiki>:/wiki \
  192.168.10.32:3000/jhonnold/ai-wiki-mcp:<version>