@empyria/mcp 0.1.3 → 0.1.5

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

package/AGENTS.md

@@ -53,6 +53,23 @@ don't special-case the "no params" path back to an omitted `inputSchema`, it sil
 of whether it takes params). See the regression test in `test/Server.test.js` ("still receives a
 real extra context, not undefined").
 
+## Optional params (`defineSchema(params, { optional: true })`)
+
+`@empyria/common`'s `defineSchema` (>= 0.1.4) accepts an `{ optional: true }` option: a property
+is excluded from JSON Schema `required` when its own schema carries `optional: true` (that
+marker is stripped before the property is embedded — not a real JSON Schema keyword, never
+leaked into the tool's advertised inputSchema). Without the option (the default, and every call
+elsewhere in the Empyria ecosystem — restate, moleculer), behavior is unchanged from before this
+existed: every declared property is required, even one with its own `default`.
+`registerService` in `lib/Server.js` always passes `{ optional: true }`, so any action's `params`
+here can mark a field optional this way. Added upstream (not as a local derivative in this repo —
+see git history for that discarded first attempt and why) 2026-08-26 for a real downstream need:
+a service wrapping an S3-shaped API had several genuinely optional/defaulted params
+(`contentType`, `expiresInSeconds`, ...) and `registerService`'s previous unconditional
+`defineSchema` call would have silently advertised all of them as required — a real API-contract
+regression, not a style preference. Usage: `params: { limit: { ...number(10), optional: true } }`.
+Requires `@empyria/common` >= 0.1.4 — this package's own `package.json` is pinned there or later.
+
 ## Auth (`lib/Guard.js`)
 
 `extra.http.req` (the raw `Request`, with real header access via `.headers.get(name)`) is

package/lib/Server.js

@@ -10,7 +10,9 @@ import { withMetaGuard } from './Guard.js'
  * @property {string} [description] - Shown to MCP clients as the tool's description.
  * @property {Object<string, Object>} [params] - Map of param name to JSON schema, built with
  *   `@empyria/common`'s schema helpers (`string()`, `number()`, `bool()`, ...). Omit for a
- *   tool that takes no arguments.
+ *   tool that takes no arguments. A property's own schema may additionally carry
+ *   `optional: true` to exclude it from the tool's `required` list — `registerService` passes
+ *   `defineSchema`'s own `{ optional: true }` option (`@empyria/common` >= 0.1.4) to honor it.
  * @property {(params: Object, extra: Object) => *} handler - Receives the validated params
  *   (or `{}` if no `params` schema was declared) and the MCP request's `extra` context.
  *   May return anything JSON-serializable, a string, or an already MCP-shaped
@@ -64,7 +66,10 @@ function registerService(server, service) {
 		// no-params action drops to a single-argument (extra) call instead — silently
 		// handing the caller's own context object to `args` and leaving `extra` (and
 		// therefore any auth context) undefined.
-		config.inputSchema = fromJsonSchema(defineSchema(params ?? {}), empyriaJsonSchemaValidator)
+		config.inputSchema = fromJsonSchema(
+			defineSchema(params ?? {}, { optional: true }),
+			empyriaJsonSchemaValidator,
+		)
 
 		server.registerTool(`${service.name}.${actionName}`, config, async (args, extra) => {
 			const result = await handler(args ?? {}, extra)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/mcp",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"description": "MCP (Model Context Protocol) helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -25,7 +25,7 @@
 	},
 	"dependencies": {
 		"@empyria/classification": "0.1.3",
-		"@empyria/common": "0.1.3",
+		"@empyria/common": "0.1.5",
 		"@modelcontextprotocol/client": "2.0.0",
 		"@modelcontextprotocol/server": "2.0.0"
 	},

package/test/Server.test.js

@@ -169,4 +169,81 @@ describe('createMcpServer', () => {
 			}),
 		).toThrow(/handler/)
 	})
+
+	test('a param marked optional: true is excluded from required', async () => {
+		const Service = {
+			name: 'Svc',
+			actions: {
+				search: {
+					params: { query: string(), limit: { ...number(10), optional: true } },
+					handler: async (params) => params,
+				},
+			},
+		}
+		const { client } = await connected([Service])
+		const { tools } = await client.listTools()
+		expect(tools[0].inputSchema.required).toEqual(['query'])
+	})
+
+	test('the optional marker itself is stripped, never leaked into the advertised schema', async () => {
+		const Service = {
+			name: 'Svc',
+			actions: {
+				search: {
+					params: { limit: { ...number(10), optional: true } },
+					handler: async (params) => params,
+				},
+			},
+		}
+		const { client } = await connected([Service])
+		const { tools } = await client.listTools()
+		expect(tools[0].inputSchema.properties.limit).toEqual({ type: 'number', default: 10 })
+	})
+
+	test('a call omitting an optional param still succeeds, and its default is applied by the validator', async () => {
+		const Service = {
+			name: 'Svc',
+			actions: {
+				search: {
+					params: { query: string(), limit: { ...number(10), optional: true } },
+					handler: async (params) => params,
+				},
+			},
+		}
+		const { client } = await connected([Service])
+		const result = await client.callTool({ name: 'Svc.search', arguments: { query: 'x' } })
+		expect(result.isError).toBeFalsy()
+		expect(JSON.parse(result.content[0].text)).toEqual({ query: 'x', limit: 10 })
+	})
+
+	test('a call omitting an optional param with no default leaves it absent', async () => {
+		const Service = {
+			name: 'Svc',
+			actions: {
+				search: {
+					params: { query: string(), tag: { ...string(), optional: true } },
+					handler: async (params) => params,
+				},
+			},
+		}
+		const { client } = await connected([Service])
+		const result = await client.callTool({ name: 'Svc.search', arguments: { query: 'x' } })
+		expect(result.isError).toBeFalsy()
+		expect(JSON.parse(result.content[0].text)).toEqual({ query: 'x' })
+	})
+
+	test("a param with only a default (no explicit optional) is still required — unchanged from @empyria/common's own defineSchema", async () => {
+		const Service = {
+			name: 'Svc',
+			actions: {
+				search: {
+					params: { limit: number(10) },
+					handler: async (params) => params,
+				},
+			},
+		}
+		const { client } = await connected([Service])
+		const { tools } = await client.listTools()
+		expect(tools[0].inputSchema.required).toEqual(['limit'])
+	})
 })