fix: merge globals into mcp tool schemas and openapi operations (#260)

* fix: merge globals into mcp tool schemas and openapi operations

Global options were only parsed from argv and HTTP command routes. MCP
tools (stdio and HTTP) omitted them from input schemas and ran commands
and middleware with empty globals, and the generated OpenAPI document
left them out of every operation.

Merge the globals schema into each tool's input schema and OpenAPI
operation, and split global keys back out of tool calls, validating
them with the globals schema before middleware runs. A global wins over
a command option of the same name, as on the CLI and over HTTP.

* fix: keep mcp positional values that share a global's name

* fix: avoid reparsing mcp globals after direct tool validation

* fix: type mcp serve middleware globals from the globals schema

* fix: document the mcp callTool globals option

* fix: mark the mcp globals changeset as minor

Author: brendanjryan

.changeset/mcp-globals.md

@@ -0,0 +1,5 @@
+---
+'incur': minor
+---
+
+Added `globals` support to MCP tools and the generated OpenAPI document. Global options are now merged into every MCP tool's input schema (stdio `--mcp` and HTTP `/mcp`) and into each OpenAPI operation's query parameters or request body. MCP tool calls split them back out, apply the globals schema's defaults and validation once, and pass them to commands and middleware as `globals`. `Mcp.serve` accepts a `globals` schema for CLIs that serve their command map directly, and types `c.globals` in its middlewares from it. A global wins over a command option of the same name, as on the CLI.

src/Cli.test.ts

@@ -6644,7 +6644,7 @@ describe('fetch', () => {
     }
 
     async function mcpRequest(
-      cli: Cli.Cli<any, any, any>,
+      cli: Cli.Cli<any, any, any, any>,
       body: unknown,
       sessionId?: string,
       extraHeaders: Record<string, string> = {},
@@ -7020,6 +7020,48 @@ describe('fetch', () => {
       `)
     })
 
+    test('POST /mcp merges globals into tool schemas and passes them to calls', async () => {
+      const cli = Cli.create('test', {
+        globals: z.object({ rpcUrl: z.string().default('fallback') }),
+        mcp: { tools: { discovery: 'direct' } },
+        vars: z.object({ rpcUrl: z.string().default('') }),
+        version: '1.0.0',
+      })
+        .use(async (c, next) => {
+          c.set('rpcUrl', c.globals.rpcUrl)
+          await next()
+        })
+        .command('ping', {
+          options: z.object({ limit: z.number().default(0) }),
+          run: (c) => ({ globals: c.globals, limit: c.options.limit, middleware: c.var.rpcUrl }),
+        })
+
+      const list = await mcpRequest(cli, {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/list',
+        params: {},
+      })
+      const call = await mcpRequest(cli, {
+        jsonrpc: '2.0',
+        id: 2,
+        method: 'tools/call',
+        params: { name: 'ping', arguments: { limit: 3, rpcUrl: 'http://example.com' } },
+      })
+
+      const [tool] = (await list.json()).result.tools
+      expect(Object.keys(tool.inputSchema.properties)).toEqual(['limit', 'rpcUrl'])
+      expect(JSON.parse((await call.json()).result.content[0].text)).toMatchInlineSnapshot(`
+        {
+          "globals": {
+            "rpcUrl": "http://example.com",
+          },
+          "limit": 3,
+          "middleware": "http://example.com",
+        }
+      `)
+    })
+
     test('POST /mcp exposes per-request headers to command context', async () => {
       const cli = Cli.create('test', {
         version: '1.0.0',
@@ -7710,6 +7752,20 @@ describe('--mcp', () => {
     }
   })
 
+  test('globals from create() are forwarded to Mcp.serve', async () => {
+    const spy = vi.spyOn(Mcp, 'serve').mockResolvedValue(undefined)
+    try {
+      const globals = z.object({ rpcUrl: z.string() })
+      const cli = Cli.create('test', { globals })
+      cli.command('ping', { run: () => ({ pong: true }) })
+      await cli.serve(['--mcp'])
+      expect(spy).toHaveBeenCalledOnce()
+      expect(spy.mock.calls[0]![3]?.globals).toBe(globals)
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
   test('instructions is omitted from Mcp.serve when not set in create()', async () => {
     const spy = vi.spyOn(Mcp, 'serve').mockResolvedValue(undefined)
     try {

src/Cli.ts

@@ -905,6 +905,7 @@ async function serveImpl(
     await Mcp.serve(options.mcp?.name ?? name, options.version ?? '0.0.0', commands, {
       middlewares: options.middlewares,
       env: options.envSchema,
+      globals: options.globals?.schema,
       vars: options.vars,
       version: options.version,
       ...(options.mcp?.instructions ? { instructions: options.mcp.instructions } : undefined),
@@ -2000,6 +2001,7 @@ declare namespace fetchImpl {
           mcpOptions?: {
             middlewares?: MiddlewareHandler[] | undefined
             env?: z.ZodObject<any> | undefined
+            globals?: z.ZodObject<any> | undefined
             vars?: z.ZodObject<any> | undefined
           },
         ) => Promise<Response>)
@@ -2028,6 +2030,7 @@ function createMcpHttpHandler(
       | {
           middlewares?: MiddlewareHandler[] | undefined
           env?: z.ZodObject<any> | undefined
+          globals?: z.ZodObject<any> | undefined
           vars?: z.ZodObject<any> | undefined
         }
       | undefined,
@@ -2047,6 +2050,7 @@ function createMcpHttpHandler(
     Mcp.registerTools(server, commands, {
       env: mcpOptions?.env,
       fromJsonSchema,
+      globals: mcpOptions?.globals,
       middlewares: mcpOptions?.middlewares,
       name,
       request: (extra) => extra?.http?.req,
@@ -2074,6 +2078,7 @@ function createMcpHttpHandler(
     mcpOptions?: {
       middlewares?: MiddlewareHandler[] | undefined
       env?: z.ZodObject<any> | undefined
+      globals?: z.ZodObject<any> | undefined
       vars?: z.ZodObject<any> | undefined
     },
   ): Promise<Response> => {
@@ -2152,6 +2157,7 @@ function generatedOpenapi(
   const openapiCli = { name, description: options.description } as Cli
   toCommands.set(openapiCli, commands)
   if (options.rootCommand) toRootDefinition.set(openapiCli as unknown as Root, options.rootCommand)
+  if (options.globals) toGlobals.set(openapiCli, options.globals)
   return Openapi.fromCli(openapiCli, {
     title: name,
     ...(options.version ? { version: options.version } : undefined),
@@ -2189,6 +2195,7 @@ async function fetchImpl(
     return options.mcpHandler(req, commands, {
       middlewares: options.middlewares,
       env: options.envSchema,
+      globals: options.globals?.schema,
       vars: options.vars,
     })
 
@@ -3046,6 +3053,7 @@ async function runMcpDoctor(
     output,
     middlewares: options.middlewares,
     env: options.envSchema,
+    globals: options.globals?.schema,
     vars: options.vars,
     version: options.version,
     ...(options.mcp?.instructions ? { instructions: options.mcp.instructions } : undefined),
@@ -3443,7 +3451,7 @@ export type GlobalsDescriptor = {
 }
 
 /** @internal Maps CLI instances to their globals schema and alias map. */
-const toGlobals = new WeakMap<Cli, GlobalsDescriptor>()
+export const toGlobals = new WeakMap<Cli, GlobalsDescriptor>()
 
 /** @internal Maps root CLI instances to their command aliases. */
 const toRootAliases = new WeakMap<Root, string[]>()

src/Mcp.test-d.ts

@@ -0,0 +1,28 @@
+import { Mcp, z } from 'incur'
+import { expectTypeOf, test } from 'vitest'
+
+test('globals type flows to Mcp.serve middleware context', () => {
+  void Mcp.serve('test', '1.0.0', new Map(), {
+    globals: z.object({
+      network: z.enum(['mainnet', 'testnet']).default('mainnet'),
+      rpcUrl: z.string().transform((value) => new URL(value)),
+    }),
+    middlewares: [
+      (c, next) => {
+        expectTypeOf(c.globals).toEqualTypeOf<{ network: 'mainnet' | 'testnet'; rpcUrl: URL }>()
+        return next()
+      },
+    ],
+  })
+})
+
+test('without globals, Mcp.serve middleware sees empty globals', () => {
+  void Mcp.serve('test', '1.0.0', new Map(), {
+    middlewares: [
+      (c, next) => {
+        expectTypeOf(c.globals).toEqualTypeOf<{}>()
+        return next()
+      },
+    ],
+  })
+})