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:

FlagDefaultDescription
--transport <stdio|http>stdioServe over stdio, or over HTTP
--host <HOST>127.0.0.1Address to bind to (only used with --transport http)
--port <PORT>8000Port 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

ToolDescription
iwe_findSearch documents with fuzzy matching and relationship filters
iwe_retrieveFetch documents with search seeds and graph expansion
iwe_treeView hierarchical document structure
iwe_statsGet knowledge graph statistics and broken link reports
iwe_squashExpand block references into a single flat document

Writing

ToolDescription
iwe_createCreate a document at a key from a complete markdown document
iwe_updateReplace the full content of an existing document
iwe_deleteDelete 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 }

ParameterDescription
keyRequired. 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.
contentRequired. 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). 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

ToolDescription
iwe_queryRun 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:

ParameterDescription
searchBM25 full-text seed query (lexical). Present → the tool searches the candidate set (keys / selector) and reads the ordered seeds.
fuzzyFuzzy seed query on title + key. Combine with search to fuse (RRF).
expandObject 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.
limitCap the number of seed documents kept before expansion — top-N by relevance when searching, the first N of the selection otherwise (0 = unlimited).
max_documentsCap 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

ToolDescription
iwe_renameRename a document key with automatic link updates
iwe_extractExtract a section into a new document with block reference
iwe_inlineReplace a block reference with the referenced content
iwe_normalizeRe-format all documents for consistent formatting
iwe_attachAttach 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:

PromptDescription
exploreGet an overview of the knowledge graph with key statistics
reviewReview a specific document with full context
refactorAnalyze a document and suggest restructuring operations

Resources

The server exposes knowledge graph data as MCP resources:

URIDescription
iwe://documents/{key}Individual document content
iwe://treeFull hierarchical document tree
iwe://statsAggregate knowledge graph statistics
iwe://configConfiguration 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

PreviousIWE UpdateNextEditors

Search

Loading pages…