obsidian-mcp-rs: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Build / run
cargo build                              # debug
cargo build --release                    # release (LTO, opt-level=3, stripped)
cargo run -- /path/to/vault              # run server against a vault
cargo run -- --no-edit /path/to/vault    # read-only mode

# Tests
cargo test                               # all tests (the unit tests live in the lib target)
cargo test --lib <name>                  # single test — tests compile under the lib crate

# Benchmarks (criterion, harness = false; see benches/vault_bench.rs)
cargo bench                              # run search / rename_tag benchmarks
RAYON_NUM_THREADS=1 cargo bench          # single-threaded baseline for comparison
cargo bench --no-run                     # compile-only — this is what CI gates on

# Lint gates enforced by CI (.github/workflows/ci.yml)
cargo fmt --check
cargo clippy -- -D warnings

# Coverage (matches CI)
cargo llvm-cov --lcov --output-path lcov-rust.info

# Cross-platform check (CI matrix: aarch64/x86_64 darwin, x86_64 linux gnu+musl, x86_64 windows-msvc)
cargo check --target <triple>

# npm wrapper (in npm/obsidian-mcp-rs/)
npm install && npm run build && npm test   # TS build + vitest

Toolchain is pinned to stable (rust-toolchain.toml); MSRV is 1.88. rustfmt: 100-col, 4-space, edition 2024. clippy.toml sets msrv = "1.88.0".

Architecture

This is a Rust library (src/lib.rs, crate obsidian_mcp_rs) holding all domain logic, with a thin binary (src/main.rs) that wires up the CLI/logging and speaks MCP over stdio. Splitting lib/bin lets benches/ and integration tests link against the code. There is also an npm wrapper that distributes prebuilt binaries via the optional-dependencies pattern.

Transport invariant (do not break)

The http cargo feature (off by default) adds a Streamable HTTP transport (src/http.rs, --http). It does not relax the stdout rule: stdio mode must stay sterile, and tests/mcp_stdio.rs proves it. The HTTP server validates the Origin header — the MCP spec requires it of local servers, and it is the only thing standing between a malicious web page and a vault the server will happily read and rewrite without authentication.