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 { 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 diff --git a/apps/ai/src/mcp/tool-catalog.ts b/apps/ai/src/mcp/tool-catalog.ts index bbb73cc77f..f26e6fd2f2 100644 --- a/apps/ai/src/mcp/tool-catalog.ts +++ b/apps/ai/src/mcp/tool-catalog.ts @@ -3,8 +3,8 @@ import { Effect } from "effect" /** * The tool catalog, loaded on the first call that needs it rather than with this module. * - * It is the largest chunk in the Worker, and most cold `/mcp` requests (`initialize`, the - * resource and prompt lists, 401s) never touch a tool. The dynamic import also breaks the - * registry -> 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.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 new file mode 100644 index 0000000000..665ae48dc6 --- /dev/null +++ b/apps/ai/src/mcp/tools/registry-core.ts @@ -0,0 +1,586 @@ +// 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).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) + 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..0bd363de26 --- /dev/null +++ b/apps/ai/src/mcp/tools/tool-lookup.ts @@ -0,0 +1,49 @@ +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" +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) => + // 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 = { + 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 +}) 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"