From f5a6735f0c27bc3e8e08efec8352d02cbf254a87 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 09:37:01 +0100 Subject: [PATCH 1/4] perf(ai): load only the called tool's module on a cold MCP tools/call A cold tools/call imported and defined the whole tool registry (every tool and its schemas) before running one tool. The registry now splits into registry-core (define, decode, aliases, errors, output encoding, render, next-call checks) and the full catalog that chat, permissions, evals and tests read. The dispatcher looks tools up through tool-modules.generated.ts: each tool name and retired alias maps to a lazy import of its own module, defined through the same define on first use and kept per executor. mcp:tools writes the map next to the descriptors; tool-lookup.test.ts fails when it drifts. Unknown names, surface audiences and audit titles answer as before. --- .oxfmtrc.jsonc | 1 + .../scripts/generate-mcp-tool-descriptors.ts | 79 +- apps/ai/src/mcp/dispatcher.ts | 18 +- apps/ai/src/mcp/tool-catalog.ts | 6 +- apps/ai/src/mcp/tool-descriptors-render.ts | 32 + apps/ai/src/mcp/tool-modules.generated.ts | 151 ++++ apps/ai/src/mcp/tools/registry-core.ts | 575 +++++++++++++ apps/ai/src/mcp/tools/registry.ts | 814 ++++-------------- apps/ai/src/mcp/tools/tool-lookup.test.ts | 91 ++ apps/ai/src/mcp/tools/tool-lookup.ts | 47 + 10 files changed, 1134 insertions(+), 680 deletions(-) create mode 100644 apps/ai/src/mcp/tool-modules.generated.ts create mode 100644 apps/ai/src/mcp/tools/registry-core.ts create mode 100644 apps/ai/src/mcp/tools/tool-lookup.test.ts create mode 100644 apps/ai/src/mcp/tools/tool-lookup.ts diff --git a/.oxfmtrc.jsonc b/.oxfmtrc.jsonc index 85cc6a3914..29e2117b04 100644 --- a/.oxfmtrc.jsonc +++ b/.oxfmtrc.jsonc @@ -27,6 +27,7 @@ "packages/security-audit/src/skill-files.generated.ts", // Generated by `bun run --cwd apps/ai mcp:tools`, whose `--check` compares it byte for byte. "apps/ai/src/mcp/tool-descriptors.generated.ts", + "apps/ai/src/mcp/tool-modules.generated.ts", "packages/eventing-core/schemas", "apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json", "lib/oxlint-config/plugins/anti-slop/**", diff --git a/apps/ai/scripts/generate-mcp-tool-descriptors.ts b/apps/ai/scripts/generate-mcp-tool-descriptors.ts index b8ab8711af..bda28bd218 100644 --- a/apps/ai/scripts/generate-mcp-tool-descriptors.ts +++ b/apps/ai/scripts/generate-mcp-tool-descriptors.ts @@ -1,28 +1,89 @@ #!/usr/bin/env bun /** * Renders `src/mcp/tool-descriptors.generated.ts`, the public `tools/list` the MCP server - * registers without importing the registry. `tool-descriptors.test.ts` fails when it drifts. + * registers without importing the registry, and `src/mcp/tool-modules.generated.ts`, the module + * each tool name loads on its first call. `tool-descriptors.test.ts` and `tool-lookup.test.ts` + * fail when they drift. * * bun run --cwd apps/ai mcp:tools # write * bun run --cwd apps/ai mcp:tools --check # verify */ -import { existsSync, readFileSync, writeFileSync } from "node:fs" +import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs" import { resolve } from "node:path" import { Effect } from "effect" -import { listMcpTools, renderToolDescriptorsModule } from "@/mcp/tool-descriptors-render" +import { + listMcpTools, + renderToolDescriptorsModule, + renderToolModulesModule, + type ToolModuleSource, +} from "@/mcp/tool-descriptors-render" +import { mapleToolCatalog } from "@/mcp/tools/registry" +import { TOOL_NAME_ALIASES } from "@/mcp/tools/tool-name-aliases" +import type { McpToolRegistrar } from "@/mcp/tools/types" -const OUTPUT = resolve(import.meta.dirname, "../src/mcp/tool-descriptors.generated.ts") +const DESCRIPTORS = resolve(import.meta.dirname, "../src/mcp/tool-descriptors.generated.ts") +const MODULES = resolve(import.meta.dirname, "../src/mcp/tool-modules.generated.ts") +const TOOLS_DIR = resolve(import.meta.dirname, "../src/mcp/tools") -const rendered = renderToolDescriptorsModule(await Effect.runPromise(listMcpTools)) -const existing = existsSync(OUTPUT) ? readFileSync(OUTPUT, "utf8") : "" +/** Which module and registration function defines each tool, found by running every registrar. */ +const findToolModules = async (): Promise< + ReadonlyMap> +> => { + const found = new Map>() + const files = readdirSync(TOOLS_DIR).filter((file) => file.endsWith(".ts") && !file.endsWith(".test.ts")) + for (const file of files.sort()) { + const module = file.slice(0, -".ts".length) + const exports: Record = await import(resolve(TOOLS_DIR, file)) + for (const [register, value] of Object.entries(exports)) { + if (!/^register\w+Tools?$/.test(register) || typeof value !== "function") continue + const registrar: McpToolRegistrar = { + define: (spec) => { + const existing = found.get(spec.name) + if (existing !== undefined) { + throw new Error(`${spec.name} is registered by both ${existing.module} and ${module}`) + } + found.set(spec.name, { module, register }) + }, + } + value(registrar) + } + } + return found +} + +const modules = await findToolModules() +const sourceOf = (name: string, tool: string): ToolModuleSource => { + const entry = mapleToolCatalog.find((candidate) => candidate.name === tool) + const location = modules.get(tool) + if (entry === undefined || location === undefined) { + throw new Error(`No module registers ${tool}`) + } + return { name, tool, title: entry.title, audience: entry.audience, ...location } +} + +const outputs = [ + { path: DESCRIPTORS, rendered: renderToolDescriptorsModule(await Effect.runPromise(listMcpTools)) }, + { + path: MODULES, + rendered: renderToolModulesModule([ + ...mapleToolCatalog.map((entry) => sourceOf(entry.name, entry.name)), + ...Object.entries(TOOL_NAME_ALIASES).map(([alias, tool]) => sourceOf(alias, tool)), + ]), + }, +] if (process.argv.includes("--check")) { - if (existing !== rendered) { + const stale = outputs.filter( + ({ path, rendered }) => (existsSync(path) ? readFileSync(path, "utf8") : "") !== rendered, + ) + if (stale.length > 0) { console.error("MCP tool descriptors are out of date. Run `bun run --cwd apps/ai mcp:tools`.") process.exit(1) } console.log("MCP tool descriptors are up to date.") } else { - writeFileSync(OUTPUT, rendered) - console.log(`Wrote ${OUTPUT}.`) + for (const { path, rendered } of outputs) { + writeFileSync(path, rendered) + console.log(`Wrote ${path}.`) + } } diff --git a/apps/ai/src/mcp/dispatcher.ts b/apps/ai/src/mcp/dispatcher.ts index 5cf2fb1640..14f01e768d 100644 --- a/apps/ai/src/mcp/dispatcher.ts +++ b/apps/ai/src/mcp/dispatcher.ts @@ -15,7 +15,8 @@ import { FEEDBACK_TOOL, type McpToolResult } from "./tools/types" import { McpRuntimeServicesLive, type McpToolRuntimeRequirements } from "./tools/runtime-services" import { CurrentMcpRequestTenant, CurrentMcpTenant } from "./tenant" import { recordExpectedMcpFailure, spanFailureMessage } from "./expected-failures" -import { loadRegistry } from "./tool-catalog" +import { executeRegisteredTool, type McpToolLookup } from "./tools/registry-core" +import { makeModuleToolLookup, mcpToolTitle } from "./tools/tool-lookup" import { recordMcpToolAudit } from "@maple/backend/services/audit/audit-access" import type { TenantContext } from "@maple/domain/http" import { productEventSpanAttributes } from "@maple/domain/tinybird/product-event-attributes" @@ -42,6 +43,7 @@ export const withFeedbackHint = (text: string, name: string, surface: McpToolSur : text const dispatchInSpan = Effect.fn("McpToolDispatcher.call")(function* ( + tools: McpToolLookup, name: string, input: unknown, surface: McpToolSurface, @@ -50,8 +52,7 @@ const dispatchInSpan = Effect.fn("McpToolDispatcher.call")(function* ( // solely because each handler happens to carry its own `McpTool.` span // — every usage query had to reconstruct it with `substring(SpanName, 9)`. yield* Effect.annotateCurrentSpan("maple.mcp.tool", name) - const registry = yield* loadRegistry - return yield* registry.executeRegisteredMcpToolUnscoped(name, input, surface).pipe( + return yield* executeRegisteredTool(tools, name, input, surface).pipe( Effect.catchTag("@maple/mcp/errors/McpDecodeError", (error) => recordExpectedMcpFailure(error, "Invalid parameters").pipe( Effect.as(failureResult(error.message, "invalid_parameters")), @@ -143,8 +144,8 @@ const dispatchInSpan = Effect.fn("McpToolDispatcher.call")(function* ( }) /** Raw dispatcher. Executable handlers stay private so callers cannot omit the request tenant. */ -const callMcpToolUnscoped = (name: string, input: unknown, surface: McpToolSurface) => - dispatchInSpan(name, input, surface).pipe( +const callMcpToolUnscoped = (tools: McpToolLookup, name: string, input: unknown, surface: McpToolSurface) => + dispatchInSpan(tools, name, input, surface).pipe( Effect.catchTag("@maple/mcp/errors/McpQueryError", (error) => Effect.logError("MCP tool execution failed").pipe( Effect.annotateLogs({ @@ -214,6 +215,8 @@ export class McpToolExecutor extends Context.Service tool -> chat/maple-toolkit -> dispatcher cycle, so no module can observe a half-built catalog. + * It is the largest chunk in the Worker; `tools/call` never needs all of it (`tools/tool-lookup.ts` + * loads one tool). The dynamic import also breaks the registry -> tool -> chat/maple-toolkit -> + * dispatcher cycle, so no module can observe a half-built catalog. */ export const loadRegistry = Effect.promise(() => import("./tools/registry")) diff --git a/apps/ai/src/mcp/tool-descriptors-render.ts b/apps/ai/src/mcp/tool-descriptors-render.ts index 3577a34dfa..7b33be1ba5 100644 --- a/apps/ai/src/mcp/tool-descriptors-render.ts +++ b/apps/ai/src/mcp/tool-descriptors-render.ts @@ -58,3 +58,35 @@ const toolDescriptors = ({ /** The public transport's `tools/list`, built from the registry; the generator writes it out. */ export const listMcpTools = Effect.map(loadRegistry, toolDescriptors) + +/** Where one callable name is defined, as the generator found it. */ +export interface ToolModuleSource { + readonly name: string + readonly tool: string + readonly title: string + readonly audience: string + /** The module under `src/mcp/tools`, without extension (`run-sql`). */ + readonly module: string + /** Its registration function (`registerRunSqlTool`). */ + readonly register: string +} + +/** The source of `tool-modules.generated.ts`: one name per line, each importing its own module. */ +export const renderToolModulesModule = (sources: ReadonlyArray): string => + Arr.join( + [ + "// Generated by `bun run --cwd apps/ai mcp:tools` from the tool registry. Do not edit.", + 'import type { McpToolModule } from "./tools/registry-core"', + "", + "/** Every tool name and retired alias, with the module that defines it, imported on first call. */", + "export const MCP_TOOL_MODULES: ReadonlyArray = [", + ...Arr.map( + sources, + (source) => + `\t{ name: ${asciiJson(source.name)}, tool: ${asciiJson(source.tool)}, title: ${asciiJson(source.title)}, audience: ${asciiJson(source.audience)}, load: () => import(${asciiJson(`./tools/${source.module}`)}).then((module) => module.${source.register}) },`, + ), + "]", + "", + ], + "\n", + ) diff --git a/apps/ai/src/mcp/tool-modules.generated.ts b/apps/ai/src/mcp/tool-modules.generated.ts new file mode 100644 index 0000000000..c44b2fae7b --- /dev/null +++ b/apps/ai/src/mcp/tool-modules.generated.ts @@ -0,0 +1,151 @@ +// Generated by `bun run --cwd apps/ai mcp:tools` from the tool registry. Do not edit. +import type { McpToolModule } from "./tools/registry-core" + +/** Every tool name and retired alias, with the module that defines it, imported on first call. */ +export const MCP_TOOL_MODULES: ReadonlyArray = [ + { name: "find_errors", tool: "find_errors", title: "Find Errors", audience: "public", load: () => import("./tools/find-errors").then((module) => module.registerFindErrorsTool) }, + { name: "inspect_trace", tool: "inspect_trace", title: "Inspect Trace", audience: "public", load: () => import("./tools/inspect-trace").then((module) => module.registerInspectTraceTool) }, + { name: "inspect_span", tool: "inspect_span", title: "Inspect Span", audience: "public", load: () => import("./tools/inspect-span").then((module) => module.registerInspectSpanTool) }, + { name: "search_logs", tool: "search_logs", title: "Search Logs", audience: "public", load: () => import("./tools/search-logs").then((module) => module.registerSearchLogsTool) }, + { name: "mine_log_patterns", tool: "mine_log_patterns", title: "Mine Log Patterns", audience: "public", load: () => import("./tools/mine-log-patterns").then((module) => module.registerMineLogPatternsTool) }, + { name: "compare_log_patterns", tool: "compare_log_patterns", title: "Compare Log Patterns", audience: "public", load: () => import("./tools/compare-log-patterns").then((module) => module.registerCompareLogPatternsTool) }, + { name: "search_traces", tool: "search_traces", title: "Search Traces", audience: "public", load: () => import("./tools/search-traces").then((module) => module.registerSearchTracesTool) }, + { name: "search_sessions", tool: "search_sessions", title: "Search Sessions", audience: "public", load: () => import("./tools/search-sessions").then((module) => module.registerSearchSessionsTool) }, + { name: "query_funnel", tool: "query_funnel", title: "Query Funnel", audience: "public", load: () => import("./tools/query-funnel").then((module) => module.registerQueryFunnelTool) }, + { name: "list_product_events", tool: "list_product_events", title: "List Product Events", audience: "public", load: () => import("./tools/list-product-events").then((module) => module.registerListProductEventsTool) }, + { name: "get_session_transcript", tool: "get_session_transcript", title: "Get Session Transcript", audience: "public", load: () => import("./tools/get-session-transcript").then((module) => module.registerGetSessionTranscriptTool) }, + { name: "get_session_traces", tool: "get_session_traces", title: "Get Session Traces", audience: "public", load: () => import("./tools/get-session-traces").then((module) => module.registerGetSessionTracesTool) }, + { name: "list_users", tool: "list_users", title: "List Users", audience: "public", load: () => import("./tools/list-users").then((module) => module.registerListUsersTool) }, + { name: "inspect_user", tool: "inspect_user", title: "Inspect User", audience: "public", load: () => import("./tools/inspect-user").then((module) => module.registerInspectUserTool) }, + { name: "list_agent_sessions", tool: "list_agent_sessions", title: "List Agent Sessions", audience: "public", load: () => import("./tools/list-agent-sessions").then((module) => module.registerListAgentSessionsTool) }, + { name: "get_agent_session", tool: "get_agent_session", title: "Get Agent Session", audience: "public", load: () => import("./tools/get-agent-session").then((module) => module.registerGetAgentSessionTool) }, + { name: "get_agent_session_transcript", tool: "get_agent_session_transcript", title: "Get Agent Session Transcript", audience: "public", load: () => import("./tools/get-agent-session-transcript").then((module) => module.registerGetAgentSessionTranscriptTool) }, + { name: "get_agent_tools_overview", tool: "get_agent_tools_overview", title: "Agent Tools Overview", audience: "public", load: () => import("./tools/get-agent-tools-overview").then((module) => module.registerGetAgentToolsOverviewTool) }, + { name: "get_agent_tool_error", tool: "get_agent_tool_error", title: "Get Agent Tool Error", audience: "public", load: () => import("./tools/get-agent-tool-error").then((module) => module.registerGetAgentToolErrorTool) }, + { name: "diagnose_service", tool: "diagnose_service", title: "Diagnose Service", audience: "public", load: () => import("./tools/diagnose-service").then((module) => module.registerDiagnoseServiceTool) }, + { name: "find_slow_traces", tool: "find_slow_traces", title: "Find Slow Traces", audience: "public", load: () => import("./tools/find-slow-traces").then((module) => module.registerFindSlowTracesTool) }, + { name: "error_detail", tool: "error_detail", title: "Error Detail", audience: "public", load: () => import("./tools/error-detail").then((module) => module.registerErrorDetailTool) }, + { name: "list_metrics", tool: "list_metrics", title: "List Metrics", audience: "public", load: () => import("./tools/list-metrics").then((module) => module.registerListMetricsTool) }, + { name: "query_data", tool: "query_data", title: "Query Data", audience: "public", load: () => import("./tools/query-data").then((module) => module.registerQueryDataTool) }, + { name: "run_sql", tool: "run_sql", title: "Run SQL", audience: "public", load: () => import("./tools/run-sql").then((module) => module.registerRunSqlTool) }, + { name: "service_map", tool: "service_map", title: "Service Map", audience: "public", load: () => import("./tools/service-map").then((module) => module.registerServiceMapTool) }, + { name: "list_alert_rules", tool: "list_alert_rules", title: "List Alert Rules", audience: "public", load: () => import("./tools/list-alert-rules").then((module) => module.registerListAlertRulesTool) }, + { name: "list_alert_destinations", tool: "list_alert_destinations", title: "List Alert Destinations", audience: "public", load: () => import("./tools/list-alert-destinations").then((module) => module.registerListAlertDestinationsTool) }, + { name: "get_alert_rule", tool: "get_alert_rule", title: "Get Alert Rule", audience: "public", load: () => import("./tools/get-alert-rule").then((module) => module.registerGetAlertRuleTool) }, + { name: "list_alert_incidents", tool: "list_alert_incidents", title: "List Alert Incidents", audience: "public", load: () => import("./tools/list-alert-incidents").then((module) => module.registerListAlertIncidentsTool) }, + { name: "list_alert_checks", tool: "list_alert_checks", title: "List Alert Checks", audience: "public", load: () => import("./tools/list-alert-checks").then((module) => module.registerListAlertChecksTool) }, + { name: "preview_alert_rule", tool: "preview_alert_rule", title: "Preview Alert Rule", audience: "public", load: () => import("./tools/preview-alert-rule").then((module) => module.registerPreviewAlertRuleTool) }, + { name: "get_incident_timeline", tool: "get_incident_timeline", title: "Incident Timeline", audience: "public", load: () => import("./tools/get-incident-timeline").then((module) => module.registerGetIncidentTimelineTool) }, + { name: "create_alert_rule", tool: "create_alert_rule", title: "Create Alert Rule", audience: "public", load: () => import("./tools/create-alert-rule").then((module) => module.registerCreateAlertRuleTool) }, + { name: "update_alert_rule", tool: "update_alert_rule", title: "Update Alert Rule", audience: "public", load: () => import("./tools/update-alert-rule").then((module) => module.registerUpdateAlertRuleTool) }, + { name: "delete_alert_rule", tool: "delete_alert_rule", title: "Delete Alert Rule", audience: "public", load: () => import("./tools/delete-alert-rule").then((module) => module.registerDeleteAlertRuleTool) }, + { name: "list_maintenance_windows", tool: "list_maintenance_windows", title: "List Maintenance Windows", audience: "public", load: () => import("./tools/list-maintenance-windows").then((module) => module.registerListMaintenanceWindowsTool) }, + { name: "create_maintenance_window", tool: "create_maintenance_window", title: "Create Maintenance Window", audience: "public", load: () => import("./tools/create-maintenance-window").then((module) => module.registerCreateMaintenanceWindowTool) }, + { name: "delete_maintenance_window", tool: "delete_maintenance_window", title: "Delete Maintenance Window", audience: "public", load: () => import("./tools/delete-maintenance-window").then((module) => module.registerDeleteMaintenanceWindowTool) }, + { name: "list_alert_silences", tool: "list_alert_silences", title: "List Alert Silences", audience: "public", load: () => import("./tools/list-alert-silences").then((module) => module.registerListAlertSilencesTool) }, + { name: "create_alert_silence", tool: "create_alert_silence", title: "Create Alert Silence", audience: "public", load: () => import("./tools/create-alert-silence").then((module) => module.registerCreateAlertSilenceTool) }, + { name: "end_alert_silence", tool: "end_alert_silence", title: "End Alert Silence", audience: "public", load: () => import("./tools/end-alert-silence").then((module) => module.registerEndAlertSilenceTool) }, + { name: "acknowledge_alert_incident", tool: "acknowledge_alert_incident", title: "Acknowledge Alert Incident", audience: "public", load: () => import("./tools/acknowledge-alert-incident").then((module) => module.registerAcknowledgeAlertIncidentTool) }, + { name: "list_escalation_chains", tool: "list_escalation_chains", title: "List Escalation Chains", audience: "public", load: () => import("./tools/list-escalation-chains").then((module) => module.registerListEscalationChainsTool) }, + { name: "create_escalation_chain", tool: "create_escalation_chain", title: "Create Escalation Chain", audience: "public", load: () => import("./tools/create-escalation-chain").then((module) => module.registerCreateEscalationChainTool) }, + { name: "update_escalation_chain", tool: "update_escalation_chain", title: "Update Escalation Chain", audience: "public", load: () => import("./tools/update-escalation-chain").then((module) => module.registerUpdateEscalationChainTool) }, + { name: "delete_escalation_chain", tool: "delete_escalation_chain", title: "Delete Escalation Chain", audience: "public", load: () => import("./tools/delete-escalation-chain").then((module) => module.registerDeleteEscalationChainTool) }, + { name: "list_oncall_schedules", tool: "list_oncall_schedules", title: "List On-Call Schedules", audience: "public", load: () => import("./tools/list-oncall-schedules").then((module) => module.registerListOnCallSchedulesTool) }, + { name: "who_is_on_call", tool: "who_is_on_call", title: "Who Is On Call", audience: "public", load: () => import("./tools/who-is-on-call").then((module) => module.registerWhoIsOnCallTool) }, + { name: "create_oncall_schedule", tool: "create_oncall_schedule", title: "Create On-Call Schedule", audience: "public", load: () => import("./tools/create-oncall-schedule").then((module) => module.registerCreateOnCallScheduleTool) }, + { name: "update_oncall_schedule", tool: "update_oncall_schedule", title: "Update On-Call Schedule", audience: "public", load: () => import("./tools/update-oncall-schedule").then((module) => module.registerUpdateOnCallScheduleTool) }, + { name: "delete_oncall_schedule", tool: "delete_oncall_schedule", title: "Delete On-Call Schedule", audience: "public", load: () => import("./tools/delete-oncall-schedule").then((module) => module.registerDeleteOnCallScheduleTool) }, + { name: "create_oncall_override", tool: "create_oncall_override", title: "Create On-Call Override", audience: "public", load: () => import("./tools/create-oncall-override").then((module) => module.registerCreateOnCallOverrideTool) }, + { name: "delete_oncall_override", tool: "delete_oncall_override", title: "Delete On-Call Override", audience: "public", load: () => import("./tools/delete-oncall-override").then((module) => module.registerDeleteOnCallOverrideTool) }, + { name: "describe_dashboard_schema", tool: "describe_dashboard_schema", title: "Describe Dashboard Schema", audience: "public", load: () => import("./tools/describe-dashboard-schema").then((module) => module.registerDescribeDashboardSchemaTool) }, + { name: "list_dashboards", tool: "list_dashboards", title: "List Dashboards", audience: "public", load: () => import("./tools/list-dashboards").then((module) => module.registerListDashboardsTool) }, + { name: "get_dashboard", tool: "get_dashboard", title: "Get Dashboard", audience: "public", load: () => import("./tools/get-dashboard").then((module) => module.registerGetDashboardTool) }, + { name: "create_dashboard", tool: "create_dashboard", title: "Create Dashboard", audience: "public", load: () => import("./tools/create-dashboard").then((module) => module.registerCreateDashboardTool) }, + { name: "update_dashboard", tool: "update_dashboard", title: "Update Dashboard", audience: "public", load: () => import("./tools/update-dashboard").then((module) => module.registerUpdateDashboardTool) }, + { name: "add_dashboard_widget", tool: "add_dashboard_widget", title: "Add Dashboard Widget", audience: "public", load: () => import("./tools/add-dashboard-widget").then((module) => module.registerAddDashboardWidgetTool) }, + { name: "describe_warehouse_tables", tool: "describe_warehouse_tables", title: "Describe Warehouse Tables", audience: "public", load: () => import("./tools/describe-warehouse-tables").then((module) => module.registerDescribeWarehouseTablesTool) }, + { name: "update_dashboard_widget", tool: "update_dashboard_widget", title: "Update Dashboard Widget", audience: "public", load: () => import("./tools/update-dashboard-widget").then((module) => module.registerUpdateDashboardWidgetTool) }, + { name: "remove_dashboard_widget", tool: "remove_dashboard_widget", title: "Remove Dashboard Widget", audience: "public", load: () => import("./tools/remove-dashboard-widget").then((module) => module.registerRemoveDashboardWidgetTool) }, + { name: "replace_dashboard_widgets", tool: "replace_dashboard_widgets", title: "Replace Dashboard Widgets", audience: "public", load: () => import("./tools/replace-dashboard-widgets").then((module) => module.registerReplaceDashboardWidgetsTool) }, + { name: "reorder_dashboard_widgets", tool: "reorder_dashboard_widgets", title: "Reorder Dashboard Widgets", audience: "public", load: () => import("./tools/reorder-dashboard-widgets").then((module) => module.registerReorderDashboardWidgetsTool) }, + { name: "inspect_chart_data", tool: "inspect_chart_data", title: "Inspect Chart Data", audience: "public", load: () => import("./tools/inspect-chart-data").then((module) => module.registerInspectChartDataTool) }, + { name: "compare_periods", tool: "compare_periods", title: "Compare Periods", audience: "public", load: () => import("./tools/compare-periods").then((module) => module.registerComparePeriodsTool) }, + { name: "compare_operations", tool: "compare_operations", title: "Compare Operations", audience: "public", load: () => import("./tools/compare-operations").then((module) => module.registerCompareOperationsTool) }, + { name: "explore_attributes", tool: "explore_attributes", title: "Explore Attributes", audience: "public", load: () => import("./tools/explore-attributes").then((module) => module.registerExploreAttributesTool) }, + { name: "list_services", tool: "list_services", title: "List Services", audience: "public", load: () => import("./tools/list-services").then((module) => module.registerListServicesTool) }, + { name: "get_service_top_operations", tool: "get_service_top_operations", title: "Service Top Operations", audience: "public", load: () => import("./tools/get-service-top-operations").then((module) => module.registerGetServiceTopOperationsTool) }, + { name: "service_deployments", tool: "service_deployments", title: "Service Deployments", audience: "public", load: () => import("./tools/service-deployments").then((module) => module.registerServiceDeploymentsTool) }, + { name: "route_usage", tool: "route_usage", title: "Route Usage", audience: "public", load: () => import("./tools/route-usage").then((module) => module.registerRouteUsageTool) }, + { name: "ingest_freshness", tool: "ingest_freshness", title: "Ingest Freshness", audience: "public", load: () => import("./tools/ingest-freshness").then((module) => module.registerIngestFreshnessTool) }, + { name: "db_query_volume", tool: "db_query_volume", title: "DB Query Volume", audience: "public", load: () => import("./tools/db-query-volume").then((module) => module.registerDbQueryVolumeTool) }, + { name: "list_infra", tool: "list_infra", title: "List Infrastructure", audience: "public", load: () => import("./tools/list-infra").then((module) => module.registerListInfraTool) }, + { name: "inspect_infra", tool: "inspect_infra", title: "Inspect Infrastructure", audience: "public", load: () => import("./tools/inspect-infra").then((module) => module.registerInspectInfraTool) }, + { name: "ingest_usage", tool: "ingest_usage", title: "Ingest Usage", audience: "public", load: () => import("./tools/ingest-usage").then((module) => module.registerIngestUsageTool) }, + { name: "get_instrumentation_recommendations", tool: "get_instrumentation_recommendations", title: "Instrumentation Recommendations", audience: "public", load: () => import("./tools/get-instrumentation-recommendations").then((module) => module.registerGetInstrumentationRecommendationsTool) }, + { name: "audit_setup", tool: "audit_setup", title: "Audit Setup", audience: "public", load: () => import("./tools/audit-setup").then((module) => module.registerAuditSetupTool) }, + { name: "list_integrations", tool: "list_integrations", title: "List Integrations", audience: "public", load: () => import("./tools/list-integrations").then((module) => module.registerListIntegrationsTool) }, + { name: "search_console_queries", tool: "search_console_queries", title: "Search Console Queries", audience: "public", load: () => import("./tools/search-console-queries").then((module) => module.registerSearchConsoleQueriesTool) }, + { name: "search_console_pages", tool: "search_console_pages", title: "Search Console Pages", audience: "public", load: () => import("./tools/search-console-pages").then((module) => module.registerSearchConsolePagesTool) }, + { name: "list_security_findings", tool: "list_security_findings", title: "List Security Findings", audience: "public", load: () => import("./tools/list-security-findings").then((module) => module.registerListSecurityFindingsTool) }, + { name: "inspect_security_finding", tool: "inspect_security_finding", title: "Inspect Security Finding", audience: "public", load: () => import("./tools/inspect-security-finding").then((module) => module.registerInspectSecurityFindingTool) }, + { name: "list_security_audit_runs", tool: "list_security_audit_runs", title: "List Security Audit Runs", audience: "public", load: () => import("./tools/list-security-audit-runs").then((module) => module.registerListSecurityAuditRunsTool) }, + { name: "inspect_security_audit_run", tool: "inspect_security_audit_run", title: "Inspect Security Audit Run", audience: "public", load: () => import("./tools/inspect-security-audit-run").then((module) => module.registerInspectSecurityAuditRunTool) }, + { name: "list_ingest_sources", tool: "list_ingest_sources", title: "List Ingest Sources", audience: "public", load: () => import("./tools/list-sources").then((module) => module.registerListSourcesTool) }, + { name: "list_data_sources", tool: "list_data_sources", title: "List Data Sources", audience: "public", load: () => import("./tools/list-data-sources").then((module) => module.registerListDataSourcesTool) }, + { name: "search_data_sources", tool: "search_data_sources", title: "Search Data Sources", audience: "public", load: () => import("./tools/search-data-sources").then((module) => module.registerSearchDataSourcesTool) }, + { name: "describe_data_source", tool: "describe_data_source", title: "Describe Data Source", audience: "public", load: () => import("./tools/describe-data-source").then((module) => module.registerDescribeDataSourceTool) }, + { name: "query_data_source", tool: "query_data_source", title: "Query Data Source", audience: "public", load: () => import("./tools/query-data-source").then((module) => module.registerQueryDataSourceTool) }, + { name: "ci_runs", tool: "ci_runs", title: "CI Runs", audience: "agent", load: () => import("./tools/ci-runs").then((module) => module.registerCiRunsTool) }, + { name: "compare_commits", tool: "compare_commits", title: "Compare Commits", audience: "agent", load: () => import("./tools/compare-commits").then((module) => module.registerCompareCommitsTool) }, + { name: "sync_vercel", tool: "sync_vercel", title: "Sync Vercel", audience: "public", load: () => import("./tools/integration-writes").then((module) => module.registerIntegrationWriteTools) }, + { name: "sync_railway", tool: "sync_railway", title: "Sync Railway", audience: "public", load: () => import("./tools/integration-writes").then((module) => module.registerIntegrationWriteTools) }, + { name: "create_scrape_target", tool: "create_scrape_target", title: "Create Scrape Target", audience: "public", load: () => import("./tools/integration-writes").then((module) => module.registerIntegrationWriteTools) }, + { name: "update_scrape_target", tool: "update_scrape_target", title: "Update Scrape Target", audience: "public", load: () => import("./tools/integration-writes").then((module) => module.registerIntegrationWriteTools) }, + { name: "delete_scrape_target", tool: "delete_scrape_target", title: "Delete Scrape Target", audience: "public", load: () => import("./tools/integration-writes").then((module) => module.registerIntegrationWriteTools) }, + { name: "list_uptime_monitors", tool: "list_uptime_monitors", title: "List Uptime Monitors", audience: "public", load: () => import("./tools/uptime-monitors").then((module) => module.registerUptimeMonitorTools) }, + { name: "create_uptime_monitor", tool: "create_uptime_monitor", title: "Create Uptime Monitor", audience: "public", load: () => import("./tools/uptime-monitors").then((module) => module.registerUptimeMonitorTools) }, + { name: "update_uptime_monitor", tool: "update_uptime_monitor", title: "Update Uptime Monitor", audience: "public", load: () => import("./tools/uptime-monitors").then((module) => module.registerUptimeMonitorTools) }, + { name: "delete_uptime_monitor", tool: "delete_uptime_monitor", title: "Delete Uptime Monitor", audience: "public", load: () => import("./tools/uptime-monitors").then((module) => module.registerUptimeMonitorTools) }, + { name: "list_slos", tool: "list_slos", title: "List SLOs", audience: "public", load: () => import("./tools/slos").then((module) => module.registerSloTools) }, + { name: "inspect_slo", tool: "inspect_slo", title: "Inspect SLO", audience: "public", load: () => import("./tools/slos").then((module) => module.registerSloTools) }, + { name: "create_slo", tool: "create_slo", title: "Create SLO", audience: "public", load: () => import("./tools/slos").then((module) => module.registerSloTools) }, + { name: "update_slo", tool: "update_slo", title: "Update SLO", audience: "public", load: () => import("./tools/slos").then((module) => module.registerSloTools) }, + { name: "delete_slo", tool: "delete_slo", title: "Delete SLO", audience: "public", load: () => import("./tools/slos").then((module) => module.registerSloTools) }, + { name: "list_ingest_rules", tool: "list_ingest_rules", title: "List Ingest Rules", audience: "public", load: () => import("./tools/ingest-rules").then((module) => module.registerIngestRuleTools) }, + { name: "preview_ingest_rule", tool: "preview_ingest_rule", title: "Preview Ingest Rule", audience: "public", load: () => import("./tools/ingest-rules").then((module) => module.registerIngestRuleTools) }, + { name: "create_ingest_rule", tool: "create_ingest_rule", title: "Create Ingest Rule", audience: "public", load: () => import("./tools/ingest-rules").then((module) => module.registerIngestRuleTools) }, + { name: "update_ingest_rule", tool: "update_ingest_rule", title: "Update Ingest Rule", audience: "public", load: () => import("./tools/ingest-rules").then((module) => module.registerIngestRuleTools) }, + { name: "delete_ingest_rule", tool: "delete_ingest_rule", title: "Delete Ingest Rule", audience: "public", load: () => import("./tools/ingest-rules").then((module) => module.registerIngestRuleTools) }, + { name: "get_status_page", tool: "get_status_page", title: "Get Status Page", audience: "public", load: () => import("./tools/status-pages").then((module) => module.registerStatusPageTools) }, + { name: "post_status_page_update", tool: "post_status_page_update", title: "Post Status Page Update", audience: "public", load: () => import("./tools/status-pages").then((module) => module.registerStatusPageTools) }, + { name: "apply_status_page_config", tool: "apply_status_page_config", title: "Apply Status Page Config", audience: "public", load: () => import("./tools/status-pages").then((module) => module.registerStatusPageTools) }, + { name: "list_source_repositories", tool: "list_source_repositories", title: "List Source Repositories", audience: "agent", load: () => import("./tools/source-code").then((module) => module.registerSourceCodeTools) }, + { name: "search_source_code", tool: "search_source_code", title: "Search Source Code", audience: "agent", load: () => import("./tools/source-code").then((module) => module.registerSourceCodeTools) }, + { name: "read_source_file", tool: "read_source_file", title: "Read Source File", audience: "agent", load: () => import("./tools/source-code").then((module) => module.registerSourceCodeTools) }, + { name: "sandbox_grep", tool: "sandbox_grep", title: "Search Repository Checkout", audience: "agent", load: () => import("./tools/sandbox").then((module) => module.registerSandboxTools) }, + { name: "sandbox_list_files", tool: "sandbox_list_files", title: "List Repository Files", audience: "agent", load: () => import("./tools/sandbox").then((module) => module.registerSandboxTools) }, + { name: "sandbox_read_file", tool: "sandbox_read_file", title: "Read Repository File", audience: "agent", load: () => import("./tools/sandbox").then((module) => module.registerSandboxTools) }, + { name: "sandbox_exec", tool: "sandbox_exec", title: "Run Command in Repository", audience: "agent", load: () => import("./tools/sandbox").then((module) => module.registerSandboxTools) }, + { name: "pr_changed_files", tool: "pr_changed_files", title: "PR Changed Files", audience: "internal", load: () => import("./tools/pull-request").then((module) => module.registerPullRequestTools) }, + { name: "pr_context", tool: "pr_context", title: "PR Context", audience: "internal", load: () => import("./tools/pull-request").then((module) => module.registerPullRequestTools) }, + { name: "pr_file_diff", tool: "pr_file_diff", title: "PR File Diff", audience: "internal", load: () => import("./tools/pull-request").then((module) => module.registerPullRequestTools) }, + { name: "list_error_issues", tool: "list_error_issues", title: "List Error Issues", audience: "public", load: () => import("./tools/list-error-issues").then((module) => module.registerListErrorIssuesTool) }, + { name: "transition_error_issue", tool: "transition_error_issue", title: "Transition Error Issue", audience: "public", load: () => import("./tools/transition-error-issue").then((module) => module.registerTransitionErrorIssueTool) }, + { name: "transition_error_issues", tool: "transition_error_issues", title: "Transition Error Issues", audience: "public", load: () => import("./tools/transition-error-issues").then((module) => module.registerTransitionErrorIssuesTool) }, + { name: "set_issue_severity", tool: "set_issue_severity", title: "Set Issue Severity", audience: "public", load: () => import("./tools/set-issue-severity").then((module) => module.registerSetIssueSeverityTool) }, + { name: "merge_error_issues", tool: "merge_error_issues", title: "Merge Error Issues", audience: "public", load: () => import("./tools/merge-error-issues").then((module) => module.registerMergeErrorIssuesTool) }, + { name: "claim_error_issue", tool: "claim_error_issue", title: "Claim Error Issue", audience: "public", load: () => import("./tools/claim-error-issue").then((module) => module.registerClaimErrorIssueTool) }, + { name: "release_error_issue", tool: "release_error_issue", title: "Release Error Issue", audience: "public", load: () => import("./tools/release-error-issue").then((module) => module.registerReleaseErrorIssueTool) }, + { name: "comment_on_error_issue", tool: "comment_on_error_issue", title: "Comment on Error Issue", audience: "public", load: () => import("./tools/comment-on-error-issue").then((module) => module.registerCommentOnErrorIssueTool) }, + { name: "propose_fix", tool: "propose_fix", title: "Propose Fix", audience: "public", load: () => import("./tools/propose-fix").then((module) => module.registerProposeFixTool) }, + { name: "link_pull_request", tool: "link_pull_request", title: "Link Pull Request", audience: "public", load: () => import("./tools/link-pull-request").then((module) => module.registerLinkPullRequestTool) }, + { name: "list_error_issue_events", tool: "list_error_issue_events", title: "List Error Issue Events", audience: "public", load: () => import("./tools/list-error-issue-events").then((module) => module.registerListErrorIssueEventsTool) }, + { name: "get_investigation", tool: "get_investigation", title: "Get Investigation", audience: "public", load: () => import("./tools/get-investigation").then((module) => module.registerGetInvestigationTool) }, + { name: "register_agent", tool: "register_agent", title: "Register Agent", audience: "public", load: () => import("./tools/register-agent").then((module) => module.registerRegisterAgentTool) }, + { name: "send_maple_feedback", tool: "send_maple_feedback", title: "Send Maple Feedback", audience: "public", load: () => import("./tools/send-maple-feedback").then((module) => module.registerSendMapleFeedbackTool) }, + { name: "list_maple_feedback", tool: "list_maple_feedback", title: "List Maple Feedback", audience: "public", load: () => import("./tools/list-maple-feedback").then((module) => module.registerListMapleFeedbackTool) }, + { name: "list_error_incidents", tool: "list_error_incidents", title: "List Error Incidents", audience: "public", load: () => import("./tools/list-error-incidents").then((module) => module.registerListErrorIncidentsTool) }, + { name: "get_error_notification_policy", tool: "get_error_notification_policy", title: "Get Error Notification Policy", audience: "public", load: () => import("./tools/get-error-notification-policy").then((module) => module.registerGetErrorNotificationPolicyTool) }, + { name: "update_error_notification_policy", tool: "update_error_notification_policy", title: "Update Error Notification Policy", audience: "public", load: () => import("./tools/update-error-notification-policy").then((module) => module.registerUpdateErrorNotificationPolicyTool) }, + { name: "list_sources", tool: "list_ingest_sources", title: "List Ingest Sources", audience: "public", load: () => import("./tools/list-sources").then((module) => module.registerListSourcesTool) }, +] diff --git a/apps/ai/src/mcp/tools/registry-core.ts b/apps/ai/src/mcp/tools/registry-core.ts new file mode 100644 index 0000000000..5eee3f4cd9 --- /dev/null +++ b/apps/ai/src/mcp/tools/registry-core.ts @@ -0,0 +1,575 @@ +// BOUNDARY-FILE: This module owns unparsed external values and narrows them before domain use. +import * as Policy from "@maple/domain/policy" +import { McpToolNotFoundError } from "@maple/domain/mcp-tool-contract" +import { scopeAllows } from "@maple/domain/http/v2" +import type { McpToolSurface } from "@maple/domain/mcp-manifest" +import { McpToolOutputs } from "@maple/domain/mcp-outputs" +import { + Clock, + Effect, + Option, + Schema, + type SchemaAST, + Array as Arr, + Record as Rec, + String as Str, +} from "effect" +import { CurrentMcpTenant } from "../tenant" +import { + audienceAdmits, + McpAuthInvalidError, + type McpToolAudience, + type McpToolError, + type McpToolHints, + type McpToolPhrases, + type McpToolRegistrar, + type McpToolResult, + refusalFor, + refusesReadOnlyCredential, +} from "./types" +import { unknownToolMessage } from "../lib/tool-suggestions" +import { + argumentWarnings, + enumValues, + formatDecodeFailure, + normalizeArguments, + type NormalizedArguments, +} from "../lib/decode-issues" +import { filterNextCalls, nextCallsOf, type NextCall, type ToolDoc } from "../lib/tool-doc" +import { stringifyJson } from "../lib/json" +import { renderToolDocWithinBudget } from "./tool-output" +import { CurrentWindowNotes, WindowNotes } from "../lib/window-notes" +import type { McpToolRequirements } from "./runtime-services" + +/** What a tool's handler produced: its typed output, rendered and encoded. */ +interface ToolRun { + readonly doc: ToolDoc + readonly structured: Schema.Json | undefined +} + +export interface MapleToolDefinition extends MapleToolCatalogEntry { + readonly run: (params: unknown) => Effect.Effect +} + +export interface MapleToolCatalogEntry { + readonly name: string + readonly title: string + readonly description: string + readonly schema: Schema.Codec + /** How arguments decode; `rejectUnknownKeys` tools refuse nested keys the schema lacks. */ + readonly parseOptions: SchemaAST.ParseOptions + readonly outputSchema: Schema.Codec + readonly hints: McpToolHints + readonly aliases: Readonly> + readonly valueAliases: Readonly>>> + readonly audience: McpToolAudience + readonly scopeFamily?: string | ReadonlyArray + readonly phrases: McpToolPhrases +} + +class McpDecodeError extends Schema.TaggedError()("@maple/mcp/errors/McpDecodeError", { + message: Schema.String, +}) {} + +/** + * The output schema's JSON Schema. MCP requires an object root, as for inputs. Unlike inputs, a + * `null` branch here is real (`Schema.NullOr` fields), so nullable unions are kept. + */ +export const toOutputSchema = (schema: Schema.Top): Record => { + const document = Schema.toJsonSchemaDocument(schema) + const base: Record = + Rec.keys(document.definitions).length > 0 + ? { ...document.schema, $defs: document.definitions } + : document.schema + if (base.type !== "object" && !("$ref" in base)) { + throw new Error( + `MCP tool output schemas must have an object root; got ${Str.slice(0, 200)(String(stringifyJson(base)))}. Wrap the output in a Schema.Struct.`, + ) + } + return base +} + +/** + * Effect emits a rootless schema for an empty `Struct({})`: `{ not: { type: + * "null" } }` since rc.116, `{ anyOf: [{ type: "object" }, { type: "array" }] }` + * before it. Both are matched structurally, so the normalization below cannot + * swallow any other rootless schema. + */ +const isEmptyStructSchema = (base: Record): boolean => { + if ("type" in base || "properties" in base) return false + const not = base.not + if (typeof not === "object" && not !== null) { + const keys = Arr.filter(Rec.keys(base), (key) => key !== "$defs") + if (keys.length === 1 && (not as { type?: unknown }).type === "null") { + return Rec.keys(not).length === 1 + } + } + const anyOf = base.anyOf + if (!Arr.isArray(anyOf) || anyOf.length === 0) return false + return Arr.every(anyOf, (member) => { + if (typeof member !== "object" || member === null) return false + const type = (member as { type?: unknown }).type + return Rec.keys(member).length === 1 && (type === "object" || type === "array") + }) +} + +/** + * Rewrite `anyOf: [T, {type: "null"}]` to plain `T`, keeping the sibling keys + * (`description`, and anything else attached to the property). + * + * `Schema.optional(X)`, which CLAUDE.md mandates for MCP tool params, has type + * `X | undefined`, but `toJsonSchemaDocument` renders that absence as a JSON + * `null` branch. The published schema therefore told every MCP client that + * `{"service": null}` was valid on every optional parameter of every tool, + * while the decoder rejects it with `Expected string | undefined`. An agent that + * read the schema literally got "Invalid parameters" for doing what it was told. + * + * So this is a correctness fix first; it also happens to remove ~2.3k tokens + * (17% of the published schema bytes) of union wrapper. + * + * Safe only while no MCP parameter is GENUINELY nullable: `Schema.NullOr` would + * render identically and be wrongly narrowed here. `registry.test.ts` pins that + * invariant by decoding `null` into every parameter of every tool. + * The one exception, `P.optionalNullableNumberOneOf`, is optional and names null in its description. + */ +const collapseNullableUnions = (node: unknown): unknown => { + if (Arr.isArray(node)) return Arr.map(node, collapseNullableUnions) + if (node === null || typeof node !== "object") return node + const obj = node as Record + const anyOf = obj.anyOf + if (Arr.isArray(anyOf)) { + // Nested unions arrive flattened: `optional(Union([A, B]))` is `anyOf: [A, B, null]`. + const kept = Arr.filter(anyOf, (member) => !isJsonObject(member) || member.type !== "null") + if (kept.length > 0 && kept.length < anyOf.length) { + const { anyOf: _replaced, ...siblings } = obj + // Siblings last: a `description` on the property outranks one on the branch. + return collapseNullableUnions( + kept.length === 1 && isJsonObject(kept[0]) + ? { ...kept[0], ...siblings } + : { anyOf: kept, ...siblings }, + ) + } + } + return Rec.fromEntries( + Arr.map(Rec.toEntries(obj), ([key, value]) => [key, collapseNullableUnions(value)]), + ) +} + +const isJsonObject = (value: unknown): value is Record => + typeof value === "object" && value !== null && !Arr.isArray(value) + +const DEFS_PREFIX = "#/$defs/" + +/** + * Replace each `$ref` with the definition it names, keeping sibling keys. A branded parameter + * (`issue_id` decoding to `ErrorIssueId`) otherwise publishes as a bare `$ref`, and its type and + * description sit in `$defs` where a model reading the property never looks. Recursive + * definitions stay referenced. + */ +const inlineDefinitions = (root: Record): Record => { + const defs = isJsonObject(root.$defs) ? root.$defs : {} + const kept = new Set() + const visit = (node: unknown, trail: ReadonlySet): unknown => { + if (Arr.isArray(node)) return Arr.map(node, (item) => visit(item, trail)) + if (!isJsonObject(node)) return node + const ref = node.$ref + if (typeof ref === "string" && Str.startsWith(DEFS_PREFIX)(ref)) { + const name = Str.replaceAll( + "~0", + "~", + )(Str.replaceAll("~1", "/")(Str.slice(DEFS_PREFIX.length)(ref))) + const definition = defs[name] + const expanded = + isJsonObject(definition) && !trail.has(name) + ? visit(definition, new Set([...trail, name])) + : undefined + if (isJsonObject(expanded)) { + const { $ref: _ref, $defs: _defs, ...siblings } = node + return { ...expanded, ...siblings } + } + kept.add(name) + return node + } + return Rec.fromEntries( + Arr.flatMap(Rec.toEntries(node), ([key, value]) => + key === "$defs" ? [] : [[key, visit(value, trail)]], + ), + ) + } + const visited = visit(root, new Set()) + const inlined = isJsonObject(visited) ? visited : root + return kept.size === 0 + ? inlined + : { ...inlined, $defs: Rec.fromEntries(Arr.map([...kept], (name) => [name, defs[name]])) } +} + +const CANONICAL_TYPES: ReadonlySet = new Set(["number", "boolean", "array"]) + +/** + * The branch of a vocabulary union a model should send. `P.*` accepts looser encodings than + * it asks for (`"15"` for a number, `"a,b"` for a list, JSON text or the object itself), and + * publishing those invites them; the decoder still takes them either way. + */ +const canonicalBranch = (branches: ReadonlyArray): unknown => { + if (branches.length === 1) return branches[0] + const jsonText = branches.find( + (branch) => isJsonObject(branch) && branch.contentMediaType === "application/json", + ) + if (jsonText !== undefined || branches.length !== 2) return jsonText + const isString = (branch: unknown) => isJsonObject(branch) && branch.type === "string" + const other = branches.find((branch) => !isString(branch)) + return Arr.some(branches, isString) && isJsonObject(other) && CANONICAL_TYPES.has(other.type) + ? other + : undefined +} + +const publishCanonical = (node: unknown): unknown => { + if (Arr.isArray(node)) return Arr.map(node, publishCanonical) + if (!isJsonObject(node)) return node + const anyOf = node.anyOf + if (Arr.isArray(anyOf)) { + const canonical = canonicalBranch(anyOf) + if (isJsonObject(canonical)) { + const { anyOf: _anyOf, ...siblings } = node + return publishCanonical({ ...canonical, ...siblings }) + } + } + // `format: "uuid"` says what the UUID regex says, in a word instead of ~200 characters. + const { pattern: _pattern, ...unpatterned } = node + const published = node.format === "uuid" ? unpatterned : node + return Rec.fromEntries( + Arr.map(Rec.toEntries(published), ([key, value]) => [key, publishCanonical(value)]), + ) +} + +export const toInputSchema = (schema: Schema.Top): Record => { + // `onExcessProperty: "error"` keeps `additionalProperties: false` on every + // published tool. rc.116 made the emitted value follow this option and + // defaults it to the decoder's behaviour, which would have loosened the + // schema every public MCP tool advertises. + const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" }) + const rawBase = + Rec.keys(document.definitions).length > 0 + ? { ...document.schema, $defs: document.definitions } + : document.schema + const base = publishCanonical(collapseNullableUnions(inlineDefinitions(rawBase))) as typeof rawBase + // MCP requires the top-level inputSchema to be an object schema (`type: "object"`). + // An empty `Struct({})` (a no-parameter tool) comes out untyped, which strict MCP + // clients reject: the Vercel AI SDK's `tools/list` Zod validator fails on + // `inputSchema.type` and drops EVERY tool from the connection. Normalize just that + // case. `$ref` roots (hoisted schemas) already carry a valid object type. + const record = base as Record + if (isEmptyStructSchema(record)) { + return { + type: "object", + properties: {}, + additionalProperties: false, + ...("$defs" in record ? { $defs: record.$defs } : undefined), + } + } + // A genuinely non-object root (a top-level `Schema.Union`/`Schema.Literals`/array) + // has parameters that an empty object schema would erase, publishing the tool to + // every MCP client as if it took none. Fail at registration instead: this runs at + // module init, so it surfaces in tests and at worker boot rather than in the wire. + if (record.type !== "object" && !("$ref" in record)) { + throw new Error( + `MCP tool input schemas must have an object root; got ${Str.slice(0, 200)(String(stringifyJson(record)))}. Wrap the tool input in a Schema.Struct.`, + ) + } + return base +} + +/** A tool module's registration function, as `registry.ts` and the generated module map import it. */ +export type McpToolRegister = (registrar: McpToolRegistrar) => void + +/** + * Runs registration functions and keeps the tools `keep` accepts. One module can register + * several tools; the per-tool lookup defines only the one a call asked for. + */ +export const collectToolDefinitions = ( + registers: ReadonlyArray, + keep: (name: string) => boolean = () => true, +): ReadonlyArray => { + const definitions: MapleToolDefinition[] = [] + const define: McpToolRegistrar["define"] = (spec) => { + if (!keep(spec.name)) return + const outputSchema: Schema.Codec = McpToolOutputs[spec.name] + const encode = Schema.encodeUnknownEffect(outputSchema) + definitions.push({ + name: spec.name, + title: spec.title, + description: spec.description, + schema: spec.parameters, + parseOptions: { onExcessProperty: spec.rejectUnknownKeys === true ? "error" : "ignore" }, + outputSchema, + hints: spec.hints, + aliases: spec.aliases ?? {}, + valueAliases: spec.valueAliases ?? {}, + audience: spec.audience ?? "public", + ...(spec.scopeFamily === undefined ? undefined : { scopeFamily: spec.scopeFamily }), + phrases: spec.phrases, + run: (params) => + Effect.gen(function* () { + const output = yield* spec.handler(params) + // A result that does not match its own schema is a bug, but the text is still right: + // the model gets its answer and the UI falls back to the text. + const structured = yield* encode(output).pipe( + Effect.flatMap(Schema.decodeUnknownEffect(Schema.Json)), + Effect.catch((error) => + Effect.logError("MCP tool output does not match its output schema").pipe( + Effect.annotateLogs({ + "maple.mcp.tool": spec.name, + "error.message": error.message, + }), + Effect.as(undefined), + ), + ), + ) + return { doc: spec.render(output), structured } + }), + }) + } + Arr.forEach(registers, (register) => register({ define })) + return definitions +} + +/** One entry of `tool-modules.generated.ts`: a callable name and the module that defines it. */ +export interface McpToolModule { + /** What a call names: a registered tool, or a retired alias of one. */ + readonly name: string + /** The registered tool that name means, the one `load` defines. */ + readonly tool: string + readonly title: string + readonly audience: McpToolAudience + readonly load: () => Promise +} + +/** + * How the executor finds tools: the whole registry (chat, tests) or one module per call + * (`tool-modules.generated.ts`). Both answer for the same names, aliases included. + */ +export interface McpToolLookup { + /** The definition a name (or retired alias) means, or undefined outside the registry. */ + readonly find: (name: string) => Effect.Effect + /** The registered names a surface may see, in catalog order, for the unknown-tool message. */ + readonly namesFor: (surface: McpToolSurface) => ReadonlyArray +} + +const inputSchemas = new Map>() + +/** The published input schema, computed on first use and kept: a hot path, and deterministic. */ +export const inputSchemaOf = (entry: MapleToolCatalogEntry): Record => { + const cached = inputSchemas.get(entry.name) + if (cached !== undefined) return cached + const schema = toInputSchema(entry.schema) + inputSchemas.set(entry.name, schema) + return schema +} + +const parameterNames = (entry: MapleToolCatalogEntry): ReadonlyArray => { + const properties = inputSchemaOf(entry).properties + return typeof properties === "object" && properties !== null ? Rec.keys(properties) : [] +} + +const enumSpelling = (value: string): string => Str.replace(/[\s-]+/g, "_")(Str.toLowerCase(Str.trim(value))) + +/** + * An enum value as the model spelled it, read as the published one it means: `Feature Request` + * and `feature-request` are `feature_request`, a declared value alias is its target. Anything + * else is left for the decoder to reject with the allowed values. + */ +const canonicalEnumArguments = (entry: MapleToolCatalogEntry, input: unknown): unknown => { + if (!isArgumentRecord(input)) return input + const enums = enumValues(inputSchemaOf(entry)) + return Rec.map(input, (value, key) => { + const allowed = enums.get(key) + if (typeof value !== "string" || allowed === undefined || allowed.includes(value)) return value + const spelled = enumSpelling(value) + if (allowed.includes(spelled)) return spelled + const target = entry.valueAliases[key]?.[spelled] + return target !== undefined && allowed.includes(target) ? target : value + }) +} + +/** How a call's arguments are read before decoding: aliases applied, enum spellings fixed, unknowns dropped. */ +export const normalizeFor = (entry: MapleToolCatalogEntry, input: unknown, nowMs?: number) => + normalizeArguments( + canonicalEnumArguments(entry, input), + parameterNames(entry), + entry.aliases, + enumValues(inputSchemaOf(entry)), + nowMs, + ) + +export const isArgumentRecord = (value: unknown): value is Readonly> => + typeof value === "object" && value !== null && !Arr.isArray(value) + +const toDecodeErrorMessage = ( + definition: MapleToolDefinition, + error: unknown, + normalized: NormalizedArguments, +): string => + Schema.isSchemaError(error) + ? formatDecodeFailure(definition.name, error, inputSchemaOf(definition), normalized) + : String(error) + +/** + * Whether a suggested call would decode on the surface it is shown on, and whether its tool is + * one the surface cannot see (a shared tool pointing at it is expected). A next call naming a + * parameter that was renamed, or a tool the caller cannot see, is worse than none. + */ +const checkNextCall = Effect.fnUntraced(function* ( + lookup: McpToolLookup, + call: NextCall, + surface: McpToolSurface, +) { + const target = yield* lookup.find(call.tool) + if (target === undefined) return { call, valid: false, hidden: false } + if (!audienceAdmits(target.audience, surface)) return { call, valid: false, hidden: true } + const normalized = normalizeFor(target, call.args) + const valid = + normalized.unknown.length === 0 && + Schema.decodeUnknownOption(target.schema)(normalized.args, target.parseOptions)._tag === "Some" + return { call, valid, hidden: false } +}) + +const finish = Effect.fnUntraced(function* ( + lookup: McpToolLookup, + definition: MapleToolDefinition, + run: ToolRun, + warnings: ReadonlyArray, + surface: McpToolSurface, +) { + const checked = yield* Effect.forEach(nextCallsOf(run.doc), (call) => + checkNextCall(lookup, call, surface), + ) + const invalid = Arr.filter(checked, (check) => !check.valid) + const undecodable = Arr.filter(invalid, (check) => !check.hidden) + if (undecodable.length > 0) { + yield* Effect.logWarning("MCP tool suggested a call that does not decode").pipe( + Effect.annotateLogs({ + "maple.mcp.tool": definition.name, + "maple.mcp.next_calls": Arr.join( + Arr.map(undecodable, (check) => check.call.tool), + ",", + ), + }), + ) + } + const invalidCalls = Arr.map(invalid, (check) => check.call) + const doc = + invalidCalls.length === 0 ? run.doc : filterNextCalls(run.doc, (call) => !invalidCalls.includes(call)) + const text = renderToolDocWithinBudget( + warnings.length === 0 ? doc : { ...doc, warnings: [...warnings, ...(doc.warnings ?? [])] }, + ) + const result: McpToolResult = { + content: [{ type: "text", text }], + ...(run.structured === undefined ? undefined : { structuredContent: run.structured }), + } + return result +}) + +/** + * The one raw registry entry point. Its full Effect environment is intentionally + * preserved; only `McpToolExecutor` may close it with tenant and app services. + * + * The surface is part of the lookup: an internal tool called from a surface it + * is not exposed on does not exist there, and gets the same answer as an unknown + * name, so the public transport cannot enumerate the internal set by probing. + */ +export const executeRegisteredTool = Effect.fn("McpToolRegistry.execute")(function* ( + lookup: McpToolLookup, + name: string, + input: unknown, + surface: McpToolSurface, +) { + const definition = yield* lookup.find(name) + if (!definition || !audienceAdmits(definition.audience, surface)) { + if (definition) { + yield* Effect.logWarning("MCP tool is not exposed on this surface").pipe( + Effect.annotateLogs({ "maple.mcp.tool": name, "maple.mcp.surface": surface }), + ) + } + return yield* new McpToolNotFoundError({ + toolName: name, + message: unknownToolMessage(name, lookup.namesFor(surface)), + }) + } + + if (refusesReadOnlyCredential(definition.name, definition.hints.readOnly)) { + const tenant = yield* CurrentMcpTenant + const refusal = refusalFor(tenant, definition.name, definition.hints.readOnly) + if (refusal !== undefined) { + return yield* new McpAuthInvalidError({ + message: + refusal === "analyst" + ? `\`${definition.name}\` changes data. ${Policy.analystMessage}` + : `\`${definition.name}\` changes data, and this API key is read-only. Use a key with write access, or connect with OAuth.`, + reason: "insufficient_scope", + }) + } + } + + if (definition.scopeFamily !== undefined) { + const access = definition.hints.readOnly ? "read" : "write" + const tenant = yield* CurrentMcpTenant + const missing = Arr.findFirst( + Arr.ensure(definition.scopeFamily), + (family) => !scopeAllows(tenant.scopes, { family, access }), + ) + if (Option.isSome(missing)) { + return yield* new McpAuthInvalidError({ + message: `\`${definition.name}\` needs the \`${missing.value}:${access}\` scope, which this API key lacks. Add it to the key, or use a full-access key.`, + reason: "insufficient_scope", + }) + } + } + + const nowMs = yield* Clock.currentTimeMillis + const normalized = normalizeFor(definition, input ?? {}, nowMs) + yield* Effect.annotateCurrentSpan({ + "maple.mcp.tool": definition.name, + "maple.mcp.tool.arguments": Arr.join( + Object.keys(typeof input === "object" && input !== null ? input : {}).sort(), + ",", + ), + ...(normalized.unknown.length === 0 + ? undefined + : { + "maple.mcp.tool.unknown_arguments": Arr.join( + Arr.map(normalized.unknown, ({ key }) => key), + ",", + ), + }), + ...(normalized.renamed.length === 0 + ? undefined + : { + "maple.mcp.tool.aliased_arguments": Arr.join( + Arr.map(normalized.renamed, ([from]) => from), + ",", + ), + }), + }) + const decoded = yield* Schema.decodeUnknownEffect(definition.schema)( + normalized.args, + definition.parseOptions, + ).pipe( + Effect.mapError( + (error) => + new McpDecodeError({ + message: toDecodeErrorMessage(definition, error, normalized), + }), + ), + ) + + const windowNotes = new WindowNotes() + const run = yield* definition.run(decoded).pipe(Effect.provideService(CurrentWindowNotes, windowNotes)) + yield* Effect.logInfo("Tool completed") + return yield* finish( + lookup, + definition, + { ...run, doc: windowNotes.decorate(run.doc) }, + argumentWarnings(normalized, definition.name), + surface, + ) +}) diff --git a/apps/ai/src/mcp/tools/registry.ts b/apps/ai/src/mcp/tools/registry.ts index 23b88be57b..ea791332ea 100644 --- a/apps/ai/src/mcp/tools/registry.ts +++ b/apps/ai/src/mcp/tools/registry.ts @@ -1,19 +1,10 @@ // BOUNDARY-FILE: This module owns unparsed external values and narrows them before domain use. -import * as Policy from "@maple/domain/policy" -import { McpToolNotFoundError } from "@maple/domain/mcp-tool-contract" -import { scopeAllows } from "@maple/domain/http/v2" +/** + * The whole registry, every tool defined up front: the catalog chat, permissions, evals and tests + * read. A public `tools/call` loads one tool instead (`tool-modules.generated.ts`, `tool-lookup.ts`). + */ import type { McpToolSurface } from "@maple/domain/mcp-manifest" -import { McpToolOutputs } from "@maple/domain/mcp-outputs" -import { - Clock, - Effect, - Option, - Schema, - type SchemaAST, - Array as Arr, - Record as Rec, - String as Str, -} from "effect" +import { Effect, Schema, Array as Arr } from "effect" import { registerAddDashboardWidgetTool } from "./add-dashboard-widget" import { registerDescribeWarehouseTablesTool } from "./describe-warehouse-tables" import { registerComparePeriodsTool } from "./compare-periods" @@ -133,439 +124,147 @@ import { registerServiceMapTool } from "./service-map" import { registerSourceCodeTools } from "./source-code" import { registerSandboxTools } from "./sandbox" import { registerPullRequestTools } from "./pull-request" -import { CurrentMcpTenant } from "../tenant" -import { - audienceAdmits, - McpAuthInvalidError, - type McpToolAudience, - type McpToolError, - type McpToolHints, - type McpToolPhrases, - type McpToolRegistrar, - type McpToolResult, - refusalFor, - refusesReadOnlyCredential, -} from "./types" -import { unknownToolMessage } from "../lib/tool-suggestions" -import { - argumentWarnings, - enumValues, - formatDecodeFailure, - normalizeArguments, - type NormalizedArguments, -} from "../lib/decode-issues" -import { filterNextCalls, nextCallsOf, type NextCall, type ToolDoc } from "../lib/tool-doc" -import { stringifyJson } from "../lib/json" -import { renderToolDocWithinBudget } from "./tool-output" -import { CurrentWindowNotes, WindowNotes } from "../lib/window-notes" -import type { McpToolRequirements } from "./runtime-services" import { registerUpdateDashboardTool } from "./update-dashboard" import { registerUpdateDashboardWidgetTool } from "./update-dashboard-widget" - -/** What a tool's handler produced: its typed output, rendered and encoded. */ -interface ToolRun { - readonly doc: ToolDoc - readonly structured: Schema.Json | undefined -} - -interface MapleToolDefinition extends MapleToolCatalogEntry { - readonly run: (params: unknown) => Effect.Effect -} - -export interface MapleToolCatalogEntry { - readonly name: string - readonly title: string - readonly description: string - readonly schema: Schema.Codec - /** How arguments decode; `rejectUnknownKeys` tools refuse nested keys the schema lacks. */ - readonly parseOptions: SchemaAST.ParseOptions - readonly outputSchema: Schema.Codec - readonly hints: McpToolHints - readonly aliases: Readonly> - readonly valueAliases: Readonly>>> - readonly audience: McpToolAudience - readonly scopeFamily?: string | ReadonlyArray - readonly phrases: McpToolPhrases -} - -class McpDecodeError extends Schema.TaggedError()("@maple/mcp/errors/McpDecodeError", { - message: Schema.String, -}) {} - -/** - * The output schema's JSON Schema. MCP requires an object root, as for inputs. Unlike inputs, a - * `null` branch here is real (`Schema.NullOr` fields), so nullable unions are kept. - */ -export const toOutputSchema = (schema: Schema.Top): Record => { - const document = Schema.toJsonSchemaDocument(schema) - const base: Record = - Rec.keys(document.definitions).length > 0 - ? { ...document.schema, $defs: document.definitions } - : document.schema - if (base.type !== "object" && !("$ref" in base)) { - throw new Error( - `MCP tool output schemas must have an object root; got ${Str.slice(0, 200)(String(stringifyJson(base)))}. Wrap the output in a Schema.Struct.`, - ) - } - return base -} - -/** - * Effect emits a rootless schema for an empty `Struct({})` — `{ not: { type: - * "null" } }` since rc.116, `{ anyOf: [{ type: "object" }, { type: "array" }] }` - * before it. Both are matched structurally, so the normalization below cannot - * swallow any other rootless schema. - */ -const isEmptyStructSchema = (base: Record): boolean => { - if ("type" in base || "properties" in base) return false - const not = base.not - if (typeof not === "object" && not !== null) { - const keys = Arr.filter(Rec.keys(base), (key) => key !== "$defs") - if (keys.length === 1 && (not as { type?: unknown }).type === "null") { - return Rec.keys(not).length === 1 - } - } - const anyOf = base.anyOf - if (!Arr.isArray(anyOf) || anyOf.length === 0) return false - return Arr.every(anyOf, (member) => { - if (typeof member !== "object" || member === null) return false - const type = (member as { type?: unknown }).type - return Rec.keys(member).length === 1 && (type === "object" || type === "array") - }) -} - -/** - * Rewrite `anyOf: [T, {type: "null"}]` to plain `T`, keeping the sibling keys - * (`description`, and anything else attached to the property). - * - * `Schema.optional(X)` — which CLAUDE.md mandates for MCP tool params — has type - * `X | undefined`, but `toJsonSchemaDocument` renders that absence as a JSON - * `null` branch. The published schema therefore told every MCP client that - * `{"service": null}` was valid on every optional parameter of every tool, - * while the decoder rejects it with `Expected string | undefined`. An agent that - * read the schema literally got "Invalid parameters" for doing what it was told. - * - * So this is a correctness fix first; it also happens to remove ~2.3k tokens - * (17% of the published schema bytes) of union wrapper. - * - * Safe only while no MCP parameter is GENUINELY nullable — `Schema.NullOr` would - * render identically and be wrongly narrowed here. `registry.test.ts` pins that - * invariant by decoding `null` into every parameter of every tool. - * The one exception, `P.optionalNullableNumberOneOf`, is optional and names null in its description. - */ -const collapseNullableUnions = (node: unknown): unknown => { - if (Arr.isArray(node)) return Arr.map(node, collapseNullableUnions) - if (node === null || typeof node !== "object") return node - const obj = node as Record - const anyOf = obj.anyOf - if (Arr.isArray(anyOf)) { - // Nested unions arrive flattened: `optional(Union([A, B]))` is `anyOf: [A, B, null]`. - const kept = Arr.filter(anyOf, (member) => !isJsonObject(member) || member.type !== "null") - if (kept.length > 0 && kept.length < anyOf.length) { - const { anyOf: _replaced, ...siblings } = obj - // Siblings last: a `description` on the property outranks one on the branch. - return collapseNullableUnions( - kept.length === 1 && isJsonObject(kept[0]) - ? { ...kept[0], ...siblings } - : { anyOf: kept, ...siblings }, - ) - } - } - return Rec.fromEntries( - Arr.map(Rec.toEntries(obj), ([key, value]) => [key, collapseNullableUnions(value)]), - ) -} - -const isJsonObject = (value: unknown): value is Record => - typeof value === "object" && value !== null && !Arr.isArray(value) - -const DEFS_PREFIX = "#/$defs/" - -/** - * Replace each `$ref` with the definition it names, keeping sibling keys. A branded parameter - * (`issue_id` decoding to `ErrorIssueId`) otherwise publishes as a bare `$ref`, and its type and - * description sit in `$defs` where a model reading the property never looks. Recursive - * definitions stay referenced. - */ -const inlineDefinitions = (root: Record): Record => { - const defs = isJsonObject(root.$defs) ? root.$defs : {} - const kept = new Set() - const visit = (node: unknown, trail: ReadonlySet): unknown => { - if (Arr.isArray(node)) return Arr.map(node, (item) => visit(item, trail)) - if (!isJsonObject(node)) return node - const ref = node.$ref - if (typeof ref === "string" && Str.startsWith(DEFS_PREFIX)(ref)) { - const name = Str.replaceAll( - "~0", - "~", - )(Str.replaceAll("~1", "/")(Str.slice(DEFS_PREFIX.length)(ref))) - const definition = defs[name] - const expanded = - isJsonObject(definition) && !trail.has(name) - ? visit(definition, new Set([...trail, name])) - : undefined - if (isJsonObject(expanded)) { - const { $ref: _ref, $defs: _defs, ...siblings } = node - return { ...expanded, ...siblings } - } - kept.add(name) - return node - } - return Rec.fromEntries( - Arr.flatMap(Rec.toEntries(node), ([key, value]) => - key === "$defs" ? [] : [[key, visit(value, trail)]], - ), - ) - } - const visited = visit(root, new Set()) - const inlined = isJsonObject(visited) ? visited : root - return kept.size === 0 - ? inlined - : { ...inlined, $defs: Rec.fromEntries(Arr.map([...kept], (name) => [name, defs[name]])) } -} - -const CANONICAL_TYPES: ReadonlySet = new Set(["number", "boolean", "array"]) - -/** - * The branch of a vocabulary union a model should send. `P.*` accepts looser encodings than - * it asks for (`"15"` for a number, `"a,b"` for a list, JSON text or the object itself), and - * publishing those invites them; the decoder still takes them either way. - */ -const canonicalBranch = (branches: ReadonlyArray): unknown => { - if (branches.length === 1) return branches[0] - const jsonText = branches.find( - (branch) => isJsonObject(branch) && branch.contentMediaType === "application/json", - ) - if (jsonText !== undefined || branches.length !== 2) return jsonText - const isString = (branch: unknown) => isJsonObject(branch) && branch.type === "string" - const other = branches.find((branch) => !isString(branch)) - return Arr.some(branches, isString) && isJsonObject(other) && CANONICAL_TYPES.has(other.type) - ? other - : undefined -} - -const publishCanonical = (node: unknown): unknown => { - if (Arr.isArray(node)) return Arr.map(node, publishCanonical) - if (!isJsonObject(node)) return node - const anyOf = node.anyOf - if (Arr.isArray(anyOf)) { - const canonical = canonicalBranch(anyOf) - if (isJsonObject(canonical)) { - const { anyOf: _anyOf, ...siblings } = node - return publishCanonical({ ...canonical, ...siblings }) - } - } - // `format: "uuid"` says what the UUID regex says, in a word instead of ~200 characters. - const { pattern: _pattern, ...unpatterned } = node - const published = node.format === "uuid" ? unpatterned : node - return Rec.fromEntries( - Arr.map(Rec.toEntries(published), ([key, value]) => [key, publishCanonical(value)]), - ) -} - -export const toInputSchema = (schema: Schema.Top): Record => { - // `onExcessProperty: "error"` keeps `additionalProperties: false` on every - // published tool. rc.116 made the emitted value follow this option and - // defaults it to the decoder's behaviour, which would have loosened the - // schema every public MCP tool advertises. - const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" }) - const rawBase = - Rec.keys(document.definitions).length > 0 - ? { ...document.schema, $defs: document.definitions } - : document.schema - const base = publishCanonical(collapseNullableUnions(inlineDefinitions(rawBase))) as typeof rawBase - // MCP requires the top-level inputSchema to be an object schema (`type: "object"`). - // An empty `Struct({})` (a no-parameter tool) comes out untyped, which strict MCP - // clients reject — the Vercel AI SDK's `tools/list` Zod validator fails on - // `inputSchema.type` and drops EVERY tool from the connection. Normalize just that - // case. `$ref` roots (hoisted schemas) already carry a valid object type. - const record = base as Record - if (isEmptyStructSchema(record)) { - return { - type: "object", - properties: {}, - additionalProperties: false, - ...("$defs" in record ? { $defs: record.$defs } : undefined), - } - } - // A genuinely non-object root (a top-level `Schema.Union`/`Schema.Literals`/array) - // has parameters that an empty object schema would erase, publishing the tool to - // every MCP client as if it took none. Fail at registration instead — this runs at - // module init, so it surfaces in tests and at worker boot rather than in the wire. - if (record.type !== "object" && !("$ref" in record)) { - throw new Error( - `MCP tool input schemas must have an object root; got ${Str.slice(0, 200)(String(stringifyJson(record)))}. Wrap the tool input in a Schema.Struct.`, - ) - } - return base -} - -const collectMapleToolDefinitions = (): ReadonlyArray => { - const definitions: MapleToolDefinition[] = [] - const define: McpToolRegistrar["define"] = (spec) => { - const outputSchema: Schema.Codec = McpToolOutputs[spec.name] - const encode = Schema.encodeUnknownEffect(outputSchema) - definitions.push({ - name: spec.name, - title: spec.title, - description: spec.description, - schema: spec.parameters, - parseOptions: { onExcessProperty: spec.rejectUnknownKeys === true ? "error" : "ignore" }, - outputSchema, - hints: spec.hints, - aliases: spec.aliases ?? {}, - valueAliases: spec.valueAliases ?? {}, - audience: spec.audience ?? "public", - ...(spec.scopeFamily === undefined ? undefined : { scopeFamily: spec.scopeFamily }), - phrases: spec.phrases, - run: (params) => - Effect.gen(function* () { - const output = yield* spec.handler(params) - // A result that does not match its own schema is a bug, but the text is still right: - // the model gets its answer and the UI falls back to the text. - const structured = yield* encode(output).pipe( - Effect.flatMap(Schema.decodeUnknownEffect(Schema.Json)), - Effect.catch((error) => - Effect.logError("MCP tool output does not match its output schema").pipe( - Effect.annotateLogs({ - "maple.mcp.tool": spec.name, - "error.message": error.message, - }), - Effect.as(undefined), - ), - ), - ) - return { doc: spec.render(output), structured } - }), - }) - } - const registrar: McpToolRegistrar = { define } - - registerFindErrorsTool(registrar) - registerInspectTraceTool(registrar) - registerInspectSpanTool(registrar) - registerSearchLogsTool(registrar) - registerMineLogPatternsTool(registrar) - registerCompareLogPatternsTool(registrar) - registerSearchTracesTool(registrar) - registerSearchSessionsTool(registrar) - registerQueryFunnelTool(registrar) - registerListProductEventsTool(registrar) - registerGetSessionTranscriptTool(registrar) - registerGetSessionTracesTool(registrar) - registerListUsersTool(registrar) - registerInspectUserTool(registrar) - registerListAgentSessionsTool(registrar) - registerGetAgentSessionTool(registrar) - registerGetAgentSessionTranscriptTool(registrar) - registerGetAgentToolsOverviewTool(registrar) - registerGetAgentToolErrorTool(registrar) - registerDiagnoseServiceTool(registrar) - registerFindSlowTracesTool(registrar) - registerErrorDetailTool(registrar) - registerListMetricsTool(registrar) - registerQueryDataTool(registrar) - registerRunSqlTool(registrar) - registerServiceMapTool(registrar) - registerListAlertRulesTool(registrar) - registerListAlertDestinationsTool(registrar) - registerGetAlertRuleTool(registrar) - registerListAlertIncidentsTool(registrar) - registerListAlertChecksTool(registrar) - registerPreviewAlertRuleTool(registrar) - registerGetIncidentTimelineTool(registrar) - registerCreateAlertRuleTool(registrar) - registerUpdateAlertRuleTool(registrar) - registerDeleteAlertRuleTool(registrar) - registerListMaintenanceWindowsTool(registrar) - registerCreateMaintenanceWindowTool(registrar) - registerDeleteMaintenanceWindowTool(registrar) - registerListAlertSilencesTool(registrar) - registerCreateAlertSilenceTool(registrar) - registerEndAlertSilenceTool(registrar) - registerAcknowledgeAlertIncidentTool(registrar) - registerListEscalationChainsTool(registrar) - registerCreateEscalationChainTool(registrar) - registerUpdateEscalationChainTool(registrar) - registerDeleteEscalationChainTool(registrar) - registerListOnCallSchedulesTool(registrar) - registerWhoIsOnCallTool(registrar) - registerCreateOnCallScheduleTool(registrar) - registerUpdateOnCallScheduleTool(registrar) - registerDeleteOnCallScheduleTool(registrar) - registerCreateOnCallOverrideTool(registrar) - registerDeleteOnCallOverrideTool(registrar) - registerDescribeDashboardSchemaTool(registrar) - registerListDashboardsTool(registrar) - registerGetDashboardTool(registrar) - registerCreateDashboardTool(registrar) - registerUpdateDashboardTool(registrar) - registerAddDashboardWidgetTool(registrar) - registerDescribeWarehouseTablesTool(registrar) - registerUpdateDashboardWidgetTool(registrar) - registerRemoveDashboardWidgetTool(registrar) - registerReplaceDashboardWidgetsTool(registrar) - registerReorderDashboardWidgetsTool(registrar) - registerInspectChartDataTool(registrar) - registerComparePeriodsTool(registrar) - registerCompareOperationsTool(registrar) - registerExploreAttributesTool(registrar) - registerListServicesTool(registrar) - registerGetServiceTopOperationsTool(registrar) - registerServiceDeploymentsTool(registrar) - registerRouteUsageTool(registrar) - registerIngestFreshnessTool(registrar) - registerDbQueryVolumeTool(registrar) - registerListInfraTool(registrar) - registerInspectInfraTool(registrar) - registerIngestUsageTool(registrar) - registerGetInstrumentationRecommendationsTool(registrar) - registerAuditSetupTool(registrar) - registerListIntegrationsTool(registrar) - registerSearchConsoleQueriesTool(registrar) - registerSearchConsolePagesTool(registrar) - registerListSecurityFindingsTool(registrar) - registerInspectSecurityFindingTool(registrar) - registerListSecurityAuditRunsTool(registrar) - registerInspectSecurityAuditRunTool(registrar) - registerListSourcesTool(registrar) - registerListDataSourcesTool(registrar) - registerSearchDataSourcesTool(registrar) - registerDescribeDataSourceTool(registrar) - registerQueryDataSourceTool(registrar) - registerCiRunsTool(registrar) - registerCompareCommitsTool(registrar) - registerIntegrationWriteTools(registrar) - registerUptimeMonitorTools(registrar) - registerSloTools(registrar) - registerIngestRuleTools(registrar) - registerStatusPageTools(registrar) - registerSourceCodeTools(registrar) - registerSandboxTools(registrar) - registerPullRequestTools(registrar) - registerListErrorIssuesTool(registrar) - registerTransitionErrorIssueTool(registrar) - registerTransitionErrorIssuesTool(registrar) - registerSetIssueSeverityTool(registrar) - registerMergeErrorIssuesTool(registrar) - registerClaimErrorIssueTool(registrar) - registerReleaseErrorIssueTool(registrar) - registerCommentOnErrorIssueTool(registrar) - registerProposeFixTool(registrar) - registerLinkPullRequestTool(registrar) - registerListErrorIssueEventsTool(registrar) - registerGetInvestigationTool(registrar) - registerRegisterAgentTool(registrar) - registerSendMapleFeedbackTool(registrar) - registerListMapleFeedbackTool(registrar) - registerListErrorIncidentsTool(registrar) - registerGetErrorNotificationPolicyTool(registrar) - registerUpdateErrorNotificationPolicyTool(registrar) - - return definitions -} - -const mapleToolDefinitions = collectMapleToolDefinitions() +import { audienceAdmits } from "./types" +import { + collectToolDefinitions, + executeRegisteredTool, + isArgumentRecord, + type MapleToolCatalogEntry, + type MapleToolDefinition, + type McpToolLookup, + type McpToolRegister, + normalizeFor, +} from "./registry-core" + +export { inputSchemaOf, type MapleToolCatalogEntry, toInputSchema, toOutputSchema } from "./registry-core" + +/** Every tool's registration function, in catalog order (the order `tools/list` publishes). */ +const MAPLE_TOOL_REGISTERS: ReadonlyArray = [ + registerFindErrorsTool, + registerInspectTraceTool, + registerInspectSpanTool, + registerSearchLogsTool, + registerMineLogPatternsTool, + registerCompareLogPatternsTool, + registerSearchTracesTool, + registerSearchSessionsTool, + registerQueryFunnelTool, + registerListProductEventsTool, + registerGetSessionTranscriptTool, + registerGetSessionTracesTool, + registerListUsersTool, + registerInspectUserTool, + registerListAgentSessionsTool, + registerGetAgentSessionTool, + registerGetAgentSessionTranscriptTool, + registerGetAgentToolsOverviewTool, + registerGetAgentToolErrorTool, + registerDiagnoseServiceTool, + registerFindSlowTracesTool, + registerErrorDetailTool, + registerListMetricsTool, + registerQueryDataTool, + registerRunSqlTool, + registerServiceMapTool, + registerListAlertRulesTool, + registerListAlertDestinationsTool, + registerGetAlertRuleTool, + registerListAlertIncidentsTool, + registerListAlertChecksTool, + registerPreviewAlertRuleTool, + registerGetIncidentTimelineTool, + registerCreateAlertRuleTool, + registerUpdateAlertRuleTool, + registerDeleteAlertRuleTool, + registerListMaintenanceWindowsTool, + registerCreateMaintenanceWindowTool, + registerDeleteMaintenanceWindowTool, + registerListAlertSilencesTool, + registerCreateAlertSilenceTool, + registerEndAlertSilenceTool, + registerAcknowledgeAlertIncidentTool, + registerListEscalationChainsTool, + registerCreateEscalationChainTool, + registerUpdateEscalationChainTool, + registerDeleteEscalationChainTool, + registerListOnCallSchedulesTool, + registerWhoIsOnCallTool, + registerCreateOnCallScheduleTool, + registerUpdateOnCallScheduleTool, + registerDeleteOnCallScheduleTool, + registerCreateOnCallOverrideTool, + registerDeleteOnCallOverrideTool, + registerDescribeDashboardSchemaTool, + registerListDashboardsTool, + registerGetDashboardTool, + registerCreateDashboardTool, + registerUpdateDashboardTool, + registerAddDashboardWidgetTool, + registerDescribeWarehouseTablesTool, + registerUpdateDashboardWidgetTool, + registerRemoveDashboardWidgetTool, + registerReplaceDashboardWidgetsTool, + registerReorderDashboardWidgetsTool, + registerInspectChartDataTool, + registerComparePeriodsTool, + registerCompareOperationsTool, + registerExploreAttributesTool, + registerListServicesTool, + registerGetServiceTopOperationsTool, + registerServiceDeploymentsTool, + registerRouteUsageTool, + registerIngestFreshnessTool, + registerDbQueryVolumeTool, + registerListInfraTool, + registerInspectInfraTool, + registerIngestUsageTool, + registerGetInstrumentationRecommendationsTool, + registerAuditSetupTool, + registerListIntegrationsTool, + registerSearchConsoleQueriesTool, + registerSearchConsolePagesTool, + registerListSecurityFindingsTool, + registerInspectSecurityFindingTool, + registerListSecurityAuditRunsTool, + registerInspectSecurityAuditRunTool, + registerListSourcesTool, + registerListDataSourcesTool, + registerSearchDataSourcesTool, + registerDescribeDataSourceTool, + registerQueryDataSourceTool, + registerCiRunsTool, + registerCompareCommitsTool, + registerIntegrationWriteTools, + registerUptimeMonitorTools, + registerSloTools, + registerIngestRuleTools, + registerStatusPageTools, + registerSourceCodeTools, + registerSandboxTools, + registerPullRequestTools, + registerListErrorIssuesTool, + registerTransitionErrorIssueTool, + registerTransitionErrorIssuesTool, + registerSetIssueSeverityTool, + registerMergeErrorIssuesTool, + registerClaimErrorIssueTool, + registerReleaseErrorIssueTool, + registerCommentOnErrorIssueTool, + registerProposeFixTool, + registerLinkPullRequestTool, + registerListErrorIssueEventsTool, + registerGetInvestigationTool, + registerRegisterAgentTool, + registerSendMapleFeedbackTool, + registerListMapleFeedbackTool, + registerListErrorIncidentsTool, + registerGetErrorNotificationPolicyTool, + registerUpdateErrorNotificationPolicyTool, +] + +const mapleToolDefinitions = collectToolDefinitions(MAPLE_TOOL_REGISTERS) /** Handler-free registry view for schemas, permissions, MCP discovery, and tests. */ export const mapleToolCatalog: ReadonlyArray = Arr.map( @@ -573,56 +272,11 @@ export const mapleToolCatalog: ReadonlyArray = Arr.map( ({ run: _run, ...entry }) => entry, ) -const inputSchemas = new Map>() - -/** The published input schema, computed on first use and kept: a hot path, and deterministic. */ -export const inputSchemaOf = (entry: MapleToolCatalogEntry): Record => { - let schema = inputSchemas.get(entry.name) - if (schema === undefined) { - schema = toInputSchema(entry.schema) - inputSchemas.set(entry.name, schema) - } - return schema -} - -const parameterNames = (entry: MapleToolCatalogEntry): ReadonlyArray => { - const properties = inputSchemaOf(entry).properties - return typeof properties === "object" && properties !== null ? Rec.keys(properties) : [] -} - -const enumSpelling = (value: string): string => Str.replace(/[\s-]+/g, "_")(Str.toLowerCase(Str.trim(value))) - -/** - * An enum value as the model spelled it, read as the published one it means: `Feature Request` - * and `feature-request` are `feature_request`, a declared value alias is its target. Anything - * else is left for the decoder to reject with the allowed values. - */ -const canonicalEnumArguments = (entry: MapleToolCatalogEntry, input: unknown): unknown => { - if (!isArgumentRecord(input)) return input - const enums = enumValues(inputSchemaOf(entry)) - return Rec.map(input, (value, key) => { - const allowed = enums.get(key) - if (typeof value !== "string" || allowed === undefined || allowed.includes(value)) return value - const spelled = enumSpelling(value) - if (allowed.includes(spelled)) return spelled - const target = entry.valueAliases[key]?.[spelled] - return target !== undefined && allowed.includes(target) ? target : value - }) +const findDefinition = (name: string): MapleToolDefinition | undefined => { + const canonical = canonicalToolName(name) + return mapleToolDefinitions.find((candidate) => candidate.name === canonical) } -/** How a call's arguments are read before decoding: aliases applied, enum spellings fixed, unknowns dropped. */ -const normalizeFor = (entry: MapleToolCatalogEntry, input: unknown, nowMs?: number) => - normalizeArguments( - canonicalEnumArguments(entry, input), - parameterNames(entry), - entry.aliases, - enumValues(inputSchemaOf(entry)), - nowMs, - ) - -const isArgumentRecord = (value: unknown): value is Readonly> => - typeof value === "object" && value !== null && !Arr.isArray(value) - /** * A call read the way the dispatcher reads it, without running it: aliases applied, enum case * fixed, unknown keys reported, and whether the result decodes. Undefined for a name the registry @@ -671,172 +325,12 @@ export const mapleToolPhrase = (name: string): string | undefined => { export const mapleToolCatalogFor = (surface: McpToolSurface): ReadonlyArray => Arr.filter(mapleToolCatalog, (definition) => audienceAdmits(definition.audience, surface)) -const toDecodeErrorMessage = ( - definition: MapleToolDefinition, - error: unknown, - normalized: NormalizedArguments, -): string => - Schema.isSchemaError(error) - ? formatDecodeFailure(definition.name, error, inputSchemaOf(definition), normalized) - : String(error) - -const findDefinition = (name: string): MapleToolDefinition | undefined => { - const canonical = canonicalToolName(name) - return mapleToolDefinitions.find((candidate) => candidate.name === canonical) -} - -/** A registered tool this surface cannot see: a shared tool pointing at it is expected. */ -const isHiddenOn = (tool: string, surface: McpToolSurface): boolean => { - const target = findDefinition(tool) - return target !== undefined && !audienceAdmits(target.audience, surface) -} - -/** - * Whether a suggested call would decode on the surface it is shown on. A next call naming a - * parameter that was renamed, or a tool the caller cannot see, is worse than none. - */ -const isValidNextCall = (call: NextCall, surface: McpToolSurface): boolean => { - const target = findDefinition(call.tool) - if (target === undefined || !audienceAdmits(target.audience, surface)) return false - const normalized = normalizeFor(target, call.args) - return ( - normalized.unknown.length === 0 && - Schema.decodeUnknownOption(target.schema)(normalized.args, target.parseOptions)._tag === "Some" - ) +/** The whole registry as a lookup, for callers that already hold it. */ +const registryLookup: McpToolLookup = { + find: (name) => Effect.sync(() => findDefinition(name)), + namesFor: (surface) => Arr.map(mapleToolCatalogFor(surface), (entry) => entry.name), } -const finish = Effect.fnUntraced(function* ( - definition: MapleToolDefinition, - run: ToolRun, - warnings: ReadonlyArray, - surface: McpToolSurface, -) { - const invalid = Arr.filter(nextCallsOf(run.doc), (call) => !isValidNextCall(call, surface)) - const undecodable = Arr.filter(invalid, (call) => !isHiddenOn(call.tool, surface)) - if (undecodable.length > 0) { - yield* Effect.logWarning("MCP tool suggested a call that does not decode").pipe( - Effect.annotateLogs({ - "maple.mcp.tool": definition.name, - "maple.mcp.next_calls": Arr.join( - Arr.map(undecodable, (call) => call.tool), - ",", - ), - }), - ) - } - const doc = invalid.length === 0 ? run.doc : filterNextCalls(run.doc, (call) => !invalid.includes(call)) - const text = renderToolDocWithinBudget( - warnings.length === 0 ? doc : { ...doc, warnings: [...warnings, ...(doc.warnings ?? [])] }, - ) - const result: McpToolResult = { - content: [{ type: "text", text }], - ...(run.structured === undefined ? undefined : { structuredContent: run.structured }), - } - return result -}) - -/** - * The one raw registry entry point. Its full Effect environment is intentionally - * preserved; only `McpToolExecutor` may close it with tenant and app services. - * - * The surface is part of the lookup: an internal tool called from a surface it - * is not exposed on does not exist there, and gets the same answer as an unknown - * name, so the public transport cannot enumerate the internal set by probing. - */ -export const executeRegisteredMcpToolUnscoped = Effect.fn("McpToolRegistry.execute")(function* ( - name: string, - input: unknown, - surface: McpToolSurface, -) { - const definition = findDefinition(name) - if (!definition || !audienceAdmits(definition.audience, surface)) { - if (definition) { - yield* Effect.logWarning("MCP tool is not exposed on this surface").pipe( - Effect.annotateLogs({ "maple.mcp.tool": name, "maple.mcp.surface": surface }), - ) - } - return yield* new McpToolNotFoundError({ - toolName: name, - message: unknownToolMessage( - name, - Arr.map(mapleToolCatalogFor(surface), (entry) => entry.name), - ), - }) - } - - if (refusesReadOnlyCredential(definition.name, definition.hints.readOnly)) { - const tenant = yield* CurrentMcpTenant - const refusal = refusalFor(tenant, definition.name, definition.hints.readOnly) - if (refusal !== undefined) { - return yield* new McpAuthInvalidError({ - message: - refusal === "analyst" - ? `\`${definition.name}\` changes data. ${Policy.analystMessage}` - : `\`${definition.name}\` changes data, and this API key is read-only. Use a key with write access, or connect with OAuth.`, - reason: "insufficient_scope", - }) - } - } - - if (definition.scopeFamily !== undefined) { - const access = definition.hints.readOnly ? "read" : "write" - const tenant = yield* CurrentMcpTenant - const missing = Arr.findFirst( - Arr.ensure(definition.scopeFamily), - (family) => !scopeAllows(tenant.scopes, { family, access }), - ) - if (Option.isSome(missing)) { - return yield* new McpAuthInvalidError({ - message: `\`${definition.name}\` needs the \`${missing.value}:${access}\` scope, which this API key lacks. Add it to the key, or use a full-access key.`, - reason: "insufficient_scope", - }) - } - } - - const nowMs = yield* Clock.currentTimeMillis - const normalized = normalizeFor(definition, input ?? {}, nowMs) - yield* Effect.annotateCurrentSpan({ - "maple.mcp.tool": definition.name, - "maple.mcp.tool.arguments": Arr.join( - Object.keys(typeof input === "object" && input !== null ? input : {}).sort(), - ",", - ), - ...(normalized.unknown.length === 0 - ? undefined - : { - "maple.mcp.tool.unknown_arguments": Arr.join( - Arr.map(normalized.unknown, ({ key }) => key), - ",", - ), - }), - ...(normalized.renamed.length === 0 - ? undefined - : { - "maple.mcp.tool.aliased_arguments": Arr.join( - Arr.map(normalized.renamed, ([from]) => from), - ",", - ), - }), - }) - const decoded = yield* Schema.decodeUnknownEffect(definition.schema)( - normalized.args, - definition.parseOptions, - ).pipe( - Effect.mapError( - (error) => - new McpDecodeError({ - message: toDecodeErrorMessage(definition, error, normalized), - }), - ), - ) - - const windowNotes = new WindowNotes() - const run = yield* definition.run(decoded).pipe(Effect.provideService(CurrentWindowNotes, windowNotes)) - yield* Effect.logInfo("Tool completed") - return yield* finish( - definition, - { ...run, doc: windowNotes.decorate(run.doc) }, - argumentWarnings(normalized, definition.name), - surface, - ) -}) +/** {@link executeRegisteredTool} over the whole registry. Only `McpToolExecutor` closes its environment. */ +export const executeRegisteredMcpToolUnscoped = (name: string, input: unknown, surface: McpToolSurface) => + executeRegisteredTool(registryLookup, name, input, surface) diff --git a/apps/ai/src/mcp/tools/tool-lookup.test.ts b/apps/ai/src/mcp/tools/tool-lookup.test.ts new file mode 100644 index 0000000000..db9f744f64 --- /dev/null +++ b/apps/ai/src/mcp/tools/tool-lookup.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from "@effect/vitest" +import type { McpToolSurface } from "@maple/domain/mcp-manifest" +import { Effect, Array as Arr, Record as Rec } from "effect" +import { MCP_TOOL_MODULES } from "../tool-modules.generated" +import { mapleToolCatalog, mapleToolCatalogFor, mapleToolTitle } from "./registry" +import { makeModuleToolLookup, mcpToolTitle } from "./tool-lookup" +import { canonicalToolName, TOOL_NAME_ALIASES } from "./tool-name-aliases" +import type { McpToolRegistrar } from "./types" + +const SURFACES: ReadonlyArray = ["mcp", "chat", "bot", "workflow", "rpc"] + +const definedBy = (entry: (typeof MCP_TOOL_MODULES)[number]) => + Effect.promise(entry.load).pipe( + Effect.map((register) => { + const names: Array = [] + const registrar: McpToolRegistrar = { define: (spec) => void names.push(spec.name) } + register(registrar) + return names + }), + ) + +describe("MCP_TOOL_MODULES", () => { + // Generated by `bun run --cwd apps/ai mcp:tools`; a new, renamed or moved tool fails here until rerun. + it("names every registered tool in catalog order, then every retired alias", () => { + expect(Arr.map(MCP_TOOL_MODULES, (entry) => entry.name)).toEqual([ + ...Arr.map(mapleToolCatalog, (entry) => entry.name), + ...Rec.keys(TOOL_NAME_ALIASES), + ]) + for (const entry of MCP_TOOL_MODULES) { + const tool = canonicalToolName(entry.name) + const registered = mapleToolCatalog.find((candidate) => candidate.name === tool) + expect({ tool: entry.tool, title: entry.title, audience: entry.audience }, entry.name).toEqual({ + tool, + title: registered?.title, + audience: registered?.audience, + }) + } + }) + + it.effect("loads, for each name, a module that registers the tool it claims", () => + Effect.forEach(MCP_TOOL_MODULES, (entry) => + Effect.map(definedBy(entry), (names) => expect(names, entry.name).toContain(entry.tool)), + ), + ) +}) + +describe("makeModuleToolLookup", () => { + it.effect("defines exactly the tool a name means, the same one the full registry has", () => + Effect.gen(function* () { + const lookup = yield* makeModuleToolLookup + yield* Effect.forEach(MCP_TOOL_MODULES, (entry) => + Effect.gen(function* () { + const definition = yield* lookup.find(entry.name) + const registered = mapleToolCatalog.find((candidate) => candidate.name === entry.tool) + expect(definition?.name, entry.name).toBe(entry.tool) + expect(definition?.description).toBe(registered?.description) + expect(definition?.outputSchema).toBe(registered?.outputSchema) + }), + ) + }), + ) + + it.effect("knows no name outside the registry, prototype keys included", () => + Effect.gen(function* () { + const lookup = yield* makeModuleToolLookup + yield* Effect.forEach(["not_a_maple_tool", "__proto__", "constructor", "toString"], (name) => + Effect.map(lookup.find(name), (definition) => { + expect(definition, name).toBeUndefined() + expect(mcpToolTitle(name)).toBeUndefined() + }), + ) + }), + ) + + it.effect("lists what each surface may see, as the full registry does", () => + Effect.gen(function* () { + const lookup = yield* makeModuleToolLookup + Arr.forEach(SURFACES, (surface) => + expect(lookup.namesFor(surface), surface).toEqual( + Arr.map(mapleToolCatalogFor(surface), (entry) => entry.name), + ), + ) + }), + ) + + it("titles a tool as the full registry does, and an alias not at all", () => { + for (const entry of MCP_TOOL_MODULES) { + expect(mcpToolTitle(entry.name), entry.name).toBe(mapleToolTitle(entry.name)) + } + }) +}) diff --git a/apps/ai/src/mcp/tools/tool-lookup.ts b/apps/ai/src/mcp/tools/tool-lookup.ts new file mode 100644 index 0000000000..2458d32e21 --- /dev/null +++ b/apps/ai/src/mcp/tools/tool-lookup.ts @@ -0,0 +1,47 @@ +import type { McpToolSurface } from "@maple/domain/mcp-manifest" +import { Effect, Array as Arr } from "effect" +import { MCP_TOOL_MODULES } from "../tool-modules.generated" +import { audienceAdmits } from "./types" +import { collectToolDefinitions, type McpToolLookup, type McpToolModule } from "./registry-core" + +const modulesByName: ReadonlyMap = new Map( + Arr.map(MCP_TOOL_MODULES, (entry) => [entry.name, entry]), +) + +/** Registered tools only, in catalog order; aliases resolve through them. */ +const registeredModules = Arr.filter(MCP_TOOL_MODULES, (entry) => entry.name === entry.tool) + +/** A tool's human title ("Search Repository Checkout"), or undefined for a name outside the registry. */ +export const mcpToolTitle = (name: string): string | undefined => { + const entry = modulesByName.get(name) + return entry !== undefined && entry.tool === name ? entry.title : undefined +} + +/** Imports one tool's module and defines that tool alone, through the registry's `define`. */ +const loadDefinition = (entry: McpToolModule) => + Effect.promise(entry.load).pipe( + Effect.map((register) => collectToolDefinitions([register], (name) => name === entry.tool)[0]), + ) + +/** + * A lookup that imports a tool's module the first time a call names it, then keeps it. Built + * once per executor: a cold `tools/call` pays for its own tool, not the whole registry. + */ +export const makeModuleToolLookup = Effect.gen(function* () { + const cachedLoads = yield* Effect.forEach(registeredModules, (entry) => + Effect.map(Effect.cached(loadDefinition(entry)), (load) => [entry.tool, load] as const), + ) + const loaders = new Map(cachedLoads) + const lookup: McpToolLookup = { + find: (name) => { + const entry = modulesByName.get(name) + return (entry === undefined ? undefined : loaders.get(entry.tool)) ?? Effect.undefined + }, + namesFor: (surface: McpToolSurface) => + Arr.map( + Arr.filter(registeredModules, (entry) => audienceAdmits(entry.audience, surface)), + (entry) => entry.name, + ), + } + return lookup +}) From 2dab83b39e86f44bcbb9bf60293fc895f945ede2 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 09:38:11 +0100 Subject: [PATCH 2/4] perf(backend): import the security audit store port, not the package root SecurityAuditStore needs AuditStore, AuditStoreError and a few types, but imported the @maple/security-audit root, which pulls the engine, prompts, skill files and validators into the MCP tool graph. A new ./store subpath exports the port alone. --- .../src/services/security-audit/SecurityAuditStore.ts | 2 +- packages/security-audit/package.json | 3 ++- packages/security-audit/src/store.ts | 6 ++++++ 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 packages/security-audit/src/store.ts diff --git a/packages/backend/src/services/security-audit/SecurityAuditStore.ts b/packages/backend/src/services/security-audit/SecurityAuditStore.ts index e09add5f42..1f864b41f2 100644 --- a/packages/backend/src/services/security-audit/SecurityAuditStore.ts +++ b/packages/backend/src/services/security-audit/SecurityAuditStore.ts @@ -49,7 +49,7 @@ import { type AuditStoreApi, type EstimatedSeverity, type Finding, -} from "@maple/security-audit" +} from "@maple/security-audit/store" import { AuditReportsRecord, CoverageUnit, diff --git a/packages/security-audit/package.json b/packages/security-audit/package.json index 3eb4a2fc5b..047b306ef5 100644 --- a/packages/security-audit/package.json +++ b/packages/security-audit/package.json @@ -7,7 +7,8 @@ ".": "./src/index.ts", "./schema": "./src/schema.ts", "./ecosystems": "./src/ecosystems.ts", - "./scope-path": "./src/scope-path.ts" + "./scope-path": "./src/scope-path.ts", + "./store": "./src/store.ts" }, "scripts": { "test": "bun scripts/vendor-skill.ts --check && node --test skill/validate-findings.test.cjs skill/validate-coverage-ledger.test.cjs && vitest run", diff --git a/packages/security-audit/src/store.ts b/packages/security-audit/src/store.ts new file mode 100644 index 0000000000..4ca1697ba4 --- /dev/null +++ b/packages/security-audit/src/store.ts @@ -0,0 +1,6 @@ +/** + * The run store's port alone: what a persistence adapter needs, without the engine, prompts, + * skill files or validators the package root brings along. + */ +export { AuditStore, AuditStoreError, type AuditEvent, type AuditStoreApi } from "./engine/ports" +export type { EstimatedSeverity, Finding } from "./schema" From 91d50c0e4b57fd19bbcd8bbc06aa350c0f16a8f7 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 09:39:49 +0100 Subject: [PATCH 3/4] fix(ai): report a tools/call that waited on a running build as joined maple.mcp.executor_build said reused for any request that did not build the executor itself, including the first request of an isolate that waited on another request's running build. It now says joined unless the build had completed before the request asked, so reused means the call paid nothing. The build already prepares the per-tool lookup, so prewarm covers it too. --- apps/ai/src/mcp/executor-loader.test.ts | 37 +++++++++++++++++++++++++ apps/ai/src/mcp/executor-loader.ts | 21 ++++++++++---- 2 files changed, 53 insertions(+), 5 deletions(-) diff --git a/apps/ai/src/mcp/executor-loader.test.ts b/apps/ai/src/mcp/executor-loader.test.ts index 9a45fee3d8..627bb84e39 100644 --- a/apps/ai/src/mcp/executor-loader.test.ts +++ b/apps/ai/src/mcp/executor-loader.test.ts @@ -376,4 +376,41 @@ describe("McpToolExecutorLoader", () => { prewarmed: ["prewarm", "reused"], }) }) + + it("reports a tools/call that waited on another request's running build as joined, not reused", async () => { + const gate = Deferred.makeUnsafe() + const entered = Deferred.makeUnsafe() + const { counts, loader } = countingGraph({ failFirstBuild: false, gate, entered }) + const kinds = await Effect.runPromise( + Effect.gen(function* () { + const executors = yield* McpToolExecutorLoader + const builder = yield* Effect.forkChild(executors.loadReportingBuild) + yield* Deferred.await(entered) + // Asks while the only build is held at the gate. + const waiter = yield* Effect.forkChild(executors.loadReportingBuild) + yield* Effect.yieldNow + yield* Deferred.succeed(gate, undefined) + const first = yield* Fiber.join(builder) + const second = yield* Fiber.join(waiter) + const third = yield* Effect.forkChild(executors.loadReportingBuild).pipe( + Effect.flatMap(Fiber.join), + ) + return [first.build, second.build, third.build] + }).pipe( + Effect.provide( + loader.pipe( + Layer.provideMerge( + Layer.mergeAll(createTestDb(createdDbs).layer, SandboxFetcher.none), + ), + ), + ), + Effect.scoped, + ), + ) + expect({ kinds, ...counts() }).toEqual({ + kinds: ["inline", "joined", "reused"], + imports: 1, + builds: 1, + }) + }) }) diff --git a/apps/ai/src/mcp/executor-loader.ts b/apps/ai/src/mcp/executor-loader.ts index 0a619cfbde..4090d10884 100644 --- a/apps/ai/src/mcp/executor-loader.ts +++ b/apps/ai/src/mcp/executor-loader.ts @@ -15,10 +15,13 @@ export type McpToolServicesLayer = Layer.Layer< > /** - * Where a `tools/call` got its executor: built on its own request (`inline`), from a background - * prewarm it is the first call to use (`prewarm`), or already in use by an earlier call (`reused`). + * Where a `tools/call` got its executor, as `maple.mcp.executor_build` records it: + * - `inline`: this request built it, and paid the whole build. + * - `prewarm`: the first call to use a background prewarm's build, finished or still running. + * - `joined`: another request's build was still running when this one asked, so it waited on it. + * - `reused`: the build had already completed when this request asked. */ -export type McpToolExecutorBuildKind = "inline" | "prewarm" | "reused" +export type McpToolExecutorBuildKind = "inline" | "prewarm" | "joined" | "reused" /** Span attribute naming the {@link McpToolExecutorBuildKind}, on the request and the build span. */ export const MCP_EXECUTOR_BUILD_ATTRIBUTE = "maple.mcp.executor_build" @@ -47,7 +50,8 @@ export class McpToolsUnavailableError extends Schema.TaggedError executor), loadReportingBuild: Effect.gen(function* () { const fiber = yield* Effect.fiberId + // Read before waiting: a request that waits on a running build did not reuse it. + const builtBefore = yield* Ref.get(ready) const { executor, builder, prewarmed } = yield* cached if (builder === fiber) return { executor, build: "inline" as const } const claimed = prewarmed && (yield* Ref.getAndSet(prewarmUnclaimed, false)) - return { executor, build: claimed ? ("prewarm" as const) : ("reused" as const) } + const build: McpToolExecutorBuildKind = claimed + ? "prewarm" + : builtBefore + ? "reused" + : "joined" + return { executor, build } }), prewarm: Effect.gen(function* () { if (yield* Ref.get(ready)) return From 3ab9fdaf4b3aa9ba850ced42e26cba8f7fa410e9 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 09:47:47 +0100 Subject: [PATCH 4/4] fix(ai): resume tool-load waiters in their own request, keep results when a hint fails Per-tool loads now use cachedRecoverable, like the executor build: waiters await a Promise, so workerd resumes each in its own request's I/O context, and a failed import is retried instead of cached. Next-call validation imports the suggested tool's module. A call that already ran no longer fails when that import does; the hint is dropped and a warning logged. --- apps/ai/src/mcp/tools/registry-core.test.ts | 57 +++++++++++++++++++++ apps/ai/src/mcp/tools/registry-core.ts | 13 ++++- apps/ai/src/mcp/tools/tool-lookup.ts | 4 +- 3 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 apps/ai/src/mcp/tools/registry-core.test.ts diff --git a/apps/ai/src/mcp/tools/registry-core.test.ts b/apps/ai/src/mcp/tools/registry-core.test.ts new file mode 100644 index 0000000000..9d68ef174b --- /dev/null +++ b/apps/ai/src/mcp/tools/registry-core.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from "@effect/vitest" +import { Context, Effect, Schema } from "effect" +import { executeRegisteredTool, type MapleToolDefinition, type McpToolLookup } from "./registry-core" + +const definition = (name: string, next: ReadonlyArray): MapleToolDefinition => ({ + name, + title: name, + description: name, + schema: Schema.Struct({}), + parseOptions: {}, + outputSchema: Schema.Unknown, + hints: { readOnly: true }, + aliases: {}, + valueAliases: {}, + audience: "public", + phrases: [name], + run: () => + Effect.succeed({ + doc: { + title: `Ran ${name}`, + blocks: [], + next: next.map((tool) => ({ tool, args: {}, why: `then ${tool}` })), + }, + structured: undefined, + }), +}) + +// `echo` suggests a loadable tool and one whose module fails to import. +const lookup: McpToolLookup = { + find: (name) => + name === "echo" + ? Effect.succeed(definition("echo", ["healthy", "broken"])) + : name === "healthy" + ? Effect.succeed(definition("healthy", [])) + : name === "broken" + ? Effect.die(new Error("import failed")) + : Effect.undefined, + namesFor: () => ["echo", "healthy", "broken"], +} + +// The registry's requirements name every tool's services; these tools reach none of them. +const withoutUnreachedServices = (effect: Effect.Effect): Effect.Effect => + Effect.provide(effect, Context.makeUnsafe(new Map())) + +describe("executeRegisteredTool", () => { + it.effect("keeps the result and drops a suggested call whose tool fails to load", () => + Effect.gen(function* () { + const result = yield* executeRegisteredTool(lookup, "echo", {}, "mcp").pipe( + withoutUnreachedServices, + ) + const text = result.content.map((block) => block.text).join("\n") + expect(text).toContain("Ran echo") + expect(text).toContain("healthy") + expect(text).not.toContain("broken") + }), + ) +}) diff --git a/apps/ai/src/mcp/tools/registry-core.ts b/apps/ai/src/mcp/tools/registry-core.ts index 5eee3f4cd9..665ae48dc6 100644 --- a/apps/ai/src/mcp/tools/registry-core.ts +++ b/apps/ai/src/mcp/tools/registry-core.ts @@ -441,7 +441,18 @@ const finish = Effect.fnUntraced(function* ( surface: McpToolSurface, ) { const checked = yield* Effect.forEach(nextCallsOf(run.doc), (call) => - checkNextCall(lookup, call, surface), + checkNextCall(lookup, call, surface).pipe( + // The call already ran: a suggested tool whose module fails to load drops the hint, not the result. + Effect.catchCause((cause) => + Effect.logWarning("MCP tool suggested a call whose tool failed to load", cause).pipe( + Effect.annotateLogs({ + "maple.mcp.tool": definition.name, + "maple.mcp.next_call": call.tool, + }), + Effect.as({ call, valid: false, hidden: true }), + ), + ), + ), ) const invalid = Arr.filter(checked, (check) => !check.valid) const undecodable = Arr.filter(invalid, (check) => !check.hidden) diff --git a/apps/ai/src/mcp/tools/tool-lookup.ts b/apps/ai/src/mcp/tools/tool-lookup.ts index 2458d32e21..0bd363de26 100644 --- a/apps/ai/src/mcp/tools/tool-lookup.ts +++ b/apps/ai/src/mcp/tools/tool-lookup.ts @@ -1,4 +1,5 @@ import type { McpToolSurface } from "@maple/domain/mcp-manifest" +import { cachedRecoverable } from "@maple/infra/cached-recoverable" import { Effect, Array as Arr } from "effect" import { MCP_TOOL_MODULES } from "../tool-modules.generated" import { audienceAdmits } from "./types" @@ -29,7 +30,8 @@ const loadDefinition = (entry: McpToolModule) => */ export const makeModuleToolLookup = Effect.gen(function* () { const cachedLoads = yield* Effect.forEach(registeredModules, (entry) => - Effect.map(Effect.cached(loadDefinition(entry)), (load) => [entry.tool, load] as const), + // Waiters await a Promise so each resumes in its own request's I/O context; a failed import is retried. + Effect.map(cachedRecoverable(loadDefinition(entry)), (load) => [entry.tool, load] as const), ) const loaders = new Map(cachedLoads) const lookup: McpToolLookup = {