zuplo 7.6.0 → 7.6.1

package/docs/handlers/mcp-server.mdx

@@ -98,6 +98,13 @@ The MCP Server handler supports the following configuration options:
 - `operations` - An array of operation references to register with the MCP
   server. Each operation can be a tool, prompt, or resource based on its
   `x-zuplo-route.mcp` configuration.
+- `toolInputStyle` (optional, default `flat`) - How generated tools advertise an
+  operation's inputs. With `flat`, a request body's properties and the
+  operation's path, query, and header parameters all become top-level tool
+  arguments. With `nested`, each input channel stays its own object (`body`,
+  `queryParams`, `pathParams`, `headers`). Flat tools accept the nested form
+  too, so switching styles doesn't break existing clients. See
+  [Tool input schemas](../mcp-server/tools.mdx#tool-input-schemas).
 
 ### MCP `2025-06-18` Global Options
 

package/docs/mcp-server/tools.mdx

@@ -140,6 +140,176 @@ array:
 See further details in the
 [MCP Server Handler documentation](../handlers/mcp-server.mdx).
 
+## Tool input schemas
+
+Zuplo derives each tool's `inputSchema` from the operation's OpenAPI definition
+and advertises it as a single flat object. The request body's properties and the
+operation's path, query, and header parameters all become top-level tool
+arguments, which is the shape MCP clients send on a first call.
+
+When a client calls the tool, the gateway routes each argument back to the
+channel it came from, so a body field lands in the request body and a query
+parameter lands in the URL.
+
+The weather route above declares one required query parameter, so its tool takes
+one required argument:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "location": {
+      "type": "string"
+    }
+  },
+  "required": ["location"],
+  "additionalProperties": false
+}
+```
+
+A request body works the same way — its fields are the tool's arguments. Given
+this operation:
+
+```json
+{
+  "/orders": {
+    "post": {
+      "operationId": "createOrder",
+      "requestBody": {
+        "required": true,
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "productId": { "type": "string" },
+                "quantity": { "type": "number" }
+              },
+              "required": ["productId"],
+              "additionalProperties": false
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The tool advertises the body's fields directly:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string" },
+    "quantity": { "type": "number" }
+  },
+  "required": ["productId"],
+  "additionalProperties": false
+}
+```
+
+And a call passes them at the top level:
+
+```json
+{
+  "name": "createOrder",
+  "arguments": {
+    "productId": "sku-123",
+    "quantity": 2
+  }
+}
+```
+
+:::note
+
+Parameters declared with `in: cookie` aren't exposed as tool arguments.
+
+:::
+
+### Undeclared arguments
+
+Your own OpenAPI schema decides whether an argument the tool doesn't declare is
+rejected:
+
+- **The schema sets `additionalProperties: false`.** The tool's flat schema is
+  closed too, and an undeclared argument fails with JSON-RPC error `-32602`.
+- **The schema omits `additionalProperties`.** JSON Schema permits extras, so
+  the tool accepts the argument and forwards it in the request body.
+
+Set `additionalProperties: false` on a request body schema when you want the
+gateway to reject fields a model invented rather than pass them upstream.
+
+An argument routes to a request header only when a header parameter declares
+that exact name. An undeclared argument never becomes an upstream header.
+
+### When arguments stay nested
+
+Some operations can't be flattened without changing what the tool accepts. Those
+tools keep the nested shape, and the MCP server logs the reason when it
+registers the tool:
+
+- **Two channels declare the same name.** A `limit` query parameter alongside a
+  `limit` body field, for example. The whole schema stays nested and the server
+  logs a warning. Rename one of them to get flat arguments.
+- **The request body isn't a plain object.** An array, a string, or a body built
+  from `oneOf`, `anyOf`, or `allOf` has no property names to hoist. Neither does
+  one that constrains the object as a whole, through `minProperties`,
+  `patternProperties`, or `dependentRequired`. The parameters still flatten and
+  the body keeps its own `body` argument. Enable
+  [`debugMode`](../handlers/mcp-server.mdx#configuration) to see which tools
+  this applies to.
+
+A nested schema wraps each channel the operation declares in its own object:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "body": {
+      "type": "object",
+      "properties": { "productId": { "type": "string" } },
+      "required": ["productId"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["body"],
+  "additionalProperties": false
+}
+```
+
+The channel names are `body`, `queryParams`, `pathParams`, and `headers`. Only
+the channels the operation declares appear.
+
+### Calling a tool with nested arguments
+
+Flat tools also accept the nested form, so a client written against the nested
+schema keeps working:
+
+```json
+{
+  "name": "createOrder",
+  "arguments": {
+    "body": { "productId": "sku-123", "quantity": 2 }
+  }
+}
+```
+
+Send flat arguments in new clients — that's what the tool advertises.
+
+To make every generated tool advertise the nested shape instead, set
+[`toolInputStyle: "nested"`](../handlers/mcp-server.mdx#configuration) in the
+handler options.
+
+:::note
+
+[Prompts](./prompts.mdx) don't use input channels. A prompt's arguments come
+from its request body schema directly, so `prompts/get` always takes them at the
+top level.
+
+:::
+
 ## Testing MCP Tools
 
 ### List Available Tools
@@ -175,7 +345,8 @@ Response:
               "type": "string"
             }
           },
-          "required": ["location"]
+          "required": ["location"],
+          "additionalProperties": false
         }
       }
     ]

package/docs/mcp-server/troubleshooting.mdx

@@ -2,9 +2,10 @@
 title: "Troubleshooting the MCP Server Handler"
 sidebar_label: "Troubleshooting"
 description:
-  Diagnose MCP Server handler tool calls that fail in an AI client even though
-  the gateway route returns 200, using debug logging and the structured-content
-  configuration.
+  Diagnose MCP Server handler tool calls that fail in an AI client — a route
+  that returns 200 while the client errors, and invalid-argument rejections —
+  using debug logging, the structured-content configuration, and the tool's
+  advertised input schema.
 ---
 
 When an AI client calls a tool exposed by the
@@ -14,8 +15,9 @@ underlying gateway route can return `200` while the MCP client still rejects the
 response, which makes these failures hard to diagnose from the client alone.
 
 This page shows how to turn on the handler's debug logging, read the log lines
-that reveal a misconfiguration, and fix the most common cause: a tool that
-advertises an output schema but returns no structured content.
+that reveal a misconfiguration, and fix the most common causes: a tool that
+advertises an output schema but returns no structured content, and arguments
+that don't match the schema the tool advertises.
 
 :::tip
 
@@ -147,6 +149,46 @@ For the full definitions of both options, see the
 [MCP `2025-06-18` Global Options](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options)
 in the handler reference.
 
+## Invalid arguments for tool (-32602)
+
+**Symptom.** A tool call fails with JSON-RPC error `-32602` and a message naming
+an argument:
+
+```
+-32602 Invalid arguments for tool 'create_order':
+  ✖ Unrecognized key: "sku"
+```
+
+**Likely cause 1: the argument isn't in the schema.** The request body schema
+backing the tool sets `additionalProperties: false`, so the tool's input schema
+is closed and an argument it doesn't declare is invalid. Read the tool's
+`inputSchema` from `tools/list` and compare the argument names. A model that
+invents a field name lands here.
+
+**Likely cause 2: the tool takes nested arguments.** Most tools take the request
+body's fields and the operation's parameters as top-level arguments. A tool
+whose OpenAPI can't be flattened keeps the nested shape instead, so its
+arguments sit under `body`, `queryParams`, `pathParams`, or `headers`. When the
+error reads `at body`, the caller sent flat arguments to a nested tool:
+
+```
+-32602 Invalid arguments for tool 'create_order':
+  ✖ Invalid input: expected object, received undefined
+  → at body
+```
+
+Two things cause a tool to stay nested, and the MCP server logs which one when
+it registers the tool: a name collision between two input channels (logged as a
+warning), or a request body that isn't a plain object (logged at debug level —
+enable `debugMode` to see it). See
+[When arguments stay nested](./tools.mdx#when-arguments-stay-nested) for both
+cases and how to resolve the collision.
+
+**Fix.** Always craft `arguments` against the `inputSchema` the tool advertises
+in `tools/list` rather than assuming a shape. The
+[MCP Inspector](#client-side-debugging-tools) shows both the schema and the
+error for a call.
+
 ## Client-side debugging tools
 
 When the gateway looks healthy, reproduce the failure against the client to see

package/docs/policies/ai-gateway-metering-v2-inbound/doc.md

@@ -2,8 +2,8 @@
 
 AI Gateway Metering records application usage and configures the app's own
 budgets before the provider request runs. It meters spend, tokens, and requests.
-Each meter has independent daily and monthly periods and an optional warning
-threshold that notifies without blocking.
+Budget rules can cover the whole application or each distinct value of an
+expression.
 
 When a limit is exceeded, the policy activates the model selection's
 `quotaFallback` when AI Gateway Fallback Model supplied one. Otherwise it
@@ -20,31 +20,47 @@ Semantic Cache, after Metering so cache hits still count toward request limits.
   "name": "ai-gateway-metering-v2-inbound",
   "options": {
     "throwOnFailure": false,
-    "limits": {
-      "costs": {
-        "monthly": {
-          "enabled": true,
-          "limit": 100,
-          "warning": {
-            "enabled": true,
-            "threshold": 80
+    "budgetRules": [
+      {
+        "budgetBy": "app",
+        "meters": [
+          {
+            "meter": "cost",
+            "period": "monthly",
+            "value": 100,
+            "action": "block"
+          },
+          {
+            "meter": "cost",
+            "period": "monthly",
+            "value": 80,
+            "action": "warn"
           }
-        }
+        ]
       },
-      "requests": {
-        "daily": {
-          "enabled": true,
-          "limit": 1000
-        }
+      {
+        "budgetBy": "expression",
+        "expression": "request.headers.get(\"x-user\")",
+        "meters": [
+          {
+            "meter": "cost",
+            "period": "daily",
+            "value": 5,
+            "action": "block"
+          }
+        ]
       }
-    }
+    ]
   }
 }
 ```
 
-The supported meters are `costs`, `tokens`, and `requests`. Each meter can have
-`daily` and `monthly` settings. A period is enforced only when `enabled` is
-`true` and `limit` is present. Usage equal to the limit is blocked.
+The supported meters are `cost`, `requests`, and `tokens`. The supported periods
+are `hourly`, `daily`, `weekly`, and `monthly`. An application can have at most
+five rules. An expression rule creates a separate budget for every distinct
+value of its expression. An action of `"warn"` notifies without blocking. An
+action of `"block"` activates the configured quota fallback or returns
+`429 Too Many Requests` when usage reaches the value.
 
 > **Budgets fail open by default.** When `throwOnFailure` is `false`, a metering
 > service failure lets the request proceed unmetered and no limit is checked.
@@ -52,8 +68,8 @@ The supported meters are `costs`, `tokens`, and `requests`. Each meter can have
 
 ## Team limits
 
-The `options.limits` settings govern only the app running this policy. Limits
-configured on a parent team or the gateway root are enforced centrally after the
+Budgets configured on this application govern only this app. Limits configured
+on a parent team or the gateway root are enforced centrally after the
 application's policy chain, whether or not this policy appears in that chain. An
 inherited limit activates the selected model's quota fallback when available and
 otherwise returns `429 Too Many Requests`.
@@ -62,83 +78,3 @@ An application cannot disable inherited enforcement through its policy chain. If
 the central hierarchical check is unavailable, the request proceeds. The
 policy's `throwOnFailure` option controls failures while checking or recording
 the app's own limits; it does not change inherited-limit behavior.
-
-## Set limits from custom code
-
-Use a custom inbound policy to vary limits for individual requests. For example,
-the following policy gives callers with a `pro` plan a higher daily request
-limit:
-
-```typescript
-import {
-  AIGatewayMeteringV2InboundPolicy,
-  type ZuploContext,
-  type ZuploRequest,
-} from "@zuplo/runtime";
-
-export default function applyPlanLimit(
-  request: ZuploRequest,
-  context: ZuploContext
-) {
-  const dailyRequestLimit = request.user?.data.plan === "pro" ? 10_000 : 1_000;
-
-  AIGatewayMeteringV2InboundPolicy.setLimits(context, {
-    requests: {
-      daily: {
-        enabled: true,
-        limit: dailyRequestLimit,
-      },
-    },
-  });
-
-  return request;
-}
-```
-
-Register the module as a custom policy:
-
-```json
-{
-  "name": "plan-based-ai-limits",
-  "policyType": "custom-code-inbound",
-  "handler": {
-    "export": "default",
-    "module": "$import(./modules/plan-based-ai-limits)"
-  }
-}
-```
-
-Place it before metering in the application's inbound policy chain:
-
-```json
-{
-  "inboundPolicyChain": [
-    {
-      "name": "plan-based-ai-limits"
-    },
-    {
-      "name": "ai-gateway-metering-v2-inbound"
-    }
-  ]
-}
-```
-
-`setLimits` changes only the fields supplied for the current request. Other
-settings from the metering policy remain unchanged. For example, setting only
-`requests.daily.limit` preserves `requests.daily.enabled`, its warning settings,
-and all monthly limits. It does not update the policy configuration or affect
-later requests.
-
-The exported `AIGatewayMeteringV2LimitOverrides` interface can be used when a
-custom policy builds the override object separately. Its shape matches the
-`limits` option. These values are called overrides because they temporarily
-replace matching policy settings for the current request:
-
-- Choose a meter: `costs`, `tokens`, or `requests`.
-- Choose a period: `daily` or `monthly`.
-- Set one or more values: `enabled`, `limit`, or `warning`.
-
-If model filtering and fallback-model policies selected a `quotaFallback`, an
-exceeded limit activates that fallback instead of returning 429. The fallback
-request is still metered. Order the chain as model filtering, fallback model,
-metering, then policies that may short-circuit such as semantic cache.

package/docs/policies/ai-gateway-metering-v2-inbound/intro.md

@@ -1,7 +1,7 @@
 The AI Gateway Metering policy records each application's spend, tokens, and
-requests and enforces daily or monthly budgets. When a limit is exceeded, it
-uses the model selection's quota fallback when one is configured or returns
-`429 Too Many Requests`.
+requests and enforces spend, token, and request budgets. When a limit is
+exceeded, it uses the model selection's quota fallback when one is configured or
+returns `429 Too Many Requests`.
 
 Place it after Model Filtering and Fallback Model, and before policies such as
 Semantic Cache that may answer without calling a provider. Metering fails open

package/docs/policies/ai-gateway-metering-v2-inbound/schema.json

@@ -38,14 +38,25 @@
           "required": [],
           "examples": [
             {
-              "limits": {
-                "requests": {
-                  "daily": {
-                    "enabled": true,
-                    "limit": 1000
-                  }
+              "budgetRules": [
+                {
+                  "budgetBy": "app",
+                  "meters": [
+                    {
+                      "meter": "cost",
+                      "period": "monthly",
+                      "value": 100,
+                      "action": "block"
+                    },
+                    {
+                      "meter": "cost",
+                      "period": "monthly",
+                      "value": 80,
+                      "action": "warn"
+                    }
+                  ]
                 }
-              },
+              ],
               "throwOnFailure": false
             }
           ],
@@ -55,8 +66,61 @@
               "default": false,
               "description": "Throw when the metering service is unavailable instead of failing open."
             },
+            "budgetRules": {
+              "type": "array",
+              "maxItems": 5,
+              "description": "Budget rules for this application. Each rule budgets the whole app (\"app\") or each distinct value of an expression (\"expression\"), with warn and block thresholds per meter and period.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["budgetBy", "meters"],
+                "properties": {
+                  "budgetBy": {
+                    "type": "string",
+                    "enum": ["app", "expression"]
+                  },
+                  "expression": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Required when budgetBy is \"expression\"; forbidden for \"app\". Each distinct value gets its own budget."
+                  },
+                  "meters": {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 24,
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["meter", "period", "value", "action"],
+                      "properties": {
+                        "meter": {
+                          "type": "string",
+                          "enum": ["cost", "requests", "tokens"]
+                        },
+                        "period": {
+                          "type": "string",
+                          "enum": ["hourly", "daily", "weekly", "monthly"]
+                        },
+                        "value": {
+                          "type": "number",
+                          "minimum": 0
+                        },
+                        "action": {
+                          "type": "string",
+                          "enum": ["warn", "block"]
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
             "limits": {
               "type": "object",
+              "deprecated": true,
+              "doNotSuggest": true,
+              "x-show-example": false,
+              "x-advanced": true,
               "description": "Usage limits grouped by meter.",
               "additionalProperties": false,
               "properties": {
@@ -271,14 +335,25 @@
           "export": "AIGatewayMeteringV2InboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "limits": {
-              "requests": {
-                "daily": {
-                  "enabled": true,
-                  "limit": 1000
-                }
+            "budgetRules": [
+              {
+                "budgetBy": "app",
+                "meters": [
+                  {
+                    "meter": "cost",
+                    "period": "monthly",
+                    "value": 100,
+                    "action": "block"
+                  },
+                  {
+                    "meter": "cost",
+                    "period": "monthly",
+                    "value": 80,
+                    "action": "warn"
+                  }
+                ]
               }
-            },
+            ],
             "throwOnFailure": false
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.0",
+  "version": "7.6.1",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.0",
-    "@zuplo/core": "7.6.0",
-    "@zuplo/runtime": "7.6.0",
-    "@zuplo/test": "7.6.0"
+    "@zuplo/cli": "7.6.1",
+    "@zuplo/core": "7.6.1",
+    "@zuplo/runtime": "7.6.1",
+    "@zuplo/test": "7.6.1"
   }
 }