obsidian-mcp-server 3.1.4 → 3.1.6

package/CLAUDE.md

@@ -1,8 +1,9 @@
 # Agent Protocol
 
 **Server:** obsidian-mcp-server
-**Version:** 3.0.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Version:** 3.1.6
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.8.20`
+**Engines:** Bun ≥1.3.11, Node ≥24.0.0
 
 > **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.
 
@@ -304,8 +305,9 @@ Available skills:
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-linter` | MCP definition linter rule reference (`bun run lint:mcp` failures) |
 | `api-services` | LLM, Speech, Graph services |
+| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-testing` | createMockContext, test patterns |
-| `api-utils` | Formatting, parsing, security, pagination, scheduling |
+| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
 | `api-workers` | Cloudflare Workers runtime |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).

package/Dockerfile

@@ -4,7 +4,7 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1 AS build
+FROM oven/bun:1.3 AS build
 
 WORKDIR /usr/src/app
 
@@ -28,7 +28,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1-slim AS production
+FROM oven/bun:1.3-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -85,6 +85,10 @@ ARG PORT
 # Set runtime environment variables
 # Note: PORT is an automatic variable in many cloud environments (e.g., Cloud Run)
 ENV MCP_HTTP_PORT=${PORT:-3010}
+# Bind to all interfaces inside the container so the host's `-p` mapping can reach it;
+# loopback would be unreachable from outside the container. For deployments beyond the
+# operator's own machine, set MCP_AUTH_MODE=jwt or oauth — the default `none` plus this
+# bind exposes the upstream OBSIDIAN_API_KEY to any caller that can reach the port.
 ENV MCP_HTTP_HOST="0.0.0.0"
 ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/obsidian-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/obsidian-mcp-server) [![Version](https://img.shields.io/badge/Version-3.1.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
+[![npm](https://img.shields.io/npm/v/obsidian-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/obsidian-mcp-server) [![Version](https://img.shields.io/badge/Version-3.1.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -231,7 +231,7 @@ MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
 
 ### Prerequisites
 
-- [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v22+).
+- [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v24+).
 - The [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin installed and enabled in your vault. Generate an API key in **Settings → Community Plugins → Local REST API** and copy it into `OBSIDIAN_API_KEY`.
 - This server defaults to `http://127.0.0.1:27123` for simplicity. Enable **"Non-encrypted (HTTP) Server"** in the plugin settings to use it. To use the always-on HTTPS port instead, set `OBSIDIAN_BASE_URL=https://127.0.0.1:27124`; the plugin's self-signed cert is handled by `OBSIDIAN_VERIFY_SSL=false` (the default).
 
@@ -281,6 +281,7 @@ MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
 | `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments (landing page, Server Card, RFC 9728 metadata). | unset |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_AUTH_SECRET_KEY` | **Required when `MCP_AUTH_MODE=jwt`.** ≥32-char shared secret used to verify incoming JWTs. | — |
+| `MCP_AUTH_DISABLE_SCOPE_CHECKS` | When `true`, bypasses per-tool scope enforcement after the auth-context presence check. Token signature, audience, issuer, and expiry validation remain intact. Use only when a custom claim can't be injected and combine with `OBSIDIAN_READ_PATHS` / `OBSIDIAN_WRITE_PATHS` / `OBSIDIAN_READ_ONLY` for access control. A `WARNING` is logged at startup whenever the bypass is active. | `false` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
 | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
@@ -320,6 +321,8 @@ docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server
 
 The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/obsidian-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
 
+The image binds to `0.0.0.0` inside the container (required for Docker port mapping). For any deployment reachable beyond your own machine, set `MCP_AUTH_MODE=jwt` (with `MCP_AUTH_SECRET_KEY`) or `oauth` — otherwise the listener forwards your `OBSIDIAN_API_KEY` to the vault on behalf of every caller.
+
 ## Project structure
 
 | Directory | Purpose |

package/changelog/3.1.x/3.1.5.md

@@ -0,0 +1,17 @@
+---
+summary: Bump @cyanheads/mcp-ts-core ^0.8.15 → ^0.8.18 and document the auth requirement for HTTP deployments beyond loopback.
+breaking: false
+---
+
+# 3.1.5 — 2026-05-06
+
+Maintenance release: framework dep refresh, paired skill sync, and a documentation clarification around HTTP transport posture. No source-code changes in this server.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` `^0.8.15 → ^0.8.18`.** Three upstream patch releases roll up:
+  - `0.8.16` — fixes an HTTP SSE per-request retention leak. `closePerRequestInstances` now binds to the request `AbortSignal` so ungraceful client disconnects close the per-request `McpServer` / transport pair. Affects this server when run under HTTP transport; pure framework fix, no consumer code change needed.
+  - `0.8.17` — surfaces `ctx.sessionId` on `Context` for HTTP handlers (defined in `stateful` / `auto` mode; opt-in via `createApp({ context: { exposeStatelessSessionId: true } })` under stateless). This server doesn't currently key on it.
+  - `0.8.18` — fixes `ctx.auth.token` being silently stripped in `toAuthContext`, and types `token?: string` on the public `AuthContext`. Doesn't apply here — this server forwards its own `OBSIDIAN_API_KEY` upstream, not the caller's bearer.
+- **`skills/api-context` `1.2 → 1.3`.** Picks up the upstream skill update covering `ctx.sessionId` — defined-when matrix across transport / session / auth modes, the stateless opt-in, capability-token coherence note, and strict / lax state-keying recipes.
+- **README + Dockerfile clarify auth requirement for non-loopback HTTP deployments.** The Docker image binds `MCP_HTTP_HOST=0.0.0.0` (required so the host's `-p` port mapping can reach the listener inside the container), and `MCP_AUTH_MODE` defaults to `none`. The README's Docker section and a new comment in the Dockerfile both now call this out and recommend `MCP_AUTH_MODE=jwt` or `oauth` for any deployment reachable beyond the operator's machine. Thanks to Ryan for surfacing the gap.

package/changelog/3.1.x/3.1.6.md

@@ -0,0 +1,23 @@
+---
+summary: "Pick up `mcp_tool_scopes` claim + `MCP_AUTH_DISABLE_SCOPE_CHECKS` bypass from `@cyanheads/mcp-ts-core` 0.8.20 — resolves [#47](https://github.com/cyanheads/obsidian-mcp-server/issues/47) for OIDC providers that can't override `scope`."
+breaking: false
+security: false
+---
+
+# 3.1.6 — 2026-05-09
+
+Maintenance release. Picks up the framework-side fix for [#47](https://github.com/cyanheads/obsidian-mcp-server/issues/47) — operators behind Authentik / Keycloak < 26.5 / Zitadel can now inject per-tool scopes via the `mcp_tool_scopes` custom claim, or set `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` and rely on `OBSIDIAN_READ_PATHS` / `OBSIDIAN_WRITE_PATHS` / `OBSIDIAN_READ_ONLY` for access control. No source changes in this server.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` `^0.8.18` → `^0.8.20`.** Two upstream releases roll up:
+  - `0.8.19` — engines bumped to Bun ≥1.3.0 / Node ≥24.0.0; Docker base `oven/bun:1` → `oven/bun:1.3`; new `api-telemetry` skill (v1.0); changelog frontmatter `security: bool` field; `init` template substitutions resolve `{{MCP_SDK_VERSION}}` and `{{ZOD_VERSION}}` from the framework `package.json`.
+  - `0.8.20` — `mcp_tool_scopes` JWT claim parsed alongside `scp` and `scope` (granted scopes are the union); `MCP_AUTH_DISABLE_SCOPE_CHECKS` env var bypasses both `withRequiredScopes` and `checkScopes` after the auth-context presence check (signature/audience/issuer/expiry validation intact); `authFactory` logs `WARNING` at startup whenever the bypass is active under non-`none` mode. ([cyanheads/mcp-ts-core#128](https://github.com/cyanheads/mcp-ts-core/issues/128))
+- **`engines.node` `>=22.0.0` → `>=24.0.0`** (mirroring the framework). README prerequisites line updated.
+- **Docker base image `oven/bun:1` → `oven/bun:1.3`** for build and production stages — pins to the matching minor of the framework's published image.
+- **`@types/node` `^25.6.0` → `^25.6.2`.**
+- **README** — env-var table gains `MCP_AUTH_DISABLE_SCOPE_CHECKS` row covering the bypass semantics, the path-policy combination, and the startup `WARNING`.
+- **`.env.example`** — new comment block under the auth section documents the `mcp_tool_scopes` claim union, the OIDC `authorization_code` restriction, and the bypass-flag fallback.
+- **`CLAUDE.md`** — header version updated; skills table picks up the new `api-telemetry` row and the refreshed `api-utils` description (now scoped to the helper API; OTel catalog moved to `api-telemetry`).
+- **Phase A skill bumps** (synced from framework): `api-telemetry` (new, v1.0), `api-auth` 1.0 → 1.1 (claims mapping table + OIDC operator setup + bypass docs), `api-config` 1.3 → 1.4 (env-var row), `api-utils` 2.1 → 2.2 (telemetry section now points to `api-telemetry`), `maintenance` 2.0 → 2.1 (Phase C resyncs pristine reference files), `report-issue-framework` 1.5 → 1.6, `report-issue-local` 1.4 → 1.5 (terser issue-writing guidance), `security-pass` 1.3 → 1.4 (Axis 2 bypass-in-production check), `setup` 1.6 → 1.7 (`bunx` examples, `release-and-publish` in progression), `tool-defs-analysis` 1.0 → 1.1 (env var names allowed in recovery hints).
+- **Phase C reference-file sync:** `scripts/build-changelog.ts` parses the new `security` frontmatter field; `changelog/template.md` documents it.

package/changelog/template.md

@@ -1,41 +1,71 @@
 ---
-# FORMAT REFERENCE — this file is never edited, never moved, never renamed.
-#
-# At release time, author a new per-version file at:
-#   changelog/<major.minor>.x/<version>.md   (e.g. changelog/0.1.x/0.1.0.md)
-# using this file's frontmatter and section layout as the starting point.
-# Set that new file's H1 to `# <version> — YYYY-MM-DD` with a concrete date.
-
-# Required. One-line headline describing the release. Max 250 chars. No markdown.
-# This line is what the CHANGELOG.md rollup shows — write it like a GitHub Release title.
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
+# with a concrete date.
+
+# Required. One-line GitHub Release-style headline. ~250 character soft cap.
+# Default short and scannable. Don't pad, don't stitch unrelated changes with
+# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
+# inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
-# Set to `true` only if this release has breaking changes (API removals, signature
-# changes, config renames, anything that requires consumer code changes on update).
-# Flagged as ⚠️ Breaking in the rollup.
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
 breaking: false
+
+# Set `true` if this release contains any security fix. Pairs with the
+# `## Security` section below. Flagged as `Security` in the rollup so
+# users can triage upgrade urgency at a glance.
+security: false
 ---
 
 # <version> — YYYY-MM-DD
 
 <!--
-  FORMAT REFERENCE — do not edit this file. It exists so the per-version file
-  structure has a single copy-source. Create new release notes at
-  `changelog/<major.minor>.x/<version>.md` using this layout.
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  each bullet with the symbol or concept name in **bold** so they can skip
+  what's irrelevant and zoom in on what's not.
+
+  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
+  name the symbol, state what changed, stop. Use a second sentence only when
+  it carries weight. If a bullet feels long, it is.
+
+  Cut: mechanism walkthroughs (those belong in JSDoc, AGENTS.md, or the
+  relevant skill), ceremonial framings ("This release introduces…",
+  backwards-compat paragraphs), file-by-file test enumerations, internal
+  implementation notes. Prefer code/symbol names over English re-explanations.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
 
-  Optional narrative intro — 1-3 sentences framing the release theme. Delete if not needed.
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
 
-  Linking issues/PRs: use full URLs so the link works everywhere (GitHub web UI,
-  npm/node_modules reads, local editors). GitHub's bare `#NN` auto-link only
-  resolves inside its own UI.
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
 
-    [#12](https://github.com/<owner>/<repo>/issues/12)   ← issue
-    [#17](https://github.com/<owner>/<repo>/pull/17)     ← PR
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
 
-  Only link numbers you've verified exist (via `gh issue view NN` or
-  `gh pr view NN`). Never speculate on a future number — `#17` for "my
-  upcoming PR" will quietly resolve to whatever real item already owns 17,
-  and GitHub timeline previews will pull in that unrelated item's title.
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
 -->
 
 ## Added
@@ -46,6 +76,18 @@ breaking: false
 
 -
 
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
 ## Fixed
 
 -
+
+<!-- ## Security
+
+- -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "mcpName": "io.github.cyanheads/obsidian-mcp-server",
   "description": "MCP server for Obsidian vaults — read, write, search, and surgically edit notes, tags, and frontmatter via the Local REST API plugin. STDIO or Streamable HTTP.",
   "type": "module",
@@ -69,14 +69,14 @@
   "license": "Apache-2.0",
   "engines": {
     "bun": ">=1.3.11",
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "packageManager": "bun@1.3.11",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.8.15",
+    "@cyanheads/mcp-ts-core": "^0.8.20",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^4.1.1",
     "pino-pretty": "^13.1.3",
@@ -84,7 +84,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.6.2",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",
     "tsc-alias": "^1.8.17",

package/server.json

@@ -6,14 +6,14 @@
     "url": "https://github.com/cyanheads/obsidian-mcp-server",
     "source": "github"
   },
-  "version": "3.1.4",
+  "version": "3.1.6",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "obsidian-mcp-server",
       "runtimeHint": "node",
-      "version": "3.1.4",
+      "version": "3.1.6",
       "packageArguments": [
         {
           "type": "positional",
@@ -95,7 +95,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "obsidian-mcp-server",
       "runtimeHint": "node",
-      "version": "3.1.4",
+      "version": "3.1.6",
       "packageArguments": [
         {
           "type": "positional",