Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: codegraph link-graph depth and MCP exposure (v1.17.0) (#108)

Sol Aitken254b58026ff2
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 0ca85199..8012afeb 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.16.0",
+ "version": "1.17.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 7340e361..c10236b6 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.16.0",
+ "version": "1.17.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 352155a1..ecec3d50 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,59 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-## [1.16.0] - 2026-06-20
+## [1.17.0] - 2026-06-21
+
+CodeGraph link-graph depth and MCP exposure. A set of strictly additive
+leaves inspired by Graphify: richer Markdown link resolution, MCP transport
+surfaces, and an explicit offline-first guarantee for keyless processing. No
+default behavior changes when the new options are unused, and the kernel still
+calls no LLM.
+
+### Added
+
+- **Reference-style Markdown links become link-graph edges
+ (`t_13c92d85`).** The deterministic link extractor now resolves
+ CommonMark reference definitions into the existing `markdown_link` row shape:
+ full (`[text][label]`), collapsed (`[text][]`), and shortcut (`[text]`)
+ references match labels case-insensitively with collapsed whitespace, reuse
+ the same external-URL / `mailto:` filtering and `#anchor` stripping as inline
+ links, and ignore image embeds and code fences. Inline-link behavior remains
+ unchanged while reference-heavy notes now contribute real graph edges.
+
+- **Standalone `graphify-mcp`-style console entry (`t_da6321a9`).** Packages now
+ expose an `o2b-mcp` bin that mirrors the existing `o2b` launcher and injects
+ the `mcp` subcommand, so `o2b-mcp --vault X` is equivalent to
+ `o2b mcp --vault X`. The shim is transport-agnostic and forwards all flags
+ verbatim, including the new HTTP transport flags.
+
+- **Streamable HTTP MCP transport with API-key auth (`t_31dfae18`).** `o2b mcp`
+ accepts `--transport stdio|http` (default `stdio`) plus `--host`, `--port`,
+ and `--api-key` for HTTP. The HTTP transport is a thin additive peer to stdio:
+ it authenticates every request with a generic constant-time API-key check,
+ rejects unauthenticated traffic with the same `401 Unauthorized` response,
+ rejects JSON-RPC batches per the 2025-06-18 MCP contract, supports JSON or
+ single-event SSE responses based on `Accept`, and dispatches every accepted
+ request through the existing `MCPServer.handleRequest` core.
+
+- **Explicit offline/deferred backend resolution for indexing
+ (`t_85252236`).** The structured `IndexStats` now declares which backend
+ processed a run: `backend: "offline"` when only the deterministic lexical
+ pipeline ran and no provider credentials were resolved, or
+ `backend: "semantic"` when the embedding backend was actually engaged. An
+ accompanying `deferredReason` string explains why the semantic backend was
+ not used (embeddings not requested, semantic search disabled, or
+ `embedding_api_key` not configured); it is null on a semantic run. Backend
+ resolution is lazy - the credential check stays inside the explicitly
+ requested embedding path, so a deterministic-only corpus indexes to
+ completion with no key and never hard-fails for a missing credential.
+ Borrowing Graphify's offline-first idea, this makes the already-keyless code
+ path an explicit, tested guarantee rather than an implicit side effect:
+ `importSession` is verified to never read provider-credential environment
+ variables, and keyless indexing is verified to report `offline`. The new
+ fields are additive; existing `IndexStats` fields are byte-identical when no
+ option changes.
+
+
Memory subsystem alignment: the write paths the Hermes memory provider
declares now match the live host memory semantics. The release makes
@@ -5817,6 +5869,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[1.17.0]: https://github.com/itechmeat/open-second-brain/compare/v1.16.0...v1.17.0
[1.16.0]: https://github.com/itechmeat/open-second-brain/compare/v1.15.0...v1.16.0
[1.15.0]: https://github.com/itechmeat/open-second-brain/compare/v1.14.0...v1.15.0
[1.14.0]: https://github.com/itechmeat/open-second-brain/compare/v1.13.0...v1.14.0
diff --git a/README.md b/README.md
index 6bcf2061..3eb2494b 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm
## What is new
-Open Second Brain 1.16.0 aligns its memory-write paths with the live Hermes memory semantics. The pinned-context writer now rejects oversized content up front with a structured budget_exceeded error instead of silently truncating it and reporting success. Pinned context and the continuity store gain an atomic batch mode that validates every operation before any write, so a mid-batch failure leaves the vault byte-for-byte unchanged and the agent gets a terminal done flag on success. The Hermes on_memory_write hook is now wired through a verified bridge that persists native host memory writes as durable continuity records, making the vault the backing store for built-in memory.
+Open Second Brain 1.17.0 widens the CodeGraph and MCP surfaces without changing any default behavior. The deterministic link extractor now resolves CommonMark reference-style Markdown links into real graph edges, a standalone MCP console entry mirrors the existing launcher and injects the mcp subcommand, an optional streamable HTTP MCP transport adds constant-time API-key auth for remote hosts, and search indexing gains an explicit offline backend that processes a keyless corpus to completion and never calls an LLM. Every change is strictly additive: the kernel still calls no LLM, and existing flows are byte-identical when the new options are unused.
## Why
diff --git a/docs/brainstorm/codegraph-link-depth-mcp/cli-output/claude.md b/docs/brainstorm/codegraph-link-depth-mcp/cli-output/claude.md
new file mode 100644
index 00000000..d2b52722
--- /dev/null
+++ b/docs/brainstorm/codegraph-link-depth-mcp/cli-output/claude.md
@@ -0,0 +1,34 @@
+### Variant 1
+- **Approach**: Introduce a transport-neutral seam: keep `MCPServer.handleRequest` as the sole JSON-RPC dispatch core, refactor the existing `serveStdio` readline loop to sit behind a small `Transport` contract, then add the Streamable HTTP transport as a peer implementation of that same contract. Packaging (new bin entries) and the offline guarantee each get a dedicated module β€” a `resolveBackend` deferral helper for credentials and an MCP launcher shared by stdio/http β€” so all four tasks plug into clean, named seams.
+- **Trade-offs**:
+ - + Long-term clean: one dispatch core, one launcher, no per-transport duplication; easiest place to add a third transport later.
+ - + Auth, framing, and protocol-version checks live once and apply uniformly.
+ - βˆ’ Refactoring the existing stdio loop puts the byte-identical stdio guarantee directly at risk; requires a golden-output regression test before any move.
+ - βˆ’ Front-loads abstraction the four cards don't all need, fighting KISS and the one-card-at-a-time cadence (card 1 must land the seam before later cards benefit).
+- **Complexity**: large.
+- **Risk**: medium.
+
+### Variant 2
+- **Approach**: Treat every task as a strictly additive leaf. The HTTP transport is a new file that calls `MCPServer.handleRequest` directly over Bun/Node built-in `http`, with auth and framing local to it; the existing `serveStdio` is never touched. New bin shims delegate to the existing stdio entry. Offline support is an in-place reordering of backend resolution inside the indexer that emits an explicit deferred-reason in its structured output, and the reference-link pass is a self-contained reference-definition sub-pass appended inside `extractLinks`.
+- **Trade-offs**:
+ - + Byte-identical stdio and inline-link output are guaranteed by construction β€” the old code paths are physically unchanged.
+ - + Minimal deps, KISS, forward-only; each card is an independent commit that cannot conflict with shared files beyond doc/changelog appends.
+ - + Matches the predecessor release's read-only/additive posture.
+ - βˆ’ A thin amount of shared logic (protocol-version gate, frame parsing) is reused rather than abstracted; the HTTP file must deliberately call `handleRequest` to satisfy the single-source-of-truth constraint instead of re-deriving dispatch.
+ - βˆ’ No unified transport picker, so a future third transport repeats the bootstrap pattern.
+- **Complexity**: medium.
+- **Risk**: low.
+
+### Variant 3
+- **Approach**: Unify everything behind one MCP runtime orchestrator: `o2b mcp serve` gains `--transport stdio|http` and `--api-key`, the new bin scripts and the HTTP server all funnel through a single runtime builder that selects the transport, and a shared "runtime readiness" report (consulted by both the MCP server and the indexer) carries the offline/deferred-credential state as structured output. The reference-link pass is folded into the same release as a link-extraction config flag surfaced through that one runtime.
+- **Trade-offs**:
+ - + Single config surface and one readiness model; offline state is reported consistently wherever it matters.
+ - + Strong discoverability β€” one command/flag set documents the whole MCP story.
+ - βˆ’ The orchestrator tends toward a god-object coupling packaging, transport, auth, and indexer-readiness concerns that are otherwise independent.
+ - βˆ’ Couples the credential-deferral work (kernel/indexer) to the MCP runtime, violating the constraint that the kernel must not depend on MCP and blurring the deliberate packaging-vs-transport task split.
+ - βˆ’ Hard to drive one card at a time: the central builder is a contended shared file across all four cards.
+- **Complexity**: large.
+- **Risk**: high.
+
+### Recommended: Variant 2
+Variant 2 is the only strategy that makes the two hard backward-compatibility guarantees β€” byte-identical stdio behavior and byte-identical inline-link output β€” true by construction rather than by careful refactoring, because it never edits the existing `serveStdio` loop or the inline-link branch of `extractLinks`. It honors the repo's minimal-dependency and KISS conventions (built-in `http`, no framework, no MCP SDK), keeps MCP optional and the kernel independent (the offline/deferred-backend work stays inside the indexer and is reported explicitly, never coupled to a running server), and respects the constraint that HTTP reuse `handleRequest` as the single dispatch source by calling it directly instead of inventing a transport abstraction. It also fits the four-card, shared-branch cadence best: each task is an additive leaf that builds cleanly on the prior commit with conflicts confined to append-only doc/changelog edits, and it continues the predecessor release's deliberately additive, forward-only posture. The one genuinely shared concern (protocol-version gate and frame parsing) is small enough to reuse as a helper without the upfront seam Variant 1 demands or the central coupling Variant 3 imposes.
diff --git a/docs/brainstorm/codegraph-link-depth-mcp/cli-output/prompt.md b/docs/brainstorm/codegraph-link-depth-mcp/cli-output/prompt.md
new file mode 100644
index 00000000..7d4cf15b
--- /dev/null
+++ b/docs/brainstorm/codegraph-link-depth-mcp/cli-output/prompt.md
@@ -0,0 +1,236 @@
+# Consultant prompt β€” release "codegraph-link-depth-mcp"
+
+You are a senior backend architect. Propose architectural variants for ONE
+coherent release of the **Open Second Brain** project. Output **variants and a
+recommendation only** β€” no implementation code, nothing outside the requested
+sections (see "Required output format" at the end).
+
+---
+
+## Project
+
+- **Name**: `open-second-brain` (npm `open-second-brain`, CLI binary `o2b`).
+- **Language / runtime**: TypeScript, ESM (`"type": "module"`), executed on
+ **Bun** (also Node-compatible for the CLI). `package.json` version `1.16.0`.
+- **Dependency posture**: intentionally minimal. Runtime deps = `proper-lockfile`
+ only. No HTTP framework, no MCP SDK. Optional native deps: `sqlite-vec`,
+ `@node-rs/jieba`, `tiny-segmenter`.
+- **Tooling**: tests via `bash scripts/test` (Bun's test runner, `bun:test`);
+ `oxlint` (lint), `oxfmt` (format), `tsc --noEmit` (typecheck);
+ `bun run validate` = typecheck + lint + test. Strict TDD convention: write the
+ focused failing test first, then implement, then refactor.
+- **Conventions (hard)**: SOLID / KISS / DRY; no misleading fallbacks (a
+ degraded path must SAY it degraded, never report success silently); no
+ hardcoding; all strings/identifiers English-only and language-agnostic; new
+ behavior must be **backward compatible** β€” existing outputs stay byte-identical
+ when no new flag/option is supplied. Keep the dependency set minimal: prefer
+ Node/Bun built-ins over new packages.
+
+## Release theme
+
+"CodeGraph link-graph depth + MCP exposure" β€” a single, coherent, forward-only
+release composed of exactly four in-scope tasks (do not add, drop, or substitute).
+Two deepen the link graph / extraction; two expose the existing MCP server
+through new packaging and transports.
+
+## In-scope tasks (verbatim bodies)
+
+### t_13c92d85 (priority 4 β€” CORE): resolve reference-style Markdown links into graph edges
+
+Graphify turns Markdown links into graph edges: it resolves inline
+`[text](./other.md)`, **reference-style** links, and `[[wikilinks]]` relative to
+the source file, skips external URLs/anchors/images, and emits `references`
+edges so hub docs surface as graph hubs.
+
+**Status in OSB**: `present_weaker`. `extractLinks`
+(`src/core/search/links.ts:60`) already covers wikilinks (`WIKILINK_ALIAS_RE`),
+inline markdown links (`MD_LINK_RE`, line 29), external-URL skip (`isUrl` line
+40), mailto skip (`isMailto` line 44), image-embed exclusion (negative
+lookbehind `(?<!!)` on `MD_LINK_RE`), and `#anchor` fragment stripping (lines
+79-81). It is invoked by the indexer (`indexInto β†’ extractLinks`,
+`src/core/search/indexer.ts`) and persisted via `store.replaceLinks`;
+hub/backlink ranking exists via `buildBacklinkIndex` / `pickTopReferenced`
+(`src/core/brain/backlinks.ts:98`). **Gap**: `MD_LINK_RE` matches only the
+inline `[text](target)` form β€” reference-style links (`[text][label]` /
+`[text][]` / `[text]` shortcut forms plus their `[label]: url` definitions) are
+never resolved, so `LinkType` (line 17) has no path for them.
+
+Closing the gap means a reference-definition pass (collect `[label]: target`
+lines, then match `[text][label]` / `[text][]` / `[text]` shortcut references
+against them) feeding the same `markdown_link` row shape; the existing
+`isUrl`/`isMailto`/anchor-strip filters apply unchanged to the resolved target.
+Relative-path resolution to canonical doc ids stays the indexer's job.
+
+### t_da6321a9 (priority 3): graphify-mcp console script for stdio MCP server
+
+Graphify v0.8.36 added a `graphify-mcp` console script β€” MCP stdio server
+directly invocable from `uv tool install` / `pipx`.
+
+**Status in OSB**: `not_in_osb_useful`. OSB has an MCP server (`src/mcp/server.ts`)
+but it is only reachable via the `o2b mcp serve` CLI command or by importing the
+class. `src/mcp/index.ts:19` exports `serveStdio`, `serveStdioFromString`;
+`pyproject.toml` has no console_scripts entry for MCP; `package.json` has no bin
+entry for the MCP server. Goal: a dedicated entry point so OSB runs as an MCP
+server via standard JS/Node tooling (`npx`, global install) without the `o2b mcp`
+subcommand. Triage validator note: this is the **packaging layer**, distinct
+from t_31dfae18 (transport layer).
+
+### t_31dfae18 (priority 2): streamable HTTP MCP transport with API-key auth
+
+Graphify v0.8.34 added a Streamable HTTP MCP transport: `graphify serve
+graph.json --transport http` serves the graph over HTTP so a team shares one
+server. Includes API-key auth (`--api-key`) and a Docker image.
+
+**Status in OSB**: `not_in_osb_useful`. OSB's MCP server only supports stdio via
+`serveStdio` (`src/mcp/stdio.ts:22`). An HTTP transport would let multiple
+agents/clients connect to a shared brain, enable remote access, and support
+team-wide sharing; API-key auth gives a simple security model. Triage validator
+note: this is the **transport layer**, distinct from t_da6321a9 (packaging).
+
+### t_85252236 (priority 1): offline code-only extraction without API keys
+
+Graphify v0.8.32 made code-only extraction work fully offline: `graphify extract`
+defers backend resolution until after file detection β€” a corpus with only code
+files runs without any `GEMINI_API_KEY` / `ANTHROPIC_API_KEY`. Keys are only
+required when docs/PDFs/images are present.
+
+**Status in OSB**: `not_in_osb_useful`. NOTE: the task's codegraph hint is
+**partly inaccurate** and must be corrected by the design. Findings from the
+current source:
+
+- **Session import is already fully offline.** `src/core/brain/sessions/import.ts`
+ (`importSession` / `importSessionPath`) runs a deterministic pipeline
+ (`discoverMarkers`, `extractFacts`, `routeExtractedFacts`,
+ `validateBrainFeedbackInput`, `importSessionRecall`) that never calls an LLM
+ and reads no provider credentials. So "session import requires provider
+ credentials" is false today.
+- **Vault indexing is already offline-capable.** Lexical FTS5 indexing
+ (`src/core/search/indexer.ts`) needs no key. The only credential-gated path is
+ semantic embeddings: `populateEmbeddings` throws `EMBEDDING_KEY_MISSING` **only
+ when** `config.semantic.enabled` AND provider != `local` AND no `apiKey` AND
+ embeddings are actually being computed. `indexStats` / `indexCheck` already
+ **degrade** with the warning `"embedding_api_key not configured; semantic
+ search disabled"`. A keyless `local` embedding provider exists.
+
+So the honest, graphify-inspired scope here is **deferred, content-aware backend
+resolution + an explicit offline guarantee**, not a brand-new extraction engine:
+ensure a keyless environment runs the full deterministic pipeline (lexical
+indexing + session import) to completion, surface any credential requirement as
+an explicit, deferred reason (never an up-front hard fail of the whole run), and
+lock the guarantee with a regression test that the keyless paths never read
+provider credentials.
+
+## Relevant architecture (current source)
+
+**MCP server (hand-rolled JSON-RPC 2.0, protocol `2025-06-18`)**
+
+- `src/mcp/server.ts` β€” `MCPServer` class. `handleRequest(request)` dispatches
+ `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`,
+ `resources/list`, `resources/templates/list`, `resources/read`. Advertises
+ `tools` + `resources` capabilities. Tools built via `buildToolTable(scope)`;
+ runtime capability window can narrow (never widen) the surface. Output goes
+ through `buildMcpToolResult` with an optional preview budget + artifact store.
+ Public `callTool(name, args)` exists for the CLI bridge.
+- `src/mcp/stdio.ts` β€” `serveStdio(ctx, ioOpts, runtimeOpts)`: readline loop,
+ newline-delimited JSON, one `handleRequest` per line. Rejects batch arrays
+ (`INVALID_REQUEST`, the `2025-06-18` spec removed batch support). Also
+ `serveStdioFromString(ctx, input, opts)` for in-memory tests.
+- `src/mcp/index.ts` β€” public barrel re-exporting `MCPServer`, `serveStdio`,
+ `serveStdioFromString`, protocol constants, etc.
+- `src/mcp/protocol.ts` β€” `PROTOCOL_VERSION = "2025-06-18"`, `SERVER_NAME`,
+ `SERVER_VERSION` (from package.json), JSON-RPC error codes, `MCPError`.
+- CLI dispatch: `src/cli/main.ts` has the `o2b mcp` command (call it `cmdMcp`).
+ It parses `--vault`, `--config`, `--repo`, `--scope full|writer|catalog`,
+ `--tool-profile`, `--writer-only`, `--probe`, `--json`, `--allow-tool`,
+ `--disable-tool`, `--max-tools`; constructs the server; prints
+ `[mcp] <name> <version> listening on stdio (vault=<vault>)` to stderr; then
+ calls `serveStdio`. JSON-RPC frames go to stdout only; logs to stderr.
+- `package.json` `bin`: `o2b` β†’ `./scripts/o2b`, `vault-log` β†’ `./scripts/vault-log`.
+ `scripts/o2b` is a bash launcher that sources a bun precheck and
+ `exec bun run $REPO_ROOT/src/cli/main.ts "$@"`. No MCP-specific bin entry.
+- `docs/mcp.md` documents the stdio server, Hermes/Claude Code/Codex
+ registration, profiles, and the writer split.
+
+**Link extraction (`src/core/search/links.ts`)** β€” see task t_13c92d85 above.
+`extractLinks(content)` returns `ExtractedLink[]` (`{ targetPath, linkText,
+linkType }`, `LinkType = "wikilink" | "markdown_link" | "tag"`). Order: strip
+code fences + inline code (`stripCode`), then wikilinks, then inline MD links,
+then tags, then `dedupe` by `type|target|text`. No standalone test file for
+`links.ts` today (covered indirectly via indexer tests) β€” a clean TDD target.
+
+**Indexing & credentials (`src/core/search/indexer.ts`)** β€” see t_85252236
+findings above. `ResolvedSearchConfig.semantic` has `enabled`, `provider`
+(incl. keyless `local`), `model`, `apiKey`, `costGateUsd`, `batchSize`,
+`concurrency`.
+
+## Constraints for this release
+
+1. Backward compatible: `o2b mcp` stdio behavior and `extractLinks` output for
+ inline links stay byte-identical when no new flag/option is supplied.
+2. MCP stays optional; nothing in the kernel may depend on the MCP server
+ running.
+3. The `2025-06-18` protocol contract (no batch; JSON-RPC 2.0; `initialize` β†’
+ `notifications/initialized` β†’ `tools/list|call`) is preserved on every
+ transport.
+4. HTTP transport must reuse `MCPServer.handleRequest` (single source of truth
+ for JSON-RPC dispatch) β€” do not duplicate request handling. Prefer Node/Bun
+ built-in `http` over adding a framework dependency (KISS, minimal deps).
+5. API-key auth on the HTTP transport: constant-time compare, reject
+ unauthenticated requests with the correct HTTP status, never leak whether the
+ failure is "missing" vs "wrong" beyond a single generic 401.
+6. No misleading fallbacks: every degraded/offline path reports its mode
+ explicitly in its structured output.
+7. The four tasks ship together but are driven one card at a time on a shared
+ branch; each card's change must build cleanly on top of the previously-driven
+ cards' commits (no duplicate abstractions, no conflicts on shared files like
+ `docs/mcp.md`, `docs/cli-reference.md`, `CHANGELOG.md`).
+
+## Recent release history (git log, newest first)
+
+```
+da2e3cc feat: memory subsystem alignment (v1.16.0) (#107)
+4db7862 fix(hermes): pass --repo so bridge skill discovery resolves repoRoot (#106)
+0a4b6da feat: calendar obligations, agenda synthesis, OKF portability (v1.15.0) (#105)
+f8b4abf feat(brain): add feedback default scope and vault write containment (#104)
+20ea7ef feat: per-handoff LLM generation tracing and prompt-prefix stability (#102)
+9c1d48f feat: CodeGraph and MCP operational readability (v1.12.0) (#101)
+c2c3ff4 feat: Session Knowledge Synthesis Suite (v1.11.0) (#100)
+... (older suites: recall quality, portability, indexer durability, provenance, integrity, search quality)
+```
+
+The directly related predecessor is `9c1d48f` (CodeGraph + MCP operational
+readability, v1.12.0): read-only `brain_codegraph_report` + option-gated cluster
+batching, deliberately keeping partner integration read-only and not adding new
+graph edge schemas. This release continues that posture on the MCP side while
+adding the one missing link-graph edge form (reference-style links).
+
+## Required output format
+
+Produce **exactly** these sections and nothing else:
+
+### Variant 1
+- **Approach**: 2-3 sentences.
+- **Trade-offs**: bullets.
+- **Complexity**: small | medium | large.
+- **Risk**: low | medium | high.
+
+### Variant 2
+- **Approach**: 2-3 sentences.
+- **Trade-offs**: bullets.
+- **Complexity**: small | medium | large.
+- **Risk**: low | medium | high.
+
+### Variant 3
+- **Approach**: 2-3 sentences.
+- **Trade-offs**: bullets.
+- **Complexity**: small | medium | large.
+- **Risk**: low | medium | high.
+
+### Recommended: Variant N
+A short rationale (a few sentences) naming the concrete reasons the chosen
+variant fits this project's conventions, the four tasks, and the constraints
+above.
+
+Do not emit any code, file listings, implementation steps, or additional
+sections. Variants must be genuinely distinct architectural strategies for
+delivering the whole 4-task release, not rearrangements of the same strategy.
diff --git a/docs/brainstorm/codegraph-link-depth-mcp/design.md b/docs/brainstorm/codegraph-link-depth-mcp/design.md
new file mode 100644
index 00000000..061921f6
--- /dev/null
+++ b/docs/brainstorm/codegraph-link-depth-mcp/design.md
@@ -0,0 +1,215 @@
+# CodeGraph link-graph depth + MCP exposure β€” design
+
+## Problem
+
+Open Second Brain's link graph and MCP surface each have one honest, narrowly
+scoped gap relative to the Graphify feature line, plus two packaging/transport
+gaps that block wider MCP adoption. This release closes all four as a single
+forward-only, backward-compatible release.
+
+1. **Reference-style Markdown links produce no graph edges.** `extractLinks`
+ (`src/core/search/links.ts`) resolves inline `[text](target)` links, wikilinks,
+ and tags, but silently drops CommonMark reference-style links
+ (`[text][label]` / `[text][]` / `[text]` shortcut forms plus their
+ `[label]: url` definitions). Docs wired together with reference links import
+ with no `references` edges, so hub/backlink ranking (`buildBacklinkIndex` /
+ `pickTopReferenced`) misses them.
+2. **The MCP server is reachable only through `o2b mcp`.** There is no standalone
+ entry point, so standard JS/Node distribution (`npx`, global install) cannot
+ launch the server without the subcommand.
+3. **The MCP server is stdio-only.** Remote, multi-client, and team-wide shared
+ deployments are impossible; there is no authenticated network transport.
+4. **Credential resolution is not honestly deferred/declared.** The task brief
+ claims session import and indexing "require provider credentials"; the actual
+ source shows session import is already fully offline and lexical indexing
+ needs no key, but that guarantee is implicit and untested, and the one
+ credential-gated path (semantic embeddings) is not surfaced as an explicit,
+ deferred reason in structured output.
+
+The release must close these gaps without turning Graphify into an owned OSB
+dependency, without adopting an MCP SDK or HTTP framework, without changing any
+existing default output, and without coupling the kernel to the MCP server.
+
+## Scope
+
+- Resolve reference-style Markdown links into `markdown_link` edges, feeding the
+ existing `replaceLinks` / backlink pipeline unchanged (t_13c92d85, CORE).
+- Add a dedicated `o2b-mcp` console-script bin entry that launches the MCP
+ server without the `o2b mcp` subcommand (t_da6321a9, packaging layer).
+- Add a Streamable HTTP MCP transport that reuses `MCPServer.handleRequest` as
+ the single JSON-RPC dispatch core, with constant-time API-key auth
+ (t_31dfae18, transport layer).
+- Make offline/deferred backend resolution explicit and guaranteed: a keyless
+ environment runs the full deterministic pipeline (lexical indexing + session
+ import) to completion; any credential requirement is reported as a deferred
+ reason in structured output, never an up-front hard fail of the whole run;
+ locked by a regression test that the keyless paths never read provider
+ credentials (t_85252236, extraction hardening).
+- Document and test every new surface through focused unit + CLI/MCP coverage.
+
+## Out of scope
+
+- Adopting `@modelcontextprotocol/sdk` or any HTTP/web framework (keep the
+ hand-rolled JSON-RPC core and the minimal dependency set).
+- Refactoring the existing `serveStdio` loop behind a transport abstraction
+ (rejected variant: puts the byte-identical stdio guarantee at risk for a seam
+ the four cards do not require).
+- A unified MCP "runtime orchestrator" coupling packaging, transport, auth, and
+ indexer readiness (rejected variant: god-object; violates kernel-independence
+ and the deliberate packaging-vs-transport task split).
+- Docker image, OAuth, or any transport other than stdio and Streamable HTTP.
+- New graph edge types beyond the existing `markdown_link` row shape.
+- LLM-generated labels, natural-language classification, or third-party graph
+ algorithms.
+- Changing default `o2b mcp` stdio output, default `extractLinks` output for
+ inline links, or default indexer output when no new option is supplied.
+
+## Chosen approach
+
+Use **Variant 2: strictly additive leaves.** Every task is an independent,
+forward-only addition that does not edit an existing happy path. The two hard
+backward-compatibility guarantees β€” byte-identical stdio behavior and
+byte-identical inline-link output β€” are true by construction because the
+existing `serveStdio` loop and the inline-link branch of `extractLinks` are never
+modified. The HTTP transport is a new file that calls
+`MCPServer.handleRequest` directly over Node/Bun built-in `http`, so dispatch
+stays single-source. The console script is a thin bin shim that delegates to the
+existing MCP command dispatch, so it inherits whichever transports the dispatch
+supports. The offline work is an in-place reordering/explicit declaration inside
+the indexer and a guarantee test, never coupled to a running server.
+
+We agree with the consultant recommendation. Variant 2 is the only strategy that
+satisfies both backward-compatibility guarantees by construction, honors the
+repo's minimal-dependency and KISS conventions, keeps the kernel independent of
+MCP, reuses `handleRequest` as the single dispatch source, and fits the
+one-card-at-a-time shared-branch cadence (each card is an additive leaf;
+conflicts are confined to append-only doc/CHANGELOG edits). It continues the
+predecessor release's (v1.12.0) deliberately additive, read-only/forward-only
+posture.
+
+## Design decisions
+
+1. **Reference-link pass is self-contained and appends inside `extractLinks`.**
+ - Add a reference-definition collection pass: scan the code-stripped content
+ for `[label]: <target>` definitions (CommonMark: up to three spaces indent,
+ case-insensitive label, target is a URL or relative path; titles ignored
+ for edge purposes), then match `[text][label]`, `[text][]` (collapsed), and
+ `[text]` (shortcut) reference forms against the definition map.
+ - Reuse the existing `isUrl` / `isMailto` / `#anchor`-strip filters on the
+ resolved target unchanged; emit the same `markdown_link` row shape
+ (`ExtractedLink` with `linkType: "markdown_link"`).
+ - Inline-link matching (`MD_LINK_RE`) and its image-embed negative
+ lookbehind are untouched β€” inline output stays byte-identical.
+ - Apply after wikilink/inline matching and before tag matching so the
+ existing `dedupe` (by `type|target|text`) collapses any overlap.
+ - Relative-path resolution to canonical doc ids stays the indexer's job, as
+ for inline links today.
+
+2. **HTTP transport reuses the dispatch core, adds no dependency.**
+ - New `src/mcp/http.ts` exports `serveHttp(ctx, opts, runtimeOpts)` built on
+ `node:http`. It constructs one `MCPServer` and routes every accepted
+ JSON-RPC request through `server.handleRequest` β€” no re-derived dispatch.
+ - Implements the MCP `2025-06-18` Streamable HTTP shape: a single endpoint
+ accepting `POST` with `Accept: application/json, text/event-stream`;
+ responses are either a single JSON body or an SSE stream when the client
+ requests event-stream and the request is resumable; `initialize` may issue
+ an `Mcp-Session-Id` header. GET is used only for an SSE stream when
+ supported. Batch (JSON array) bodies are rejected with `INVALID_REQUEST`
+ (`-32600`), mirroring the stdio loop's batch rejection β€” the protocol
+ removed batch support.
+ - `MCPServer.handleRequest` is unchanged; it already returns well-formed
+ JSON-RPC frames (result or error). The transport only frames them for HTTP.
+
+3. **API-key auth is constant-time and generic.**
+ - When `--api-key` is supplied, every request must present a matching key
+ (header `Authorization: Bearer <key>` is the canonical form; accept the
+ exact configured value only). Compare in constant time; on any
+ missing/wrong/absent credential respond with a single generic `401
+ Unauthorized` carrying no information about which check failed.
+ - When `--api-key` is not supplied, the HTTP transport refuses to start and
+ prints a clear stderr reason (HTTP without auth would expose the brain to
+ the network); stdio is unaffected and remains auth-less by design.
+
+4. **Console script delegates; it does not re-parse.**
+ - New `scripts/o2b-mcp` mirrors `scripts/o2b` (bash launcher + bun precheck)
+ and execs the CLI with the MCP command injected, forwarding all flags. It
+ is transport-agnostic: once the HTTP transport lands in the shared
+ dispatch, the console script exposes it automatically with no edit.
+ - Add `"o2b-mcp": "./scripts/o2b-mcp"` to `package.json` `bin` and ensure the
+ script is covered by `files`. A separate TS `main()` is rejected as DRY
+ duplication of dispatch already in `cmdMcp`.
+
+5. **Offline/deferred backend resolution is declared, not newly invented.**
+ - The indexer already runs lexically without a key and already degrades
+ semantic search with a warning when `embedding_api_key` is absent. Make the
+ guarantee explicit: structured index output carries a `mode`/`backend`
+ field (`offline` when no provider credentials are resolved, `semantic` when
+ the embedding backend is active, plus the existing deferred reason string),
+ and ensure the credential check is evaluated lazily β€” after content is
+ detected β€” so a corpus that needs only deterministic processing never
+ hard-fails for a missing key.
+ - Add a regression test proving `importSession` and keyless indexing never
+ read provider-credential environment variables or config keys, locking the
+ offline guarantee the task brief incorrectly assumed was absent.
+
+6. **Preserve language-agnostic behavior.**
+ - No natural-language keyword lists. Link forms, transport framing, auth,
+ and offline detection use structural/typed fields and explicit operator
+ input only. All identifiers and messages are English.
+
+## File changes
+
+Expected implementation touchpoints (final paths confirmed by each driven card):
+
+- **t_13c92d85**: `src/core/search/links.ts` (reference-definition pass +
+ matcher, appended; inline path untouched); **extend the existing**
+ `tests/core/search/links.test.ts` (which already covers wikilinks, inline MD
+ links, image-embed exclusion, anchor-strip, tags, code-fence stripping, dedupe,
+ mailto) with reference-style cases and a byte-identical-inline regression;
+ `CHANGELOG.md`.
+- **t_da6321a9**: new `scripts/o2b-mcp` (bash launcher delegating to the MCP
+ command); `package.json` (`bin.o2b-mcp`, ensure `files` coverage); new
+ `tests/cli/o2b-mcp-launcher.test.ts` (or extend an existing CLI launch test)
+ proving the entry resolves to MCP serving; `docs/mcp.md`, `docs/cli-reference.md`,
+ `CHANGELOG.md`.
+- **t_31dfae18**: new `src/mcp/http.ts` (`serveHttp` over `node:http`, framing,
+ constant-time API-key auth, batch rejection, session header); `src/cli/main.ts`
+ (`cmdMcp` gains `--transport stdio|http`, `--port`, `--host`, `--api-key`;
+ stdio path byte-identical when no transport flag is supplied); `src/mcp/index.ts`
+ (re-export `serveHttp`); new `tests/mcp/http-transport.test.ts` (auth
+ accept/reject, initialize handshake, tools/list, framing, batch rejection);
+ `docs/mcp.md`, `docs/cli-reference.md`, `CHANGELOG.md`.
+- **t_85252236**: `src/core/search/indexer.ts` (explicit `mode`/`backend` +
+ deferred credential reason in structured output; lazy credential evaluation);
+ `src/core/search/config.ts` / `src/core/search/index.ts` (credential
+ resolution surface used by the regression test, if a seam is needed);
+ `tests/core/search/index-offline.test.ts` and
+ `tests/core/brain/sessions-import-offline.test.ts` (keyless path +
+ no-credential-read guarantee); `CHANGELOG.md`.
+
+Shared, append-only edits (each driven card updates in place if a sibling
+already touched it): `CHANGELOG.md`, `docs/mcp.md`, `docs/cli-reference.md`.
+
+## Risks
+
+- **Reference-link regex can over- or under-match.** Mitigation: implement the
+ CommonMark definition + three reference forms precisely, cover edge cases
+ (collapsed/shortcut, duplicate labels, definitions after use, code-fence
+ stripping already applied), and add a byte-identical-inline regression test.
+- **HTTP transport can drift from the `2025-06-18` Streamable HTTP spec.**
+ Mitigation: reuse `handleRequest` for all dispatch; keep framing minimal and
+ spec-aligned (single endpoint, POST + optional SSE, `Mcp-Session-Id`, batch
+ rejection); cover handshake + framing with focused tests; no framework to
+ impose its own semantics.
+- **API-key handling can leak timing or diagnostic detail.** Mitigation:
+ constant-time compare; single generic `401` with no missing-vs-wrong
+ distinction; refuse to start HTTP without `--api-key`.
+- **Offline declaration can accidentally change default indexer output.**
+ Mitigation: the new `mode`/`backend` field is additive; existing fields stay
+ byte-identical when no option changes; regression test pins the default shape.
+- **Console-script delegation can break if the MCP command surface changes.**
+ Mitigation: the shim forwards flags verbatim and a launch test pins that the
+ entry reaches MCP serving; it never re-implements parsing.
+- **Doc/CHANGELOG conflicts across the four cards on a shared branch.**
+ Mitigation: cards are driven one at a time; each updates shared doc sections in
+ place on top of the prior commit rather than re-creating them.
diff --git a/docs/brainstorm/codegraph-link-depth-mcp/plan.md b/docs/brainstorm/codegraph-link-depth-mcp/plan.md
new file mode 100644
index 00000000..b6138b6c
--- /dev/null
+++ b/docs/brainstorm/codegraph-link-depth-mcp/plan.md
@@ -0,0 +1,184 @@
+# CodeGraph link-graph depth + MCP exposure β€” plan
+
+Shared branch: `feat/codegraph-link-depth-mcp`. Combined design:
+`docs/brainstorm/codegraph-link-depth-mcp/design.md` (Variant 2 β€” strictly
+additive leaves).
+
+<lock-scope>
+<task_ids>
+t_13c92d85
+t_da6321a9
+t_31dfae18
+t_85252236
+</task_ids>
+</lock-scope>
+
+Cards are driven **one at a time** in priority order (highest first):
+`t_13c92d85` β†’ `t_da6321a9` β†’ `t_31dfae18` β†’ `t_85252236`. Before editing,
+inspect the current branch commits and build on any previously-driven in-scope
+card commits. Do not duplicate sibling work; update shared doc/CHANGELOG
+sections in place if a sibling already touched them.
+
+Every task is implemented under TDD: write/adjust the focused failing test
+first, then make it pass, then refactor. All identifiers and messages are
+English; no natural-language keyword lists.
+
+---
+
+## t_13c92d85 (P4 β€” CORE): resolve reference-style Markdown links into graph edges
+
+### Files
+
+- `src/core/search/links.ts` β€” add a reference-definition collection pass and a
+ reference-usage matcher, appended after the inline-link loop and before the
+ tag loop. Collect `[label]: <target>` definitions (CommonMark: up to three
+ leading spaces, case-insensitive label, URL or relative path target; ignore
+ link titles for edge purposes) from the already code-stripped content, then
+ resolve `[text][label]`, `[text][]` (collapsed), and `[text]` (shortcut)
+ references against the map. Reuse `isUrl` / `isMailto` / `#anchor`-strip on
+ the resolved target unchanged and emit the existing `markdown_link` row shape
+ (`ExtractedLink` with `linkType: "markdown_link"`). The inline `MD_LINK_RE`
+ branch and its image-embed negative lookbehind stay byte-identical.
+- `tests/core/search/links.test.ts` (**extend** β€” the file already exists with
+ wikilink/inline/tag/code-fence/dedupe coverage) β€” add reference-style cases
+ (full/collapsed/shortcut, label case-insensitivity, duplicate labels,
+ definition-after-use, image-embed exclusion still holds, external-URL/mailto
+ skip still holds, code fences still ignored) and a byte-identical-inline
+ regression asserting that inline-link output is unchanged by the new pass.
+- `CHANGELOG.md` β€” append under the new release section.
+
+### Acceptance
+
+A passing test in `tests/core/search/links.test.ts` asserts that Markdown
+containing a reference-style link (`Some [text][ref] prose\n\n[ref]: ./other.md`)
+produces an `ExtractedLink` with `linkType: "markdown_link"`, `targetPath:
+"./other.md"`, `linkText: "text"`, and that a second test asserts inline-link
+output for a fixture is byte-identical before and after the change. `bun run
+validate` is green.
+
+### Depends on
+
+None. Self-contained inside `extractLinks`; the indexer and
+`store.replaceLinks` consume the same row shape, so no downstream change is
+needed.
+
+---
+
+## t_da6321a9 (P3): graphify-mcp console script for stdio MCP server
+
+### Files
+
+- `scripts/o2b-mcp` (new) β€” bash launcher mirroring `scripts/o2b` (follow
+ symlink, source `_bun-precheck.sh` / `_macos-sqlite.sh`, resolve repo root)
+ that execs the CLI with the MCP command injected, forwarding `"$@"` verbatim.
+ Confirm the exact MCP command form in `src/cli/main.ts` (`o2b mcp …`) and
+ inject that subcommand so `o2b-mcp --vault X` ≑ `o2b mcp --vault X`. The shim
+ is transport-agnostic: do NOT add transport logic here.
+- `package.json` β€” add `"o2b-mcp": "./scripts/o2b-mcp"` to `bin`; ensure the
+ script is reachable (it lives under `scripts/`, already in `files`).
+- `tests/cli/o2b-mcp-launcher.test.ts` (new, or extend an existing CLI launch
+ test) β€” assert the bin entry resolves to MCP serving (e.g. `--probe`/version
+ path reaches the MCP server banner) and forwards flags.
+- `docs/mcp.md`, `docs/cli-reference.md` β€” document the `o2b-mcp` entry point.
+- `CHANGELOG.md` β€” append under the new release section.
+
+### Acceptance
+
+A passing test proves `o2b-mcp` (via the launcher) reaches MCP serving with
+forwarded flags (e.g. the `[mcp] … listening on stdio` banner or the probe
+report), and `package.json` `bin` exposes `o2b-mcp`. `bun run validate` is green.
+
+### Depends on
+
+None (hard). The shim delegates to the shared MCP command dispatch, so it
+exposes whichever transports the dispatch supports at the time it runs. If driven
+before `t_31dfae18`, it serves stdio; once `t_31dfae18` lands `--transport`,
+the console script inherits HTTP automatically with no edit. Coordinate
+`docs/mcp.md` / `CHANGELOG.md` append sections with the HTTP card to avoid
+duplication.
+
+---
+
+## t_31dfae18 (P2): streamable HTTP MCP transport with API-key auth
+
+### Files
+
+- `src/mcp/http.ts` (new) β€” `serveHttp(ctx, opts, runtimeOpts)` built on
+ `node:http`. Construct one `MCPServer` and route every accepted JSON-RPC
+ request through `server.handleRequest` (single dispatch source β€” do not
+ re-derive handling). Implement the `2025-06-18` Streamable HTTP shape: single
+ endpoint, `POST` with `Accept: application/json, text/event-stream`; respond
+ with a single JSON body or an SSE stream when the client requests event-stream;
+ `initialize` may issue `Mcp-Session-Id`; reject JSON-array (batch) bodies with
+ `INVALID_REQUEST` (`-32600`), matching the stdio loop's batch rejection.
+ Constant-time API-key check on every request (accept the configured key only);
+ single generic `401 Unauthorized` with no missing-vs-wrong distinction.
+ Refuse to start without `--api-key` (HTTP without auth would expose the brain
+ to the network) and print a clear stderr reason.
+- `src/mcp/index.ts` β€” re-export `serveHttp`.
+- `src/cli/main.ts` β€” extend `cmdMcp` with `--transport stdio|http` (default
+ `stdio`), `--port`, `--host` (default `127.0.0.1`), and `--api-key` (required
+ for `http`). The stdio path is byte-identical when no `--transport` flag is
+ supplied.
+- `tests/mcp/http-transport.test.ts` (new) β€” auth accept/reject (missing,
+ wrong, correct; constant-time generic 401), initialize handshake, `tools/list`
+ over HTTP, single-body vs SSE framing, batch rejection, refusal to start
+ without `--api-key`. Use Node's built-in client or an in-memory server handle
+ so no new test dependency is added.
+- `docs/mcp.md`, `docs/cli-reference.md` β€” document the HTTP transport, flags,
+ and auth model.
+- `CHANGELOG.md` β€” append under the new release section.
+
+### Acceptance
+
+A passing test asserts an authenticated `initialize` β†’ `tools/list` round-trip
+over HTTP returns well-formed JSON-RPC results through `handleRequest`, that an
+unauthenticated request gets a generic `401`, that a batch body is rejected, and
+that starting HTTP without `--api-key` fails fast. The stdio path's existing
+tests stay green and byte-identical. `bun run validate` is green.
+
+### Depends on
+
+None. Adds a new transport file and extends `cmdMcp` additively. Builds on
+`t_da6321a9` only insofar as the console script inherits the new `--transport`
+flag automatically (no coordinated edit required).
+
+---
+
+## t_85252236 (P1): offline code-only extraction without API keys
+
+### Files
+
+- `src/core/search/indexer.ts` β€” make deferred/offline backend resolution
+ explicit: structured index output gains an additive `mode`/`backend` field
+ (`offline` when no provider credentials are resolved; `semantic` when the
+ embedding backend is active) carrying the existing deferred reason string, and
+ the credential check is evaluated lazily (after content detection) so a
+ deterministic-only corpus never hard-fails for a missing key. Existing fields
+ stay byte-identical when no option changes.
+- `src/core/search/config.ts` and/or `src/core/search/index.ts` β€” expose a
+ minimal credential-resolution seam (no new behavior, just a named, testable
+ surface) if the regression test needs it.
+- `tests/core/search/index-offline.test.ts` (new) β€” keyless indexing runs the
+ lexical pipeline to completion with `mode: offline`, computes no embeddings,
+ and the structured output reports the deferred reason; default output shape is
+ unchanged.
+- `tests/core/brain/sessions-import-offline.test.ts` (new) β€” `importSession`
+ runs to completion and never reads provider-credential env vars or config keys
+ (assert via a scrubbed env / credential-read spy), locking the guarantee the
+ task brief incorrectly assumed was absent.
+- `CHANGELOG.md` β€” append under the new release section (frame honestly: the
+ paths were already largely offline; this makes the guarantee explicit and
+ tested).
+
+### Acceptance
+
+A passing test asserts that keyless indexing completes with an explicit
+`mode: offline` and a deferred-credential reason, and that `importSession` never
+reads provider credentials. Default indexer output is byte-identical to the
+prior commit when no new option is supplied. `bun run validate` is green.
+
+### Depends on
+
+None. Kernel/indexer-only; stays independent of MCP. Coordinate `CHANGELOG.md`
+append with siblings.
diff --git a/docs/brainstorm/codegraph-link-depth-mcp/variants.md b/docs/brainstorm/codegraph-link-depth-mcp/variants.md
new file mode 100644
index 00000000..9e2b6d24
--- /dev/null
+++ b/docs/brainstorm/codegraph-link-depth-mcp/variants.md
@@ -0,0 +1,110 @@
+# CodeGraph link-graph depth + MCP exposure β€” variants
+
+Verbatim consultant output (Claude, `claude-opus-4-8`) plus the final rationale.
+Primary consultant run succeeded (exit 0, 3 parseable variants); no fallback run
+was required.
+
+---
+
+## Variant 1
+
+- **Approach**: Introduce a transport-neutral seam: keep
+ `MCPServer.handleRequest` as the sole JSON-RPC dispatch core, refactor the
+ existing `serveStdio` readline loop to sit behind a small `Transport`
+ contract, then add the Streamable HTTP transport as a peer implementation of
+ that same contract. Packaging (new bin entries) and the offline guarantee each
+ get a dedicated module β€” a `resolveBackend` deferral helper for credentials
+ and an MCP launcher shared by stdio/http β€” so all four tasks plug into clean,
+ named seams.
+- **Trade-offs**:
+ - + Long-term clean: one dispatch core, one launcher, no per-transport
+ duplication; easiest place to add a third transport later.
+ - + Auth, framing, and protocol-version checks live once and apply uniformly.
+ - βˆ’ Refactoring the existing stdio loop puts the byte-identical stdio
+ guarantee directly at risk; requires a golden-output regression test before
+ any move.
+ - βˆ’ Front-loads abstraction the four cards don't all need, fighting KISS and
+ the one-card-at-a-time cadence (card 1 must land the seam before later cards
+ benefit).
+- **Complexity**: large.
+- **Risk**: medium.
+
+## Variant 2
+
+- **Approach**: Treat every task as a strictly additive leaf. The HTTP transport
+ is a new file that calls `MCPServer.handleRequest` directly over Bun/Node
+ built-in `http`, with auth and framing local to it; the existing `serveStdio`
+ is never touched. New bin shims delegate to the existing stdio entry. Offline
+ support is an in-place reordering of backend resolution inside the indexer that
+ emits an explicit deferred-reason in its structured output, and the
+ reference-link pass is a self-contained reference-definition sub-pass appended
+ inside `extractLinks`.
+- **Trade-offs**:
+ - + Byte-identical stdio and inline-link output are guaranteed by
+ construction β€” the old code paths are physically unchanged.
+ - + Minimal deps, KISS, forward-only; each card is an independent commit that
+ cannot conflict with shared files beyond doc/changelog appends.
+ - + Matches the predecessor release's read-only/additive posture.
+ - βˆ’ A thin amount of shared logic (protocol-version gate, frame parsing) is
+ reused rather than abstracted; the HTTP file must deliberately call
+ `handleRequest` to satisfy the single-source-of-truth constraint instead of
+ re-deriving dispatch.
+ - βˆ’ No unified transport picker, so a future third transport repeats the
+ bootstrap pattern.
+- **Complexity**: medium.
+- **Risk**: low.
+
+## Variant 3
+
+- **Approach**: Unify everything behind one MCP runtime orchestrator: `o2b mcp
+ serve` gains `--transport stdio|http` and `--api-key`, the new bin scripts and
+ the HTTP server all funnel through a single runtime builder that selects the
+ transport, and a shared "runtime readiness" report (consulted by both the MCP
+ server and the indexer) carries the offline/deferred-credential state as
+ structured output. The reference-link pass is folded into the same release as
+ a link-extraction config flag surfaced through that one runtime.
+- **Trade-offs**:
+ - + Single config surface and one readiness model; offline state is reported
+ consistently wherever it matters.
+ - + Strong discoverability β€” one command/flag set documents the whole MCP
+ story.
+ - βˆ’ The orchestrator tends toward a god-object coupling packaging, transport,
+ auth, and indexer-readiness concerns that are otherwise independent.
+ - βˆ’ Couples the credential-deferral work (kernel/indexer) to the MCP runtime,
+ violating the constraint that the kernel must not depend on MCP and blurring
+ the deliberate packaging-vs-transport task split.
+ - βˆ’ Hard to drive one card at a time: the central builder is a contended
+ shared file across all four cards.
+- **Complexity**: large.
+- **Risk**: high.
+
+---
+
+## Recommended: Variant 2
+
+Consultant rationale (verbatim): Variant 2 is the only strategy that makes the
+two hard backward-compatibility guarantees β€” byte-identical stdio behavior and
+byte-identical inline-link output β€” true by construction rather than by careful
+refactoring, because it never edits the existing `serveStdio` loop or the
+inline-link branch of `extractLinks`. It honors the repo's minimal-dependency and
+KISS conventions (built-in `http`, no framework, no MCP SDK), keeps MCP optional
+and the kernel independent (the offline/deferred-backend work stays inside the
+indexer and is reported explicitly, never coupled to a running server), and
+respects the constraint that HTTP reuse `handleRequest` as the single dispatch
+source by calling it directly instead of inventing a transport abstraction. It
+also fits the four-card, shared-branch cadence best: each task is an additive
+leaf that builds cleanly on the prior commit with conflicts confined to
+append-only doc/changelog edits, and it continues the predecessor release's
+deliberately additive, forward-only posture. The one genuinely shared concern
+(protocol-version gate and frame parsing) is small enough to reuse as a helper
+without the upfront seam Variant 1 demands or the central coupling Variant 3
+imposes.
+
+## Final decision
+
+**Adopted: Variant 2.** No override. The recommendation matches the project's
+established conventions (minimal deps, byte-identical backward compatibility,
+additive/forward-only releases as in v1.12.0) and the release's fixed four-task
+scope. Variant 1's transport seam is rejected as premature abstraction that
+endangers the stdio guarantee; Variant 3's orchestrator is rejected for
+god-object coupling and kernel→MCP dependence.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 2faa98f1..060dd1b1 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -10,12 +10,13 @@ Most verbs accept `--vault <path>` and `--config <path>`; the values default to
o2b status Show config / vault status
o2b init Bootstrap the vault profile (idempotent)
o2b init --interactive Guided first-time setup wizard
-o2b install-cli Symlink o2b and o2b-hook into ~/.local/bin
+o2b install-cli Symlink o2b and vault-log into ~/.local/bin
+o2b-mcp Console-script alias for `o2b mcp`, forwards all flags
o2b doctor Run vault + adapter checks
o2b index Rebuild the Markdown page index
o2b export-config Write a redacted config snapshot
o2b secrets list|status Inspect $secret:NAME references without printing values
-o2b mcp Run the MCP tool server (stdio); --scope full|writer|catalog, --tool-profile full|writer|catalog|recall|minimal, --probe, --allow-tool, --disable-tool, --max-tools
+o2b mcp Run the MCP tool server (stdio by default; --transport http requires --api-key); --scope full|writer|catalog, --tool-profile full|writer|catalog|recall|minimal, --probe, --allow-tool, --disable-tool, --max-tools
o2b tool-call Invoke an MCP tool handler from the CLI
o2b help --json Print the command/flag manifest as JSON
o2b completions --shell zsh Print completions for bash|zsh|fish|elvish|nushell|powershell
diff --git a/docs/mcp.md b/docs/mcp.md
index 852adafb..28b5b51a 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -9,7 +9,8 @@ in Open Second Brain depends on the MCP server being running.
## Protocol
-- Transport: stdio (JSON-RPC 2.0, newline-delimited).
+- Transport: stdio (JSON-RPC 2.0, newline-delimited) by default; optional
+ Streamable HTTP on the same JSON-RPC core with per-request API-key auth.
- Protocol version: `2025-06-18`.
- Capabilities advertised: `tools` and `resources` (see "Resources"
below). No `prompts` or `sampling`.
@@ -178,8 +179,12 @@ with a `not found` message β€” same shape as `brain_query`'s
```bash
scripts/o2b mcp --vault /path/to/vault
+scripts/o2b-mcp --vault /path/to/vault
```
+`o2b-mcp` is a console-script alias for `o2b mcp`; it injects the `mcp`
+subcommand and forwards every flag verbatim.
+
Optional flags:
- `--config PATH` β€” override the Open Second Brain config file location.
@@ -187,13 +192,22 @@ Optional flags:
- `--scope full|writer` β€” choose the full server or the always-loaded writer subset.
- `--writer-only` β€” alias for `--scope writer`.
- `--probe` β€” start an in-process handshake and print whether the server can advertise tools, then exit.
+- `--transport stdio|http` β€” choose stdio (default) or Streamable HTTP.
+- `--host HOST` β€” HTTP bind host (default `127.0.0.1`).
+- `--port PORT` β€” HTTP bind port (default `0`, choose an available port).
+- `--api-key KEY` β€” required for `--transport http`; accepted as `Authorization: Bearer KEY` or `X-API-Key: KEY` on every request.
- `--json` β€” with `--probe`, print a machine-readable capability report.
- `--allow-tool NAME` β€” expose only named tools from the static scope. Repeatable.
- `--disable-tool NAME` β€” withhold named tools from the static scope. Repeatable.
- `--max-tools N` β€” expose only the first N non-diagnostic tools from the static scope.
-The server logs its banner to `stderr` and only writes JSON-RPC frames to
-`stdout`, so it is safe to use as a subprocess in any MCP client.
+The stdio server logs its banner to `stderr` and only writes JSON-RPC frames to
+`stdout`, so it is safe to use as a subprocess in any MCP client. HTTP refuses
+to start without `--api-key`, checks the key on every request using a generic
+constant-time comparison, and returns the same `401 Unauthorized` body for a
+missing or wrong key. JSON responses are the default; clients that send
+`Accept: text/event-stream` receive a single SSE `message` event for the same
+JSON-RPC response.
## Runtime capability window
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index df0442dd..7a5984f3 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "1.16.0",
+ "version": "1.17.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index fd6aacdf..d63a1b85 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.16.0",
+ "version": "1.17.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
@@ -18,6 +18,7 @@
},
"bin": {
"o2b": "./scripts/o2b",
+ "o2b-mcp": "./scripts/o2b-mcp",
"vault-log": "./scripts/vault-log"
},
"files": [
diff --git a/plugin.yaml b/plugin.yaml
index 110c9524..c420e6a4 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.16.0"
+version: "1.17.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 11805406..cd64d223 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.16.0",
+ "version": "1.17.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 110c9524..c420e6a4 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.16.0"
+version: "1.17.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index ac5bc25b..37431d8d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "1.16.0"
+version = "1.17.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/scripts/o2b-mcp b/scripts/o2b-mcp
new file mode 100755
index 00000000..7544ad99
--- /dev/null
+++ b/scripts/o2b-mcp
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Follow symlink so the repo root is correct even when invoked through
+# a package-manager bin shim or a symlink in ~/.local/bin.
+SELF=$(realpath -- "${BASH_SOURCE[0]}")
+SCRIPT_DIR=$(cd -- "$(dirname -- "$SELF")" && pwd)
+REPO_ROOT=$(cd -- "$SCRIPT_DIR/.." && pwd)
+
+# shellcheck source=./_bun-precheck.sh
+. "$SCRIPT_DIR/_bun-precheck.sh"
+
+# shellcheck source=./_macos-sqlite.sh
+. "$SCRIPT_DIR/_macos-sqlite.sh"
+
+exec bun run "$REPO_ROOT/src/cli/main.ts" mcp "$@"
diff --git a/src/cli/main.ts b/src/cli/main.ts
index ba98cea1..2effeac6 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -51,6 +51,7 @@ import { cmdInitInteractive } from "./install/init-interactive.ts";
import { CLI_COMMAND_MANIFEST, manifestForJson } from "./command-manifest.ts";
import { COMPLETION_SHELLS, isCompletionShell, renderCompletions } from "./completions.ts";
import { MCPServer } from "../mcp/server.ts";
+import { startHttp } from "../mcp/http.ts";
import { serveStdio } from "../mcp/stdio.ts";
import { SERVER_VERSION } from "../mcp/protocol.ts";
import { buildToolTable } from "../mcp/tools.ts";
@@ -385,6 +386,10 @@ async function cmdMcp(argv: string[]): Promise<number> {
"tool-profile": { type: "string" },
probe: { type: "boolean" },
json: { type: "boolean" },
+ transport: { type: "string", default: "stdio" },
+ host: { type: "string", default: "127.0.0.1" },
+ port: { type: "string", default: "0" },
+ "api-key": { type: "string" },
"allow-tool": { type: "string-array" },
"disable-tool": { type: "string-array" },
"max-tools": { type: "string" },
@@ -415,6 +420,25 @@ async function cmdMcp(argv: string[]): Promise<number> {
}
const config = (flags["config"] as string | undefined) ?? defaultConfigPath();
+ const transport = flags["transport"] as string;
+ if (transport !== "stdio" && transport !== "http") {
+ process.stderr.write(
+ `o2b mcp: invalid --transport value: ${transport}; expected one of: stdio, http\n`,
+ );
+ return 2;
+ }
+ const rawPort = flags["port"] as string;
+ const port = Number(rawPort);
+ if (!Number.isInteger(port) || port < 0 || port > 65535) {
+ process.stderr.write(`o2b mcp: --port must be an integer from 0 to 65535\n`);
+ return 2;
+ }
+ const host = flags["host"] as string;
+ const apiKey = flags["api-key"] as string | undefined;
+ if (transport === "http" && (apiKey === undefined || apiKey === "")) {
+ process.stderr.write("o2b mcp: --api-key is required when --transport http is used\n");
+ return 2;
+ }
// Named tool-surface profile: flag wins over the config key; an
// unknown name FAILS OPEN to the full surface (logged, never fatal).
@@ -461,6 +485,22 @@ async function cmdMcp(argv: string[]): Promise<number> {
});
}
+ if (transport === "http") {
+ const handle = await startHttp(
+ { vault, configPath: config, repoRoot },
+ { host, port, apiKey },
+ { scope, serverName, capabilityWindow },
+ );
+ // Log the actually-bound endpoint. With the default --port 0 the OS
+ // assigns an ephemeral port, so the requested `port` value ("0") would
+ // advertise the wrong URL. handle.url carries the real bound port.
+ process.stderr.write(
+ `[mcp] ${serverName} ${SERVER_VERSION} listening on ${handle.url} (vault=${vault})\n`,
+ );
+ await new Promise<void>((resolve) => handle.server.once("close", resolve));
+ return 0;
+ }
+
process.stderr.write(
`[mcp] ${serverName} ${SERVER_VERSION} listening on stdio (vault=${vault})\n`,
);
@@ -660,7 +700,7 @@ Commands:
doctor Run health checks on vault, config, and plugins
export-config Write a redacted config snapshot
index Regenerate the vault index from discovered pages
- mcp Run the optional MCP tool server (stdio JSON-RPC)
+ mcp Run the optional MCP tool server (stdio or HTTP JSON-RPC)
install-cli Create symlinks for o2b and vault-log in ~/.local/bin
install Multi-runtime install orchestrator (v0.10.11) β€” detect / plan / apply / --check (see install/)
update Update OSB installation across all detected runtimes
diff --git a/src/core/search/indexer.ts b/src/core/search/indexer.ts
index d44aa803..32662852 100644
--- a/src/core/search/indexer.ts
+++ b/src/core/search/indexer.ts
@@ -101,6 +101,8 @@ interface MutableStats {
relationViolations: IndexStats["relationViolations"];
tierDrift: IndexStats["tierDrift"];
aliasResolved: number;
+ backend: IndexStats["backend"];
+ deferredReason: IndexStats["deferredReason"];
}
function newStats(): MutableStats {
@@ -116,6 +118,10 @@ function newStats(): MutableStats {
relationViolations: [],
tierDrift: [],
aliasResolved: 0,
+ // Resolved lazily at the end of the run, after content detection.
+ // Defaults to the deterministic offline backend.
+ backend: "offline",
+ deferredReason: null,
};
}
@@ -132,10 +138,31 @@ function freezeStats(s: MutableStats, durationMs: number): IndexStats {
relationViolations: Object.freeze([...s.relationViolations]),
tierDrift: Object.freeze([...s.tierDrift]),
aliasResolved: s.aliasResolved,
+ backend: s.backend,
+ deferredReason: s.deferredReason,
durationMs,
});
}
+/**
+ * Explain why the semantic backend was not engaged, inspecting only the
+ * already-resolved config (never `process.env`). Used for an offline run
+ * so operators see whether the cause is an unset option, disabled
+ * semantic search, or a missing credential.
+ */
+function offlineDeferredReason(config: ResolvedSearchConfig, embeddingsRequested: boolean): string {
+ if (!config.semantic.enabled) {
+ return "semantic search disabled (search_semantic_enabled=false); ran offline lexical backend";
+ }
+ if (config.semantic.provider !== "local" && !config.semantic.apiKey) {
+ return "embedding_api_key not configured; semantic backend deferred, ran offline lexical backend";
+ }
+ if (!embeddingsRequested) {
+ return "embeddings not requested this run; ran offline lexical backend";
+ }
+ return "semantic backend not engaged; ran offline lexical backend";
+}
+
function sha256(text: string): string {
return createHash("sha256").update(text).digest("hex");
}
@@ -427,6 +454,12 @@ async function indexInto(
}
}
+ // Lazy backend resolution (offline code-only extraction, t_85252236).
+ // The credential-gated embedding path runs only when explicitly
+ // requested; reaching past populateEmbeddings without throwing means a
+ // credential was resolved (or the local provider needs none), so the
+ // semantic backend is genuinely active. Otherwise the run is offline
+ // and we record why the semantic backend was deferred.
if (opts?.embeddings) {
await populateEmbeddings(
store,
@@ -436,6 +469,11 @@ async function indexInto(
opts?.safeguard,
opts?.signal,
);
+ stats.backend = "semantic";
+ stats.deferredReason = null;
+ } else {
+ stats.backend = "offline";
+ stats.deferredReason = offlineDeferredReason(config, false);
}
const now = new Date().toISOString();
diff --git a/src/core/search/links.ts b/src/core/search/links.ts
index 13bfdf48..40e5b4fb 100644
--- a/src/core/search/links.ts
+++ b/src/core/search/links.ts
@@ -10,6 +10,15 @@
* a code sample mentioning `[[foo]]` or `#hash` does not become a real
* link. This is best-effort: nested fenced fences are rare and we err
* on the side of stripping too much rather than capturing junk links.
+ *
+ * Reference-style links (CommonMark) are also resolved: a first pass
+ * collects `[label]: target` definitions, then full (`[text][label]`),
+ * collapsed (`[text][]`), and shortcut (`[text]`) references are matched
+ * against them and emitted as `markdown_link` rows β€” the same shape and
+ * `isUrl`/`isMailto`/anchor-strip filtering the inline form uses. Like
+ * inline links, resolution is scoped to the content passed in (a single
+ * chunk): a definition and a reference that land in different chunks are
+ * not cross-resolved, mirroring the existing per-chunk extraction unit.
*/
import { WIKILINK_ALIAS_RE } from "../brain/wikilink.ts";
@@ -30,6 +39,19 @@ const MD_LINK_RE = /(?<!!)\[([^\]\n]*)\]\(([^)\n\s]+)(?:\s+"[^"\n]*")?\)/g;
// Obsidian-style tag: #word where word starts with a letter/_ and may contain
// letters, digits, dashes, underscores, and '/' for hierarchy.
const TAG_RE = /(^|[^\w/])#([A-Za-z_][\w\-/]*)/g;
+// Reference-link definition: `[label]: target` with up to 3 leading spaces
+// (4+ would be an indented code block in CommonMark). The target is a bare
+// token or an `<...>` form; an optional title (quoted or parenthesised)
+// follows. Only single-line definitions are recognised β€” the rare
+// title-on-next-line form is treated as no title.
+const REF_DEF_RE =
+ /^ {0,3}\[([^\]\n]+)\]:[ \t]*(?:<([^>\n]+)>|(\S+))(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?[ \t]*$/gm;
+// Reference usage. Matches `[text]`, `[text][]`, and `[text][label]`. The
+// leading `!` is captured (not a lookbehind) so a `![text][label]` image embed
+// is consumed as one unit and skipped, rather than leaving its `[label]` to be
+// re-read as a shortcut reference. The link text / label may not contain
+// unescaped brackets or newlines.
+const REF_LINK_RE = /(!?)\[([^\]\n]+)\](?:\[([^\]\n]*)\])?/g;
function stripCode(text: string): string {
let out = text.replace(CODE_FENCE_RE, "\n");
@@ -45,6 +67,23 @@ function isMailto(target: string): boolean {
return target.toLowerCase().startsWith("mailto:");
}
+// Shared target normalisation for inline and reference-style markdown links:
+// reject external URLs / mailto, strip the optional `#anchor` fragment, and
+// return the bare path β€” or null when nothing link-worthy remains.
+function resolveMarkdownTarget(rawTarget: string): string | null {
+ const target = rawTarget.trim();
+ if (target === "" || isUrl(target) || isMailto(target)) return null;
+ const hashIdx = target.indexOf("#");
+ const path = hashIdx >= 0 ? target.slice(0, hashIdx) : target;
+ return path === "" ? null : path;
+}
+
+// CommonMark reference labels are case-insensitive and collapse internal
+// whitespace runs to a single space after trimming.
+function normaliseLabel(label: string): string {
+ return label.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
function dedupe(links: ExtractedLink[]): ExtractedLink[] {
const seen = new Set<string>();
const out: ExtractedLink[] = [];
@@ -57,6 +96,67 @@ function dedupe(links: ExtractedLink[]): ExtractedLink[] {
return out;
}
+/**
+ * Resolve CommonMark reference-style links against their definitions and
+ * append the resolved `markdown_link` rows to `out`. Operates on
+ * already-code-stripped content.
+ *
+ * Two passes: first collect every `[label]: target` definition (the
+ * definition lines are then blanked so their own `[label]` does not read
+ * as a shortcut reference), then scan for full / collapsed / shortcut
+ * references. Shortcut `[text]` references are only emitted when `text`
+ * resolves to a known definition β€” that gate is what keeps ordinary
+ * bracketed prose from becoming spurious edges.
+ */
+function extractReferenceLinks(cleaned: string, out: ExtractedLink[]): void {
+ const defs = new Map<string, string>();
+ for (const m of cleaned.matchAll(REF_DEF_RE)) {
+ const label = normaliseLabel(m[1] ?? "");
+ const rawTarget = m[2] ?? m[3] ?? "";
+ if (label === "" || rawTarget === "") continue;
+ // First definition wins, matching CommonMark.
+ if (!defs.has(label)) defs.set(label, rawTarget);
+ }
+ if (defs.size === 0) return;
+
+ // Blank out definition lines so the `[label]` in `[label]: target` is not
+ // re-read as a shortcut reference below.
+ const body = cleaned.replace(REF_DEF_RE, "");
+
+ for (const m of body.matchAll(REF_LINK_RE)) {
+ if (m[1] === "!") continue; // image embed β€” consumed but not an edge
+ const text = (m[2] ?? "").trim();
+ const second = m[3];
+ let label: string;
+ let linkText: string;
+ if (second === undefined) {
+ // Shortcut reference `[text]`. Skip if the next char makes this an
+ // inline link `[text](…)` or a definition `[text]:` instead.
+ const after = body[m.index + m[0].length];
+ if (after === "(" || after === ":") continue;
+ label = text;
+ linkText = text;
+ } else if (second.trim() === "") {
+ // Collapsed reference `[text][]`: the text doubles as the label.
+ label = text;
+ linkText = text;
+ } else {
+ // Full reference `[text][label]`.
+ label = second;
+ linkText = text;
+ }
+ const rawTarget = defs.get(normaliseLabel(label));
+ if (rawTarget === undefined) continue;
+ const path = resolveMarkdownTarget(rawTarget);
+ if (path === null) continue;
+ out.push({
+ targetPath: path,
+ linkText: linkText || null,
+ linkType: "markdown_link",
+ });
+ }
+}
+
export function extractLinks(content: string): ExtractedLink[] {
const cleaned = stripCode(content);
const out: ExtractedLink[] = [];
@@ -74,12 +174,8 @@ export function extractLinks(content: string): ExtractedLink[] {
for (const m of cleaned.matchAll(MD_LINK_RE)) {
const text = (m[1] ?? "").trim();
- const target = (m[2] ?? "").trim();
- if (target === "" || isUrl(target) || isMailto(target)) continue;
- // Strip the optional `#anchor` fragment for path matching.
- const hashIdx = target.indexOf("#");
- const path = hashIdx >= 0 ? target.slice(0, hashIdx) : target;
- if (path === "") continue;
+ const path = resolveMarkdownTarget(m[2] ?? "");
+ if (path === null) continue;
out.push({
targetPath: path,
linkText: text || null,
@@ -87,6 +183,8 @@ export function extractLinks(content: string): ExtractedLink[] {
});
}
+ extractReferenceLinks(cleaned, out);
+
for (const m of cleaned.matchAll(TAG_RE)) {
const tag = (m[2] ?? "").trim();
if (tag === "") continue;
diff --git a/src/core/search/types.ts b/src/core/search/types.ts
index 30f6e432..880c51c8 100644
--- a/src/core/search/types.ts
+++ b/src/core/search/types.ts
@@ -210,6 +210,22 @@ export interface IndexStats {
* (link-recall-intelligence, v7).
*/
readonly aliasResolved: number;
+ /**
+ * Backend that processed this run, resolved lazily after content
+ * detection (offline code-only extraction, t_85252236). `"offline"`
+ * when only the deterministic lexical pipeline ran and no provider
+ * credentials were resolved; `"semantic"` when the embedding backend
+ * was actually engaged. Additive β€” the deterministic fields above are
+ * unaffected by this field's value.
+ */
+ readonly backend: "offline" | "semantic";
+ /**
+ * Human-readable explanation of why the semantic backend was not
+ * engaged this run (e.g. embeddings not requested, semantic disabled,
+ * or `embedding_api_key` not configured). Null when the semantic
+ * backend ran (`backend === "semantic"`).
+ */
+ readonly deferredReason: string | null;
readonly durationMs: number;
}
diff --git a/src/mcp/http.ts b/src/mcp/http.ts
new file mode 100644
index 00000000..4bf1a6de
--- /dev/null
+++ b/src/mcp/http.ts
@@ -0,0 +1,192 @@
+/**
+ * Streamable HTTP transport for the MCP server.
+ *
+ * This stays transport-only: every accepted JSON-RPC request is dispatched
+ * through MCPServer.handleRequest, the same core used by stdio.
+ */
+
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { once } from "node:events";
+import type { Writable } from "node:stream";
+
+import { MCPServer, type MCPServerOptions, type MCPServerRuntimeOptions } from "./server.ts";
+import { errorResponse, type JsonRpcResponse } from "./server.ts";
+import { INVALID_REQUEST, PARSE_ERROR } from "./protocol.ts";
+
+export interface ServeHttpOptions {
+ readonly host?: string;
+ readonly port?: number;
+ readonly apiKey?: string | null;
+ readonly stderr?: Writable;
+}
+
+export interface HttpServerHandle {
+ readonly server: Server;
+ readonly host: string;
+ readonly port: number;
+ readonly url: string;
+ close(): Promise<void>;
+}
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+export async function startHttp(
+ ctx: MCPServerOptions,
+ opts: ServeHttpOptions = {},
+ runtimeOpts: MCPServerRuntimeOptions = {},
+): Promise<HttpServerHandle> {
+ const apiKey = opts.apiKey ?? null;
+ if (apiKey === null || apiKey === "") {
+ throw new Error("HTTP MCP transport requires --api-key");
+ }
+ const host = opts.host ?? "127.0.0.1";
+ const port = opts.port ?? 0;
+ const mcp = new MCPServer(ctx, runtimeOpts);
+ const server = createServer(async (req, res) => {
+ await handleHttpRequest(mcp, apiKey, req, res);
+ });
+ server.listen(port, host);
+ await once(server, "listening");
+ const addr = server.address();
+ const actualPort = typeof addr === "object" && addr !== null ? addr.port : port;
+ return {
+ server,
+ host,
+ port: actualPort,
+ url: `http://${host}:${actualPort}`,
+ close: () =>
+ new Promise<void>((resolve, reject) => {
+ server.close((err) => (err ? reject(err) : resolve()));
+ }),
+ };
+}
+
+export async function serveHttp(
+ ctx: MCPServerOptions,
+ opts: ServeHttpOptions = {},
+ runtimeOpts: MCPServerRuntimeOptions = {},
+): Promise<number> {
+ const handle = await startHttp(ctx, opts, runtimeOpts);
+ await once(handle.server, "close");
+ return 0;
+}
+
+async function handleHttpRequest(
+ mcp: MCPServer,
+ apiKey: string,
+ req: IncomingMessage,
+ res: ServerResponse,
+): Promise<void> {
+ if (!authorized(req, apiKey)) {
+ res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
+ res.end("Unauthorized\n");
+ return;
+ }
+ if (req.method !== "POST") {
+ res.writeHead(405, { allow: "POST", "content-type": "text/plain; charset=utf-8" });
+ res.end("Method Not Allowed\n");
+ return;
+ }
+
+ let raw: string;
+ try {
+ raw = await readBody(req);
+ } catch (exc) {
+ writeJson(res, errorResponse(null, INVALID_REQUEST, (exc as Error).message));
+ return;
+ }
+
+ let request: unknown;
+ try {
+ request = JSON.parse(raw);
+ } catch (exc) {
+ writeJson(res, errorResponse(null, PARSE_ERROR, `invalid JSON: ${(exc as Error).message}`));
+ return;
+ }
+ if (Array.isArray(request)) {
+ writeJson(
+ res,
+ errorResponse(
+ null,
+ INVALID_REQUEST,
+ "batch requests are not supported by the 2025-06-18 spec",
+ ),
+ );
+ return;
+ }
+ if (typeof request !== "object" || request === null) {
+ writeJson(res, errorResponse(null, INVALID_REQUEST, "request must be an object"));
+ return;
+ }
+
+ const jsonReq = request as Record<string, unknown>;
+ const response = await mcp.handleRequest(jsonReq);
+ if (response === null) {
+ res.writeHead(204);
+ res.end();
+ return;
+ }
+ const headers: Record<string, string> = {};
+ if (jsonReq["method"] === "initialize") headers["mcp-session-id"] = randomUUID();
+ const accept = String(req.headers.accept ?? "");
+ if (accept.includes("text/event-stream")) writeSse(res, response, headers);
+ else writeJson(res, response, headers);
+}
+
+function authorized(req: IncomingMessage, apiKey: string): boolean {
+ const presented = bearerToken(req.headers.authorization) ?? firstHeader(req.headers["x-api-key"]);
+ if (presented === undefined) return false;
+ return constantTimeEqual(presented, apiKey);
+}
+
+function bearerToken(value: string | undefined): string | undefined {
+ if (value === undefined) return undefined;
+ const m = /^Bearer\s+(.+)$/i.exec(value.trim());
+ return m?.[1];
+}
+
+function firstHeader(value: string | string[] | undefined): string | undefined {
+ if (Array.isArray(value)) return value[0];
+ return value;
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+ const da = createHash("sha256").update(a).digest();
+ const db = createHash("sha256").update(b).digest();
+ return timingSafeEqual(da, db);
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+ const chunks: Buffer[] = [];
+ let total = 0;
+ for await (const chunk of req) {
+ const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+ total += buf.length;
+ if (total > MAX_BODY_BYTES) throw new Error("request body too large");
+ chunks.push(buf);
+ }
+ return Buffer.concat(chunks).toString("utf8");
+}
+
+function writeJson(
+ res: ServerResponse,
+ response: JsonRpcResponse,
+ extraHeaders: Record<string, string> = {},
+): void {
+ res.writeHead(200, { "content-type": "application/json", ...extraHeaders });
+ res.end(JSON.stringify(response));
+}
+
+function writeSse(
+ res: ServerResponse,
+ response: JsonRpcResponse,
+ extraHeaders: Record<string, string> = {},
+): void {
+ res.writeHead(200, {
+ "content-type": "text/event-stream",
+ "cache-control": "no-cache",
+ ...extraHeaders,
+ });
+ res.end(`event: message\ndata: ${JSON.stringify(response)}\n\n`);
+}
diff --git a/src/mcp/index.ts b/src/mcp/index.ts
index 5839c7da..3f7b6b05 100644
--- a/src/mcp/index.ts
+++ b/src/mcp/index.ts
@@ -16,6 +16,7 @@ export {
MCPError,
} from "./protocol.ts";
export { MCPServer, errorResponse, type JsonRpcRequest, type JsonRpcResponse } from "./server.ts";
+export { serveHttp, startHttp, type ServeHttpOptions, type HttpServerHandle } from "./http.ts";
export { serveStdio, serveStdioFromString } from "./stdio.ts";
export { buildToolTable, PLACEHOLDER_AGENT_VALUES, type ToolDefinition } from "./tools.ts";
export { evaluateToolCapabilities, type RuntimeCapabilityWindow } from "./capabilities.ts";
diff --git a/tests/cli/o2b-mcp-launcher.test.ts b/tests/cli/o2b-mcp-launcher.test.ts
new file mode 100644
index 00000000..21c50217
--- /dev/null
+++ b/tests/cli/o2b-mcp-launcher.test.ts
@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import pkg from "../../package.json" with { type: "json" };
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-mcp-launcher-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("o2b-mcp console script", () => {
+ test("package bin exposes the launcher", () => {
+ expect(pkg.bin["o2b-mcp"]).toBe("./scripts/o2b-mcp");
+ const script = readFileSync(join(import.meta.dir, "../../scripts/o2b-mcp"), "utf8");
+ expect(script).toContain(' mcp "$@"');
+ });
+
+ test("launcher reaches MCP probe and forwards flags", async () => {
+ const proc = Bun.spawn(["bash", "scripts/o2b-mcp", "--probe", "--scope", "writer"], {
+ cwd: join(import.meta.dir, "../.."),
+ env: { ...process.env, VAULT_DIR: vault },
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ const [stdout, stderr, returncode] = await Promise.all([
+ new Response(proc.stdout).text(),
+ new Response(proc.stderr).text(),
+ proc.exited,
+ ]);
+ expect(stderr).toBe("");
+ expect(returncode).toBe(0);
+ expect(stdout).toContain("mcp probe ok: open-second-brain-writer");
+ });
+});
diff --git a/tests/core/brain/sessions-import-offline.test.ts b/tests/core/brain/sessions-import-offline.test.ts
new file mode 100644
index 00000000..8cbff00f
--- /dev/null
+++ b/tests/core/brain/sessions-import-offline.test.ts
@@ -0,0 +1,87 @@
+/**
+ * Offline guarantee for session import (t_85252236).
+ *
+ * The triage brief assumed `importSession` "requires provider
+ * credentials". It does not: the pipeline is fully deterministic. This
+ * regression test locks that guarantee by running an import under a
+ * scrubbed environment with a credential-read spy installed over
+ * `process.env`, asserting the import completes and never reads any
+ * provider-credential variable.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { DEFAULT_BRAIN_CONFIG_YAML } from "../../../src/core/brain/policy.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { importSession } from "../../../src/core/brain/sessions/import.ts";
+
+const CLAUDE = resolve("tests/fixtures/sessions/claude-minimal.jsonl");
+
+// Provider-credential variable names that must never be touched by a
+// deterministic import. OSB resolves its own embedding key from
+// `OPEN_SECOND_BRAIN_EMBEDDING_KEY`; the others are the generic provider
+// keys the upstream task brief called out.
+const CREDENTIAL_KEYS = [
+ "OPEN_SECOND_BRAIN_EMBEDDING_KEY",
+ "GEMINI_API_KEY",
+ "ANTHROPIC_API_KEY",
+ "OPENAI_API_KEY",
+] as const;
+
+let tmp: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-import-offline-"));
+ const dirs = brainDirs(tmp);
+ for (const d of [
+ dirs.brain,
+ dirs.inbox,
+ dirs.processed,
+ dirs.preferences,
+ dirs.retired,
+ dirs.log,
+ dirs.snapshots,
+ ]) {
+ mkdirSync(d, { recursive: true });
+ }
+ atomicWriteFileSync(join(dirs.brain, "_brain.yaml"), DEFAULT_BRAIN_CONFIG_YAML);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+test("importSession completes and never reads provider credentials", async () => {
+ const realEnv = process.env;
+ const touched: string[] = [];
+
+ // Scrub credentials and spy on every read so an accidental
+ // credential lookup is observable, not silent.
+ const scrubbed: NodeJS.ProcessEnv = { ...realEnv };
+ for (const k of CREDENTIAL_KEYS) delete scrubbed[k];
+
+ const spy = new Proxy(scrubbed, {
+ get(target, prop: string | symbol) {
+ if (typeof prop === "string" && (CREDENTIAL_KEYS as readonly string[]).includes(prop)) {
+ touched.push(prop);
+ }
+ return Reflect.get(target, prop);
+ },
+ });
+
+ // eslint-disable-next-line no-global-assign
+ (process as { env: NodeJS.ProcessEnv }).env = spy;
+ try {
+ const res = await importSession(tmp, CLAUDE, { agent: "test" });
+ expect(res.format).toBe("claude");
+ expect(res.signals_created).toBeGreaterThan(0);
+ } finally {
+ (process as { env: NodeJS.ProcessEnv }).env = realEnv;
+ }
+
+ expect(touched).toEqual([]);
+});
diff --git a/tests/core/search/index-offline.test.ts b/tests/core/search/index-offline.test.ts
new file mode 100644
index 00000000..cba8c779
--- /dev/null
+++ b/tests/core/search/index-offline.test.ts
@@ -0,0 +1,111 @@
+/**
+ * Offline code-only / keyless indexing (t_85252236).
+ *
+ * Locks the explicit, deferred backend-resolution guarantee inspired by
+ * Graphify's offline-first extraction: a corpus that needs only
+ * deterministic (lexical) processing runs to completion with no provider
+ * credentials, the structured `IndexStats` declares `backend: "offline"`,
+ * and a non-empty `deferredReason` explains why the semantic backend was
+ * not engaged. The credential check stays lazy (only the explicitly
+ * requested embedding path resolves a key), so a missing key never
+ * hard-fails a deterministic-only run.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+import { startFakeHttp, type FakeHttp } from "../../helpers/fake-http.ts";
+import { sqliteVecLoadable } from "../../helpers/sqlite-vec.ts";
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ const v = createTempVault("index-offline");
+ vault = v.vault;
+ dbPath = v.dbPath;
+ cleanup = v.cleanup;
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+test("keyless indexing completes with backend=offline and a deferred reason", async () => {
+ writeMd(vault, "a.md", "# A\n\nFirst note about something.");
+ writeMd(vault, "b.md", "# B\n\nSecond note discussing things.");
+ // Default config: semantic disabled, no API key resolved.
+ const cfg = makeConfig({ vault, dbPath });
+
+ const stats = await indexVault(cfg);
+
+ // The deterministic pipeline ran to completion.
+ expect(stats.added).toBe(2);
+ expect(stats.chunksTotal).toBeGreaterThanOrEqual(2);
+ // No semantic backend engaged: zero embeddings, explicit offline mode.
+ expect(stats.embeddingsComputed).toBe(0);
+ expect(stats.backend).toBe("offline");
+ expect(typeof stats.deferredReason).toBe("string");
+ expect((stats.deferredReason ?? "").length).toBeGreaterThan(0);
+});
+
+test("a missing key never hard-fails a deterministic-only run (lazy credential check)", async () => {
+ writeMd(vault, "a.md", "# A\n\nContent.");
+ // Semantic enabled + remote provider + NO key, but embeddings are not
+ // requested this run: the credential check must stay deferred and the
+ // lexical pipeline must complete offline rather than throwing.
+ const cfg = makeConfig({
+ vault,
+ dbPath,
+ semantic: {
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: "http://127.0.0.1:9",
+ model: "fake-model",
+ apiKey: null,
+ dimension: 4,
+ },
+ });
+
+ const stats = await indexVault(cfg);
+
+ expect(stats.added).toBe(1);
+ expect(stats.embeddingsComputed).toBe(0);
+ expect(stats.backend).toBe("offline");
+ // The reason is credential-aware when a key is the gating factor.
+ expect((stats.deferredReason ?? "").toLowerCase()).toContain("embedding_api_key");
+});
+
+test("the semantic backend is declared when embeddings are computed", async () => {
+ if (!sqliteVecLoadable()) return;
+ const server: FakeHttp = await startFakeHttp();
+ try {
+ writeMd(vault, "a.md", "# A\n\nFirst note about something.");
+ const cfg = makeConfig({
+ vault,
+ dbPath,
+ semantic: {
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: server.url,
+ model: "fake-model",
+ apiKey: "test-key",
+ dimension: 4,
+ timeoutMs: 5_000,
+ concurrency: 2,
+ batchSize: 8,
+ costGateUsd: 0,
+ },
+ });
+
+ const stats = await indexVault(cfg, { embeddings: true });
+
+ expect(stats.embeddingsComputed).toBeGreaterThan(0);
+ expect(stats.backend).toBe("semantic");
+ expect(stats.deferredReason).toBeNull();
+ } finally {
+ await server.close();
+ }
+});
diff --git a/tests/core/search/links.test.ts b/tests/core/search/links.test.ts
index 9252af07..16897b0e 100644
--- a/tests/core/search/links.test.ts
+++ b/tests/core/search/links.test.ts
@@ -80,3 +80,102 @@ test("skips mailto:", () => {
const links = extractLinks("[email me](mailto:[email protected])");
expect(links.length).toBe(0);
});
+
+test("resolves full reference-style links ([text][label])", () => {
+ const text = `See [the spec][spec] for details.\n\n[spec]: ./design.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]).toEqual({
+ linkType: "markdown_link",
+ targetPath: "./design.md",
+ linkText: "the spec",
+ });
+});
+
+test("resolves collapsed reference-style links ([text][])", () => {
+ const text = `Read [design][] now.\n\n[design]: notes/design.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]).toEqual({
+ linkType: "markdown_link",
+ targetPath: "notes/design.md",
+ linkText: "design",
+ });
+});
+
+test("resolves shortcut reference-style links ([text]) only when defined", () => {
+ const text = `Both [design] and [undefined] here.\n\n[design]: ./design.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]?.targetPath).toBe("./design.md");
+ expect(md[0]?.linkText).toBe("design");
+});
+
+test("reference labels match case-insensitively and normalise whitespace", () => {
+ const text = `See [The Spec][My Label].\n\n[my label]: ./design.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]?.targetPath).toBe("./design.md");
+ expect(md[0]?.linkText).toBe("The Spec");
+});
+
+test("reference definitions to external URLs and mailto are skipped", () => {
+ const text = `Go [home][h] or [mail][m] or [local][l].\n\n[h]: https://example.com\n[m]: mailto:[email protected]\n[l]: ./x.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]?.targetPath).toBe("./x.md");
+});
+
+test("strips anchor fragments from reference-style targets", () => {
+ const text = `Jump [there][t].\n\n[t]: notes/x.md#section`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md[0]?.targetPath).toBe("notes/x.md");
+});
+
+test("reference definitions accept titles and angle-bracketed targets", () => {
+ const text = `A [one][a] and [two][b].\n\n[a]: ./one.md "Title here"\n[b]: <./two.md>`;
+ const links = extractLinks(text);
+ const targets = links
+ .filter((l) => l.linkType === "markdown_link")
+ .map((l) => l.targetPath)
+ .toSorted();
+ expect(targets).toEqual(["./one.md", "./two.md"]);
+});
+
+test("reference-style image embeds (![text][label]) are not captured", () => {
+ const text = `![cover][img] and [real][doc].\n\n[img]: assets/cover.png\n[doc]: ./design.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]?.targetPath).toBe("./design.md");
+});
+
+test("reference definition lines do not themselves become links", () => {
+ const text = `[spec]: ./design.md`;
+ const links = extractLinks(text);
+ expect(links.filter((l) => l.linkType === "markdown_link").length).toBe(0);
+});
+
+test("inline links are not double-counted as shortcut references", () => {
+ const text = `[the spec](./design.md)\n\n[the spec]: ./other.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ // The inline link wins for its own occurrence; the bare [the spec] before the
+ // definition resolves to the definition target. Both are legitimate, distinct edges.
+ const targets = md.map((l) => l.targetPath).toSorted();
+ expect(targets).toContain("./design.md");
+});
+
+test("reference links inside code fences are ignored", () => {
+ const text = `\`\`\`\n[fake][ref]\n[ref]: ./nope.md\n\`\`\`\n\nReal [doc][d].\n\n[d]: ./design.md`;
+ const links = extractLinks(text);
+ const md = links.filter((l) => l.linkType === "markdown_link");
+ expect(md.length).toBe(1);
+ expect(md[0]?.targetPath).toBe("./design.md");
+});
diff --git a/tests/mcp/http-transport.test.ts b/tests/mcp/http-transport.test.ts
new file mode 100644
index 00000000..f8ee3417
--- /dev/null
+++ b/tests/mcp/http-transport.test.ts
@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { JSONRPC_VERSION, PROTOCOL_VERSION, startHttp } from "../../src/mcp/index.ts";
+
+interface JsonObject {
+ readonly [key: string]: any;
+}
+
+async function responseJson(res: Response): Promise<JsonObject> {
+ return (await res.json()) as JsonObject;
+}
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-mcp-http-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function rpc(method: string, id: number, params: Record<string, unknown> = {}) {
+ return { jsonrpc: JSONRPC_VERSION, id, method, params };
+}
+
+async function post(
+ url: string,
+ body: unknown,
+ opts: { key?: string; accept?: string } = {},
+): Promise<Response> {
+ const headers: Record<string, string> = {
+ "content-type": "application/json",
+ accept: opts.accept ?? "application/json",
+ };
+ if (opts.key !== undefined) headers.authorization = `Bearer ${opts.key}`;
+ return fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+}
+
+describe("Streamable HTTP MCP transport", () => {
+ test("refuses to start without an API key", async () => {
+ await expect(startHttp({ vault }, { host: "127.0.0.1", port: 0 })).rejects.toThrow(/api-key/i);
+ });
+
+ test("uses generic 401 for missing and wrong API keys", async () => {
+ const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
+ try {
+ const req = rpc("ping", 1);
+ const missing = await post(handle.url, req);
+ const wrong = await post(handle.url, req, { key: "wrong" });
+ expect(missing.status).toBe(401);
+ expect(wrong.status).toBe(401);
+ expect(await missing.text()).toBe("Unauthorized\n");
+ expect(await wrong.text()).toBe("Unauthorized\n");
+ } finally {
+ await handle.close();
+ }
+ });
+
+ test("authenticated initialize and tools/list round-trip through JSON responses", async () => {
+ const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
+ try {
+ const initRes = await post(
+ handle.url,
+ rpc("initialize", 1, { protocolVersion: PROTOCOL_VERSION, capabilities: {} }),
+ { key: "secret" },
+ );
+ expect(initRes.status).toBe(200);
+ expect(initRes.headers.get("mcp-session-id")).toBeTruthy();
+ const init = await responseJson(initRes);
+ expect(init.result.protocolVersion).toBe(PROTOCOL_VERSION);
+
+ const listRes = await post(handle.url, rpc("tools/list", 2), { key: "secret" });
+ const list = await responseJson(listRes);
+ expect(list.jsonrpc).toBe(JSONRPC_VERSION);
+ expect(Array.isArray(list.result.tools)).toBe(true);
+ expect(list.result.tools.length).toBeGreaterThan(0);
+ } finally {
+ await handle.close();
+ }
+ });
+
+ test("returns one SSE event when the client accepts event-stream", async () => {
+ const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
+ try {
+ const res = await post(handle.url, rpc("ping", 3), {
+ key: "secret",
+ accept: "application/json, text/event-stream",
+ });
+ expect(res.status).toBe(200);
+ expect(res.headers.get("content-type") ?? "").toContain("text/event-stream");
+ const text = await res.text();
+ expect(text).toContain("event: message");
+ expect(text).toContain('"id":3');
+ } finally {
+ await handle.close();
+ }
+ });
+
+ test("rejects JSON-RPC batch bodies like stdio", async () => {
+ const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
+ try {
+ const res = await post(handle.url, [rpc("ping", 1)], { key: "secret" });
+ const body = await responseJson(res);
+ expect(body.error.code).toBe(-32600);
+ expect(body.error.message).toContain("batch requests are not supported");
+ } finally {
+ await handle.close();
+ }
+ });
+});