obsidian-mcp-server: Instructions file for Codex

Agent Protocol

Server: obsidian-mcp-server Version: 3.7.0 Framework: @cyanheads/mcp-ts-core ^0.13.12 Engines: Bun ≥1.4.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.2.0 Zod: ^4.6.5

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

---

What's Next?

When the user asks what to do next, what's left, or needs direction, suggest relevant options based on the current project state:

1. Re-run the setup skill — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
2. Run the design-mcp-server skill — if the tool/resource surface hasn't been mapped yet, work through domain design
3. Add tools/resources/prompts — scaffold new definitions using the add-tool, add-app-tool, add-resource, add-prompt skills
4. Add services — scaffold domain service integrations using the add-service skill
5. Add tests — scaffold tests for existing definitions using the add-test skill
6. Field-test definitions — exercise tools/resources/prompts with real inputs using the field-test skill, get a report of issues and pain points
7. Run devcheck — lint, format, typecheck, and security audit
8. Run the security-pass skill — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
9. Run the polish-docs-meta skill — finalize README, CHANGELOG, metadata, and agent protocol for shipping
10. Run the maintenance skill — investigate changelogs, adopt upstream changes, and sync skills after bun update --latest

Tailor suggestions to what's actually missing or stale — don't recite the full list every time.

---

Core Rules

• Logic throws, framework catches. Tool/resource handlers are pure — throw on failure, no try/catch. Plain Error is fine; the framework catches, classifies, and formats. Use error factories (notFound(), validationError(), etc.) when the error code matters.
• Use ctx.log for request-scoped logging. No console calls.
• The delete confirmation is opt-in; when on, it is gated on a consent record. OBSIDIAN_DELETE_ELICITATION (default false) decides whether obsidian_delete_note confirms through ctx.requestInput. Off is the default for two reasons: a client that declares elicitation but cannot render the form declines every round automatically, which the server cannot tell from a real decline (#151), and the round forces a stateful HTTP session, which locks out MCP_SESSION_MODE=stateless. Off, OBSIDIAN_WRITE_PATHS / OBSIDIAN_READ_ONLY bound what a delete can reach — the same bound obsidian_write_note with overwrite: true has — and destructiveHint stays for client-side approval. The mode is the operator's choice alone: never derive it from ctx.clientCapabilities or from a decline. On, the handler redeems (reads and deletes) the ctx.state record named by ctx.inputs.state() before anything else, checks write scope on the resolved path before it reads the note or asks, and acts on the ctx.inputs answer only when that record deep-equals { operation, clientId, subject, target, contentHash } for this call; otherwise it stores a fresh record (ttl: 600) and return ctx.requestInput(...) with the record id as requestState. An answer alone is never proof the user was asked. Never await user input mid-handler.
• All Obsidian access goes through getObsidianService(). No direct fetch() calls to the Local REST API in tools/resources — the service centralizes auth, TLS, timeouts, and ctx.signal propagation.
• Secrets in env vars only. OBSIDIAN_API_KEY is required; never hardcoded.
• Cut noise. Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
• Command-palette tools are opt-in. obsidian_list_commands and obsidian_execute_command are callable only when OBSIDIAN_ENABLE_COMMANDS=true — Obsidian commands are opaque and can be destructive. When the flag is unset, the entry point wraps both with disabledTool() so they're absent from tools/list (LLM can't invoke) but visible in the operator-facing manifest with a hint to enable them.
• Path-policy gating goes through PathPolicy. Every path-taking method on ObsidianService calls policy.assertReadable / assertWritable before the upstream HTTP call; listFiles gates with assertListable and filters entries with filterListing (readable entries plus folders on the way to the scope), so every listing consumer inherits the scope; obsidian_search_notes post-filters hits via svc.policy.filterReadable, and listTags collects per-note tags through it when policy.restrictsReads. Don't bypass this — OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS / OBSIDIAN_READ_ONLY are the single chokepoint, and path_forbidden is declared on every path-taking tool's errors[] contract.
• Close the loop on issues. When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.