@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/components/mcp/tools/application.ts

@@ -0,0 +1,603 @@
+/**
+ * Application-profile tool generation. Walks Harper's `Resources` registry
+ * and registers verb tools (`get_*`, `search_*`, `create_*`, `update_*`,
+ * `delete_*`) for each exported Resource that:
+ *   1. Has a `'mcp'` exportType not explicitly set to `false`.
+ *   2. Implements the corresponding verb on its prototype.
+ *
+ * Tool dispatch delegates to the static `Resource.get/post/put/delete/search`
+ * methods, which wrap `transactional()` internally. That means
+ * `allowRead/allowCreate/allowUpdate/allowDelete` per-record predicates run
+ * unchanged, and restricted-attribute writes are rejected at runtime by
+ * `Table.allowUpdate` even when the input schema permits them — defense in
+ * depth.
+ */
+import { createHash } from 'node:crypto';
+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, type AuthedUser, type ToolResult } from '../toolRegistry.ts';
+import {
+	type AttributePermissionEntry,
+	type HarperAttribute,
+	deriveCreateSchema,
+	deriveDeleteSchema,
+	deriveGetSchema,
+	deriveSearchSchema,
+	deriveUpdateSchema,
+} from './schemas/derive.ts';
+
+type ExportTypes = Record<string, boolean> | undefined;
+
+interface ResourceRegistryEntry {
+	Resource: ResourceClassLike;
+	path: string;
+	exportTypes?: ExportTypes;
+	hasSubPaths?: boolean;
+	relativeURL?: string;
+}
+
+interface ResourceClassLike {
+	prototype?: Record<string, unknown>;
+	databaseName?: string;
+	tableName?: string;
+	primaryKey?: string;
+	attributes?: HarperAttribute[];
+	get?: (target: unknown, request: unknown, data?: unknown) => unknown;
+	put?: (target: unknown, data: unknown, request: unknown) => unknown;
+	post?: (target: unknown, data: unknown, request: unknown) => unknown;
+	patch?: (target: unknown, data: unknown, request: unknown) => unknown;
+	delete?: (target: unknown, request: unknown, data?: unknown) => unknown;
+	search?: (target: unknown, request: unknown) => unknown;
+	loadAsInstance?: boolean;
+	/**
+	 * Component-author opt-in (#622): expose non-verb instance methods as MCP
+	 * tools. Each entry maps an instance-method name to an MCP tool descriptor.
+	 * RBAC stays as whatever the Resource's method itself enforces; the MCP
+	 * layer does not invent new ACLs for these.
+	 */
+	mcpTools?: ReadonlyArray<{
+		name: string;
+		method: string;
+		description?: string;
+		inputSchema?: object;
+		annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean };
+	}>;
+}
+
+type ResourcesRegistry = Map<string, ResourceRegistryEntry>;
+type RequestTargetCtor = new () => Record<string, unknown> & {
+	conditions?: unknown[];
+	operator?: string;
+	limit?: number;
+	offset?: number;
+	select?: string[];
+	id?: unknown;
+};
+
+// Test seams: avoid Harper's eager graph init in unit tests.
+let _resourcesOverride: ResourcesRegistry | undefined;
+let _requestTargetCtorOverride: RequestTargetCtor | undefined;
+export function _setResourcesForTest(r: ResourcesRegistry | undefined): void {
+	_resourcesOverride = r;
+}
+export function _setRequestTargetForTest(ctor: RequestTargetCtor | undefined): void {
+	_requestTargetCtorOverride = ctor;
+}
+
+function loadResources(): ResourcesRegistry | undefined {
+	if (_resourcesOverride) return _resourcesOverride;
+	try {
+		return require('../../../resources/Resources').resources as ResourcesRegistry;
+	} catch (err) {
+		harperLogger.trace(`MCP application tools: Resources registry unavailable (${(err as Error).message})`);
+		return undefined;
+	}
+}
+
+function loadRequestTarget(): RequestTargetCtor | undefined {
+	if (_requestTargetCtorOverride) return _requestTargetCtorOverride;
+	try {
+		return require('../../../resources/RequestTarget').RequestTarget as RequestTargetCtor;
+	} catch {
+		// Tests that don't use the real RequestTarget can supply a fake.
+		return undefined;
+	}
+}
+
+const DEFAULT_SEARCH_LIMIT = 100;
+const MAX_SEARCH_LIMIT = 1000;
+
+function searchLimitFor(_profile: 'application'): number {
+	const v = env.get(CONFIG_PARAMS.MCP_APPLICATION_MAXTOOLS); // existing knob; treat as a sane upper bound
+	if (typeof v === 'number' && v > 0) return Math.min(v, MAX_SEARCH_LIMIT);
+	return DEFAULT_SEARCH_LIMIT;
+}
+
+/**
+ * Sanitize a Resource path into a valid MCP tool-name segment.
+ * MCP tool names must be JSON-encodable identifiers; `/` and `.` are the
+ * common offenders. Anything else non-identifier-friendly gets dropped.
+ */
+function sanitizePath(path: string): string {
+	return path.replace(/[/.]/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
+}
+
+/**
+ * Resolve a unique tool-name suffix for this Resource. Default is the
+ * sanitized path; on collision we prefix with the database name; on second
+ * collision we add a short hash. The collision recovery is deterministic
+ * so two boots produce the same tool names.
+ */
+function uniqueSuffix(path: string, databaseName: string | undefined, claimed: Set<string>): string {
+	const base = sanitizePath(path);
+	if (!claimed.has(base)) return base;
+	if (databaseName) {
+		const dbPrefixed = `${sanitizePath(databaseName)}_${base}`;
+		if (!claimed.has(dbPrefixed)) return dbPrefixed;
+	}
+	// Final fallback: append a short stable hash of the full path.
+	const hash = createHash('sha256').update(path).digest('hex').slice(0, 6);
+	return `${base}_${hash}`;
+}
+
+function getUserTablePermissions(
+	user: AuthedUser,
+	databaseName: string | undefined,
+	tableName: string | undefined
+): {
+	read?: boolean;
+	insert?: boolean;
+	update?: boolean;
+	delete?: boolean;
+	describe?: boolean;
+	attribute_permissions?: AttributePermissionEntry[];
+} | null {
+	if (user?.role?.permission?.super_user === true) {
+		return { read: true, insert: true, update: true, delete: true, describe: true };
+	}
+	if (!databaseName || !tableName) return null;
+	const dbPerm = user?.role?.permission?.[databaseName];
+	if (!dbPerm || typeof dbPerm !== 'object' || Array.isArray(dbPerm)) return null;
+	const tablePerm = (dbPerm as { tables?: Record<string, unknown> }).tables?.[tableName];
+	if (!tablePerm || typeof tablePerm !== 'object') return null;
+	return tablePerm as ReturnType<typeof getUserTablePermissions>;
+}
+
+function buildContext(user: AuthedUser): { user: AuthedUser; authorize: true; checkPermission: object } {
+	return {
+		user,
+		authorize: true,
+		checkPermission: user?.role?.permission ?? {},
+	};
+}
+
+function makeTarget(): InstanceType<RequestTargetCtor> {
+	const Ctor = loadRequestTarget();
+	if (!Ctor) {
+		// Fallback target shape — exposes the writable fields Resource methods
+		// read. Real production runs always have RequestTarget available.
+		return {} as InstanceType<RequestTargetCtor>;
+	}
+	return new Ctor();
+}
+
+function wrapResult(data: unknown): ToolResult {
+	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;
+}
+
+function wrapError(toolName: string, err: unknown): ToolResult {
+	const e = err as { message?: string; http_resp_msg?: string };
+	const message = e?.http_resp_msg ?? e?.message ?? `${toolName} failed`;
+	harperLogger.trace(`MCP ${toolName} threw: ${(err as Error).stack ?? message}`);
+	return {
+		isError: true,
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify({ kind: 'harper_error', tool: toolName, message }),
+			},
+		],
+	};
+}
+
+function encodeCursor(offset: number): string {
+	return Buffer.from(JSON.stringify({ offset }), 'utf8').toString('base64url');
+}
+
+function decodeCursor(cursor: string | undefined): number {
+	if (!cursor) return 0;
+	try {
+		const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as { offset?: unknown };
+		const o = decoded?.offset;
+		if (typeof o === 'number' && o >= 0 && Number.isInteger(o)) return o;
+		return 0;
+	} catch {
+		return 0;
+	}
+}
+
+// ─── Verb-specific handler factories ───────────────────────────────────────
+
+function makeGetHandler(toolName: string, ResourceClass: ResourceClassLike) {
+	return async function (args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		const a = (args ?? {}) as Record<string, unknown>;
+		try {
+			const target = makeTarget();
+			target.id = a.id;
+			if (Array.isArray(a.get_attributes)) target.select = a.get_attributes as string[];
+			const data = await ResourceClass.get!(target, buildContext(context.user));
+			return wrapResult(data);
+		} catch (err) {
+			return wrapError(toolName, err);
+		}
+	};
+}
+
+function makeSearchHandler(toolName: string, ResourceClass: ResourceClassLike) {
+	return async function (args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		const a = (args ?? {}) as Record<string, unknown>;
+		try {
+			const target = makeTarget();
+			if (Array.isArray(a.conditions)) target.conditions = a.conditions as unknown[];
+			if (typeof a.operator === 'string') target.operator = a.operator;
+			if (Array.isArray(a.get_attributes)) target.select = a.get_attributes as string[];
+			const requestedLimit = typeof a.limit === 'number' && a.limit > 0 ? Math.floor(a.limit) : DEFAULT_SEARCH_LIMIT;
+			const limit = Math.min(requestedLimit, searchLimitFor('application'));
+			const offset = decodeCursor(typeof a.cursor === 'string' ? a.cursor : undefined);
+			// Fetch one extra to know if there's a next page without a second round-trip.
+			target.limit = limit + 1;
+			target.offset = offset;
+			const rawData = await ResourceClass.search!(target, buildContext(context.user));
+			const rows: unknown[] = await collectRows(rawData);
+			const hasMore = rows.length > limit;
+			const page = hasMore ? rows.slice(0, limit) : rows;
+			const result: { rows: unknown[]; nextCursor?: string } = { rows: page };
+			if (hasMore) result.nextCursor = encodeCursor(offset + limit);
+			return wrapResult(result);
+		} catch (err) {
+			return wrapError(toolName, err);
+		}
+	};
+}
+
+async function collectRows(rawData: unknown): Promise<unknown[]> {
+	if (rawData == null) return [];
+	if (Array.isArray(rawData)) return rawData;
+	// AsyncIterable
+	if (typeof (rawData as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function') {
+		const out: unknown[] = [];
+		for await (const row of rawData as AsyncIterable<unknown>) out.push(row);
+		return out;
+	}
+	// Sync iterable
+	if (typeof (rawData as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function') {
+		return Array.from(rawData as Iterable<unknown>);
+	}
+	// Single value
+	return [rawData];
+}
+
+function makeCreateHandler(toolName: string, ResourceClass: ResourceClassLike) {
+	return async function (args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		const a = (args ?? {}) as Record<string, unknown>;
+		try {
+			const target = makeTarget();
+			const data = await ResourceClass.post!(target, a, buildContext(context.user));
+			return wrapResult(data ?? { ok: true });
+		} catch (err) {
+			return wrapError(toolName, err);
+		}
+	};
+}
+
+function makeUpdateHandler(toolName: string, ResourceClass: ResourceClassLike, verb: 'put' | 'patch') {
+	return async function (args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		const a = (args ?? {}) as Record<string, unknown>;
+		const { id, ...rest } = a;
+		try {
+			const target = makeTarget();
+			target.id = id;
+			const fn = verb === 'put' ? ResourceClass.put : ResourceClass.patch;
+			const data = await fn!(target, rest, buildContext(context.user));
+			return wrapResult(data ?? { ok: true });
+		} catch (err) {
+			return wrapError(toolName, err);
+		}
+	};
+}
+
+function makeDeleteHandler(toolName: string, ResourceClass: ResourceClassLike) {
+	return async function (args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		const a = (args ?? {}) as Record<string, unknown>;
+		try {
+			const target = makeTarget();
+			target.id = a.id;
+			const data = await ResourceClass.delete!(target, buildContext(context.user));
+			return wrapResult(data ?? { ok: true });
+		} catch (err) {
+			return wrapError(toolName, err);
+		}
+	};
+}
+
+// ─── Verb-presence introspection ───────────────────────────────────────────
+
+interface VerbAvailability {
+	get: boolean;
+	search: boolean;
+	create: boolean;
+	updatePut: boolean;
+	updatePatch: boolean;
+	delete: boolean;
+}
+
+function detectVerbs(ResourceClass: ResourceClassLike): VerbAvailability {
+	const p = ResourceClass.prototype as Record<string, unknown> | undefined;
+	if (!p || typeof p !== 'object') {
+		return { get: false, search: false, create: false, updatePut: false, updatePatch: false, delete: false };
+	}
+	return {
+		get: typeof p.get === 'function',
+		search: typeof p.search === 'function',
+		// Resource.post defaults to no-op on the base class, but `update()` is the
+		// implicit override per the openApi pattern. Treat either as "has create".
+		create: typeof p.post === 'function' || typeof p.update === 'function',
+		updatePut: typeof p.put === 'function',
+		updatePatch: typeof p.patch === 'function',
+		delete: typeof p.delete === 'function',
+	};
+}
+
+// ─── Visibility predicate ──────────────────────────────────────────────────
+
+function makeVisibleTo(
+	databaseName: string | undefined,
+	tableName: string | undefined,
+	mode: 'read' | 'insert' | 'update' | 'delete'
+) {
+	return function visibleTo(user: AuthedUser): boolean {
+		// Super-user sees everything.
+		if (user?.role?.permission?.super_user === true) return true;
+		// Non-table Resources have no static permission gate — runtime allow*
+		// predicates enforce. Conservative default: don't list them for
+		// non-super users; they can still call via tools/call if they know
+		// the tool name (pass-through is documented behavior).
+		if (!databaseName || !tableName) return false;
+		const perm = getUserTablePermissions(user, databaseName, tableName);
+		if (!perm) return false;
+		if (mode === 'read') return perm.read === true || perm.describe === true;
+		return perm[mode] === true;
+	};
+}
+
+// ─── Registration ──────────────────────────────────────────────────────────
+
+interface ResourceContext {
+	path: string;
+	suffix: string;
+	ResourceClass: ResourceClassLike;
+	databaseName: string | undefined;
+	tableName: string | undefined;
+	attributes: HarperAttribute[];
+	verbs: VerbAvailability;
+}
+
+function shouldEnumerate(entry: ResourceRegistryEntry): boolean {
+	const types = entry.exportTypes;
+	if (!types) return true; // no per-protocol controls → all enabled
+	return types.mcp !== false;
+}
+
+/**
+ * Per-tool registration; reads attribute_permissions for the registering
+ * call's hypothetical "schema-time" user — but since we register at boot
+ * (one user-agnostic surface), schemas reflect the *table's* attribute
+ * list. The `attribute_permissions` filter on input schemas only applies
+ * for users with restricted permissions; at registration time we treat
+ * the schema as "all attributes". Runtime enforcement is the real gate.
+ */
+function registerVerbTools(ctx: ResourceContext): number {
+	let count = 0;
+	const { suffix, ResourceClass, attributes, verbs, tableName, databaseName } = ctx;
+	const baseDescription = (verb: string) =>
+		`${verb} on resource '${ctx.path}'${tableName ? ` (table ${tableName})` : ''}. ` +
+		`Runtime RBAC (allow${verb[0].toUpperCase() + verb.slice(1)}) enforces per-record access at call time.`;
+
+	if (verbs.get) {
+		const name = `get_${suffix}`;
+		addTool({
+			name,
+			description: baseDescription('get'),
+			inputSchema: deriveGetSchema(attributes, undefined),
+			profile: 'application',
+			annotations: { readOnlyHint: true },
+			visibleTo: makeVisibleTo(databaseName, tableName, 'read'),
+			handler: makeGetHandler(name, ResourceClass),
+		});
+		count++;
+	}
+	if (verbs.search) {
+		const name = `search_${suffix}`;
+		addTool({
+			name,
+			description: baseDescription('search'),
+			inputSchema: deriveSearchSchema(attributes, undefined),
+			profile: 'application',
+			annotations: { readOnlyHint: true },
+			visibleTo: makeVisibleTo(databaseName, tableName, 'read'),
+			handler: makeSearchHandler(name, ResourceClass),
+		});
+		count++;
+	}
+	if (verbs.create) {
+		const name = `create_${suffix}`;
+		addTool({
+			name,
+			description: baseDescription('create'),
+			inputSchema: deriveCreateSchema(attributes, undefined),
+			profile: 'application',
+			visibleTo: makeVisibleTo(databaseName, tableName, 'insert'),
+			handler: makeCreateHandler(name, ResourceClass),
+		});
+		count++;
+	}
+	if (verbs.updatePut) {
+		const name = `update_${suffix}`;
+		addTool({
+			name,
+			description: baseDescription('update'),
+			inputSchema: deriveUpdateSchema(attributes, undefined),
+			profile: 'application',
+			visibleTo: makeVisibleTo(databaseName, tableName, 'update'),
+			handler: makeUpdateHandler(name, ResourceClass, 'put'),
+		});
+		count++;
+	} else if (verbs.updatePatch) {
+		const name = `patch_${suffix}`;
+		addTool({
+			name,
+			description: baseDescription('patch'),
+			inputSchema: deriveUpdateSchema(attributes, undefined),
+			profile: 'application',
+			visibleTo: makeVisibleTo(databaseName, tableName, 'update'),
+			handler: makeUpdateHandler(name, ResourceClass, 'patch'),
+		});
+		count++;
+	}
+	if (verbs.delete) {
+		const name = `delete_${suffix}`;
+		addTool({
+			name,
+			description: baseDescription('delete'),
+			inputSchema: deriveDeleteSchema(attributes, undefined),
+			profile: 'application',
+			annotations: { destructiveHint: true },
+			visibleTo: makeVisibleTo(databaseName, tableName, 'delete'),
+			handler: makeDeleteHandler(name, ResourceClass),
+		});
+		count++;
+	}
+	return count;
+}
+
+/**
+ * #622 — Component-author opt-in. Walk `ResourceClass.mcpTools` and register
+ * each entry as a standalone MCP tool that invokes the named instance method.
+ *
+ * Each invocation constructs an instance with `(undefined, context)` and
+ * calls `instance[method](args)`. This mirrors what a custom user-defined
+ * Harper Resource expects when its methods are reached outside of a REST
+ * request — they receive arguments and rely on internal Harper calls to
+ * enforce any RBAC they need.
+ *
+ * No `visibleTo` filter beyond "is the user authenticated" — per the design,
+ * the Resource is responsible for its own ACLs. An LLM that calls a tool
+ * it shouldn't gets the Resource's natural error back as `isError: true`.
+ */
+function registerCustomMcpTools(ResourceClass: ResourceClassLike, path: string): number {
+	const tools = ResourceClass.mcpTools;
+	if (!Array.isArray(tools) || tools.length === 0) return 0;
+	let count = 0;
+	for (const def of tools) {
+		if (!def?.name || !def?.method) {
+			harperLogger.warn(
+				`MCP application profile: skipping invalid mcpTools entry on '${path}' (missing name or method): ${JSON.stringify(def)}`
+			);
+			continue;
+		}
+		const methodName = def.method;
+		if (typeof (ResourceClass.prototype as Record<string, unknown>)?.[methodName] !== 'function') {
+			harperLogger.warn(
+				`MCP application profile: '${path}' declares mcpTool '${def.name}' for method '${methodName}', but no such instance method exists on the prototype`
+			);
+			continue;
+		}
+		addTool({
+			name: def.name,
+			description:
+				def.description ??
+				`Custom MCP tool exposed by Resource '${path}' (method '${methodName}'). RBAC is enforced by the Resource itself.`,
+			inputSchema: def.inputSchema ?? { type: 'object', additionalProperties: true },
+			profile: 'application',
+			...(def.annotations ? { annotations: def.annotations } : {}),
+			// Per the design: custom-tool RBAC is delegated to the Resource. No
+			// visibleTo filter beyond "the user is authenticated" — the runtime
+			// rejects unauthorized calls naturally.
+			visibleTo: () => true,
+			handler: makeCustomMethodHandler(def.name, ResourceClass, methodName),
+		});
+		count++;
+	}
+	return count;
+}
+
+function makeCustomMethodHandler(toolName: string, ResourceClass: ResourceClassLike, methodName: string) {
+	return async function (args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
+		try {
+			// Instantiate per call. Component authors define custom methods on
+			// the instance side; the Harper context carries the user so any
+			// internal Resource calls the method makes pick up RBAC naturally.
+			const Ctor = ResourceClass as unknown as new (id: unknown, ctx: unknown) => Record<string, unknown>;
+			const instance = new Ctor(undefined, buildContext(context.user));
+			const method = instance[methodName] as ((a: unknown) => unknown) | undefined;
+			if (typeof method !== 'function') {
+				throw new Error(`method '${methodName}' is not a function on the constructed Resource`);
+			}
+			const data = await method.call(instance, args ?? {});
+			return wrapResult(data ?? { ok: true });
+		} catch (err) {
+			return wrapError(toolName, err);
+		}
+	};
+}
+
+/**
+ * Idempotent registration — walk the Resources Map, register verb tools
+ * for each entry that passes the exportTypes + verb-presence filters.
+ * Re-invocation overwrites prior tool entries (Map.set semantics).
+ */
+export function registerApplicationTools(): void {
+	const resources = loadResources();
+	if (!resources) {
+		harperLogger.warn('MCP application profile: Resources registry not available; no tools registered');
+		return;
+	}
+	const claimedSuffixes = new Set<string>();
+	let toolsRegistered = 0;
+	let resourcesConsidered = 0;
+	for (const [path, entry] of resources) {
+		resourcesConsidered++;
+		if (!shouldEnumerate(entry)) continue;
+		const ResourceClass = entry.Resource;
+		const verbs = detectVerbs(ResourceClass);
+		const hasVerbs = verbs.get || verbs.search || verbs.create || verbs.updatePut || verbs.updatePatch || verbs.delete;
+		const hasCustomTools = Array.isArray(ResourceClass?.mcpTools) && ResourceClass.mcpTools.length > 0;
+		if (!hasVerbs && !hasCustomTools) continue;
+		const databaseName = ResourceClass?.databaseName;
+		const tableName = ResourceClass?.tableName;
+		const suffix = uniqueSuffix(path, databaseName, claimedSuffixes);
+		claimedSuffixes.add(suffix);
+		const attributes = (ResourceClass?.attributes ?? []) as HarperAttribute[];
+		if (hasVerbs) {
+			toolsRegistered += registerVerbTools({
+				path,
+				suffix,
+				ResourceClass,
+				databaseName,
+				tableName,
+				attributes,
+				verbs,
+			});
+		}
+		toolsRegistered += registerCustomMcpTools(ResourceClass, path);
+	}
+	harperLogger.info(
+		`MCP application profile: considered ${resourcesConsidered} resource(s), registered ${toolsRegistered} tool(s)`
+	);
+}