feat: item 8 (search-mcp cartridge) + ADR-0013 streamable HTTP transport (epic #87)

[hyperpolymath]

Summary

Two epic #87 Tier A items in one PR — item 8 ships as code, item 14 ships as an RFC (the impl is ~1-2 weeks of focused work per epic estimate; design-first per the Tier B pattern).

Item 8 — `search-mcp` cartridge + `boj_search` bridge tool

Multi-provider web search behind one cartridge:

Provider	Strength	Auth env
Tavily	LLM-optimised summaries; answer-mode; extract API	`TAVILY_API_KEY`
Brave	Privacy-first index; no tracking	`BRAVE_SEARCH_API_KEY`
Exa	Neural search over high-quality content; extract API	`EXA_API_KEY`
Perplexity	Q&A-style with citations	`PERPLEXITY_API_KEY`

What's in the diff

• `cartridges/search-mcp/cartridge.json` — manifest with 4 cartridge-level tools (`search_authenticate` / `web` / `answer` / `extract`)
• `cartridges/search-mcp/README.adoc` — provider strengths matrix + bridge wiring note
• `mcp-bridge/lib/tools.js` — single `boj_search` bridge tool dispatching via `operation` + `provider` args; AAA-tier description carries the provider matrix so the LLM picks correctly
• `mcp-bridge/main.js` — dispatch case + hardeningGate requires `operation` + domain classification `search`
• `mcp-bridge/lib/offline-menu.js` — `search-mcp` added to Teranga tier so it shows in `boj_menu` even offline

Status

Bridge surface captured — MCP clients discover and invoke today. Backend dispatch implementation in Elixir/Zig deferred (separate work).

Tests

• ✅ 15/15 existing tests pass
• ✅ `tools/list` advertises `boj_search` with full 41+1 = 42 tools

Item 14 — ADR-0013 Streamable HTTP transport

RFC for adding MCP's HTTP+SSE transport alongside stdio. Same bridge binary; `BOJ_TRANSPORT=stdio|http|both` selects mode. No existing stdio clients break.

Why this RFC matters

JSR's runtime-compatibility question surfaced the gap: the user can't tick "Browsers" or "Cloudflare Workers" because the bridge legitimately doesn't run there. Item 14 is the right framing — not "make stdio work in a browser" (architecturally wrong) but "add an HTTP transport for the contexts where stdio doesn't work."

Key design points

• Single endpoint `POST /mcp` + `GET /mcp` (SSE) per latest MCP spec
• Session state via `Mcp-Session-Id` UUIDs (rate-limit counters, OTel trace context, in-flight async work)
• Four auth modes: none (loopback-only), bearer, mTLS, OIDC
• Mounts on the same Cowboy listener as webhooks (ADR-0004 honoured)
• Cartridge compat matrix: ~60% work on Workers (HTTP-API-based: GitHub, GitLab, Cloudflare, ML, Search, Hugging Face); 40% don't (local-only: browser-mcp, container-mcp, local-coord-mcp, local sandbox). New `boj_capabilities` resource reports per-deployment availability so clients don't try locally-impossible operations.

Three new deployment targets unlocked

• Cloudflare Workers (with Durable Objects for session state)
• Docker / Podman containers
• Browser-based agent web apps (via `fetch` against a hosted BoJ)

Implementation sketch

2 PRs over ~1-2 weeks:

• PR 1: bridge HTTP transport + auth modes + session manager (~1 week)
• PR 2: Workers deployment guide + Durable Objects shim + cold-start optimisation (~1 week)

Federation alignment

ADR-0010 (cross-machine federation) needs HTTPS transport anyway. ADR-0013's transport layer is reusable for federation. Webhook notifications (ADR-0011) fan out over this RFC's SSE stream.

Sequencing

Independent of all currently-open PRs. Item 8 lands as code; item 14 lands as RFC awaiting implementation in follow-up. After this lands, epic #87 Tier A remaining is items 7 (vector DBs × 4) + 9 (multi-modal × 4) — both multi-cartridge waves that warrant separate sessions, not a single rushed PR.

🤖 Generated with Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 33 issues detected

Severity	Count
🔴 Critical	19
🟠 High	5
🟡 Medium	9

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Issue in quality.yml",
    "type": "missing_workflow",
    "file": "quality.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in security-policy.yml",
    "type": "missing_workflow",
    "file": "security-policy.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action actions/cache@v4 needs attention",
    "type": "unpinned_action",
    "file": "abi-drift.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/.github/scripts/validate-eclexiaiser.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence