@harperfast/harper-pro 5.0.25 → 5.1.0-beta.1

package/dist/core/components/mcp/adapters/fastify.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFastifyHandler = createFastifyHandler;
+/**
+ * Fastify adapter for the MCP transport core (operations port, #614).
+ *
+ * Maps Fastify's `(request, reply)` ↔ the transport's normalized
+ * Request/Response shape. The route is registered with the
+ * `authAndEnsureUserOnRequest` preValidation hook, so the authenticated
+ * user lands on `request.hdb_user` before this handler runs.
+ *
+ * Fastify auto-parses JSON request bodies; we re-stringify so the core's
+ * `parseMessage` sees the raw envelope it expects. The round-trip is
+ * cheap for the small JSON-RPC frames in the MCP wire format and keeps
+ * the core framework-agnostic.
+ */
+const transport_ts_1 = require("../transport.js");
+function createFastifyHandler(profile) {
+    return async function mcpFastifyHandler(request, reply) {
+        const norm = {
+            method: request.method,
+            headers: normalizeHeaders(request.headers),
+            // Fastify has already parsed the JSON body into an object via its
+            // preParsing pipeline. Pass it through directly — the transport
+            // core's parseMessage accepts both strings and parsed values, so we
+            // avoid an unnecessary stringify/re-parse round trip on the hot path.
+            body: request.body,
+            user: request.hdb_user?.username ?? '',
+            userObject: (request.hdb_user ?? undefined),
+            profile,
+        };
+        const res = await (0, transport_ts_1.handleMcpRequest)(norm);
+        reply.code(res.status);
+        for (const [name, value] of Object.entries(res.headers)) {
+            reply.header(name, value);
+        }
+        if (res.jsonBody !== undefined) {
+            if (!res.headers['Content-Type'] && !res.headers['content-type']) {
+                reply.header('Content-Type', 'application/json');
+            }
+            reply.send(res.jsonBody);
+            return;
+        }
+        if (res.sseIterable !== undefined) {
+            // Reserved for #619 (server-push GET stream). Fastify will iterate
+            // the async iterable and write SSE frames via the contentTypes
+            // serializer at `server/serverHelpers/contentTypes.ts:128-162`.
+            if (!res.headers['Content-Type'] && !res.headers['content-type']) {
+                reply.header('Content-Type', 'text/event-stream');
+            }
+            reply.header('Cache-Control', 'no-store');
+            reply.send(res.sseIterable);
+            return;
+        }
+        // 202/204/4xx with empty body.
+        reply.send();
+    };
+}
+function normalizeHeaders(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        out[name.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+    }
+    return out;
+}
+//# sourceMappingURL=fastify.js.map

package/dist/core/components/mcp/adapters/fastify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../../../../../core/components/mcp/adapters/fastify.ts"],"names":[],"mappings":";;AAiCA,oDA6CC;AA9ED;;;;;;;;;;;;GAYG;AACH,kDAAsF;AAoBtF,SAAgB,oBAAoB,CAAC,OAAmB;IACvD,OAAO,KAAK,UAAU,iBAAiB,CAAC,OAA2B,EAAE,KAAuB;QAC3F,MAAM,IAAI,GAAgB;YACzB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC;YAC1C,kEAAkE;YAClE,gEAAgE;YAChE,oEAAoE;YACpE,sEAAsE;YACtE,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE;YACtC,UAAU,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,SAAS,CAA8B;YACxE,OAAO;SACP,CAAC;QAEF,MAAM,GAAG,GAAG,MAAM,IAAA,+BAAgB,EAAC,IAAI,CAAC,CAAC;QAEzC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzD,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QAED,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;gBAClE,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;YAClD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACzB,OAAO;QACR,CAAC;QAED,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnC,mEAAmE;YACnE,+DAA+D;YAC/D,gEAAgE;YAChE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;gBAClE,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;YACnD,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC5B,OAAO;QACR,CAAC;QAED,+BAA+B;QAC/B,KAAK,CAAC,IAAI,EAAE,CAAC;IACd,CAAC,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAsD;IAC/E,MAAM,GAAG,GAAuC,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/core/components/mcp/adapters/harperHttp.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHarperHttpHandler = createHarperHttpHandler;
+/**
+ * Harper-HTTP adapter for the MCP transport core (application port, #614).
+ *
+ * Maps Harper's HTTP handler signature `(request, nextHandler) => { status,
+ * headers, body }` to/from the transport's normalized Request/Response.
+ * Auth runs upstream via `{ after: 'authentication' }` on the registration,
+ * so `request.user` is already populated when this handler fires.
+ *
+ * SSE responses (reserved for #619) are returned as `{ body: iterable,
+ * headers: { 'content-type': 'text/event-stream' } }`. Harper's serializer
+ * at `server/serverHelpers/contentTypes.ts:128-162` picks the SSE writer
+ * automatically and pipes the iterable to the wire.
+ */
+const transport_ts_1 = require("../transport.js");
+function createHarperHttpHandler(profile) {
+    return async function mcpHarperHttpHandler(request, nextHandler) {
+        // WebSocket upgrades aren't ours — let the next handler take it.
+        if (request.isWebSocket)
+            return nextHandler(request);
+        const norm = {
+            method: request.method,
+            headers: normalizeHeaders(request.headers),
+            body: await readBody(request.body),
+            user: request.user?.username ?? '',
+            userObject: request.user,
+            profile,
+        };
+        const res = await (0, transport_ts_1.handleMcpRequest)(norm);
+        return toHarperResponse(res);
+    };
+}
+function normalizeHeaders(headers) {
+    const out = {};
+    for (const [name, value] of headers) {
+        out[name.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+    }
+    return out;
+}
+async function readBody(body) {
+    if (!body)
+        return '';
+    const chunks = [];
+    for await (const chunk of body) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function toHarperResponse(res) {
+    const headers = { ...res.headers };
+    if (res.jsonBody !== undefined) {
+        if (!headers['Content-Type'] && !headers['content-type']) {
+            headers['Content-Type'] = 'application/json';
+        }
+        return {
+            status: res.status,
+            headers,
+            body: JSON.stringify(res.jsonBody),
+        };
+    }
+    if (res.sseIterable !== undefined) {
+        if (!headers['Content-Type'] && !headers['content-type']) {
+            headers['Content-Type'] = 'text/event-stream';
+        }
+        if (!headers['Cache-Control'] && !headers['cache-control']) {
+            headers['Cache-Control'] = 'no-store';
+        }
+        return {
+            status: res.status,
+            headers,
+            body: res.sseIterable,
+        };
+    }
+    return { status: res.status, headers };
+}
+//# sourceMappingURL=harperHttp.js.map

package/dist/core/components/mcp/adapters/harperHttp.js.map

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

package/dist/core/components/mcp/audit.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactArgs = redactArgs;
+exports.maskSessionId = maskSessionId;
+exports.emitAuditEntry = emitAuditEntry;
+/**
+ * Per-`tools/call` audit logging. Emits a structured info-level log entry
+ * for every tool invocation so operators can replay who-did-what after the
+ * fact. The shape mirrors what Harper's existing operations audit captures
+ * (operation, user, status, duration) plus MCP-specific identity
+ * (session id, profile, tool name).
+ *
+ * Argument summarization runs through a redaction step that drops anything
+ * that looks like a credential (key/secret/password). Operators who need
+ * stricter PII handling configure `mcp.audit.argumentRedactor` to a custom
+ * function via a future component-author hook (v1.1).
+ */
+const harper_logger_ts_1 = __importDefault(require("../../utility/logging/harper_logger.js"));
+const REDACTION_PATTERN = /(secret|password|token|api[-_]?key|credentials?|auth)/i;
+const REDACTION_PLACEHOLDER = '[redacted]';
+const MAX_REDACTION_DEPTH = 10;
+/**
+ * Recursively walk an object and replace values for keys matching the
+ * redaction pattern. Bounded depth so a pathological cyclic input doesn't
+ * stall the audit emit; on overflow the entire sub-object is redacted so
+ * a credential buried below the depth limit cannot leak. Returns a shallow
+ * clone — the caller's payload is never mutated.
+ */
+function redactArgs(value, depth = 0) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth > MAX_REDACTION_DEPTH)
+        return REDACTION_PLACEHOLDER;
+    if (Array.isArray(value)) {
+        return value.map((v) => redactArgs(v, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (REDACTION_PATTERN.test(k)) {
+            out[k] = REDACTION_PLACEHOLDER;
+        }
+        else {
+            out[k] = redactArgs(v, depth + 1);
+        }
+    }
+    return out;
+}
+/** Mask a session id for logging — first 8 chars, suffix elided. */
+function maskSessionId(id) {
+    if (typeof id !== 'string' || id.length <= 8)
+        return id;
+    return `${id.slice(0, 8)}…`;
+}
+/**
+ * Emit a single audit entry. Writes to the structured log channel as INFO
+ * so it's captured by Harper's standard log rotation; downstream tooling
+ * can filter on `category: 'mcp.audit'`.
+ */
+function emitAuditEntry(entry) {
+    try {
+        const masked = { ...entry, sessionId: maskSessionId(entry.sessionId), args: redactArgs(entry.args) };
+        harper_logger_ts_1.default.info({ category: 'mcp.audit', ...masked });
+    }
+    catch (err) {
+        // Audit emission must never break a tool call. If logging itself fails
+        // (logger disposed, disk full, whatever), trace-log the loss and move on.
+        harper_logger_ts_1.default.trace(`MCP audit emit failed: ${err.message}`);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/core/components/mcp/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../../core/components/mcp/audit.ts"],"names":[],"mappings":";;;;;AAqCA,gCAeC;AAGD,sCAGC;AAOD,wCASC;AA1ED;;;;;;;;;;;GAWG;AACH,8FAAkE;AAclE,MAAM,iBAAiB,GAAG,wDAAwD,CAAC;AACnF,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAC3C,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC;IACnD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,KAAK,GAAG,mBAAmB;QAAE,OAAO,qBAAqB,CAAC;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC;QAChC,CAAC;aAAM,CAAC;YACP,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,oEAAoE;AACpE,SAAgB,aAAa,CAAC,EAAU;IACvC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACxD,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,KAAiB;IAC/C,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrG,0BAAY,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,uEAAuE;QACvE,0EAA0E;QAC1E,0BAAY,CAAC,KAAK,CAAC,0BAA2B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;AACF,CAAC"}

package/dist/core/components/mcp/index.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._setGetConfigObjForTest = _setGetConfigObjForTest;
+exports._restoreGetConfigObj = _restoreGetConfigObj;
+exports.registerMcpProfile = registerMcpProfile;
+exports.handleApplication = handleApplication;
+exports._resetApplicationStartedForTest = _resetApplicationStartedForTest;
+/**
+ * Native MCP (Model Context Protocol) server component for Harper.
+ *
+ * #614 replaces the foundation stub from #613 with a real Streamable HTTP
+ * transport. Two entry points:
+ *
+ *   - `registerMcpProfile({profile:'operations', host, config, routeOptions})`
+ *     called from `server/operationsServer.ts` (Fastify-side gate).
+ *
+ *   - `handleApplication(scope)` invoked by the component loader when the
+ *     root config contains a top-level `mcp:` block. Registers the
+ *     application-profile handler on the HTTP port iff `mcp.application` is
+ *     present.
+ *
+ * Profile presence drives enablement, matching Harper's `replication`
+ * convention (no `enabled` flag). See #465 for the umbrella design.
+ */
+const harper_logger_ts_1 = __importDefault(require("../../utility/logging/harper_logger.js"));
+const configUtils_js_1 = require("../../config/configUtils.js");
+const fastify_ts_1 = require("./adapters/fastify.js");
+const harperHttp_ts_1 = require("./adapters/harperHttp.js");
+const session_ts_1 = require("./session.js");
+const listChanged_ts_1 = require("./listChanged.js");
+const application_ts_1 = require("./tools/application.js");
+const operations_ts_1 = require("./tools/operations.js");
+// Indirection so tests can swap the config source.
+let getConfigObj = configUtils_js_1.getConfigObj;
+function _setGetConfigObjForTest(fn) {
+    getConfigObj = fn;
+}
+function _restoreGetConfigObj() {
+    getConfigObj = configUtils_js_1.getConfigObj;
+}
+const DEFAULT_MOUNT_PATH = '/mcp';
+/**
+ * Fastify-side registration. Used by `server/operationsServer.ts` for the
+ * operations profile. Idempotent through the host's own route table.
+ */
+function registerMcpProfile({ profile, host, config, routeOptions }) {
+    const profileConfig = config?.mcp?.[profile];
+    if (!profileConfig) {
+        harper_logger_ts_1.default.trace(`MCP ${profile} profile not configured, skipping registration`);
+        return;
+    }
+    (0, session_ts_1.ensureSessionTable)();
+    (0, listChanged_ts_1.initListChanged)();
+    if (profile === 'operations') {
+        (0, operations_ts_1.registerOperationsTools)();
+    }
+    const mountPath = profileConfig.mountPath ?? DEFAULT_MOUNT_PATH;
+    const handler = (0, fastify_ts_1.createFastifyHandler)(profile);
+    // Register POST, GET, and DELETE on the same mount path. The transport
+    // core decides whether to handle (POST initialize / JSON-RPC dispatch),
+    // return 405 with an accurate `Allow` header (GET always in v1, DELETE
+    // when `mcp.session.allowClientDelete` is false), or process (DELETE
+    // when enabled). Without explicit GET/DELETE routes Fastify would
+    // short-circuit to its built-in 404 before the transport runs.
+    for (const method of ['post', 'get', 'delete']) {
+        if (routeOptions) {
+            host[method](mountPath, routeOptions, handler);
+        }
+        else {
+            host[method](mountPath, handler);
+        }
+    }
+    harper_logger_ts_1.default.info(`MCP ${profile} profile registered at ${mountPath}`);
+}
+let applicationStarted = false;
+/**
+ * Trusted-Resource-Plugin entry point for the application profile. The
+ * component loader invokes this with the runtime `Scope` when the root
+ * config contains a top-level `mcp:` block. We register the handler iff the
+ * `application` sub-block is also present.
+ *
+ * Idempotent — repeated invocations no-op via `applicationStarted`. This
+ * matches REST's pattern at `server/REST.ts:283-303`.
+ */
+function handleApplication(scope) {
+    if (applicationStarted)
+        return;
+    const config = getConfigObj();
+    if (!config?.mcp?.application) {
+        harper_logger_ts_1.default.trace('MCP application profile not configured, skipping registration');
+        return;
+    }
+    applicationStarted = true;
+    (0, session_ts_1.ensureSessionTable)();
+    (0, listChanged_ts_1.initListChanged)();
+    (0, application_ts_1.registerApplicationTools)();
+    const mountPath = config.mcp.application.mountPath ?? DEFAULT_MOUNT_PATH;
+    const handler = (0, harperHttp_ts_1.createHarperHttpHandler)('application');
+    scope.server.http(handler, { urlPath: mountPath, after: 'authentication' });
+    harper_logger_ts_1.default.info(`MCP application profile registered at ${mountPath}`);
+}
+/** Test seam: reset the module-level guard so tests can re-invoke handleApplication. */
+function _resetApplicationStartedForTest() {
+    applicationStarted = false;
+}
+//# sourceMappingURL=index.js.map

package/dist/core/components/mcp/index.js.map

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

package/dist/core/components/mcp/jsonrpc.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * JSON-RPC 2.0 envelope parsing + error helpers for the MCP Streamable HTTP
+ * transport (#614). The MCP wire format is one JSON-RPC message per HTTP body
+ * (no batches in the 2025-06-18 revision — spec §transports).
+ *
+ * Spec: https://www.jsonrpc.org/specification
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_CODES = exports.JSONRPC_VERSION = void 0;
+exports.parseMessage = parseMessage;
+exports.isClientFireAndForget = isClientFireAndForget;
+exports.buildSuccess = buildSuccess;
+exports.buildError = buildError;
+exports.JSONRPC_VERSION = '2.0';
+/** Standard JSON-RPC 2.0 error codes (spec §5.1). */
+exports.ERROR_CODES = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};
+/**
+ * Validate a JSON-RPC envelope. Accepts either a raw UTF-8 JSON string
+ * (e.g., from a streamed request body) or an already-parsed value (e.g.,
+ * Fastify hands us a parsed object via its preParsing pipeline). Returns
+ * either a typed message or a structured parse error that the caller maps
+ * to a JSON-RPC error response. Never throws.
+ */
+function parseMessage(body) {
+    let parsed;
+    if (typeof body === 'string') {
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch (err) {
+            const fail = { ok: false, code: exports.ERROR_CODES.PARSE_ERROR, reason: err.message };
+            return fail;
+        }
+    }
+    else {
+        parsed = body;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        // Batch requests (arrays) are not used in the MCP Streamable HTTP wire
+        // format; rejecting them keeps the transport unambiguous.
+        const fail = { ok: false, code: exports.ERROR_CODES.INVALID_REQUEST, reason: 'expected a JSON object' };
+        return fail;
+    }
+    const obj = parsed;
+    if (obj.jsonrpc !== exports.JSONRPC_VERSION) {
+        const fail = {
+            ok: false,
+            code: exports.ERROR_CODES.INVALID_REQUEST,
+            reason: `jsonrpc must be "${exports.JSONRPC_VERSION}"`,
+        };
+        return fail;
+    }
+    const hasMethod = typeof obj.method === 'string';
+    const hasResultOrError = 'result' in obj || 'error' in obj;
+    if (!hasMethod && !hasResultOrError) {
+        const fail = {
+            ok: false,
+            code: exports.ERROR_CODES.INVALID_REQUEST,
+            reason: 'missing method, result, or error field',
+        };
+        return fail;
+    }
+    const success = { ok: true, message: parsed };
+    return success;
+}
+/**
+ * True if the message is a "fire-and-forget" frame from the client's
+ * perspective — a notification (no `id`) or a response to a server-initiated
+ * request (has `result` or `error`). Per MCP §transports point 4, both yield
+ * HTTP 202 with no body.
+ */
+function isClientFireAndForget(message) {
+    const hasId = 'id' in message;
+    const hasResultOrError = 'result' in message || 'error' in message;
+    return !hasId || hasResultOrError;
+}
+function buildSuccess(id, result) {
+    return { jsonrpc: exports.JSONRPC_VERSION, id, result };
+}
+function buildError(id, code, message, data) {
+    const error = { code, message };
+    if (data !== undefined)
+        error.data = data;
+    return { jsonrpc: exports.JSONRPC_VERSION, id, error };
+}
+//# sourceMappingURL=jsonrpc.js.map

package/dist/core/components/mcp/jsonrpc.js.map

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

package/dist/core/components/mcp/lifecycle.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_CAPABILITIES = exports.SERVER_INFO = exports.SUPPORTED_PROTOCOL_VERSIONS = exports.PROTOCOL_VERSION_BACKCOMPAT = exports.PROTOCOL_VERSION_PREFERRED = void 0;
+exports.handleInitialize = handleInitialize;
+exports.handleInitialized = handleInitialized;
+/**
+ * MCP lifecycle handlers — `initialize` and `notifications/initialized`.
+ *
+ * Spec: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle
+ * v1 supports protocol version `2025-06-18` (preferred) and `2025-03-26`
+ * (backcompat). Anything else returns 400 to the client; per the spec, the
+ * server SHOULD respond with its preferred supported version so the client
+ * can decide whether to connect on the older version or disconnect.
+ */
+const session_ts_1 = require("./session.js");
+const packageUtils_js_1 = require("../../utility/packageUtils.js");
+exports.PROTOCOL_VERSION_PREFERRED = '2025-06-18';
+exports.PROTOCOL_VERSION_BACKCOMPAT = '2025-03-26';
+exports.SUPPORTED_PROTOCOL_VERSIONS = [exports.PROTOCOL_VERSION_PREFERRED, exports.PROTOCOL_VERSION_BACKCOMPAT];
+exports.SERVER_INFO = {
+    name: 'harper-mcp',
+    version: packageUtils_js_1.packageJson.version,
+};
+/** Server capabilities advertised on `initialize` for v1. */
+exports.SERVER_CAPABILITIES = {
+    tools: { listChanged: true },
+    resources: { listChanged: true },
+    logging: {},
+};
+/**
+ * Negotiate protocol version, create a session, and return the JSON-RPC
+ * result body. The caller (transport core) maps `ok: false` to HTTP 400.
+ *
+ * Per the MCP spec: if the client requests a version the server does not
+ * support, the server MUST respond with a version it does support (so the
+ * client can decide whether to downgrade or disconnect) — NOT fail. We
+ * pick `PROTOCOL_VERSION_PREFERRED` for any unknown version. The only
+ * `ok: false` cases are a missing or non-string `protocolVersion` field,
+ * which is a protocol-level violation rather than version negotiation.
+ *
+ * `instructions` is optional per spec; we omit it in v1 (it can be wired
+ * later when tools land in #617 and we know which profile is active).
+ */
+async function handleInitialize(params, user) {
+    const requested = params?.protocolVersion;
+    if (typeof requested !== 'string') {
+        return {
+            ok: false,
+            reason: `protocolVersion is required and must be a string`,
+            supportedVersions: exports.SUPPORTED_PROTOCOL_VERSIONS,
+        };
+    }
+    const negotiated = exports.SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : exports.PROTOCOL_VERSION_PREFERRED;
+    const session = await (0, session_ts_1.createSession)({ user, protocolVersion: negotiated });
+    return {
+        ok: true,
+        session,
+        result: {
+            protocolVersion: negotiated,
+            serverInfo: exports.SERVER_INFO,
+            capabilities: exports.SERVER_CAPABILITIES,
+        },
+    };
+}
+/**
+ * Flip the session to `initialized: true`. Called when the client posts the
+ * `notifications/initialized` JSON-RPC notification (per MCP §lifecycle).
+ * The transport returns HTTP 202 with no body regardless of outcome here.
+ */
+async function handleInitialized(session) {
+    if (session.initialized)
+        return session;
+    const updated = { ...session, initialized: true };
+    await (0, session_ts_1.saveSession)(updated);
+    return updated;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/core/components/mcp/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../../core/components/mcp/lifecycle.ts"],"names":[],"mappings":";;;AAmEA,4CAyBC;AAOD,8CAKC;AAxGD;;;;;;;;GAQG;AACH,6CAAiF;AACjF,mEAA4D;AAE/C,QAAA,0BAA0B,GAAG,YAAY,CAAC;AAC1C,QAAA,2BAA2B,GAAG,YAAY,CAAC;AAC3C,QAAA,2BAA2B,GAAG,CAAC,kCAA0B,EAAE,mCAA2B,CAAU,CAAC;AAEjG,QAAA,WAAW,GAAG;IAC1B,IAAI,EAAE,YAAY;IAClB,OAAO,EAAG,6BAAmC,CAAC,OAAO;CAC5C,CAAC;AAEX,6DAA6D;AAChD,QAAA,mBAAmB,GAAG;IAClC,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;IAC5B,SAAS,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;IAChC,OAAO,EAAE,EAAE;CACF,CAAC;AA2BX;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,gBAAgB,CACrC,MAAoC,EACpC,IAAY;IAEZ,MAAM,SAAS,GAAG,MAAM,EAAE,eAAe,CAAC;IAC1C,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACnC,OAAO;YACN,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,kDAAkD;YAC1D,iBAAiB,EAAE,mCAA2B;SAC9C,CAAC;IACH,CAAC;IACD,MAAM,UAAU,GAAG,mCAA2B,CAAC,QAAQ,CAAC,SAAyD,CAAC;QACjH,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,kCAA0B,CAAC;IAC9B,MAAM,OAAO,GAAG,MAAM,IAAA,0BAAa,EAAC,EAAE,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3E,OAAO;QACN,EAAE,EAAE,IAAI;QACR,OAAO;QACP,MAAM,EAAE;YACP,eAAe,EAAE,UAAU;YAC3B,UAAU,EAAE,mBAAW;YACvB,YAAY,EAAE,2BAAmB;SACjC;KACD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,iBAAiB,CAAC,OAAyB;IAChE,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,OAAO,CAAC;IACxC,MAAM,OAAO,GAAqB,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACpE,MAAM,IAAA,wBAAW,EAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AAChB,CAAC"}