ai-wiki-mcp

ai-wiki-mcp

A small, wiki-aware MCP server over the ai-wiki/ markdown knowledge base. Itreplaces the Obsidian + cyanheads/obsidian-mcp-server stack: agents (ClaudeCode, Hermes, Open WebUI) operate the wiki over a single streamable-HTTP MCPendpoint, 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 dataviewgave us (lost on leaving Obsidian).
• Schema-validated writes — frontmatter crosses the wire as JSON and isemitted as real YAML; the old "['a','b']" array-mangling bug is impossible byconstruction.
• Server-side lint — one wiki_lint call runs every structural check insteadof dozens of agent round-trips.

Tools

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), themachine-readable source of truth for frontmatter rules and the tag taxonomy. Thehuman-readable ai-wiki/SCHEMA.md is kept in sync (a wiki_lint drift checkguards this). The file is stat-reloaded on change, so adding a domain takes effectwithout a restart. With no .schema.yaml, validation degrades to warn-not-block.

Configuration

Metrics

Prometheus metrics are served unauthenticated at GET /metrics on the sameAI_WIKI_MCP_PORT as /mcp (no extra port to expose). They cover per-tool callcounts/latency/errors plus scrape-time wiki state — file count and size by layer,wikilink totals, broken/ambiguous/orphan links, and lint findings by severity. Allmetric names are prefixed ai_wiki_mcp_. The wiki gauges are recomputed on eachscrape, 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, aforce-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 ano-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 workflowfails a PR unless its pyproject.toml version is a valid X.Y.Z strictly greater thanmain'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 theimage, 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>