@quantakrypto/mcp 0.1.0

package/dist/http.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * quantakrypto MCP — hostable HTTP transport (Streamable-HTTP-style JSON-RPC).
+ *
+ * A zero-dependency {@link node:http} server that exposes the same
+ * {@link McpServer} over HTTP so the quantakrypto MCP can run as a remote service:
+ *
+ *   POST /mcp     — body is a single JSON-RPC 2.0 message; the JSON-RPC
+ *                   response is returned as the 200 response body
+ *                   (`application/json`). Notifications get HTTP 202 with no body.
+ *   GET  /health  — liveness probe, returns `{ status: "ok", ... }`.
+ *
+ * This is the minimal-but-working core of the MCP Streamable HTTP transport.
+ * The full spec also supports an SSE response (`text/event-stream`) for
+ * server-initiated messages; this server speaks the JSON request/response half,
+ * which is sufficient for stateless tool calls. See HOSTING.md for the
+ * production design (auth, multi-tenant sessions, rate limiting, scaling).
+ *
+ * SAFE-BY-DEFAULT POSTURE (P0-1). Unlike the stdio transport — which trusts the
+ * local user and stays fully featured — the HTTP transport is hardened because a
+ * hosted endpoint is reachable by untrusted peers:
+ *
+ *   - Binds to 127.0.0.1 by default (NOT 0.0.0.0). Override with QUANTAKRYPTO_MCP_HOST.
+ *   - Bearer-token auth: when QUANTAKRYPTO_MCP_TOKEN is set, every /mcp request must
+ *     send `Authorization: Bearer <token>` (else 401). Binding to a non-loopback
+ *     host WITHOUT a token is refused at startup (it would be an open relay).
+ *   - The filesystem tools (scan_path, inventory_crypto, generate_cbom) read
+ *     arbitrary server paths and are DISABLED over HTTP unless QUANTAKRYPTO_MCP_ALLOW_FS=1
+ *     (security audit Q-01). The knowledge tools (explain_finding, suggest_hybrid,
+ *     list_rules) are always available. Gating is enforced by registering only the
+ *     permitted tools, so tools/list and tools/call both reflect it.
+ *   - Per-request timeout (QUANTAKRYPTO_MCP_TIMEOUT_MS) and a response-size cap
+ *     (QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES), in addition to the 1 MiB request-body cap.
+ *
+ * Run with `node dist/http.js` (PORT/QUANTAKRYPTO_MCP_* from env).
+ */
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import { createQuantakryptoServer } from "./index.js";
+import { ErrorCode, makeFailure } from "./protocol.js";
+import { quantakryptoTools, FS_TOOL_NAMES } from "./tools.js";
+/** Header carrying the MCP session id (per the Streamable HTTP transport). */
+export const SESSION_HEADER = "mcp-session-id";
+/** Maximum accepted request body size (1 MiB) — a basic abuse guard. */
+const MAX_BODY_BYTES = 1024 * 1024;
+/** Default per-request tool-execution deadline (ms). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Default cap on the serialized response body (4 MiB). */
+const DEFAULT_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** Loopback hosts that are safe to bind without authentication. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+/**
+ * Resolve the HTTP transport config from env + explicit overrides. Pure: does
+ * no I/O and never reads `process` directly. Overrides win over env.
+ */
+export function resolveHttpConfig(env, options = {}) {
+    const host = options.host ?? env.QUANTAKRYPTO_MCP_HOST ?? env.HOST ?? "127.0.0.1";
+    const port = options.port ?? toInt(env.PORT, 3000);
+    const token = (options.token ?? env.QUANTAKRYPTO_MCP_TOKEN ?? "").trim();
+    const allowFs = options.allowFs ??
+        (env.QUANTAKRYPTO_MCP_ALLOW_FS === "1" || env.QUANTAKRYPTO_MCP_ALLOW_FS === "true");
+    const timeoutMs = options.timeoutMs ?? toInt(env.QUANTAKRYPTO_MCP_TIMEOUT_MS, DEFAULT_TIMEOUT_MS);
+    const maxResponseBytes = options.maxResponseBytes ??
+        toInt(env.QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES, DEFAULT_MAX_RESPONSE_BYTES);
+    return {
+        host,
+        port,
+        token,
+        allowFs,
+        timeoutMs,
+        maxResponseBytes,
+        loopback: isLoopbackHost(host),
+    };
+}
+/** Parse a positive integer from an env string, falling back on bad input. */
+function toInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+/** True when binding to `host` keeps the server private to this machine. */
+export function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host.trim().toLowerCase());
+}
+/**
+ * Decide whether a non-loopback bind is permitted. A server reachable from the
+ * network MUST require auth; binding wide-open without a token would be an open,
+ * unauthenticated arbitrary-tool relay. Pure decision used at startup.
+ */
+export function startupDecision(config) {
+    if (!config.loopback && config.token.length === 0) {
+        return {
+            ok: false,
+            reason: `refusing to bind to non-loopback host "${config.host}" without a token. ` +
+                `Set QUANTAKRYPTO_MCP_TOKEN to require Bearer auth, or bind to 127.0.0.1.`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Decide whether a request is authorized given the configured token and the
+ * incoming Authorization header. When no token is configured, all requests are
+ * allowed (the loopback / trusted-edge case). Pure and testable.
+ */
+export function authorizeRequest(token, authorizationHeader) {
+    if (token.length === 0)
+        return { authorized: true };
+    const header = (authorizationHeader ?? "").trim();
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    const presented = match?.[1]?.trim();
+    if (!presented) {
+        return { authorized: false, status: 401, message: "missing bearer token" };
+    }
+    if (!timingSafeEqualStr(presented, token)) {
+        return { authorized: false, status: 401, message: "invalid bearer token" };
+    }
+    return { authorized: true };
+}
+/** Constant-time-ish string compare (length-independent short-circuit guarded). */
+function timingSafeEqualStr(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Select the tools to expose over HTTP for a given policy. The knowledge tools
+ * are always returned; the filesystem tools are included only when
+ * `allowFs` is true. Pure function of its inputs — the single source of truth
+ * for HTTP tool gating, so tools/list and tools/call stay consistent.
+ */
+export function gateHttpTools(tools, allowFs) {
+    const fsNames = new Set(FS_TOOL_NAMES);
+    return tools.filter((t) => allowFs || !fsNames.has(t.name));
+}
+/* -------------------------------------------------------------------------- */
+/* HTTP plumbing                                                               */
+/* -------------------------------------------------------------------------- */
+/** Read a request body fully, enforcing the size cap. Resolves to the raw string. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/** Write a JSON response with the given status and optional extra headers. */
+function sendJson(res, status, body, headers = {}) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "content-length": Buffer.byteLength(payload).toString(),
+        ...headers,
+    });
+    res.end(payload);
+}
+/** Race a handler against a deadline; rejects with a timeout error if exceeded. */
+function withTimeout(promise, ms) {
+    if (!(ms > 0))
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("request timed out")), ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+/**
+ * Build (but do not start) the HTTP server wrapping an {@link McpServer}.
+ * Exposed for testing and for embedding in a larger process. The `config`
+ * carries the resolved auth / timeout / response-cap policy.
+ */
+export function createHttpServer(server, config) {
+    return createServer((req, res) => {
+        void handleRequest(server, config, req, res).catch((err) => {
+            const messageText = err instanceof Error ? err.message : String(err);
+            if (!res.headersSent) {
+                sendJson(res, 500, makeFailure(null, ErrorCode.InternalError, messageText));
+            }
+            else {
+                res.end();
+            }
+        });
+    });
+}
+/** Route and handle a single HTTP request. */
+async function handleRequest(server, config, req, res) {
+    const url = req.url ?? "/";
+    const method = req.method ?? "GET";
+    const path = url.split("?")[0];
+    if (method === "GET" && path === "/health") {
+        sendJson(res, 200, { status: "ok", server: "quantakrypto", transport: "http" });
+        return;
+    }
+    if (path === "/mcp") {
+        if (method !== "POST") {
+            // The full transport also allows GET for an SSE stream; we don't here.
+            sendJson(res, 405, makeFailure(null, ErrorCode.InvalidRequest, "method not allowed"), {
+                allow: "POST",
+            });
+            return;
+        }
+        // Authenticate BEFORE reading the body or dispatching (Q-02).
+        const auth = authorizeRequest(config.token, req.headers.authorization);
+        if (!auth.authorized) {
+            sendJson(res, auth.status ?? 401, makeFailure(null, ErrorCode.InvalidRequest, auth.message ?? "unauthorized"), { "www-authenticate": "Bearer" });
+            return;
+        }
+        await handleMcpPost(server, config, req, res);
+        return;
+    }
+    sendJson(res, 404, makeFailure(null, ErrorCode.MethodNotFound, "not found"));
+}
+/** Handle `POST /mcp`: parse one JSON-RPC message, dispatch, return the result. */
+async function handleMcpPost(server, config, req, res) {
+    // Session handling (stateless here): echo a provided session id, else mint one.
+    // A production server would look this up in a session store — see HOSTING.md.
+    const incomingSession = req.headers[SESSION_HEADER];
+    const sessionId = (Array.isArray(incomingSession) ? incomingSession[0] : incomingSession) ?? randomUUID();
+    const sessionHeaders = { [SESSION_HEADER]: sessionId };
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        const messageText = err instanceof Error ? err.message : String(err);
+        sendJson(res, 413, makeFailure(null, ErrorCode.InvalidRequest, messageText), sessionHeaders);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, makeFailure(null, ErrorCode.ParseError, "parse error"), sessionHeaders);
+        return;
+    }
+    let response;
+    try {
+        response = await withTimeout(server.handle(parsed), config.timeoutMs);
+    }
+    catch (err) {
+        const messageText = err instanceof Error ? err.message : String(err);
+        sendJson(res, 504, makeFailure(null, ErrorCode.InternalError, messageText), sessionHeaders);
+        return;
+    }
+    if (response === null) {
+        // Notification — acknowledge with 202 and no body.
+        res.writeHead(202, sessionHeaders);
+        res.end();
+        return;
+    }
+    // Enforce the response-size cap (Q-03): never stream back an unbounded body.
+    const serialized = JSON.stringify(response);
+    if (Buffer.byteLength(serialized) > config.maxResponseBytes) {
+        sendJson(res, 500, makeFailure(null, ErrorCode.InternalError, "response too large"), sessionHeaders);
+        return;
+    }
+    sendJson(res, 200, response, sessionHeaders);
+}
+/**
+ * Build the HTTP-facing {@link McpServer}: the same server used over stdio but
+ * with the filesystem tools gated per policy. Exposed for tests.
+ */
+export function createHttpMcpServer(config) {
+    return createQuantakryptoServer({ tools: gateHttpTools(quantakryptoTools, config.allowFs) });
+}
+/** Start the HTTP server, resolving once it is listening. */
+export function startHttpServer(options = {}) {
+    const config = resolveHttpConfig(process.env, options);
+    const decision = startupDecision(config);
+    if (!decision.ok) {
+        return Promise.reject(new Error(decision.reason ?? "refusing to start"));
+    }
+    if (!config.loopback) {
+        process.stderr.write(`quantakrypto MCP (http): WARNING binding to non-loopback host ${config.host}; ` +
+            `Bearer auth is required and active.\n`);
+    }
+    const mcp = createHttpMcpServer(config);
+    const httpServer = createHttpServer(mcp, config);
+    return new Promise((resolve) => {
+        httpServer.listen(config.port, config.host, () => {
+            const auth = config.token ? "bearer-auth" : "no-auth";
+            const fs = config.allowFs ? "fs-tools:on" : "fs-tools:off";
+            process.stderr.write(`quantakrypto MCP server (http) listening on http://${config.host}:${config.port} ` +
+                `[${auth}, ${fs}]\n`);
+            process.stderr.write(`  POST http://${config.host}:${config.port}/mcp   ` +
+                `GET http://${config.host}:${config.port}/health\n`);
+            resolve(httpServer);
+        });
+    });
+}
+/** Entry point when run directly. */
+function main() {
+    startHttpServer().catch((err) => {
+        const messageText = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`quantakrypto MCP (http) failed to start: ${messageText}\n`);
+        process.exitCode = 1;
+    });
+}
+/** True when this module is the program's entry point (handles symlinks). */
+function isMainModule() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    const thisPath = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(argv1) === realpathSync(thisPath);
+    }
+    catch {
+        return argv1 === thisPath;
+    }
+}
+// Only auto-run when invoked as a script, not when imported by tests.
+if (isMainModule()) {
+    main();
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @quantakrypto/mcp — public API.
+ *
+ * Exports the transport-agnostic {@link McpServer}, the quantakrypto tool set, and a
+ * {@link createQuantakryptoServer} factory that wires them together. Transports
+ * (stdio, http) consume the factory; tests drive the server's `handle` method
+ * directly.
+ */
+import { McpServer } from "./server.js";
+import { quantakryptoTools } from "./tools.js";
+export { McpServer } from "./server.js";
+export type { McpServerOptions, ServerInfo } from "./server.js";
+export { quantakryptoTools, CORE_VERSION } from "./tools.js";
+export { MCP_PROTOCOL_VERSION, JSONRPC_VERSION, ErrorCode, RpcError, textResult, errorResult, } from "./protocol.js";
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcSuccess, JsonRpcFailure, ToolDefinition, ToolDescriptor, ToolResult, Content, TextContent, JsonSchema, } from "./protocol.js";
+/** The MCP server name advertised to clients. */
+export declare const SERVER_NAME = "quantakrypto";
+/** The version reported by the server (kept in sync with @quantakrypto/core). */
+export declare const SERVER_VERSION = "0.1.0";
+export interface CreateServerOptions {
+    /** Override the advertised server version (defaults to @quantakrypto/core VERSION). */
+    version?: string;
+    /** Override or extend the registered tool set (defaults to all quantakrypto tools). */
+    tools?: typeof quantakryptoTools;
+}
+/**
+ * Create a fully-wired quantakrypto {@link McpServer} with all tools registered.
+ *
+ * @example
+ * ```ts
+ * const server = createQuantakryptoServer();
+ * const res = await server.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+ * ```
+ */
+export declare function createQuantakryptoServer(options?: CreateServerOptions): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,eAAe,EACf,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,UAAU,EACV,OAAO,EACP,WAAW,EACX,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,iDAAiD;AACjD,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAE1C,iFAAiF;AACjF,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,KAAK,CAAC,EAAE,OAAO,iBAAiB,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,GAAG,SAAS,CAarF"}

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * @quantakrypto/mcp — public API.
+ *
+ * Exports the transport-agnostic {@link McpServer}, the quantakrypto tool set, and a
+ * {@link createQuantakryptoServer} factory that wires them together. Transports
+ * (stdio, http) consume the factory; tests drive the server's `handle` method
+ * directly.
+ */
+import { VERSION } from "@quantakrypto/core";
+import { McpServer } from "./server.js";
+import { quantakryptoTools } from "./tools.js";
+export { McpServer } from "./server.js";
+export { quantakryptoTools, CORE_VERSION } from "./tools.js";
+export { MCP_PROTOCOL_VERSION, JSONRPC_VERSION, ErrorCode, RpcError, textResult, errorResult, } from "./protocol.js";
+/** The MCP server name advertised to clients. */
+export const SERVER_NAME = "quantakrypto";
+/** The version reported by the server (kept in sync with @quantakrypto/core). */
+export const SERVER_VERSION = VERSION;
+/**
+ * Create a fully-wired quantakrypto {@link McpServer} with all tools registered.
+ *
+ * @example
+ * ```ts
+ * const server = createQuantakryptoServer();
+ * const res = await server.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+ * ```
+ */
+export function createQuantakryptoServer(options = {}) {
+    const server = new McpServer({
+        info: { name: SERVER_NAME, version: options.version ?? SERVER_VERSION },
+        instructions: "quantakrypto checks code for quantum-vulnerable cryptography and recommends " +
+            "post-quantum (NIST PQC) migrations. Use scan_path / inventory_crypto to " +
+            "assess a path, list_rules to see detectors, and explain_finding / " +
+            "suggest_hybrid for remediation guidance.",
+    });
+    for (const tool of options.tools ?? quantakryptoTools) {
+        server.registerTool(tool);
+    }
+    return server;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,eAAe,CAAC;AAcvB,iDAAiD;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAE1C,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAStC;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAA+B,EAAE;IACxE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,cAAc,EAAE;QACvE,YAAY,EACV,8EAA8E;YAC9E,0EAA0E;YAC1E,oEAAoE;YACpE,0CAA0C;KAC7C,CAAC,CAAC;IACH,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,iBAAiB,EAAE,CAAC;QACtD,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,109 @@
+/**
+ * JSON-RPC 2.0 + Model Context Protocol (MCP) wire types.
+ *
+ * This module is pure type/shape definitions plus a few small helpers for
+ * constructing valid JSON-RPC responses and errors. It has no runtime
+ * dependencies and no I/O — the transport layers (stdio, http) and the
+ * {@link McpServer} build on top of it.
+ *
+ * Reference: JSON-RPC 2.0 (https://www.jsonrpc.org/specification) and the
+ * Model Context Protocol specification (https://modelcontextprotocol.io).
+ */
+/** The fixed JSON-RPC protocol marker. */
+export declare const JSONRPC_VERSION: "2.0";
+/**
+ * MCP protocol revision this server speaks. The `initialize` handshake echoes
+ * the client's requested version when we support it, otherwise advertises this.
+ */
+export declare const MCP_PROTOCOL_VERSION: "2025-06-18";
+/** A JSON-RPC id: string or number per spec (we never originate notifications). */
+export type JsonRpcId = string | number | null;
+/** Any JSON value. Kept structural rather than `any` for strict mode. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON-RPC 2.0 request or notification (notifications omit `id`). */
+export interface JsonRpcRequest {
+    jsonrpc: typeof JSONRPC_VERSION;
+    /** Absent for notifications. */
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown> | unknown[];
+}
+/** A successful JSON-RPC response. */
+export interface JsonRpcSuccess {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: JsonRpcId;
+    result: unknown;
+}
+/** A JSON-RPC error object. */
+export interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** A failed JSON-RPC response. */
+export interface JsonRpcFailure {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: JsonRpcId;
+    error: JsonRpcErrorObject;
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+/** Standard JSON-RPC 2.0 error codes (plus MCP conventions). */
+export declare const ErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+};
+/** An error that carries a JSON-RPC error code, thrown by tool handlers/dispatch. */
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Build a successful response envelope. */
+export declare function makeSuccess(id: JsonRpcId, result: unknown): JsonRpcSuccess;
+/** Build a failure response envelope. */
+export declare function makeFailure(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcFailure;
+/** Narrow an unknown parsed value to something request-shaped enough to dispatch. */
+export declare function isJsonRpcRequestLike(value: unknown): value is JsonRpcRequest;
+/** True when a request is a notification (no `id` field present). */
+export declare function isNotification(req: JsonRpcRequest): boolean;
+/** A single piece of MCP content. We only emit text content in this server. */
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+export type Content = TextContent;
+/** The result envelope returned by a `tools/call`. */
+export interface ToolResult {
+    content: Content[];
+    /** True when the tool ran but produced an error result (vs. a protocol error). */
+    isError?: boolean;
+}
+/** A minimal JSON Schema object describing a tool's input. */
+export interface JsonSchema {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+/** The public descriptor of a tool, as returned by `tools/list`. */
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+}
+/** A registered tool: descriptor plus its async handler. */
+export interface ToolDefinition extends ToolDescriptor {
+    /** Executes the tool with already-parsed arguments. */
+    handler: (args: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
+}
+/** Convenience: wrap one or more strings as a non-error text tool result. */
+export declare function textResult(...parts: string[]): ToolResult;
+/** Convenience: wrap a string as an error text tool result. */
+export declare function errorResult(text: string): ToolResult;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,68 @@
+/**
+ * JSON-RPC 2.0 + Model Context Protocol (MCP) wire types.
+ *
+ * This module is pure type/shape definitions plus a few small helpers for
+ * constructing valid JSON-RPC responses and errors. It has no runtime
+ * dependencies and no I/O — the transport layers (stdio, http) and the
+ * {@link McpServer} build on top of it.
+ *
+ * Reference: JSON-RPC 2.0 (https://www.jsonrpc.org/specification) and the
+ * Model Context Protocol specification (https://modelcontextprotocol.io).
+ */
+/** The fixed JSON-RPC protocol marker. */
+export const JSONRPC_VERSION = "2.0";
+/**
+ * MCP protocol revision this server speaks. The `initialize` handshake echoes
+ * the client's requested version when we support it, otherwise advertises this.
+ */
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+/** Standard JSON-RPC 2.0 error codes (plus MCP conventions). */
+export const ErrorCode = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+};
+/** An error that carries a JSON-RPC error code, thrown by tool handlers/dispatch. */
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "RpcError";
+        this.code = code;
+        this.data = data;
+    }
+}
+/** Build a successful response envelope. */
+export function makeSuccess(id, result) {
+    return { jsonrpc: JSONRPC_VERSION, id, result };
+}
+/** Build a failure response envelope. */
+export function makeFailure(id, code, message, data) {
+    const error = { code, message };
+    if (data !== undefined)
+        error.data = data;
+    return { jsonrpc: JSONRPC_VERSION, id, error };
+}
+/** Narrow an unknown parsed value to something request-shaped enough to dispatch. */
+export function isJsonRpcRequestLike(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return v.jsonrpc === JSONRPC_VERSION && typeof v.method === "string";
+}
+/** True when a request is a notification (no `id` field present). */
+export function isNotification(req) {
+    return !("id" in req) || req.id === undefined;
+}
+/** Convenience: wrap one or more strings as a non-error text tool result. */
+export function textResult(...parts) {
+    return { content: parts.map((text) => ({ type: "text", text })) };
+}
+/** Convenience: wrap a string as an error text tool result. */
+export function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,eAAe,GAAG,KAAc,CAAC;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAqB,CAAC;AA8C1D,gEAAgE;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU,EAAE,CAAC,KAAK;IAClB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;IACtB,aAAa,EAAE,CAAC,KAAK;IACrB,aAAa,EAAE,CAAC,KAAK;CACb,CAAC;AAEX,qFAAqF;AACrF,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,IAAI,CAAW;IACxB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAc;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,4CAA4C;AAC5C,MAAM,UAAU,WAAW,CAAC,EAAa,EAAE,MAAe;IACxD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;AAClD,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,WAAW,CACzB,EAAa,EACb,IAAY,EACZ,OAAe,EACf,IAAc;IAEd,MAAM,KAAK,GAAuB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACpD,IAAI,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CAAC,CAAC,OAAO,KAAK,eAAe,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC;AACvE,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,cAAc,CAAC,GAAmB;IAChD,OAAO,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC;AAChD,CAAC;AA2CD,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,GAAG,KAAe;IAC3C,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC9D,CAAC"}