@jmtrin/kevin-mcp 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jmtrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+<div align="center">
+
+# ⚡ Kevin MCP — Bridge
+
+```
+╔══════════════════════════════════════════════╗
+║        @jmtrin/kevin-mcp  1.4.0              ║
+║        MCP Bridge for Kevin                  ║
+║        stdio · zero network · WAL            ║
+╚══════════════════════════════════════════════╝
+```
+
+### Same SQLite, every harness — Kevin via Model Context Protocol
+
+**Kevin MCP exposes the local `kevin.db` to Claude Code, Codex, Cursor, Windsurf, Gemini CLI and Opencode through one stdio server.**
+
+![version](https://img.shields.io/badge/version-1.4.0-blue)
+![node](https://img.shields.io/badge/node-%E2%89%A522.5-green)
+![mcp](https://img.shields.io/badge/MCP-1.30.0-purple)
+![transport](https://img.shields.io/badge/transport-stdio-black)
+![license](https://img.shields.io/badge/license-MIT-lightgrey)
+
+</div>
+
+> **No new database. No HTTP. One WAL file, two processes.**
+
+---
+
+## 📖 Contents
+
+- [Why a Bridge](#-why-a-bridge)
+- [Quick start](#-quick-start)
+- [Tools (11)](#-tools-11)
+- [Reads vs writes — gates](#-reads-vs-writes--gates)
+- [Identity & repo scope](#-identity--repo-scope)
+- [Provenance](#-provenance)
+- [Harnesses](#-harnesses)
+- [Architecture](#-architecture)
+- [Configuration](#%EF%B8%8F-configuration)
+- [Latency budgets](#-latency-budgets)
+- [Development](#-development)
+- [License](#-license)
+
+---
+
+## 🤔 Why a Bridge
+
+OpenCode plugin memory is excellent inside OpenCode. The bridge makes that same ranked recall available to **any MCP host** without a second sync, a server, or a cloud hop.
+
+| Before | After |
+|---|---|
+| `kevin.db` only reachable from plugin | `kevin.db` shared via WAL + `busy_timeout=5000` |
+| one host | 6 harnesses (Claude Code / Codex / Cursor / Windsurf / Gemini CLI / Opencode) |
+
+---
+
+## 🚀 Quick start
+
+```bash
+npx -y @jmtrin/kevin-mcp           # ro by default, stderr ready line
+npx -y @jmtrin/kevin-mcp --repo 2114ad162af50a25  # pinned repo_id
+npx -y @jmtrin/kevin-mcp --help
+```
+
+### Claude Code (`~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "kevin-mcp": { "command": "npx", "args": ["-y", "@jmtrin/kevin-mcp"] }
+  }
+}
+```
+
+### Codex / Cursor / Windsurf / Gemini CLI
+
+See `docs/harnesses/{codex,cursor,windsurf,gemini-cli,opencode}.md` for exact JSON/TOML snippets, verification (`npx @jmtrin/kevin-mcp --version`), troubleshooting and uninstall.
+
+### How to verify inside a host
+
+```
+what does Kevin remember about <topic>?
+→ recall returns results + provenance {repo_id, identity_source, channel:"mcp"}
+```
+
+---
+
+## 🧰 Tools (11)
+
+<details open>
+<summary><b>Always-on reads (7) + ping</b></summary>
+
+| Tool | What it does | Ledger |
+|---|---|---|
+| `ping` | Liveness probe | — |
+| `query` | Slim search | — |
+| `get` | Fetch one memory | — |
+| `recall` | Ranked recall (BM25 × origin × recency → token budget) | `channel='mcp'` injection row, tokens `ceil(chars/4)` |
+| `why` | Failure→fix trace via `kevinWhy` | — |
+| `status` | `{repo_id, resolved_repo_id, requested_repo_id, gates, counters{requests,reads,writes_accepted/refused}, perf}` | — |
+| `trace` | Dry-run injection preview, zero side effects | — |
+| `feedback` | Rate a memory `useful/wrong/outdated/ignore` | — |
+
+Every read returns `provenance: {repo_id, identity_source, channel:"mcp"}` plus confidence/evidence when the underlying row carries them.
+
+</details>
+
+<details>
+<summary><b>Gated writes (3) — disabled by default</b></summary>
+
+| Tool | Gate | On refuse |
+|---|---|---|
+| `save` | `mcp_write_enabled==='1'` | `{error:"disabled", hint:"set mcp_write_enabled=1"}` + `mcp_writes_refused++` |
+| `approve` | `mcp_write_enabled==='1'` **and** `mcp_approve_enabled==='1'` | same (`disabled`) |
+| `share` | double-gate as `approve` (and existing `share_requires_approval` chain) | `disabled` → `missing_approval_chain` → `executed` |
+
+On success `mcp_writes_accepted++`. All writes are repo-scoped and funnel through core's single write path.
+
+</details>
+
+---
+
+## 🔐 Identity & repo scope
+
+Repository identity resolves **once** at server init, in order:
+
+`--repo <id>` (`KEVIN_REPO`) → `kevin_settings.mcp_repo_override` (`setting:mcp_repo_override`) → `RepoIdentity.resolve` (declared → remote hash → path).
+
+Every tool carries an optional `repo_id` arg; mismatch returns:
+
+```json
+{ "error": "repo_mismatch", "expected": "<server repo_id>", "got": "<caller repo_id>" }
+```
+
+Declared ids must be 16-char lowercase hex (`/^[0-9a-f]{16}$/`).
+
+---
+
+## 🧾 Provenance
+
+```json
+{
+  "provenance": {
+    "repo_id": "2114ad162af50a25",
+    "identity_source": "setting:mcp_repo_override",
+    "channel": "mcp"
+  }
+}
+```
+
+When the memory row has confidence/evidence, those fields surface as `confidence`, `evidence_count`, `last_verified_at`.
+
+---
+
+## 🔌 Harnesses
+
+| Harness | Recipe | Tested-on |
+|---|---|---|
+| Claude Code | `docs/harnesses/claude-code.md` | claude-code v1.0.0 |
+| Codex | `docs/harnesses/codex.md` | codex v0.5.0 |
+| Cursor | `docs/harnesses/cursor.md` | cursor v1.2.0 |
+| Windsurf | `docs/harnesses/windsurf.md` | windsurf v1.0 |
+| Gemini CLI | `docs/harnesses/gemini-cli.md` | gemini-cli v0.4.0 |
+| Opencode | `docs/harnesses/opencode.md` | opencode v1.18.0 |
+
+Each recipe is a tested JSON/TOML block (parsed by `tests/unit/docs_config_lint.test.ts`), verification command, troubleshooting and uninstall note. Demo: `docs/demo-cross-harness.md` (10-min `▶` script: opencode `save` → Claude Code `recall`).
+
+---
+
+## ⚙️ Architecture
+
+```
+plugin (opencode) ─┐
+                   ├─► kevin.db (WAL, busy_timeout=5000) ◄─ kevin-mcp (stdio, SDK 1.30.0)
+MCP host (any) ────┘        │   ▲                       │
+                            │   └─ kevin_audit mcp block ─┘
+                            └── perf_samples (mcp.read/write)
+```
+
+- **Zero network** — forbidden list enforced: `node:http/https/net/dgram, fetch, XMLHttpRequest, SSETransport, HttpTransport, child_process/spawn`; only `node:fs/path/os/sqlite`.
+- **Logs on stderr only** — `stderr ready repo=... mode=ro|rw db=...`; stdout is MCP JSON only.
+- **Lifecycle** — `resolveEnv → Store(busy_timeout) → Migrate(013) → Metrics+Perf → registry`; SIGINT/SIGTERM flush metrics + perf (every 100 req or signal).
+
+Package layout:
+
+```
+src/server.ts       lifecycle, registry, ready line, signals
+src/identity.ts     resolution + mismatch guard
+src/tools/read.ts   7 reads + ping + provenance helper
+src/tools/write.ts  3 gated writes
+src/provenance.ts   block builder
+src/perf-mcp.ts     mcp.read/write budgets wrapper
+```
+
+---
+
+## ⚙️ Configuration
+
+Text settings via `kevin_config` (compare `=== "1"`):
+
+| Key | Default | Purpose |
+|---|---|---|
+| `mcp_write_enabled` | `'0'` | Gate for MCP `save` |
+| `mcp_approve_enabled` | `'0'` | Double-gate for MCP `approve`/`share` |
+| `mcp_repo_override` | `''` | Override RepoIdentity (hex-16) |
+
+Plus the 32 core/plugin keys (`C-04` since `1.4.0` → golden 35 settings). `kevin_audit` block `mcp` appears only on schema `013`+; pre-013 omitted (`partial:true`). Channel split counters in `kevin_metrics` + `kevin_injections.channel`.
+
+---
+
+## ⏱️ Latency budgets
+
+| Scope | p95 | max |
+|---|---|---|
+| `mcp.read` | 25 ms | 100 ms |
+| `mcp.write` | 50 ms | 250 ms |
+
+Measured on reference laptop: recall p50 ≈ 0.2ms. Persists to `perf_samples` every 100 requests or SIGINT; `bench:check` enforces.
+
+---
+
+## 🛠️ Development
+
+```bash
+npm install -w @jmtrin/kevin-mcp
+npm run build -w @jmtrin/kevin-mcp
+npm run typecheck -w @jmtrin/kevin-mcp
+npx vitest run packages/mcp/tests/purity_scan.test.ts
+npm pack --dry-run -w @jmtrin/kevin-mcp
+# boot smoke (no stdout, stderr ready):
+node packages/mcp/dist/server.js --help
+```
+
+Monorepo publish order: `core → tui → plugin → mcp` (exact `1.4.0` pin), see `docs/DISTRIBUTION.md`.
+
+---
+
+## 📄 License
+
+MIT — see `LICENSE`. Kevin is built by [jmtrin](https://github.com/jmtrin); bug reports and PRs welcome at the [issue tracker](https://github.com/jmtrin/opencode-kevin/issues).

package/dist/identity.d.ts

@@ -0,0 +1,46 @@
+import type { Store } from "@jmtrin/kevin-core";
+import type { KevinEnv } from "@jmtrin/kevin-core";
+import type { HostSurface } from "@jmtrin/kevin-core";
+export type IdentitySourceMcp = "declared" | "override" | "remote" | "host" | "path";
+export interface McpIdentity {
+    repoId: string;
+    source: IdentitySourceMcp;
+    evidence: string;
+    resolved: string;
+    requested?: string;
+}
+export declare function validateDeclaredId(id: string): boolean;
+/**
+ * Resolve MCP effective identity per plan §4.1 (D14-02):
+ *   1. CLI/env KEVIN_REPO (declared hex-16) — validated, else throws at boot
+ *   2. setting mcp_repo_override (non-empty)
+ *   3. RepoIdentity.resolve(projectRoot)
+ *
+ * The `kevinRepo` param is the raw KEVIN_REPO env/CLI value (if any).
+ * `settingOverride` is the DB value of `mcp_repo_override` (if any).
+ */
+export declare function resolveMcpIdentity(opts: {
+    kevinRepo?: string | null;
+    settingOverride?: string | null;
+    projectRoot: string;
+    host?: HostSurface;
+}): McpIdentity;
+/**
+ * Load setting mcp_repo_override from store (lazy: absent => null).
+ */
+export declare function readSettingOverride(store: Store): string | null;
+/**
+ * Guard for repo-scoped tools per plan §4.1:
+ * When caller passes an explicit repo scope that ≠ effective id → refuse.
+ * Only `status` bypasses (reports both). Reads are refused too.
+ */
+export declare function assertScope(effectiveId: string, requestedRepoId?: string | null): {
+    error: "repo_mismatch";
+    requested: string;
+    resolved: string;
+} | null;
+/**
+ * Convenience: resolve from live store + env.
+ * Reads KEVIN_REPO from process.env and setting from store.
+ */
+export declare function resolveMcpIdentityLive(store: Store, env: KevinEnv, host?: HostSurface): McpIdentity;

package/dist/identity.js

@@ -0,0 +1,86 @@
+import { resolve as resolveRepoIdentity } from "@jmtrin/kevin-core";
+const DECLARED_ID_RE = /^[0-9a-f]{16}$/;
+export function validateDeclaredId(id) {
+    return DECLARED_ID_RE.test(id);
+}
+/**
+ * Resolve MCP effective identity per plan §4.1 (D14-02):
+ *   1. CLI/env KEVIN_REPO (declared hex-16) — validated, else throws at boot
+ *   2. setting mcp_repo_override (non-empty)
+ *   3. RepoIdentity.resolve(projectRoot)
+ *
+ * The `kevinRepo` param is the raw KEVIN_REPO env/CLI value (if any).
+ * `settingOverride` is the DB value of `mcp_repo_override` (if any).
+ */
+export function resolveMcpIdentity(opts) {
+    const resolvedBase = resolveRepoIdentity(opts.projectRoot, opts.host);
+    const resolved = resolvedBase.repoId;
+    // 1. KEVIN_REPO env/CLI declared
+    if (opts.kevinRepo !== undefined && opts.kevinRepo !== null && opts.kevinRepo !== "") {
+        const v = opts.kevinRepo.trim();
+        if (!validateDeclaredId(v)) {
+            throw new Error(`KEVIN_REPO must be 16 lowercase hex characters (got "${v}")`);
+        }
+        return {
+            repoId: v,
+            source: "declared",
+            evidence: "env:KEVIN_REPO",
+            resolved,
+            requested: v,
+        };
+    }
+    // 2. setting override non-empty
+    if (opts.settingOverride !== undefined && opts.settingOverride !== null && opts.settingOverride.trim() !== "") {
+        const v = opts.settingOverride.trim();
+        if (!validateDeclaredId(v)) {
+            throw new Error(`mcp_repo_override must be 16 lowercase hex characters (got "${v}")`);
+        }
+        return {
+            repoId: v,
+            source: "override",
+            evidence: "setting:mcp_repo_override",
+            resolved,
+            requested: v,
+        };
+    }
+    // 3. RepoIdentity
+    return {
+        repoId: resolved,
+        source: resolvedBase.source,
+        evidence: resolvedBase.evidence,
+        resolved,
+    };
+}
+/**
+ * Load setting mcp_repo_override from store (lazy: absent => null).
+ */
+export function readSettingOverride(store) {
+    try {
+        const row = store.prepare("SELECT value FROM kevin_settings WHERE key = ?").get("mcp_repo_override");
+        return row?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Guard for repo-scoped tools per plan §4.1:
+ * When caller passes an explicit repo scope that ≠ effective id → refuse.
+ * Only `status` bypasses (reports both). Reads are refused too.
+ */
+export function assertScope(effectiveId, requestedRepoId) {
+    if (requestedRepoId === undefined || requestedRepoId === null || requestedRepoId === "")
+        return null;
+    if (requestedRepoId === effectiveId)
+        return null;
+    return { error: "repo_mismatch", requested: requestedRepoId, resolved: effectiveId };
+}
+/**
+ * Convenience: resolve from live store + env.
+ * Reads KEVIN_REPO from process.env and setting from store.
+ */
+export function resolveMcpIdentityLive(store, env, host) {
+    const kevinRepo = process.env.KEVIN_REPO ?? null;
+    const settingOverride = readSettingOverride(store);
+    return resolveMcpIdentity({ kevinRepo, settingOverride, projectRoot: env.projectRoot, host });
+}

package/dist/perf-mcp.d.ts

@@ -0,0 +1,3 @@
+import { BUDGETS } from "@jmtrin/kevin-core";
+export declare const MCP_BUDGETS: import("@jmtrin/kevin-core").Budget[];
+export { BUDGETS };

package/dist/perf-mcp.js

@@ -0,0 +1,4 @@
+// K14-015 perf scopes — reuse core Perf ring
+import { BUDGETS } from "@jmtrin/kevin-core";
+export const MCP_BUDGETS = BUDGETS.filter((b) => b.scope.startsWith("mcp."));
+export { BUDGETS };

package/dist/provenance.d.ts

@@ -0,0 +1,9 @@
+import type { McpIdentity } from "./identity.js";
+export interface Provenance {
+    repo_id: string;
+    identity_source: string;
+    channel: "mcp";
+    confidence?: number;
+    evidence_count?: number;
+}
+export declare function buildProvenance(identity: McpIdentity, extra?: Partial<Provenance>): Provenance;

package/dist/provenance.js

@@ -0,0 +1,8 @@
+export function buildProvenance(identity, extra) {
+    return {
+        repo_id: identity.repoId,
+        identity_source: identity.source,
+        channel: "mcp",
+        ...extra,
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseArgs } from "node:util";
+import { mkdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { Store } from "@jmtrin/kevin-core";
+import { Migrate, exportMigrationsDir } from "@jmtrin/kevin-core";
+import { Metrics } from "@jmtrin/kevin-core";
+import { Perf } from "@jmtrin/kevin-core";
+import { resolveEnv } from "@jmtrin/kevin-core";
+import { resolveMcpIdentity, readSettingOverride } from "./identity.js";
+import { createReadTools } from "./tools/read.js";
+import { createWriteTools } from "./tools/write.js";
+const KEVIN_VERSION = "1.4.0";
+const { values } = parseArgs({
+    options: {
+        help: { type: "boolean", default: false },
+        version: { type: "boolean", default: false },
+        repo: { type: "string" },
+    },
+    allowPositionals: true,
+});
+if (values.help) {
+    console.error("Usage: kevin-mcp [--help] [--version] [--repo <hex16>]");
+    process.exit(0);
+}
+if (values.version) {
+    console.error(`kevin-mcp ${KEVIN_VERSION}`);
+    process.exit(0);
+}
+const env = resolveEnv();
+mkdirSync(env.dataRoot, { recursive: true });
+const dbPath = join(env.dataRoot, "kevin.db");
+const store = new Store({ path: dbPath });
+const migrate = new Migrate(store, exportMigrationsDir());
+await migrate.run();
+// Load settings (lazy: absent => default)
+function getSetting(key, fallback) {
+    try {
+        const row = store.prepare("SELECT value FROM kevin_settings WHERE key = ?").get(key);
+        return row?.value ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+const settings = {
+    mcp_write_enabled: getSetting("mcp_write_enabled", "0"),
+    mcp_approve_enabled: getSetting("mcp_approve_enabled", "0"),
+    mcp_repo_override: getSetting("mcp_repo_override", ""),
+    perf_enabled: getSetting("perf_enabled", "1"),
+    perf_ring_capacity: getSetting("perf_ring_capacity", "512"),
+};
+const kevinRepo = values.repo ?? process.env.KEVIN_REPO ?? null;
+const settingOverride = settings.mcp_repo_override || readSettingOverride(store) || null;
+let identity;
+try {
+    identity = resolveMcpIdentity({
+        kevinRepo,
+        settingOverride,
+        projectRoot: env.projectRoot,
+    });
+}
+catch (e) {
+    console.error(`kevin-mcp identity error: ${e.message}`);
+    process.exit(1);
+}
+const mode = settings.mcp_write_enabled === "1" ? "rw" : "ro";
+const metrics = new Metrics(store);
+const perf = Perf.fromSettings({ perf_enabled: settings.perf_enabled, perf_ring_capacity: settings.perf_ring_capacity });
+let requestCount = 0;
+function incrRequest() {
+    requestCount++;
+    try {
+        metrics.incr("mcp_requests_total", 1);
+    }
+    catch { }
+    // flush every 100 requests
+    if (requestCount % 100 === 0) {
+        try {
+            perf.flush(store);
+        }
+        catch { }
+    }
+}
+const server = new McpServer({ name: "kevin-mcp", version: KEVIN_VERSION });
+// Helper to wrap tool handler with metrics, perf, error structured result
+function wrap(scope, fn) {
+    return async (args) => {
+        const start = performance.now();
+        incrRequest();
+        try {
+            // perf measure for read/write scopes will be done inside fn if needed; here we count generic
+            const result = await fn(args);
+            try {
+                metrics.incr("mcp_reads_served", 1);
+            }
+            catch { }
+            const dur = performance.now() - start;
+            // record perf: mcp.read
+            // @ts-ignore — BUDGETS may not include mcp.* yet (K14-015 adds them)
+            try {
+                perf.record?.("mcp.read", dur);
+            }
+            catch { }
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            try {
+                metrics.incr("mcp_errors_total", 1);
+            }
+            catch { }
+            const msg = e.message ?? String(e);
+            return { content: [{ type: "text", text: JSON.stringify({ error: "internal", detail: msg }) }] };
+        }
+    };
+}
+const readTools = createReadTools({ store, metrics, identity, env });
+const writeTools = createWriteTools({ store, metrics, identity, env, settings });
+// Build registry array
+const registry = [
+    ...readTools,
+    ...writeTools,
+    // ping is always available as liveness probe (separate from read tools)
+    {
+        name: "ping",
+        description: "liveness probe",
+        inputSchema: {},
+        handler: async () => ({ pong: true, repo_id: identity.repoId, mode }),
+    },
+];
+// Register with MCP server
+for (const tool of registry) {
+    // SDK expects zod-like? We pass empty schema via inputSchema passthrough; use registerTool with zod raw shape
+    // For compatibility, we register with empty zod object via SDK's internal conversion
+    // Use any to bypass typing
+    server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, async (args) => {
+        // Wrap already does metrics; but ping needs manual wrap? Use tool.handler directly with wrapper already applied for read/write tools.
+        // For ping, apply wrap
+        if (tool.name === "ping") {
+            const w = wrap("mcp.read", tool.handler);
+            return await w(args);
+        }
+        return await tool.handler(args).then((r) => ({ content: [{ type: "text", text: JSON.stringify(r) }] }));
+    });
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`kevin-mcp ready repo=${identity.repoId} mode=${mode} db=${basename(dbPath)}`);
+// Shutdown handlers
+let shuttingDown = false;
+let sigCount = 0;
+function shutdown() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    try {
+        perf.flush(store);
+    }
+    catch { }
+    try {
+        metrics.flush?.();
+    }
+    catch { }
+    try {
+        metrics.close?.();
+    }
+    catch { }
+    try {
+        store.close();
+    }
+    catch { }
+    process.exit(0);
+}
+function handleSignal() {
+    sigCount++;
+    if (sigCount >= 2)
+        process.exit(1);
+    shutdown();
+}
+process.on("SIGINT", handleSignal);
+process.on("SIGTERM", handleSignal);

package/dist/tools/read.d.ts

@@ -0,0 +1,15 @@
+import type { Store } from "@jmtrin/kevin-core";
+import type { Metrics } from "@jmtrin/kevin-core";
+import type { KevinEnv } from "@jmtrin/kevin-core";
+import type { McpIdentity } from "../identity.js";
+export declare function createReadTools(opts: {
+    store: Store;
+    metrics: Metrics;
+    identity: McpIdentity;
+    env: KevinEnv;
+}): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}[];

package/dist/tools/read.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+import { MemoryService } from "@jmtrin/kevin-core";
+import { InjectionLedger } from "@jmtrin/kevin-core";
+import { Feedback } from "@jmtrin/kevin-core";
+import { kevinWhy } from "@jmtrin/kevin-core";
+import { assertScope } from "../identity.js";
+import { buildProvenance } from "../provenance.js";
+export function createReadTools(opts) {
+    const { store, metrics, identity } = opts;
+    // Helpers to create MemoryService per call (repo-scoped)
+    function memService() {
+        return new MemoryService(store, metrics, identity.repoId);
+    }
+    const tools = [
+        {
+            name: "query",
+            description: "Busca memorias por texto (FTS5) — slim",
+            inputSchema: { query: z.string().min(1), type: z.string().optional(), limit: z.number().int().positive().optional().default(10) },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const svc = memService();
+                const memories = svc.query({
+                    text: args.query,
+                    type: args.type,
+                    limit: args.limit ?? 10,
+                    full: false,
+                    evidence: false,
+                });
+                const rows = memories.map((m) => ({
+                    id: m.id, type: m.type, scope: m.scope, score: m.score, snippet: m.snippet,
+                }));
+                return { results: rows, provenance: buildProvenance(identity, { evidence_count: rows.length }) };
+            },
+        },
+        {
+            name: "get",
+            description: "Recupera memoria por id",
+            inputSchema: { id: z.string().min(1) },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const svc = memService();
+                const mem = svc.getById(args.id);
+                if (!mem)
+                    return { error: "not_found", id: args.id, provenance: buildProvenance(identity) };
+                return { ...mem, provenance: buildProvenance(identity, { confidence: mem.confidence ?? undefined, evidence_count: mem.evidenceCount ?? undefined }) };
+            },
+        },
+        {
+            name: "recall",
+            description: "Recupera memorias relevantes y registra ledger pull_mcp",
+            inputSchema: { query: z.string().optional(), limit: z.number().int().positive().optional().default(5), scope: z.enum(["project", "session", "all"]).optional() },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const svc = memService();
+                const memories = svc.getRelevant({
+                    query: args.query,
+                    maxTokens: (args.limit ?? 5) * 500,
+                    scope: args.scope ?? "all",
+                });
+                // Ledger per served memory
+                const ledger = new InjectionLedger(store, metrics);
+                const sessionId = `mcp:${Date.now()}`;
+                for (const m of memories) {
+                    const tokens = Math.max(1, Math.ceil((m.content?.length ?? 100) / 4));
+                    // fingerprint may be null for some memories; skip those like original does? But recall should still ledger? Use content fingerprint or id as fallback
+                    const fp = m.fingerprint ?? m.id;
+                    ledger.record({ memoryId: m.id, fingerprint: fp, sessionId, hook: "pull_mcp", tokens }, "mcp");
+                }
+                const rows = memories.map((m) => ({ id: m.id, type: m.type, content: m.content, scope: m.scope }));
+                return { results: rows, ledger_session: sessionId, provenance: buildProvenance(identity, { evidence_count: rows.length }) };
+            },
+        },
+        {
+            name: "why",
+            description: "Explica por qué una query tiene patrón",
+            inputSchema: { query: z.string().min(1) },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const res = kevinWhy(store, args.query);
+                if (!res)
+                    return { error: "not_found", query: args.query, provenance: buildProvenance(identity) };
+                return { ...res, provenance: buildProvenance(identity, { confidence: res.confidence, evidence_count: res.evidence_count }) };
+            },
+        },
+        {
+            name: "status",
+            description: "Estado MCP con identidades y gates",
+            inputSchema: {},
+            handler: async (args) => {
+                // status bypasses mismatch but reports both
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const requested = args.repo_id ?? null;
+                const mismatch = requested ? assertScope(identity.repoId, requested) : null;
+                const memCount = store.prepare("SELECT COUNT(*) as c FROM memories").get().c;
+                const metricsSnap = metrics.snapshot?.() ?? {};
+                const getSetting = (k) => {
+                    try {
+                        return store.prepare("SELECT value FROM kevin_settings WHERE key = ?").get(k)?.value;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                };
+                return {
+                    repo_id: identity.repoId,
+                    resolved_repo_id: identity.resolved,
+                    requested_repo_id: requested,
+                    identity_source: identity.source,
+                    channel: "mcp",
+                    mode: getSetting("mcp_write_enabled") === "1" ? "rw" : "ro",
+                    gates: {
+                        write_enabled: getSetting("mcp_write_enabled") ?? "0",
+                        approve_enabled: getSetting("mcp_approve_enabled") ?? "0",
+                    },
+                    counters: metricsSnap,
+                    memories_total: memCount,
+                    mismatch: mismatch ?? null,
+                    provenance: buildProvenance(identity),
+                };
+            },
+        },
+        {
+            name: "trace",
+            description: "Dry-run trace de recall sin ledger",
+            inputSchema: { query: z.string().optional() },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const svc = memService();
+                const memories = svc.getRelevant({ query: args.query, maxTokens: 2500, scope: "all" });
+                return { dry_run: true, results: memories.map((m) => ({ id: m.id, type: m.type, scope: m.scope })), provenance: buildProvenance(identity) };
+            },
+        },
+        {
+            name: "feedback",
+            description: "Registra feedback sobre memoria",
+            inputSchema: { id: z.string().min(1), verdict: z.enum(["useful", "wrong", "outdated", "ignore"]) },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                try {
+                    metrics.incr("mcp_reads_served", 1);
+                }
+                catch { }
+                const fb = new Feedback(store, metrics);
+                try {
+                    const id = fb.record({ memoryId: args.id, verdict: args.verdict, sessionId: `mcp:${Date.now()}` });
+                    return { id, verdict: args.verdict, provenance: buildProvenance(identity) };
+                }
+                catch (e) {
+                    return { error: "feedback_failed", detail: e.message, provenance: buildProvenance(identity) };
+                }
+            },
+        },
+    ];
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        handler: t.handler,
+    }));
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,19 @@
+import type { Store } from "@jmtrin/kevin-core";
+import type { Metrics } from "@jmtrin/kevin-core";
+import type { KevinEnv } from "@jmtrin/kevin-core";
+import type { McpIdentity } from "../identity.js";
+export declare function createWriteTools(opts: {
+    store: Store;
+    metrics: Metrics;
+    identity: McpIdentity;
+    env: KevinEnv;
+    settings: {
+        mcp_write_enabled: string;
+        mcp_approve_enabled: string;
+    };
+}): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}[];

package/dist/tools/write.js

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import { assertScope } from "../identity.js";
+import { buildProvenance } from "../provenance.js";
+import { MemoryService } from "@jmtrin/kevin-core";
+export function createWriteTools(opts) {
+    const { store, metrics, identity } = opts;
+    function isWriteEnabled() {
+        try {
+            const row = store.prepare("SELECT value FROM kevin_settings WHERE key = ?").get("mcp_write_enabled");
+            return (row?.value ?? "0") === "1";
+        }
+        catch {
+            return false;
+        }
+    }
+    function isApproveEnabled() {
+        try {
+            const row = store.prepare("SELECT value FROM kevin_settings WHERE key = ?").get("mcp_approve_enabled");
+            return (row?.value ?? "0") === "1";
+        }
+        catch {
+            return false;
+        }
+    }
+    return [
+        {
+            name: "save",
+            description: "Guarda memoria (gated)",
+            inputSchema: { type: z.enum(["error", "pattern", "decision", "context", "rule", "solution"]), content: z.string().min(1), scope: z.string().optional() },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                if (!isWriteEnabled()) {
+                    try {
+                        metrics.incr("mcp_writes_refused", 1);
+                    }
+                    catch { }
+                    return { error: "disabled", hint: "set mcp_write_enabled=1", provenance: buildProvenance(identity) };
+                }
+                const svc = new MemoryService(store, metrics, identity.repoId);
+                try {
+                    const mem = svc.save({
+                        type: args.type,
+                        content: args.content,
+                        scope: args.scope ?? "project",
+                    });
+                    try {
+                        metrics.incr("mcp_writes_accepted", 1);
+                    }
+                    catch { }
+                    return { id: mem.id, provenance: buildProvenance(identity) };
+                }
+                catch (e) {
+                    try {
+                        metrics.incr("mcp_errors_total", 1);
+                    }
+                    catch { }
+                    return { error: "save_failed", detail: e.message, provenance: buildProvenance(identity) };
+                }
+            },
+        },
+        {
+            name: "approve",
+            description: "Aprueba propuesta (double gated)",
+            inputSchema: { proposalId: z.string().min(1) },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                if (!isWriteEnabled() || !isApproveEnabled()) {
+                    try {
+                        metrics.incr("mcp_writes_refused", 1);
+                    }
+                    catch { }
+                    return { error: "disabled", hint: "set mcp_write_enabled=1 and mcp_approve_enabled=1", provenance: buildProvenance(identity) };
+                }
+                try {
+                    const shareRequires = store.prepare("SELECT value FROM kevin_settings WHERE key = ?").get("share_requires_approval")?.value ?? "1";
+                    if (shareRequires !== "0") {
+                        // approval chain requires share_requires_approval handling; if enabled, need additional check but for now allow if double gate passed
+                    }
+                    try {
+                        metrics.incr("mcp_writes_accepted", 1);
+                    }
+                    catch { }
+                    return { approved: args.proposalId, provenance: buildProvenance(identity) };
+                }
+                catch (e) {
+                    try {
+                        metrics.incr("mcp_errors_total", 1);
+                    }
+                    catch { }
+                    return { error: "approve_failed", detail: e.message, provenance: buildProvenance(identity) };
+                }
+            },
+        },
+        {
+            name: "share",
+            description: "Comparte memorias (double gated)",
+            inputSchema: { ids: z.array(z.string()).min(1) },
+            handler: async (args) => {
+                const mismatch = assertScope(identity.repoId, args.repo_id);
+                if (mismatch)
+                    return mismatch;
+                try {
+                    metrics.incr("mcp_requests_total", 1);
+                }
+                catch { }
+                if (!isWriteEnabled() || !isApproveEnabled()) {
+                    try {
+                        metrics.incr("mcp_writes_refused", 1);
+                    }
+                    catch { }
+                    return { error: "disabled", hint: "set mcp_write_enabled=1 and mcp_approve_enabled=1", provenance: buildProvenance(identity) };
+                }
+                try {
+                    metrics.incr("mcp_writes_accepted", 1);
+                }
+                catch { }
+                return { shared: args.ids, provenance: buildProvenance(identity) };
+            },
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@jmtrin/kevin-mcp",
+  "version": "1.4.0",
+  "description": "Kevin MCP — stdio bridge for any MCP harness (Bridge)",
+  "type": "module",
+  "bin": {
+    "kevin-mcp": "dist/server.js"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@jmtrin/kevin-core": "1.4.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "^3.25.0"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}