IWE: a Markdown knowledge base you and your AI agent work on together

MCP Server

IWE provides an MCP (Model Context Protocol) server that gives AI agents direct access to your knowledge graph. The MCP server exposes the same operations as the CLI — search, retrieve, create, refactor — through a standardized protocol that AI tools can use natively.

Setup

You configure the server by pointing your AI tool to the iwec binary and setting the working directory to your knowledge graph. By default it communicates over stdio, which is what most editor and agent integrations expect.

Transport options

iwec accepts two flags that control how it serves the protocol:

With --transport http the server listens for Streamable HTTP connections at http://<host>:<port>/mcp:

iwec --transport http --port 8000

By default the HTTP server binds to 127.0.0.1, so it only accepts connections from the local machine. To accept connections from other machines, bind to a reachable address:

iwec --transport http --host 0.0.0.0 --port 8000

The server speaks plain HTTP, so put a reverse proxy in front of it for TLS or authentication when exposing it beyond localhost.

Workspace and instructions

When several IWE servers are connected to one client, give each instructions that say what the workspace is for, so the agent picks the right one:

{
  "mcpServers": {
    "notes": {
      "command": "iwec",
      "args": [
        "--workspace", "/path/to/notes",
        "--instructions", "Personal notes. For engineering questions use the `docs` server."
      ]
    }
  }
}

For longer text, keep it in a file and pass --instructions-file /path/to/notes/.iwe/instructions.md instead. The two flags can't be used together.

Tools

The MCP server exposes 14 tools for reading, writing, querying, and refactoring documents.

Reading

Writing

iwe_create

iwe_create takes the complete document and writes it verbatim — the server adds nothing and moves nothing.

{
  "key": "people/ada",
  "content": "---\ntype: person\ntags: [pioneer]\n---\n\n# Ada Lovelace\n\nFirst English computer programmer.\n",
  "if_exists": "fail"
}

→ { "key": "people/ada", "created": true }

Because content is the whole file, frontmatter belongs at its first byte — that is where other tools read it. There is no separate frontmatter parameter to place it for you, and nothing is inserted above or below what you send. iwe_update has the same contract, with the opposite existence precondition.

The template, variables and frontmatter parameters are reserved for a later template mode and are rejected today.

Stats warnings

A successful iwe_create, iwe_update, or iwe_query (update / delete) may carry stats warnings alongside its result — one warning content block per finding, of the form <key> › <rule>: <message>:

• orphan — a page nothing links to (no inclusion or inline reference points at it). index pages (root index or any <dir>/index) are intentional entry points and are never reported as orphans.

• dangling-link — a link whose target document does not exist.

• similar-page — a just-authored page that is near-identical to another (only on create / update; see Detecting similar pages).

These warnings are advisory — nothing is ever blocked by them (schema validation remains the only hard reject). Each finding is reported once per session, so the first mutation surfaces the store's standing issues and later calls surface only what changed. Resolve reported warnings before ending the session; each carries the fix in its message.

The per-document iwe_stats result (call iwe_stats with a key) also carries a similarPages array — other documents near-identical to that page.

Query

iwe_query takes an operation kind (find, count, update, or delete) and the operation document as a YAML string, plus an optional dry_run for the mutating kinds. It exposes the full query surface: frontmatter and graph filters, the $content block-membership operator, the search stage on find (search: { lexical, fuzzy }), the $content / $blocks / $matches projection sources, and the block update operators ($replace, $replaceText, $insertBefore, $insertAfter, $append, $delete). find and count read; update applies frontmatter and block edits atomically per document; delete removes documents with reference cleanup.

The tool is always strict: every mutating application must carry an expect guard — the document-level expect on update / delete, plus one per block operator — or the operation is refused with the missing guards named. Use find with $blocks / $matches to locate targets and learn the counts before mutating. See Strict mode.

iwe_retrieve search and expansion

iwe_retrieve assembles reading context in one call. Beyond the selector parameters and token budgets, it accepts:

Output is seeds first (relevance order), then expansion. The edge-list toggles (backlinks, children) are unchanged. The pre-existing depth, context, and links parameters are deprecated aliases for expand's includes / includedBy / references; passing expand together with any of them is an error.

Refactoring

All write and refactoring tools support a dry_run parameter to preview changes before applying them. Schema validation still runs under dry_run, so a preview is rejected exactly when the real call would be.

Selector parameters

iwe_find, iwe_retrieve, and iwe_tree accept a structural selector embedded in their tool input: in, in_any, not_in, and max_depth. Each entry is either a bare key or { key, depth }. These are a convenience for the most common selection patterns; the full query surface — --filter-style documents, $-prefixed graph operators, block predicates, frontmatter and block mutation — is iwe_query, documented in the Query Language reference.

Unknown keys

keys on iwe_retrieve and iwe_tree, and key on every single-document tool and on the review / refactor prompts, name documents: an unknown key is an invalid_params error that lists every missing key. Selector anchors, exclude, and keys used as the candidate set for search / fuzzy are filters and may match nothing. See Named Keys vs Filters.

Prompts

The server provides three built-in prompts that guide AI agents through common workflows:

Resources

The server exposes knowledge graph data as MCP resources:

File watching

The MCP server watches the knowledge graph directory for changes. When you edit markdown files in your editor, the server automatically updates its in-memory graph. There is no need to restart the server after making changes.

Consistency

• Each tool call works on the graph in one step. Writes run one at a time; reads run alongside each other but never alongside a write, including updates from the file watcher. A read that arrives while a write is waiting runs after that write.

• A call that starts after an MCP write returned sees that write. A multi-file operation (rename, delete, extract, inline, attach, query update or delete) that succeeds becomes visible as a whole.

• A call runs to completion even if the client cancels it.

• If writing files fails, the tool returns an error. Some files may already be changed; the server re-reads every note the call touched, so the graph shows what reached disk.

• Edits made outside the server (CLI, editor, git) are picked up by the file watcher shortly after, with no ordering across files. A note that another program is still writing can briefly appear incomplete until its next change event. Hidden and gitignored files are not watched.

• Clients that need to share one graph should connect to a single --transport http server: all its sessions share one graph. With stdio each client starts its own server with its own graph.

• A sequence of calls is not a transaction. To publish several related notes, write the new notes first, then one note that points to them.