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:
| Flag | Default | Description |
|---|---|---|
--transport <stdio|http> | stdio | Serve over stdio, or over HTTP |
--host <HOST> | 127.0.0.1 | Address to bind to (only used with --transport http) |
--port <PORT> | 8000 | Port to listen on (only used with --transport http) |
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.
Tools
The MCP server exposes 14 tools for reading, writing, querying, and refactoring documents.
Reading
| Tool | Description |
|---|---|
iwe_find | Search documents with fuzzy matching and relationship filters |
iwe_retrieve | Fetch documents with search seeds and graph expansion |
iwe_tree | View hierarchical document structure |
iwe_stats | Get knowledge graph statistics and broken link reports |
iwe_squash | Expand block references into a single flat document |
Writing
| Tool | Description |
|---|---|
iwe_create | Create a document at a key from a complete markdown document |
iwe_update | Replace the full content of an existing document |
iwe_delete | Delete a document and clean up all references |
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 }
| Parameter | Description |
|---|---|
key | Required. The document’s stable identity — draw it from metadata (an entity name, a session date), not the title wording. Subdirectory keys such as people/ada are allowed; omit the file extension. |
content | Required. Frontmatter block first (when there is one), then the markdown, normally starting with # Title. |
if_exists | "fail" (default) errors when the key is taken; "skip" leaves the existing document untouched and returns created: false, which makes retries idempotent. |
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).
indexpages (rootindexor 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
| Tool | Description |
|---|---|
iwe_query | Run a Query Language operation document verbatim |
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:
| Parameter | Description |
|---|---|
search | BM25 full-text seed query (lexical). Present → the tool searches the candidate set (keys / selector) and reads the ordered seeds. |
fuzzy | Fuzzy seed query on title + key. Combine with search to fuse (RRF). |
expand | Object over includes / includedBy / references / referencedBy → integer depths (0 = unbounded, omitted key = not followed). Follows those edges out from each seed. Expansion is doc-only when omitted. |
limit | Cap the number of seed documents kept before expansion — top-N by relevance when searching, the first N of the selection otherwise (0 = unlimited). |
max_documents | Cap the number of documents returned after expansion, trimming periphery documents first (0 = unlimited). |
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
| Tool | Description |
|---|---|
iwe_rename | Rename a document key with automatic link updates |
iwe_extract | Extract a section into a new document with block reference |
iwe_inline | Replace a block reference with the referenced content |
iwe_normalize | Re-format all documents for consistent formatting |
iwe_attach | Attach a document to a target using configured actions |
All write and refactoring tools support a dry_run parameter to preview changes before applying them.
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:
| Prompt | Description |
|---|---|
explore | Get an overview of the knowledge graph with key statistics |
review | Review a specific document with full context |
refactor | Analyze a document and suggest restructuring operations |
Resources
The server exposes knowledge graph data as MCP resources:
| URI | Description |
|---|---|
iwe://documents/{key} | Individual document content |
iwe://tree | Full hierarchical document tree |
iwe://stats | Aggregate knowledge graph statistics |
iwe://config | Configuration with templates and actions |
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.
From the blog
- Designing edit operations for AI agents Four lessons from designing IWE's block-edit language for AI agents: declared blast radius, identity as a constraint, recoverable failures, and errors that teach.
- The benchmark that built the tools A plain-Markdown knowledge graph as agent memory, measured on LOCOMO: it lost to grep, rebuilt our tools, and ended at parity with published memory systems.
- Five components of agent memory in plain Markdown The five things agent memory must do — persistence, structure, retrieval, writeback, forgetting — implemented as plain Markdown files and CLI queries, no vector database.
- My agent kept "remembering" things wrong. The fix was embarrassingly simple. Why structured Markdown beats embeddings for architectural knowledge: a vector store kept retrieving the similar-but-wrong note, so I moved to CLI-navigable notes.