okc-mcp

Status: Inception review pending. The feature and installation documentation below describes an unapproved implementation draft. Construction began before the requirements review; that process error has been recorded and further implementation is paused. Confirm the product scope and success criteria in the Inception review proposal first.

A local Obsidian Vault authoring MCP for building high-quality knowledge inputs for OKC.

Create Markdown notes without the Obsidian app, plugins, or API keys; read and search existing notes; and audit frontmatter, links, duplicates, and input quality. OKC remains responsible for actual integration, review, and compilation.

The current local implementation is 0.1.0-alpha.1 and has not been published to npm. It requires Node.js 22.13+. Actual validation environments and limitations will be recorded in a Construction validation log after that phase is authorized.

Install and connect

Build the package from this repository and install it locally.

npm ci
npm run check
npm pack
npm install -g ./okc-mcp-0.1.0-alpha.1.tgz

Generate a configuration using the absolute path of an existing Vault. Store the configuration outside the Vault.

okc-mcp config --vault /absolute/path/to/MyVault > /absolute/path/to/okc-mcp.json
okc-mcp doctor --config /absolute/path/to/okc-mcp.json
okc-mcp client-config --config /absolute/path/to/okc-mcp.json

Merge the mcpServers entry printed by client-config into your MCP client's configuration. Preserve any other server settings. The generation command never edits another application's configuration automatically. Configuration screens and wrapper objects vary by client, but the connection uses standard stdio. The output includes absolute paths to the installed Node executable and server file to reduce PATH differences in GUI applications.

To run from the development tree without installing, use node dist/cli.js instead of okc-mcp in the commands above. To run the server directly, use the following command; stdin and stdout are reserved for the MCP protocol after startup.

okc-mcp serve --config /absolute/path/to/okc-mcp.json

First use

Ask the connected AI client something like:

Read the authoring guidance and find notes about HTTP caching in my Vault. Draft a new note that distinguishes claims from the sources I provided, apply it, and then audit its quality as OKC input. Do not invent missing sources.

Authoring guidance is available through the okc://guide/authoring resource and the capture_knowledge prompt. The authoring tools default dryRun to true. A result with applied: false is only a preview; call the tool with dryRun: false to save the change. That argument does not prove separate human approval.

The offset and length used for partial reads count JavaScript string characters, not bytes or line numbers. Lists, searches, and audits use offset and limit; continue with nextOffset. Read and review the entire range before editing a long note. Use the expectedHash returned by read_note.

What makes a good Vault for OKC

You do not need to reorganize an existing Vault. For a new Vault, a shallow structure such as inbox/, notes/, sources/, and maps/ is a reasonable starting point. What matters is one clear claim per paragraph, nearby sources, unambiguous links, and metadata that is not needlessly repetitive.

Fields such as source, status, and type, beyond title, aliases, and tags, are optional authoring conventions. Do not assume that OKC interprets them as approval, publication permission, or classification policy. Keep templates, MCP configuration, backups, and operational documents outside the Vault so they do not become input knowledge.

MyKnowledge/
├── AuthoringVault/        ← edited by Obsidian and this MCP
│   ├── inbox/
│   ├── notes/
│   ├── sources/
│   └── maps/
├── tooling/
│   └── okc-mcp.json
├── Knowledge.okc-project/ ← OKC work and review state
└── artifacts/             ← preserved OKC outputs

Backups and locks live under the configured statePath. By default, this is .local/state/okc-mcp/<vault-id> under the user's home directory; neither a path inside the Vault nor a path containing the Vault is allowed. OKC registers the authoring Vault separately as a source and captures snapshots. Changes made after a snapshot become input to the next capture. Resulting artifacts and .okc-project directories are not editable targets for this MCP.

See the authoring guide and OKC Vault design for detailed examples.

Configuration and troubleshooting

Every path in the example configuration is absolute. With readOnly: true, the server does not register any of the three authoring tools. Diagnostics check paths and scan access; they do not guarantee write access or compiler compatibility.

Current guarantees and limitations

• All note-query results are sent to the MCP host. The server itself does not call AI services, remote search, or telemetry. If the host uses a remote model, the host's data-handling policy applies.

• Input auditing uses selected OKC 0.3.0 sources as authoring heuristics. It does not replace compiler validation, complete Obsidian link interpretation, sensitive-data detection, or factual verification.

• OKC still has release requirements around preserving attachments, Canvas, and Base files and fully rewriting links.

• Hash checks and file replacement do not provide operating-system compare-and-swap with external Obsidian or Sync processes. Avoid editing the same note concurrently. Backups and observed stale-hash checks support recovery and conflict review.

• Node path checks do not claim complete isolation from malicious concurrent replacement of ancestor directories. Environments where uncontrolled processes replace the filesystem are unsupported.

• Delete, rename, automatic folder moves, snapshot export, OKC approval, compilation, and semantic search are not currently exposed as tools.

Design and development

The official AI-DLC 2.7.1 Codex workflow is installed in this project. In a new Codex conversation, run $aidlc --doctor and follow the setup and usage guide. The product is still awaiting Inception review; installing the workflow does not record approval to enter Construction.

• AWS AI-DLC application proposal

• Source review of four existing Obsidian MCPs

• Requirements · Implementation design

• Repository and installation UX · Contributing

• Current status and follow-up units · Requirements traceability (to be created during Construction)

This product implements the protocol with the MCP SDK. User-facing semantics for Obsidian links and properties follow the official Obsidian Help documentation. Differences from actual OKC parser behavior are documented as audit limitations.