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.jsonindex 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.jsonindex 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.mdindex 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 providerdeclares 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.0diff --git a/README.md b/README.mdindex 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.## Whydiff --git a/docs/brainstorm/codegraph-link-depth-mcp/cli-output/claude.md b/docs/brainstorm/codegraph-link-depth-mcp/cli-output/claude.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 too2b status Show config / vault statuso2b 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 flagso2b doctor Run vault + adapter checkso2b index Rebuild the Markdown page indexo2b export-config Write a redacted config snapshoto2b 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-toolso2b tool-call Invoke an MCP tool handler from the CLIo2b help --json Print the command/flag manifest as JSONo2b completions --shell zsh Print completions for bash|zsh|fish|elvish|nushell|powershelldiff --git a/docs/mcp.md b/docs/mcp.mdindex 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```bashscripts/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 windowdiff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 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.jsonindex 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.yamlindex 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: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.yamlindex 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: truediff --git a/pyproject.toml b/pyproject.tomlindex 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-mcpnew file mode 100755index 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.tsindex 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 pluginsexport-config Write a redacted config snapshotindex 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/bininstall Multi-runtime install orchestrator (v0.10.11) β detect / plan / apply / --check (see install/)update Update OSB installation across all detected runtimesdiff --git a/src/core/search/indexer.ts b/src/core/search/indexer.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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();+ }+ });+});