@jervaise/jerv-mcp 0.6.0

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { canonicalToolNames, runJervTool } from "./tools.js";
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const VERSION = readPackageVersion();
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+    console.log(VERSION);
+    process.exit(0);
+}
+function send(message) {
+    const body = JSON.stringify(message);
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`);
+}
+function toolDescription(name) {
+    return `Run canonical Jerv memory tool ${name} through jerv-cli.`;
+}
+function toolsList() {
+    return canonicalToolNames.map((name) => ({
+        name,
+        description: toolDescription(name),
+        inputSchema: {
+            type: "object",
+            additionalProperties: true,
+            properties: {},
+        },
+    }));
+}
+async function handle(request) {
+    if (!request.id && request.method?.startsWith("notifications/"))
+        return;
+    if (request.method === "initialize") {
+        send({
+            jsonrpc: "2.0",
+            id: request.id,
+            result: {
+                protocolVersion: "2024-11-05",
+                capabilities: { tools: {} },
+                serverInfo: { name: "jerv-mcp", version: VERSION },
+            },
+        });
+        return;
+    }
+    if (request.method === "tools/list") {
+        send({ jsonrpc: "2.0", id: request.id, result: { tools: toolsList() } });
+        return;
+    }
+    if (request.method === "tools/call") {
+        const name = String(request.params?.name ?? "");
+        if (!canonicalToolNames.includes(name)) {
+            send({ jsonrpc: "2.0", id: request.id, error: { code: -32602, message: `unknown tool: ${name}` } });
+            return;
+        }
+        const result = await runJervTool(name, (request.params?.arguments ?? {}), { cwd: process.cwd() });
+        send({
+            jsonrpc: "2.0",
+            id: request.id,
+            result: {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            },
+        });
+        return;
+    }
+    send({ jsonrpc: "2.0", id: request.id, error: { code: -32601, message: `unknown method: ${request.method ?? ""}` } });
+}
+function parseFrames(buffer) {
+    const requests = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const headerEnd = buffer.indexOf("\r\n\r\n", offset, "utf8");
+        if (headerEnd < 0)
+            break;
+        const header = buffer.slice(offset, headerEnd).toString("utf8");
+        const match = /content-length:\s*(\d+)/i.exec(header);
+        if (!match)
+            break;
+        const length = Number(match[1]);
+        const start = headerEnd + 4;
+        const end = start + length;
+        if (end > buffer.length)
+            break;
+        requests.push(JSON.parse(buffer.slice(start, end).toString("utf8")));
+        offset = end;
+    }
+    return { requests, rest: buffer.slice(offset) };
+}
+let frameBuffer = Buffer.alloc(0);
+let queue = Promise.resolve();
+function pump(chunk) {
+    frameBuffer = Buffer.concat([frameBuffer, chunk]);
+    const parsed = parseFrames(frameBuffer);
+    frameBuffer = parsed.rest;
+    for (const request of parsed.requests) {
+        queue = queue.then(() => handle(request));
+    }
+}
+process.stdin.on("data", (chunk) => pump(chunk));
+process.stdin.on("error", (error) => {
+    send({ jsonrpc: "2.0", id: null, error: { code: -32000, message: error.message } });
+    process.exitCode = 1;
+});

package/dist/tools.d.ts

@@ -0,0 +1,21 @@
+export declare const canonicalToolNames: readonly ["jerv_resume", "jerv_save", "jerv_block_get", "jerv_block_put", "jerv_northstar_list", "jerv_northstar_show", "jerv_northstar_set", "jerv_recall_list", "jerv_recall_show", "jerv_archival_search", "jerv_archival_insert", "jerv_context_compile", "jerv_event_append", "jerv_governance_action", "jerv_graph_query"];
+export type CanonicalToolName = (typeof canonicalToolNames)[number];
+export interface CliResult {
+    stdout: string;
+    stderr?: string;
+    status?: number | null;
+}
+export interface CliRunOptions {
+    cwd?: string;
+    input?: string;
+}
+export type CliRunner = (args: string[], options?: CliRunOptions) => Promise<CliResult> | CliResult;
+export interface RunJervToolOptions {
+    cwd?: string;
+    runCli?: CliRunner;
+}
+type ToolArgs = Record<string, unknown>;
+export declare function redactSecretText(text: string): string;
+export declare function defaultRunCli(args: string[], options?: CliRunOptions): Promise<CliResult>;
+export declare function runJervTool(name: CanonicalToolName, args: ToolArgs, options?: RunJervToolOptions): Promise<unknown>;
+export {};

package/dist/tools.js

@@ -0,0 +1,207 @@
+import { spawn } from "node:child_process";
+export const canonicalToolNames = [
+    "jerv_resume",
+    "jerv_save",
+    "jerv_block_get",
+    "jerv_block_put",
+    "jerv_northstar_list",
+    "jerv_northstar_show",
+    "jerv_northstar_set",
+    "jerv_recall_list",
+    "jerv_recall_show",
+    "jerv_archival_search",
+    "jerv_archival_insert",
+    "jerv_context_compile",
+    "jerv_event_append",
+    "jerv_governance_action",
+    "jerv_graph_query",
+];
+const GITHUB_TOKEN_RE = /gh[pousr]_[A-Za-z0-9_]{20,}/g;
+const ASSIGNMENT_SECRET_RE = /\b(?:TOKEN|PASSWORD|PASS|SECRET|API_KEY|PRIVATE_KEY)\s*=\s*[^\s]+/gi;
+export function redactSecretText(text) {
+    return text
+        .replace(GITHUB_TOKEN_RE, "[REDACTED_SECRET]")
+        .replace(ASSIGNMENT_SECRET_RE, (match) => {
+        const key = match.split("=")[0]?.trim() || "SECRET";
+        return `${key}=[REDACTED_SECRET]`;
+    });
+}
+function stringArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function booleanArg(args, key) {
+    return args[key] === true;
+}
+function arrayArg(args, key) {
+    const value = args[key];
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function requireString(args, key) {
+    const value = stringArg(args, key);
+    if (!value)
+        throw new Error(`${key} is required`);
+    return value;
+}
+export async function defaultRunCli(args, options = {}) {
+    const invocation = process.platform === "win32"
+        ? { command: "cmd.exe", args: ["/d", "/s", "/c", "jerv-cli", ...args] }
+        : { command: "jerv-cli", args };
+    return new Promise((resolve, reject) => {
+        const child = spawn(invocation.command, invocation.args, {
+            cwd: options.cwd,
+            env: { ...process.env, JERV_AGENT_SURFACE: "mcp" },
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => { stdout += chunk; });
+        child.stderr.on("data", (chunk) => { stderr += chunk; });
+        child.on("error", reject);
+        child.on("close", (status) => {
+            if (status === 0) {
+                resolve({ stdout, stderr, status });
+                return;
+            }
+            reject(Object.assign(new Error(`jerv-cli exited with status ${status}`), { stdout, stderr, status }));
+        });
+        child.stdin.end(options.input);
+    });
+}
+function toolToCli(name, args) {
+    switch (name) {
+        case "jerv_resume":
+            return { cliArgs: ["resume", "--json"] };
+        case "jerv_save": {
+            const cliArgs = ["save"];
+            const next = stringArg(args, "next");
+            const message = stringArg(args, "message");
+            const session = stringArg(args, "session");
+            if (next)
+                cliArgs.push("--next", next);
+            if (message)
+                cliArgs.push("--message", message);
+            for (const lesson of arrayArg(args, "lessons"))
+                cliArgs.push("--lesson", lesson);
+            if (session)
+                cliArgs.push("--session", session);
+            return { cliArgs };
+        }
+        case "jerv_block_get": {
+            const cliArgs = ["memory", "block", "get", requireString(args, "block"), "--json"];
+            const project = stringArg(args, "project");
+            if (project)
+                cliArgs.push("--project", project);
+            return { cliArgs };
+        }
+        case "jerv_block_put": {
+            const cliArgs = ["memory", "block", "put", requireString(args, "block")];
+            const project = stringArg(args, "project");
+            if (project)
+                cliArgs.push("--project", project);
+            return { cliArgs, input: requireString(args, "text") };
+        }
+        case "jerv_northstar_list": {
+            const cliArgs = ["northstar", "list", "--json"];
+            if (booleanArg(args, "all"))
+                cliArgs.push("--all");
+            return { cliArgs };
+        }
+        case "jerv_northstar_show":
+            return { cliArgs: ["northstar", "show", requireString(args, "slug"), "--json"] };
+        case "jerv_northstar_set":
+            return { cliArgs: ["northstar", "set", requireString(args, "slug")], input: requireString(args, "body") };
+        case "jerv_recall_list":
+            return { cliArgs: ["recall", "list", "--json"] };
+        case "jerv_recall_show":
+            return { cliArgs: ["recall", "show", requireString(args, "session")] };
+        case "jerv_archival_search": {
+            const cliArgs = ["memory", "archival", "search", requireString(args, "query"), "--json"];
+            const top = args.top ?? args.topK;
+            if (top !== undefined)
+                cliArgs.push("--top", String(top));
+            return { cliArgs };
+        }
+        case "jerv_archival_insert": {
+            const cliArgs = ["memory", "archival", "insert", requireString(args, "text")];
+            const project = stringArg(args, "project");
+            if (project)
+                cliArgs.push("--project", project);
+            for (const tag of arrayArg(args, "tags"))
+                cliArgs.push("--tag", tag);
+            return { cliArgs };
+        }
+        case "jerv_context_compile": {
+            const cliArgs = ["memory", "context", "compile", "--project", requireString(args, "project"), "--json"];
+            const maxItems = args.maxItems;
+            if (maxItems !== undefined)
+                cliArgs.push("--max-items", String(maxItems));
+            return { cliArgs };
+        }
+        case "jerv_event_append": {
+            const cliArgs = ["memory", "event", "append", requireString(args, "type"), "--project", requireString(args, "project"), "--summary", requireString(args, "summary")];
+            const session = stringArg(args, "session");
+            const raw = stringArg(args, "rawText") ?? stringArg(args, "raw");
+            const source = stringArg(args, "source");
+            if (session)
+                cliArgs.push("--session", session);
+            if (raw)
+                cliArgs.push("--raw", raw);
+            if (source)
+                cliArgs.push("--source", source);
+            return { cliArgs };
+        }
+        case "jerv_governance_action":
+            {
+                const cliArgs = [
+                    "memory",
+                    "governance",
+                    requireString(args, "action"),
+                    requireString(args, "targetId"),
+                    "--project",
+                    requireString(args, "project"),
+                    "--reason",
+                    requireString(args, "reason"),
+                ];
+                const supersededBy = stringArg(args, "supersededBy");
+                if (supersededBy)
+                    cliArgs.push("--superseded-by", supersededBy);
+                return { cliArgs };
+            }
+        case "jerv_graph_query":
+            return { cliArgs: ["memory", "graph", "query", "--project", requireString(args, "project"), "--json"] };
+    }
+}
+function parseCliResult(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return { ok: true };
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return { ok: true, output: trimmed };
+    }
+}
+export async function runJervTool(name, args, options = {}) {
+    try {
+        const mapped = toolToCli(name, args);
+        const result = await (options.runCli ?? defaultRunCli)(mapped.cliArgs, { cwd: options.cwd, input: mapped.input });
+        return parseCliResult(result.stdout);
+    }
+    catch (error) {
+        const err = error;
+        return {
+            ok: false,
+            error: {
+                code: err.code === "ENOENT" ? "JERV_CLI_UNAVAILABLE" : "JERV_CLI_FAILED",
+                message: redactSecretText(err.message || "jerv-cli failed"),
+                status: err.status ?? null,
+                stderr: redactSecretText(err.stderr ?? ""),
+            },
+        };
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jervaise/jerv-mcp",
+  "version": "0.6.0",
+  "description": "Canonical MCP server for Jerv native memory tools.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": {
+    "name": "Suphi",
+    "email": "ssarigollu@gmail.com"
+  },
+  "homepage": "https://github.com/mutmutco/Jerv-PowerTools#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mutmutco/Jerv-PowerTools.git",
+    "directory": "packages/jerv-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/mutmutco/Jerv-PowerTools/issues"
+  },
+  "bin": {
+    "jerv-mcp": "dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "exports": {
+    ".": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run test && npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.9"
+  }
+}