@harperfast/harper-pro 5.0.30 → 5.1.0-beta.2

package/core/components/mcp/audit.ts

@@ -0,0 +1,75 @@
+/**
+ * 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).
+ */
+import harperLogger from '../../utility/logging/harper_logger.ts';
+
+export interface AuditEntry {
+	timestamp: string;
+	profile: 'operations' | 'application';
+	sessionId: string;
+	tool: string;
+	user: string;
+	args: object;
+	status: 'ok' | 'isError' | 'rate_limited' | 'protocol_error';
+	durationMs: number;
+	errorMessage?: string;
+}
+
+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.
+ */
+export function redactArgs(value: unknown, depth = 0): unknown {
+	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: Record<string, unknown> = {};
+	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. */
+export function maskSessionId(id: string): string {
+	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'`.
+ */
+export function emitAuditEntry(entry: AuditEntry): void {
+	try {
+		const masked = { ...entry, sessionId: maskSessionId(entry.sessionId), args: redactArgs(entry.args) };
+		harperLogger.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.
+		harperLogger.trace(`MCP audit emit failed: ${(err as Error).message}`);
+	}
+}

package/core/components/mcp/index.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import { getConfigObj as realGetConfigObj } from '../../config/configUtils.js';
+import { createFastifyHandler } from './adapters/fastify.ts';
+import { createHarperHttpHandler } from './adapters/harperHttp.ts';
+import { ensureSessionTable } from './session.ts';
+import { initListChanged } from './listChanged.ts';
+import { registerApplicationTools } from './tools/application.ts';
+import { registerOperationsTools } from './tools/operations.ts';
+import type { McpProfile } from './transport.ts';
+
+// Indirection so tests can swap the config source.
+let getConfigObj: () => unknown = realGetConfigObj as () => unknown;
+export function _setGetConfigObjForTest(fn: () => unknown): void {
+	getConfigObj = fn;
+}
+export function _restoreGetConfigObj(): void {
+	getConfigObj = realGetConfigObj as () => unknown;
+}
+
+interface McpProfileConfig {
+	mountPath?: string;
+}
+
+interface FullConfig {
+	mcp?: {
+		operations?: McpProfileConfig;
+		application?: McpProfileConfig;
+		session?: unknown;
+	};
+}
+
+interface FastifyLikeHost {
+	post: (path: string, ...rest: unknown[]) => unknown;
+	get: (path: string, ...rest: unknown[]) => unknown;
+	delete: (path: string, ...rest: unknown[]) => unknown;
+}
+
+export interface RegisterMcpProfileArgs {
+	profile: McpProfile;
+	host: FastifyLikeHost;
+	config: FullConfig;
+	routeOptions?: Record<string, unknown>;
+}
+
+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.
+ */
+export function registerMcpProfile({ profile, host, config, routeOptions }: RegisterMcpProfileArgs): void {
+	const profileConfig = config?.mcp?.[profile];
+	if (!profileConfig) {
+		harperLogger.trace(`MCP ${profile} profile not configured, skipping registration`);
+		return;
+	}
+	ensureSessionTable();
+	initListChanged();
+	if (profile === 'operations') {
+		registerOperationsTools();
+	}
+	const mountPath = profileConfig.mountPath ?? DEFAULT_MOUNT_PATH;
+	const handler = 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'] as const) {
+		if (routeOptions) {
+			host[method](mountPath, routeOptions, handler);
+		} else {
+			host[method](mountPath, handler);
+		}
+	}
+	harperLogger.info(`MCP ${profile} profile registered at ${mountPath}`);
+}
+
+let applicationStarted = false;
+
+interface ScopeLike {
+	server: {
+		http: (handler: unknown, options: Record<string, unknown>) => unknown;
+	};
+}
+
+/**
+ * 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`.
+ */
+export function handleApplication(scope: ScopeLike): void {
+	if (applicationStarted) return;
+	const config = getConfigObj() as FullConfig | undefined;
+	if (!config?.mcp?.application) {
+		harperLogger.trace('MCP application profile not configured, skipping registration');
+		return;
+	}
+	applicationStarted = true;
+	ensureSessionTable();
+	initListChanged();
+	registerApplicationTools();
+	const mountPath = config.mcp.application.mountPath ?? DEFAULT_MOUNT_PATH;
+	const handler = createHarperHttpHandler('application');
+	scope.server.http(handler, { urlPath: mountPath, after: 'authentication' });
+	harperLogger.info(`MCP application profile registered at ${mountPath}`);
+}
+
+/** Test seam: reset the module-level guard so tests can re-invoke handleApplication. */
+export function _resetApplicationStartedForTest(): void {
+	applicationStarted = false;
+}

package/core/components/mcp/jsonrpc.ts

@@ -0,0 +1,134 @@
+/**
+ * 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
+ */
+
+export const JSONRPC_VERSION = '2.0';
+
+/** Standard JSON-RPC 2.0 error codes (spec §5.1). */
+export const ERROR_CODES = {
+	PARSE_ERROR: -32700,
+	INVALID_REQUEST: -32600,
+	METHOD_NOT_FOUND: -32601,
+	INVALID_PARAMS: -32602,
+	INTERNAL_ERROR: -32603,
+} as const;
+
+export type JsonRpcId = string | number | null;
+
+export interface JsonRpcRequest {
+	jsonrpc: '2.0';
+	id: JsonRpcId;
+	method: string;
+	params?: unknown;
+}
+
+export interface JsonRpcNotification {
+	jsonrpc: '2.0';
+	method: string;
+	params?: unknown;
+}
+
+export interface JsonRpcSuccessResponse {
+	jsonrpc: '2.0';
+	id: JsonRpcId;
+	result: unknown;
+}
+
+export interface JsonRpcErrorObject {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+export interface JsonRpcErrorResponse {
+	jsonrpc: '2.0';
+	id: JsonRpcId;
+	error: JsonRpcErrorObject;
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcSuccessResponse | JsonRpcErrorResponse;
+
+export interface ParseSuccess {
+	ok: true;
+	message: JsonRpcMessage;
+}
+export interface ParseFailure {
+	ok: false;
+	code: number;
+	reason: string;
+}
+export type ParseResult = ParseSuccess | ParseFailure;
+
+/**
+ * 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.
+ */
+export function parseMessage(body: string | unknown): ParseResult {
+	let parsed: unknown;
+	if (typeof body === 'string') {
+		try {
+			parsed = JSON.parse(body);
+		} catch (err) {
+			const fail: ParseFailure = { ok: false, code: ERROR_CODES.PARSE_ERROR, reason: (err as Error).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: ParseFailure = { ok: false, code: ERROR_CODES.INVALID_REQUEST, reason: 'expected a JSON object' };
+		return fail;
+	}
+	const obj = parsed as Record<string, unknown>;
+	if (obj.jsonrpc !== JSONRPC_VERSION) {
+		const fail: ParseFailure = {
+			ok: false,
+			code: ERROR_CODES.INVALID_REQUEST,
+			reason: `jsonrpc must be "${JSONRPC_VERSION}"`,
+		};
+		return fail;
+	}
+	const hasMethod = typeof obj.method === 'string';
+	const hasResultOrError = 'result' in obj || 'error' in obj;
+	if (!hasMethod && !hasResultOrError) {
+		const fail: ParseFailure = {
+			ok: false,
+			code: ERROR_CODES.INVALID_REQUEST,
+			reason: 'missing method, result, or error field',
+		};
+		return fail;
+	}
+	const success: ParseSuccess = { ok: true, message: parsed as JsonRpcMessage };
+	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.
+ */
+export function isClientFireAndForget(message: JsonRpcMessage): boolean {
+	const hasId = 'id' in message;
+	const hasResultOrError = 'result' in message || 'error' in message;
+	return !hasId || hasResultOrError;
+}
+
+export function buildSuccess(id: JsonRpcId, result: unknown): JsonRpcSuccessResponse {
+	return { jsonrpc: JSONRPC_VERSION, id, result };
+}
+
+export function buildError(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcErrorResponse {
+	const error: JsonRpcErrorObject = { code, message };
+	if (data !== undefined) error.data = data;
+	return { jsonrpc: JSONRPC_VERSION, id, error };
+}

package/core/components/mcp/lifecycle.ts

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import { createSession, saveSession, type McpSessionRecord } from './session.ts';
+import { packageJson } from '../../utility/packageUtils.js';
+
+export const PROTOCOL_VERSION_PREFERRED = '2025-06-18';
+export const PROTOCOL_VERSION_BACKCOMPAT = '2025-03-26';
+export const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION_PREFERRED, PROTOCOL_VERSION_BACKCOMPAT] as const;
+
+export const SERVER_INFO = {
+	name: 'harper-mcp',
+	version: (packageJson as { version: string }).version,
+} as const;
+
+/** Server capabilities advertised on `initialize` for v1. */
+export const SERVER_CAPABILITIES = {
+	tools: { listChanged: true },
+	resources: { listChanged: true },
+	logging: {},
+} as const;
+
+export interface InitializeParams {
+	protocolVersion?: unknown;
+	capabilities?: unknown;
+	clientInfo?: unknown;
+}
+
+export interface InitializeResult {
+	protocolVersion: string;
+	serverInfo: typeof SERVER_INFO;
+	capabilities: typeof SERVER_CAPABILITIES;
+	instructions?: string;
+}
+
+export interface InitializeOutcome {
+	ok: true;
+	session: McpSessionRecord;
+	result: InitializeResult;
+}
+
+export interface InitializeFailure {
+	ok: false;
+	reason: string;
+	supportedVersions: readonly string[];
+}
+
+/**
+ * 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).
+ */
+export async function handleInitialize(
+	params: InitializeParams | undefined,
+	user: string
+): Promise<InitializeOutcome | InitializeFailure> {
+	const requested = params?.protocolVersion;
+	if (typeof requested !== 'string') {
+		return {
+			ok: false,
+			reason: `protocolVersion is required and must be a string`,
+			supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
+		};
+	}
+	const negotiated = SUPPORTED_PROTOCOL_VERSIONS.includes(requested as (typeof SUPPORTED_PROTOCOL_VERSIONS)[number])
+		? requested
+		: PROTOCOL_VERSION_PREFERRED;
+	const session = await createSession({ user, protocolVersion: negotiated });
+	return {
+		ok: true,
+		session,
+		result: {
+			protocolVersion: negotiated,
+			serverInfo: SERVER_INFO,
+			capabilities: 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.
+ */
+export async function handleInitialized(session: McpSessionRecord): Promise<McpSessionRecord> {
+	if (session.initialized) return session;
+	const updated: McpSessionRecord = { ...session, initialized: true };
+	await saveSession(updated);
+	return updated;
+}