Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .oxfmtrc.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -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/**",
Expand Down
79 changes: 70 additions & 9 deletions apps/ai/scripts/generate-mcp-tool-descriptors.ts
Original file line number Diff line number Diff line change
@@ -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<string, Pick<ToolModuleSource, "module" | "register">>
> => {
const found = new Map<string, Pick<ToolModuleSource, "module" | "register">>()
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<string, unknown> = 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}.`)
}
}
18 changes: 10 additions & 8 deletions apps/ai/src/mcp/dispatcher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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,
Expand All @@ -50,8 +52,7 @@ const dispatchInSpan = Effect.fn("McpToolDispatcher.call")(function* (
// solely because each handler happens to carry its own `McpTool.<name>` 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")),
Expand Down Expand Up @@ -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({
Expand Down Expand Up @@ -214,6 +215,8 @@ export class McpToolExecutor extends Context.Service<McpToolExecutor, McpToolExe
const source = yield* VcsSourceService
const dataSources = yield* ExternalDataSourceService
const featureFlags = yield* OrganizationFeatureFlagsService
// Each tool's module loads on the first call that names it, not the whole registry.
const tools = yield* makeModuleToolLookup

const execute = Effect.fn("McpToolExecutor.execute")(function* (
tenant: TenantContext,
Expand Down Expand Up @@ -241,17 +244,16 @@ export class McpToolExecutor extends Context.Service<McpToolExecutor, McpToolExe
}),
)
}
const result = yield* callMcpToolUnscoped(name, input, surface).pipe(
const result = yield* callMcpToolUnscoped(tools, name, input, surface).pipe(
Effect.provideService(CurrentMcpTenant, tenant),
Effect.provide(runtimeServices),
)
// Every tool call is a read of (or change to) org data; the entry
// carries the tool, its parameters, and whether it failed in-band.
const registry = yield* loadRegistry
yield* recordMcpToolAudit({
tenant,
name,
title: registry.mapleToolTitle(name),
title: mcpToolTitle(name),
input,
surface,
isError: result.isError === true,
Expand Down
37 changes: 37 additions & 0 deletions apps/ai/src/mcp/executor-loader.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -376,4 +376,41 @@ describe("McpToolExecutorLoader", () => {
prewarmed: ["prewarm", "reused"],
})
})

it("reports a tools/call that waited on another request's running build as joined, not reused", async () => {
const gate = Deferred.makeUnsafe<void>()
const entered = Deferred.makeUnsafe<void>()
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,
})
})
})
21 changes: 16 additions & 5 deletions apps/ai/src/mcp/executor-loader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -47,7 +50,8 @@ export class McpToolsUnavailableError extends Schema.TaggedError<McpToolsUnavail
* The tool executor, imported and built on first use, once per isolate.
*
* The executor's service graph is most of the Worker's code. `initialize`, the resource and
* prompt lists and 401s never run a tool, so they must not pay to load or build it.
* prompt lists and 401s never run a tool, so they must not pay to load or build it. The build
* also prepares the per-tool lookup, so a call after it imports only its own tool's module.
*/
export class McpToolExecutorLoader extends Context.Service<
McpToolExecutorLoader,
Expand Down Expand Up @@ -122,10 +126,17 @@ export class McpToolExecutorLoader extends Context.Service<
load: Effect.map(cached, ({ executor }) => 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
Expand Down
6 changes: 3 additions & 3 deletions apps/ai/src/mcp/tool-catalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
32 changes: 32 additions & 0 deletions apps/ai/src/mcp/tool-descriptors-render.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<ToolModuleSource>): 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<McpToolModule> = [",
...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",
)
Loading
Loading