@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/components/mcp/tools/operations.ts

@@ -0,0 +1,283 @@
+/**
+ * Operations-profile tool generation. Walks Harper's `OPERATION_FUNCTION_MAP`
+ * and registers one MCP tool per operation that survives the
+ * `mcp.operations.allow` / `deny` filter.
+ *
+ * The default v1 allow list is read-only and intentionally narrow:
+ * `describe_*`, `list_*`, `search_*`, plus an explicit set of safe
+ * getters (`get_job`, `get_status`, `get_analytics`, `get_metrics`),
+ * `system_information`, `read_log`, `read_audit_log`. A `get_*` glob
+ * was rejected because it would have matched `get_configuration`
+ * (TLS/S3/auth secrets), `get_components` + `get_component_file` +
+ * `get_custom_function*` (component source code, which can embed
+ * secrets), `get_backup`, and `get_deployment{,_payload}` — none of
+ * which should default into the MCP surface even though
+ * `verifyPerms` still gates the actual call. Operators who want any
+ * of those opt in via `mcp.operations.allow`. Destructive ops carry
+ * `destructiveHint: true` so well-behaved MCP clients can surface a
+ * confirmation prompt.
+ *
+ * Tool dispatch delegates to `chooseOperation` + `processLocalTransaction`
+ * — the same path Harper's REST `/operation` endpoint uses. That means
+ * `verifyPerms` runs unchanged, replication catchup runs unchanged, and
+ * server-side validation errors surface as `isError: true` results without
+ * the MCP layer needing to know what each operation expects.
+ */
+import * as env from '../../../utility/environment/environmentManager.ts';
+import { CONFIG_PARAMS } from '../../../utility/hdbTerms.ts';
+import harperLogger from '../../../utility/logging/harper_logger.ts';
+import { addTool, canRoleInvokeOperation, type AuthedUser, type ToolResult } from '../toolRegistry.ts';
+import { OPERATION_INPUT_SCHEMAS, PERMISSIVE_SCHEMA } from './schemas/operations.ts';
+
+// Eager-resolved at module load. The map is built at Harper boot and
+// doesn't mutate, so caching here is safe.
+type OperationFunction = (json: object) => unknown | Promise<unknown>;
+type OperationFunctionMap = Map<string, { operation_function: OperationFunction }>;
+
+type ChooseOperation = (body: object) => OperationFunction;
+type ProcessLocalTransaction = (req: { body: object }, fn: OperationFunction) => Promise<unknown>;
+
+interface OperationsConfig {
+	allow?: readonly string[];
+	deny?: readonly string[];
+}
+
+// Test seams. Avoids importing Harper's heavy server-helpers graph from unit
+// tests that only want to exercise the registration logic.
+let _opMapOverride: OperationFunctionMap | undefined;
+let _chooseOperationOverride: ChooseOperation | undefined;
+let _processLocalTransactionOverride: ProcessLocalTransaction | undefined;
+
+export function _setOperationFunctionMapForTest(m: OperationFunctionMap | undefined): void {
+	_opMapOverride = m;
+}
+export function _setChooseOperationForTest(fn: ChooseOperation | undefined): void {
+	_chooseOperationOverride = fn;
+}
+export function _setProcessLocalTransactionForTest(fn: ProcessLocalTransaction | undefined): void {
+	_processLocalTransactionOverride = fn;
+}
+
+function loadServerUtilities():
+	| {
+			OPERATION_FUNCTION_MAP?: OperationFunctionMap;
+			chooseOperation?: ChooseOperation;
+			processLocalTransaction?: ProcessLocalTransaction;
+	  }
+	| undefined {
+	try {
+		// Lazy require: Harper's server-helpers graph initializes eagerly
+		// (RocksDB lock acquisition, schema preload). Loading it from a unit
+		// test that hasn't booted Harper throws; treat that as "we're not in
+		// a Harper process" and let callers gracefully no-op.
+		return require('../../../server/serverHelpers/serverUtilities');
+	} catch (err) {
+		harperLogger.trace(`MCP operations tools: serverUtilities unavailable (${(err as Error).message})`);
+		return undefined;
+	}
+}
+
+function getOperationFunctionMap(): OperationFunctionMap | undefined {
+	if (_opMapOverride) return _opMapOverride;
+	const utils = loadServerUtilities();
+	return utils?.OPERATION_FUNCTION_MAP;
+}
+
+function getChooseOperation(): ChooseOperation | undefined {
+	if (_chooseOperationOverride) return _chooseOperationOverride;
+	return loadServerUtilities()?.chooseOperation;
+}
+
+function getProcessLocalTransaction(): ProcessLocalTransaction | undefined {
+	if (_processLocalTransactionOverride) return _processLocalTransactionOverride;
+	return loadServerUtilities()?.processLocalTransaction;
+}
+
+/**
+ * Default v1 allow list — read-only operations only. Operators who want
+ * destructive ops on the MCP surface opt in via `mcp.operations.allow`.
+ */
+export const DEFAULT_ALLOW: readonly string[] = [
+	'describe_*',
+	'list_*',
+	'search_*',
+	// Explicit safe getters only — see file-header rationale. `get_*` would
+	// pull in `get_configuration`, `get_components`, `get_custom_function*`,
+	// `get_backup`, and `get_deployment*`, all of which can leak secrets or
+	// source code into the LLM context even with `verifyPerms` enforcing.
+	'get_job',
+	'get_status',
+	'get_analytics',
+	'get_metrics',
+	'system_information',
+	'read_log',
+	'read_audit_log',
+];
+
+/**
+ * Operations that carry `destructiveHint: true` when opted into the allow
+ * list. The hint lets MCP clients surface a confirmation prompt before
+ * calling. It is **not** an authorization check — Harper's `verifyPerms`
+ * still runs at the actual dispatch site.
+ */
+const DESTRUCTIVE_OPERATIONS: ReadonlySet<string> = new Set([
+	'drop_schema',
+	'drop_database',
+	'drop_table',
+	'drop_attribute',
+	'delete',
+	'delete_files_before',
+	'delete_records_before',
+	'delete_audit_logs_before',
+	'delete_transaction_logs_before',
+	'drop_user',
+	'drop_role',
+	'restart',
+	'restart_service',
+	'set_configuration',
+	'remove_node',
+]);
+
+/**
+ * Read-only operations carry `readOnlyHint: true`. The category is wider
+ * than the default allow list (some custom-allowed ops are also read-only
+ * — `system_information`, for example). Any op matching one of these
+ * prefixes or names is treated as read-only.
+ */
+const READ_ONLY_PREFIXES: readonly string[] = ['describe_', 'list_', 'search_', 'get_', 'read_'];
+const READ_ONLY_NAMES: ReadonlySet<string> = new Set(['system_information', 'status']);
+
+function isReadOnly(operationName: string): boolean {
+	if (READ_ONLY_NAMES.has(operationName)) return true;
+	return READ_ONLY_PREFIXES.some((p) => operationName.startsWith(p));
+}
+
+function isDestructive(operationName: string): boolean {
+	return DESTRUCTIVE_OPERATIONS.has(operationName);
+}
+
+/**
+ * Translates a single glob pattern (only `*` is supported) into a regex.
+ * `describe_*` matches `describe_schema`, `describe_table`, etc.; literals
+ * like `system_information` match exactly. No escape hatch yet — operators
+ * should use literals when they need them; the glob language is delibarately
+ * minimal to keep behavior predictable in audit/security reviews.
+ */
+function globToRegex(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+	return new RegExp(`^${escaped}$`);
+}
+
+function matchesAny(operation: string, patterns: readonly string[] | undefined): boolean {
+	if (!patterns || patterns.length === 0) return false;
+	for (const p of patterns) {
+		if (globToRegex(p).test(operation)) return true;
+	}
+	return false;
+}
+
+function isOperationAllowed(operation: string, config: OperationsConfig): boolean {
+	const allowList = config.allow && config.allow.length > 0 ? config.allow : DEFAULT_ALLOW;
+	if (!matchesAny(operation, allowList)) return false;
+	if (matchesAny(operation, config.deny)) return false;
+	return true;
+}
+
+function getOperationsConfig(): OperationsConfig {
+	const allow = env.get(CONFIG_PARAMS.MCP_OPERATIONS_ALLOW);
+	const deny = env.get(CONFIG_PARAMS.MCP_OPERATIONS_DENY);
+	return {
+		allow: Array.isArray(allow) ? (allow as readonly string[]) : undefined,
+		deny: Array.isArray(deny) ? (deny as readonly string[]) : undefined,
+	};
+}
+
+function buildDescription(operationName: string, hasCuratedSchema: boolean): string {
+	const base = `Harper operation '${operationName}'.`;
+	const schemaNote = hasCuratedSchema
+		? ' Arguments validated against the curated schema below.'
+		: ' Arguments forwarded as-is; the server validates and returns a structured error on rejection.';
+	return base + schemaNote;
+}
+
+/**
+ * Build the dispatch handler for one operation. Returns a function suitable
+ * for `ToolDef.handler` that delegates to Harper's normal operation pipeline.
+ *
+ * Errors from `chooseOperation` (permission denied) or from the operation
+ * itself surface as `isError: true` MCP results, not JSON-RPC errors —
+ * matches the MCP spec's `tools/call` convention so the LLM sees and can
+ * adapt to the failure.
+ */
+function makeOperationToolHandler(operationName: string) {
+	return async function operationToolHandler(args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		const body: Record<string, unknown> = {
+			...(args && typeof args === 'object' ? (args as Record<string, unknown>) : {}),
+			operation: operationName,
+			hdb_user: context.user,
+		};
+		try {
+			const chooseOperation = getChooseOperation();
+			const processLocalTransaction = getProcessLocalTransaction();
+			if (!chooseOperation || !processLocalTransaction) {
+				throw new Error('Harper operations runtime unavailable');
+			}
+			const operationFn = chooseOperation(body);
+			const data = await processLocalTransaction({ body }, operationFn);
+			const text = typeof data === 'string' ? data : JSON.stringify(data ?? null);
+			const result: ToolResult = {
+				content: [{ type: 'text', text }],
+			};
+			if (data !== null && typeof data === 'object') {
+				result.structuredContent = data as object;
+			}
+			return result;
+		} catch (err) {
+			const e = err as { message?: string; http_resp_msg?: string; statusCode?: number };
+			const message = e?.http_resp_msg ?? e?.message ?? `operation '${operationName}' failed`;
+			harperLogger.trace(`MCP operations/${operationName} threw: ${(err as Error).stack ?? message}`);
+			return {
+				isError: true,
+				content: [
+					{
+						type: 'text',
+						text: JSON.stringify({ kind: 'harper_error', operation: operationName, message }),
+					},
+				],
+			};
+		}
+	};
+}
+
+/**
+ * Idempotent registration: walk the op map, register every operation that
+ * passes the allow/deny filter. Safe to invoke multiple times — `addTool`
+ * is `Map.set`-backed.
+ */
+export function registerOperationsTools(): void {
+	const opMap = getOperationFunctionMap();
+	if (!opMap) {
+		harperLogger.warn('MCP operations profile: OPERATION_FUNCTION_MAP not available; no tools registered');
+		return;
+	}
+	const config = getOperationsConfig();
+	let registered = 0;
+	for (const operationName of opMap.keys()) {
+		if (!isOperationAllowed(operationName, config)) continue;
+		const inputSchema = OPERATION_INPUT_SCHEMAS[operationName] ?? PERMISSIVE_SCHEMA;
+		const annotations: { readOnlyHint?: boolean; destructiveHint?: boolean } = {};
+		if (isReadOnly(operationName)) annotations.readOnlyHint = true;
+		if (isDestructive(operationName)) annotations.destructiveHint = true;
+		addTool({
+			name: operationName,
+			description: buildDescription(operationName, operationName in OPERATION_INPUT_SCHEMAS),
+			inputSchema,
+			profile: 'operations',
+			...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+			visibleTo: (user) => canRoleInvokeOperation(user, operationName),
+			handler: makeOperationToolHandler(operationName),
+		});
+		registered++;
+	}
+	harperLogger.info(`MCP operations profile: registered ${registered} tool(s)`);
+}

package/components/mcp/tools/schemas/derive.ts

@@ -0,0 +1,256 @@
+/**
+ * Derive MCP tool input schemas from a Harper Resource's `Table.attributes`.
+ *
+ * Harper attribute types map to JSON Schema's primitive types; nested
+ * `properties[]` and array `elements` map recursively. `attribute_permissions`
+ * (per role, per table) narrows the schema by removing attributes the user
+ * can't read (for `get_*`/`search_*`) or write (for `create_*`/`update_*`).
+ *
+ * Runtime enforcement still happens in `Table.allowUpdate` /
+ * `Table.allowCreate` — the schema narrowing here is a UX layer (so the LLM
+ * doesn't waste tokens on fields it can't write), NOT a security boundary.
+ */
+
+export interface HarperAttribute {
+	name: string;
+	type?: string;
+	nullable?: boolean;
+	isPrimaryKey?: boolean;
+	properties?: HarperAttribute[];
+	elements?: HarperAttribute;
+	computed?: unknown;
+	computedFromExpression?: string;
+	assignCreatedTime?: boolean;
+	assignUpdatedTime?: boolean;
+	expiresAt?: boolean;
+}
+
+export interface AttributePermissionEntry {
+	attribute_name: string;
+	read?: boolean;
+	insert?: boolean;
+	update?: boolean;
+}
+
+type Mode = 'read' | 'insert' | 'update';
+
+/**
+ * Maps a Harper attribute type to a JSON Schema `type` value (or list of
+ * types when nullable). Falls back to "string" for unknown types — better
+ * than blocking the field entirely; the runtime will validate.
+ */
+function harperTypeToJsonSchema(type: string | undefined): { type: string | string[] } | object {
+	switch (type) {
+		case 'Int':
+		case 'Long':
+		case 'BigInt':
+			return { type: 'integer' };
+		case 'Float':
+			return { type: 'number' };
+		case 'Boolean':
+			return { type: 'boolean' };
+		case 'String':
+		case 'ID':
+			return { type: 'string' };
+		case 'Date':
+			// Harper Date may be ISO string or number; allow both for LLM flexibility.
+			return { type: ['string', 'number'], description: 'ISO 8601 timestamp or epoch milliseconds.' };
+		case 'Bytes':
+		case 'Blob':
+			return { type: 'string', contentEncoding: 'base64' };
+		case 'Any':
+		case undefined:
+			return {};
+		default:
+			return { type: 'string' };
+	}
+}
+
+function attributeToProperty(attr: HarperAttribute): object {
+	let base: object;
+	if (attr.type === 'Object' && attr.properties) {
+		base = {
+			type: 'object',
+			properties: Object.fromEntries(attr.properties.map((p) => [p.name, attributeToProperty(p)])),
+		};
+	} else if (attr.type === 'Array' && attr.elements) {
+		base = {
+			type: 'array',
+			items: attributeToProperty(attr.elements),
+		};
+	} else {
+		base = harperTypeToJsonSchema(attr.type);
+	}
+	if (attr.nullable && 'type' in (base as { type?: unknown })) {
+		const t = (base as { type: string | string[] }).type;
+		const types = Array.isArray(t) ? t : [t];
+		if (!types.includes('null')) {
+			(base as { type: string[] }).type = [...types, 'null'];
+		}
+	}
+	return base;
+}
+
+/**
+ * `true` if the user has the requested mode (read/insert/update) on this
+ * attribute. When no per-attribute permissions exist, returns true (the
+ * table-level perm gates the call already).
+ */
+function attributeAllowed(
+	attributeName: string,
+	permissions: AttributePermissionEntry[] | undefined,
+	mode: Mode
+): boolean {
+	if (!permissions || permissions.length === 0) return true;
+	const match = permissions.find((p) => p.attribute_name === attributeName);
+	if (!match) return false; // explicit list with no entry → denied
+	return match[mode] !== false;
+}
+
+/**
+ * Build a JSON Schema object covering some subset of the table's attributes.
+ * `mode` controls how attribute_permissions are interpreted; `include`
+ * optionally limits to a subset (e.g. primary-key-only for `delete_*`).
+ */
+function buildPropertiesObject(
+	attributes: HarperAttribute[],
+	permissions: AttributePermissionEntry[] | undefined,
+	mode: Mode,
+	include?: (a: HarperAttribute) => boolean
+): { properties: Record<string, object>; required: string[] } {
+	const properties: Record<string, object> = {};
+	const required: string[] = [];
+	for (const attr of attributes) {
+		if (include && !include(attr)) continue;
+		if (!attributeAllowed(attr.name, permissions, mode)) continue;
+		// Skip auto-managed columns from write inputs — Harper assigns them.
+		if (mode !== 'read' && (attr.assignCreatedTime || attr.assignUpdatedTime || attr.expiresAt)) continue;
+		if (mode !== 'read' && (attr.computed !== undefined || attr.computedFromExpression !== undefined)) continue;
+		properties[attr.name] = attributeToProperty(attr);
+		if (mode === 'insert' && !attr.nullable && !attr.isPrimaryKey) {
+			required.push(attr.name);
+		}
+	}
+	return { properties, required };
+}
+
+function findPrimaryKey(attributes: HarperAttribute[]): HarperAttribute | undefined {
+	return attributes.find((a) => a.isPrimaryKey);
+}
+
+export function deriveGetSchema(
+	attributes: HarperAttribute[],
+	_permissions: AttributePermissionEntry[] | undefined
+): object {
+	const pk = findPrimaryKey(attributes);
+	const pkSchema = pk ? attributeToProperty(pk) : { type: 'string' };
+	return {
+		type: 'object',
+		properties: {
+			id: { ...pkSchema, description: pk ? `Primary key (${pk.name}).` : 'Primary key.' },
+			get_attributes: {
+				type: 'array',
+				items: { type: 'string' },
+				description: 'Attribute names to project; defaults to all readable attributes.',
+			},
+		},
+		required: ['id'],
+	};
+}
+
+export function deriveSearchSchema(
+	attributes: HarperAttribute[],
+	permissions: AttributePermissionEntry[] | undefined
+): object {
+	// `conditions` is freeform — Harper supports many comparators; we expose
+	// the common subset and rely on server-side validation for the rest.
+	const readableAttrs = attributes.filter((a) => attributeAllowed(a.name, permissions, 'read'));
+	const attrNames = readableAttrs.map((a) => a.name);
+	return {
+		type: 'object',
+		properties: {
+			conditions: {
+				type: 'array',
+				items: {
+					type: 'object',
+					properties: {
+						attribute: {
+							type: 'string',
+							...(attrNames.length > 0 ? { enum: attrNames } : {}),
+							description: 'Attribute name to filter on.',
+						},
+						comparator: {
+							type: 'string',
+							enum: [
+								'equals',
+								'not_equals',
+								'contains',
+								'starts_with',
+								'ends_with',
+								'greater_than',
+								'less_than',
+								'greater_than_equal',
+								'less_than_equal',
+								'between',
+							],
+							description: 'Comparison operator. Defaults to "equals" if omitted.',
+						},
+						value: { description: 'Comparison value (any JSON type).' },
+					},
+					required: ['attribute', 'value'],
+				},
+			},
+			operator: { type: 'string', enum: ['and', 'or'], description: 'How to combine conditions; defaults to "and".' },
+			get_attributes: { type: 'array', items: { type: 'string' } },
+			limit: { type: 'integer', minimum: 1, description: 'Max records to return on this page.' },
+			cursor: { type: 'string', description: 'Opaque pagination cursor returned by a previous call.' },
+		},
+	};
+}
+
+export function deriveCreateSchema(
+	attributes: HarperAttribute[],
+	permissions: AttributePermissionEntry[] | undefined
+): object {
+	const { properties, required } = buildPropertiesObject(attributes, permissions, 'insert');
+	const schema: { type: string; properties: Record<string, object>; required?: string[] } = {
+		type: 'object',
+		properties,
+	};
+	if (required.length > 0) schema.required = required;
+	return schema;
+}
+
+export function deriveUpdateSchema(
+	attributes: HarperAttribute[],
+	permissions: AttributePermissionEntry[] | undefined
+): object {
+	const pk = findPrimaryKey(attributes);
+	const { properties } = buildPropertiesObject(attributes, permissions, 'update', (a) => !a.isPrimaryKey);
+	return {
+		type: 'object',
+		properties: {
+			id: pk
+				? { ...attributeToProperty(pk), description: `Primary key (${pk.name}). Required.` }
+				: { type: 'string', description: 'Primary key. Required.' },
+			...properties,
+		},
+		required: ['id'],
+	};
+}
+
+export function deriveDeleteSchema(
+	attributes: HarperAttribute[],
+	_permissions: AttributePermissionEntry[] | undefined
+): object {
+	const pk = findPrimaryKey(attributes);
+	return {
+		type: 'object',
+		properties: {
+			id: pk
+				? { ...attributeToProperty(pk), description: `Primary key (${pk.name}).` }
+				: { type: 'string', description: 'Primary key.' },
+		},
+		required: ['id'],
+	};
+}