obsidian-native-mcp 1.0.3 → 1.2.0

package/.github/workflows/ci.yml

@@ -2,74 +2,102 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
+      - master
+      - develop
+      - "feature/**"
+      - "renovate/**"
   pull_request:
-    branches: [main]
+  workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
-  lint:
-    name: Lint and Type Check
+  setup:
+    name: Setup
     runs-on: ubuntu-latest
+    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]')
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+
+  format:
+    name: Format
+    needs: setup
+    runs-on: ubuntu-latest
+    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
           cache: npm
       - run: npm ci
-      - run: npm run lint
       - run: npm run format:check
-      - run: npm test
-      - run: npm run check
 
-  build:
-    name: Build
-    needs: lint
+  lint:
+    name: Lint
+    needs: setup
     runs-on: ubuntu-latest
+    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]')
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version-file: .nvmrc
           cache: npm
       - run: npm ci
-      - run: npm run build
-      - run: npm run build:plugin
-      - uses: actions/upload-artifact@v4
+      - run: npm run lint
+
+  typecheck:
+    name: Typecheck
+    needs: setup
+    runs-on: ubuntu-latest
+    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          name: dist
-          path: dist/
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run check
 
-  release:
-    name: Release
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    needs: build
+  test:
+    name: Test
+    needs: setup
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      issues: write
-      pull-requests: write
-      id-token: write
+    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]')
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          fetch-depth: 0
-          persist-credentials: false
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  build:
+    name: Build
+    needs: [format, lint, typecheck, test]
+    runs-on: ubuntu-latest
+    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]')
+    steps:
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version-file: .nvmrc
           cache: npm
       - run: npm ci
-      - name: Install npm with OIDC support
-        run: npm install --no-save npm@11.5.1
       - run: npm run build
-      - name: Semantic Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          export PATH="$PWD/node_modules/.bin:$PATH"
-          npm --version
-          npx semantic-release
+      - run: npm run build:plugin
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

package/.github/workflows/release.yml

@@ -0,0 +1,152 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types:
+      - completed
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: Optional note for this manual release.
+        required: false
+        default: ""
+
+concurrency:
+  group: release-${{ github.event.workflow_run.head_branch || github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  checks: read
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+env:
+  RELEASE_ALLOWED_ACTORS: "usrivastava92"
+
+jobs:
+  authorize:
+    name: Authorize actor
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check triggering actor against allow-list
+        env:
+          ACTOR: ${{ github.triggering_actor }}
+          ALLOWED: ${{ env.RELEASE_ALLOWED_ACTORS }}
+        run: |
+          echo "Triggered by: $ACTOR"
+          echo "Allow-list:   $ALLOWED"
+          if printf '%s' ",$ALLOWED," | tr -d ' ' | grep -q ",${ACTOR},"; then
+            echo "$ACTOR is authorized to trigger releases."
+          else
+            echo "$ACTOR is NOT in RELEASE_ALLOWED_ACTORS." >&2
+            echo "Update the allow-list in .github/workflows/release.yml if needed." >&2
+            exit 1
+          fi
+
+  verify-ci:
+    name: Verify CI passed
+    needs: authorize
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ensure target commit passed CI build
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const ref = context.sha;
+            const { data } = await github.rest.checks.listForRef({
+              owner,
+              repo,
+              ref,
+              per_page: 100,
+            });
+
+            const buildCheck = data.check_runs.find((run) => run.name === 'Build');
+
+            if (!buildCheck) {
+              core.setFailed(`No 'Build' check found for ${ref}. Run CI on this commit before releasing.`);
+              return;
+            }
+
+            if (buildCheck.status !== 'completed' || buildCheck.conclusion !== 'success') {
+              core.setFailed(
+                `'Build' check for ${ref} is ${buildCheck.status}/${buildCheck.conclusion ?? 'null'}. ` +
+                  `Release requires a successful CI run first.`,
+              );
+            }
+
+  release-auto:
+    name: Release npm package
+    if: |
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - run: npm ci
+
+      - name: Install npm with OIDC support
+        run: npm install --no-save npm@11.5.1
+
+      - run: npm run build
+
+      - name: Semantic Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          export PATH="$PWD/node_modules/.bin:$PATH"
+          npm --version
+          npx semantic-release
+
+  release-manual:
+    name: Release npm package (manual)
+    needs: verify-ci
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Record trigger reason
+        if: ${{ inputs.reason != '' }}
+        run: echo "Manual release reason - ${{ inputs.reason }}" >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - run: npm ci
+
+      - name: Install npm with OIDC support
+        run: npm install --no-save npm@11.5.1
+
+      - run: npm run build
+
+      - name: Semantic Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          export PATH="$PWD/node_modules/.bin:$PATH"
+          npm --version
+          npx semantic-release

package/.husky/commit-msg

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+
+message_file="$1"
+subject="$(head -n 1 "$message_file")"
+
+if printf '%s' "$subject" | grep -Eq '^(Merge|Revert )'; then
+  exit 0
+fi
+
+if printf '%s' "$subject" | grep -Eq '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?(!)?: .+'; then
+  exit 0
+fi
+
+echo "Invalid commit message format."
+echo "Expected Conventional Commits, for example:"
+echo "  feat: add MCP file management tools"
+echo "  fix(cli): handle missing vault config"
+exit 1

package/.nvmrc

@@ -0,0 +1 @@
+22

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-## [1.0.3](https://github.com/usrivastava92/obsidian-native-mcp/compare/v1.0.2...v1.0.3) (2026-05-14)
+# [1.2.0](https://github.com/usrivastava92/obsidian-native-mcp/compare/v1.1.0...v1.2.0) (2026-05-21)
 
 
-### Bug Fixes
+### Features
 
-* align MCP transports with opencode and add smoke coverage ([3d4a072](https://github.com/usrivastava92/obsidian-native-mcp/commit/3d4a07282331b7251a71ff13545fcf3ced644c99))
+* v1.0 complete rewrite — LLM-optimized MCP server ([3215b40](https://github.com/usrivastava92/obsidian-native-mcp/commit/3215b40a12a241dcad001532efa6021d33f12465))

package/DEVELOPER.md

@@ -1,158 +1,210 @@
 # Developer Guide
 
+Engineering reference for **obsidian-native-mcp v1.0**. For the user-facing tool surface, see `README.md`. For design rationale and invariants, see `DESIGN_V1.md`.
+
 ## Architecture
 
 ```
 src/
-  cli/index.ts              CLI entry — reads config, starts stdio transport
+  cli/index.ts           # CLI entry — reads config, starts stdio transport
   plugin/
-    main.ts                 Obsidian plugin entry (extends Plugin)
-    settings.ts             Settings tab with vault picker + copy URL
+    main.ts              # Obsidian plugin entry (extends Plugin)
+    settings.ts          # Settings tab: vault picker, token, per-tool toggles, audit viewer
   mcp/
-    protocol.ts             JSON-RPC 2.0 types + Content-Length framing
-    transport.ts            Transport interface
-    stdio-transport.ts      Stdio transport (for CLI)
-    http-transport.ts       HTTP/SSE transport (for plugin)
-    server.ts               Transport-agnostic server — creates handlers + routes requests
+    framing.ts           # Content-Length framing (encode + buffered decode)
+    protocol.ts          # JSON-RPC 2.0 types + standard error codes
+    transport.ts         # Transport interface
+    stdio.ts             # Stdio transport (CLI)
+    http.ts              # HTTP/SSE transport with bearer token, origin allowlist,
+                         #   body cap, max-sessions, idle TTL, heartbeat, /healthz
+    server.ts            # createServer() factory — transport-agnostic request router
   handlers/
-    tools.ts                Tool implementations (9 tools)
-    prompts.ts              Prompt directory reader + template parser
+    registry.ts          # Declarative tool registry (no boilerplate per tool)
+    args.ts              # Typed argument parsers per tool kind
+  tools/
+    common.ts            # Shared types: ToolContext, ToolResult envelope
+    read.ts              # 14 read tools
+    write-basic.ts       # file.create, file.replace, file.append, file.move, file.delete
+    write-surgical.ts    # str_replace, apply_edits, lines.replace, lines.insert
+    write-structural.ts  # heading.*, block.*, frontmatter.set/delete
+    write-patch.ts       # apply_patch (unified diff parser)
+    write-bulk.ts        # bulk.apply (atomic), regex.replace (proposal-token)
+    index.ts             # Aggregate registry of all tools
+  prompts/
+    provider.ts          # Vault Prompts/ scanner + Templater-style arg parser
+  markdown/
+    parse.ts             # mdast parsing (gfm + frontmatter, no broken wiki-link dep)
+    parse-file.ts        # Glue: text → ParsedFile (ast + headings + blocks + links + tags + frontmatter + hashes)
+    fingerprint.ts       # Canonical normalization + sha256 helpers, lineOffsets
+    headings.ts          # AST-aware heading extraction, section bounds, disambiguation
+    blocks.ts            # ^block-id extraction with structural-type classification
+    links.ts             # Typed link extraction (wiki/embed/header/block/markdown) — fence-blind
+    tags.ts              # Tag extraction — fence-blind, URL-fragment-blind
+    frontmatter.ts       # YAML-backed nested get/set/delete preserving formatting
+    outline.ts           # Skeleton derivation from HeadingInfo
+  cache/
+    file-cache.ts        # LRU<path, ParsedFile> with mtime+size invalidation, write-through
+  fs/
+    io.ts                # readText, writeTextAtomic, ensureDir, uniquePath, fileExists
+    walk.ts              # Async recursive walker with ignore patterns
+    trash.ts             # <vault>/.obsidian/trash/ move with structure preserved
+    paths.ts             # Path-traversal guard, posix/native normalization
+  vault/
+    registry.ts          # VaultRegistry: env + config file + Obsidian auto-discovery
+    permissions.ts       # Read-only mode, per-tool toggle, per-vault subdir rules
+  audit/
+    log.ts               # JSONL audit log + sha256 args hashing + 5MB rotation
   utils/
-    fs-utils.ts             File I/O, frontmatter parsing, heading/block patching
-    search.ts               Recursive text search across .md files
-    vaults.ts               VaultRegistry — config from env, file, Obsidian auto-discovery
+    types.ts             # Canonical types: ParsedFile, HeadingInfo, BlockInfo, ExtractedLink, ToolError, etc.
+    log.ts               # Structured stderr logger (key=value)
 ```
 
-### Key Design Decisions
+### Layering rules
 
-**Zero dependencies.** The MCP protocol (JSON-RPC 2.0 over stdio with Content-Length framing) is implemented from scratch. No npm packages needed at runtime — only Node.js stdlib.
+1. `markdown/` and `fs/` are leaf modules — no dependencies on `tools/`, `handlers/`, or `mcp/`.
+2. `cache/` depends only on `markdown/` and `fs/`.
+3. `tools/` depends on `markdown/`, `fs/`, `cache/`, `audit/`, `vault/` — never on `mcp/` or `handlers/`.
+4. `handlers/` orchestrates `tools/` and wraps results into MCP responses.
+5. `mcp/` knows nothing about tools — just transports and JSON-RPC.
 
-**Node.js everywhere.** All I/O uses `fs` and `fs/promises` — runs on any platform Node.js supports. Obsidian plugin runs inside Obsidian's Electron. CLI runs standalone.
+### Key design decisions
 
-**Two transports, shared logic.** The `server.ts` exports a `createServer()` factory that returns tool definitions and a `handleRequest()` function. The stdio and HTTP/SSE transports both use the same factory — only the I/O layer differs.
+- **Surgical-first edits.** `str_replace` / `apply_patch` / `apply_edits` are the workhorses. Whole-file `file.replace` is the documented escape hatch.
+- **Hash-based concurrency.** Every read returns content hashes (file, range, section, block, frontmatter, line). Every write that targets an existing range requires the matching `expected_*_hash`. Stale precondition → structured `STALE_PRECONDITION` error with current hashes, never silent clobbering.
+- **Server is source of truth for hashes.** Clients echo opaque strings the server gave them. We never trust client-computed hashes.
+- **AST-aware everywhere.** mdast classifies code-fenced text as `code` nodes, HTML-commented blocks as `html` nodes — so heading/block/tag/link extractors get fence-safety _for free_.
+- **Real YAML for frontmatter.** We use the `yaml` package for round-trip preserving nested get/set/delete. No more hand-rolled line matching.
+- **Two transports, shared core.** `createServer()` returns `{handleRequest, toolDefinitions}`. Stdio and HTTP/SSE differ only in I/O layer.
+- **Process-atomic bulk writes.** `bulk.apply` with `atomic: true` snapshots originals in memory, applies all ops, writes, and restores on any failure.
 
-**Direct filesystem access.** Unlike `obsidian-mcp-tools` which communicates via HTTP with the Local REST API plugin, this server reads/writes files directly.
+## Development workflow
 
-**Multi-vault first.** The `VaultRegistry` supports env var, config file, and Obsidian auto-discovery.
+```bash
+npm install
+npm run dev              # tsx watch on the CLI
+npm run check            # tsc --noEmit
+npm run lint             # eslint src/
+npm run format           # prettier --write src/
+npm test                 # node:test runner across tests/**/*.test.ts
+npm run test:coverage    # c8 with --check-coverage thresholds
+npm run build            # tsc → dist/
+npm run build:plugin     # esbuild plugin bundle for Obsidian
+```
 
-## Development Workflow
+### Testing the CLI manually
 
 ```bash
-# Install dependencies
-npm install
+OBSIDIAN_VAULT_PATHS=/path/to/vault node dist/cli/index.js
+```
 
-# Run CLI in dev mode (watch + hot reload)
-npm run dev
+Then pipe in Content-Length framed JSON-RPC requests on stdin. The `tests/helpers/sandbox.ts` helper does this programmatically for tests.
 
-# Type-check
-npm run check
+### Testing the Plugin
 
-# Lint + format
-npm run lint
-npm run format
+1. `npm run build:plugin`
+2. Copy `dist/plugin/` to `<your-vault>/.obsidian/plugins/obsidian-native-mcp/`
+3. Reload Obsidian, enable in Community Plugins, open settings tab.
 
-# Build TS to dist/
-npm run build
+## Adding a new tool
 
-# Build plugin bundle for Obsidian
-npm run build:plugin
+1. Decide its layer: read-only, surgical write, structural write, whole-file write, or batch.
+2. Add the implementation to the right file under `src/tools/` (`read.ts`, `write-surgical.ts`, etc.).
+3. Export it via `src/tools/index.ts` so the aggregate registry picks it up.
+4. Add an argument parser in `src/handlers/args.ts` if its shape doesn't fit an existing one.
+5. Write tests:
+   - **Unit** for any pure helper logic (`tests/unit/...`).
+   - **Integration** for the tool itself (`tests/integration/<tool>.test.ts`).
+   - **Scenario** if it changes a multi-step LLM flow (`tests/scenarios/...`).
+6. Update the relevant table in `README.md` and the schema list in `src/tools/index.ts`.
 
-# Run CLI from compiled JS
-npm run start
+### Tool contract checklist
 
-# Test via env var
-OBSIDIAN_VAULT_PATHS=/path/to/vault node dist/cli/index.js
-```
+- Reads must return hashes the corresponding write expects (`contentHash`, `rangeHash`, `sectionHash`, `blockHash`, `frontmatterHash`, `lineHash`).
+- Writes that target existing ranges must accept `expected_*_hash` and return `STALE_PRECONDITION` on mismatch.
+- Mutating tools must support `dry_run: true` returning the _would-be_ new hashes without touching disk.
+- Errors must be `{ok: false, error: {code, message, ...details}}` — never throw across the JSON-RPC boundary.
+- Every mutating tool appends one audit-log line via `AuditLog`.
 
-### Testing the CLI
+## Test strategy
 
-```bash
-OBSIDIAN_VAULT_PATHS=/path/to/vault node --input-type=module -e '
-const msgs = [
-  {jsonrpc:"2.0",id:1,method:"initialize",params:{}},
-  {jsonrpc:"2.0",id:2,method:"tools/call",params:{name:"list_vaults",arguments:{}}},
-  {jsonrpc:"2.0",id:3,method:"tools/call",params:{name:"list_files",arguments:{vault:"default"}}},
-];
-let input = "";
-for(const m of msgs){ const s = JSON.stringify(m); input += "Content-Length: "+s.length+"\r\n\r\n"+s; }
-const {spawn} = await import("child_process");
-const child = spawn("node", ["dist/cli/index.js"], {stdio:["pipe","pipe","pipe"]});
-let buf = "";
-child.stdout.on("data", c => buf += c.toString());
-child.on("close", () => {
-  let remaining = buf;
-  while(true){
-    const m = remaining.match(/^Content-Length: (\d+)\r\n\r\n/);
-    if(!m) break;
-    const len = parseInt(m[1]), start = m[0].length;
-    if(remaining.length < start + len) break;
-    console.log(JSON.parse(remaining.slice(start, start + len)));
-    remaining = remaining.slice(start + len);
-  }
-});
-child.stdin.write(input);
-child.stdin.end();
-setTimeout(() => process.exit(0), 2000);
-'
-```
+| Layer       | Location             | What                                                                                                                                                                                                                                                                                           |
+| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Unit        | `tests/unit/`        | Pure-function correctness for `markdown/`, `fingerprint`, `frontmatter`, `headings`                                                                                                                                                                                                            |
+| Integration | `tests/integration/` | One file per tool family — permissions, blocks, apply_edits, audit, links, file-ops                                                                                                                                                                                                            |
+| Scenario    | `tests/scenarios/`   | Multi-tool LLM flows: S1 mark-tasks-done, S2 refactor section, S4/S5 concurrency, S6/S7 large file, S8 bulk rollback, S9 nested frontmatter, S10 code-fence safety, S11 no-fabrication, S12 apply_patch validation, S13 search pagination, S14 read-write roundtrip, S15 byte-budget benchmark |
+| Property    | (inline in unit)     | Round-trip and hash-stability invariants                                                                                                                                                                                                                                                       |
 
-### Testing the Plugin
+The headline benchmark (`S15`) asserts that a surgical workflow uses ≤ 30 % of the byte budget of the equivalent whole-file rewrite — that's the v1.0 thesis in test form.
 
-1. Build the plugin: `npm run build:plugin`
-2. Copy `dist/plugin/` to `<your-vault>/.obsidian/plugins/obsidian-native-mcp/`
-3. Reload Obsidian, enable the plugin in Community Plugins
-4. Open plugin settings to see discovered vaults
+### Fixtures
 
-## Adding a New Tool
+Under `tests/fixtures/vaults/`:
 
-1. Define the tool schema in `src/mcp/server.ts` — add to the `toolDefinitions` array
-2. Implement the handler in `src/handlers/tools.ts` — add to `getHandlers()`
-3. Implement the core logic in `src/utils/fs-utils.ts`, `search.ts`, or a new util
+- `tiny/` — smoke
+- `agents/` — realistic AGENTS.md shape
+- `daily-note/` — task lists, headings, frontmatter
+- `code-heavy/` — fenced code with heading- and tag-looking content inside (the single biggest historical bug source)
+- `dup-headings/` — multiple `## Tasks` plus `### Tasks` for disambiguation tests
+- `frontmatter-stress/` — block scalars, nested maps, similar key names
+- `links-zoo/` — wiki, embed, header-ref, block-ref, aliased, markdown
+- `large-kb/` — 5,500-line generated file for outline + search perf
 
-## Release Process
+Add more fixtures whenever you find a new edge class — the test suite rewards breadth.
 
-```bash
-# 1. Update version in package.json and manifest.json
-# 2. Build
-npm run build
-npm run build:plugin
+## Release process
 
-# 3. Publish to npm
+```bash
+# Bump version in package.json + manifest.json (the prepare hook + sync-version.cjs keep them aligned)
+npm run check && npm run lint && npm test && npm run build && npm run build:plugin
 npm publish
+gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
+# Plugin: submit dist/plugin/ to https://github.com/obsidianmd/obsidian-releases
+```
 
-# 4. Create GitHub release
-gh release create v0.2.0 --title "v0.2.0" --generate-notes
+CI uses semantic-release on the `main` branch.
 
-# 5. Submit plugin to Obsidian community plugin list
-#    https://github.com/obsidianmd/obsidian-releases
-```
+## Protocol reference
 
-## Protocol Reference
+The server speaks standard MCP over stdio (CLI) or HTTP/SSE (plugin).
 
-The server speaks the standard MCP protocol over stdio (CLI) or HTTP/SSE (plugin):
+### Stdio framing
 
-### Stdio
+The CLI uses the official `@modelcontextprotocol/sdk` (`StdioServerTransport`), which as of v1.29.0 uses **newline-delimited JSON**:
 
 ```
-Client → Server:  Content-Length: <N>\r\n\r\n<JSON-RPC body>
-Server → Client:  Content-Length: <N>\r\n\r\n<JSON-RPC body>
+Client → Server:  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}\n
+Server → Client:  {"jsonrpc":"2.0","id":1,"result":{...}}\n
 ```
 
+Note: The MCP spec originally described Content-Length framing (LSP-style). The official SDK switched to newline-delimited JSON in recent versions. We follow the SDK — not our own framing implementation. `src/mcp/framing.ts` and `src/mcp/stdio.ts` are retained for the HTTP/SSE plugin transport but are not used by the CLI.
+
 ### HTTP/SSE
 
 ```
-Client → Server:  GET /sse → SSE stream with endpoint event
-Client → Server:  POST /message?session_id=<id> → JSON-RPC request
-Server → Client:  SSE event "message" with JSON-RPC response
+Client → Server:  GET /sse?token=<bearer> → SSE stream starts; first event is "endpoint" with the POST URL
+Client → Server:  POST /message?session_id=<id> → JSON-RPC request (body capped at 5 MB)
+Server → Client:  SSE event "message" with the JSON-RPC response
+Server → Client:  Heartbeat events keep the connection alive; idle sessions are GC'd
 ```
 
-### Supported Methods
+`/healthz` returns `{ok: true, sessions: N, version: "X.Y.Z"}`.
+
+### Supported methods
+
+| Method                      | Purpose                                                |
+| --------------------------- | ------------------------------------------------------ |
+| `initialize`                | Protocol handshake                                     |
+| `tools/list`                | List available tools (filtered by current permissions) |
+| `tools/call`                | Execute a tool                                         |
+| `prompts/list`              | List available prompts (from vault Prompts/ folders)   |
+| `prompts/get`               | Get prompt content with arguments substituted          |
+| `notifications/initialized` | Client-ready notification                              |
+
+## Logs and auditing
+
+- **Stderr logs** are key=value structured (`component=http session=abc msg="…"`), safe to ship to journald, OpsAgent, etc.
+- **Audit log** is JSONL at `<vault>/.obsidian/plugins/obsidian-native-mcp/audit.log`, one line per mutating call. Use it for forensic analysis and regression replays.
+
+## See also
 
-| Method                      | Purpose                   |
-| --------------------------- | ------------------------- |
-| `initialize`                | Protocol handshake        |
-| `tools/list`                | List available tools      |
-| `tools/call`                | Execute a tool            |
-| `prompts/list`              | List available prompts    |
-| `prompts/get`               | Get prompt content        |
-| `notifications/initialized` | Client-ready notification |
+- `DESIGN_V1.md` — design rationale, invariants, tool surface, and roadmap.