Local workspace and MCP

The local AI workspace is deterministic and model-free. It gives tools a bounded Markdown root, an inspectable index, and explicit write permission without exposing arbitrary shell execution. No model, API key, endpoint, embeddings service, or network is required.

Initialize, index, and audit

pnpm silen ai init docs
pnpm silen ai index docs
pnpm silen ai audit docs
pnpm silen ai eval docs

ai init creates wiki/ and the ignored .silen/ai/ cache without changing existing MDX. ai index rebuilds the optional .silen/ai/index.json workspace snapshot. ai audit checks links, citations, generated artifacts, and the production contract. A missing or stale snapshot is only a notice because MCP search uses an in-memory index.

Build, audit, and evaluate

pnpm silen build docs
pnpm silen ai audit docs
pnpm silen ai eval docs

ai eval reads .silen/ai-evals.json and the production .silen/dist/search-index.json; it neither starts MCP nor calls a model or the network. Version 1 uses one route and optional heading within topK. Version 2 adds optional expected.maxRank. Strict "schemaVersion": 3 requires present acceptable and forbidden arrays, at least one target between them, and an explicit maxRank from 1 through topK. Negative-only cases use acceptable: [] and maxRank: topK.

Version 3 reports matchedRank: null when no acceptable target appears and lists prohibited hits in forbiddenMatches. Exit 0 means every case passed, exit 1 means a retrieval expectation failed, and exit 2 means the suite or input is invalid. The full diagnostic Top K remains in stable case order.

For the Silen repository, pnpm site:ai-check composes the complete read-only gate and saves exact evaluation JSON at artifacts/ai-eval/site-ai-eval.json. The optional .silen/ai/index.json snapshot remains non-blocking and does not replace the production search index.

Connect an MCP client

Run the server from the repository root:

{
  "mcpServers": {
    "silen": {
      "command": "pnpm",
      "args": ["silen", "mcp", "docs"]
    }
  }
}

The default server registers seven read-only tools: guide, list, search, read, backlinks, citations, and build. The build tool is a bounded preflight: it reads Markdown inputs and existing artifacts but does not load project config, execute MDX, invoke Vite, or write files.

Protocol and structured results

The command uses the stable split TypeScript SDK v2. One stdio entry accepts verified legacy 2025-11-25 and modern 2026-07-28 clients; see the official protocol-version guide. The server is read-only by default. Every successful tool call includes text and schema-validated structuredContent, and every listed tool declares an outputSchema. Remote transport is not enabled.

For the string-valued guide tool, modern clients receive the native string; legacy clients receive the SDK's compatibility { result: ... } object. The object-valued tools keep their existing structured shape in both eras.

Experimental Skills over MCP

Filesystem installation does not require MCP. Hosts that explicitly support the draft Resources binding can opt into the same packaged bytes:

pnpm silen mcp docs --experimental-skills-over-mcp

The experiment declares io.modelcontextprotocol/skills, serves skill://index.json, and maps the five files beneath skill://silen-docs-readonly/. It is local stdio only and read-only. The experiment is off by default. It adds no tools, scripts, subscriptions, network transport, or write authority; --allow-write remains a separate explicit tool-registration flag.

Grant writes deliberately

pnpm silen mcp docs --allow-write

This explicit flag adds write, link, and append. Writes accept only workspace-relative .md or .mdx paths, reject traversal and escaping symlinks, use atomic replacement, and enforce a 2 MiB UTF-8 limit. It never adds a shell tool.

Grant write mode only to a trusted local client for a bounded task. After a change, run the audit and site build, inspect the Git diff, and obtain separate authorization before committing or deploying.

Ask AI is separate: it requires an explicitly configured endpoint. With no endpoint, Silen emits neither the control nor its bundle.

Read Agent Contract for client discovery rules.