@namzu/sdk 2.0.0 → 3.1.0

package/src/connector/mcp/adapter.ts

@@ -5,49 +5,284 @@ import type {
 	MCPToolDefinition,
 	MCPToolResult,
 } from '../../types/connector/index.js'
+import type { ToolResultBlock } from '../../types/message/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
 import type { MCPClient } from './client.js'
+import { inlineSchemaRefs } from './schema-refs.js'
 
+/**
+ * Convert an MCP server's declared input schema into the Zod type namzu
+ * validates and re-renders with.
+ *
+ * The re-render is why fidelity matters here. A bridged tool's schema makes
+ * a round trip — server JSON Schema → Zod → JSON Schema on the wire — and
+ * whatever this function drops is dropped from what the MODEL is shown. The
+ * previous version collapsed `array` to `z.array(z.unknown())` and `object`
+ * to `z.record(z.unknown())`, so every MCP tool taking a structured
+ * argument was presented as "an array of anything" or "an object with any
+ * keys". Nested properties, item types, enums, and descriptions all
+ * vanished, and the model was left guessing at a shape the server had
+ * spelled out precisely.
+ */
 export function mcpJsonSchemaToZod(schema: MCPJsonSchema): z.ZodType {
-	if (!schema.properties || Object.keys(schema.properties).length === 0) {
-		return z.object({}).passthrough()
+	// Pointers first: a `$ref` is invisible to every branch below, and a
+	// schema whose main argument is a `$ref` was rendered to the model as
+	// "anything" — and, because the result is inherently optional in Zod,
+	// stopped being required as well.
+	const inlined = inlineSchemaRefs(schema as unknown as Record<string, unknown>)
+	return objectToZod(inlined, 0)
+}
+
+/**
+ * Ceiling on the `objectToZod` / `jsonSchemaPropertyToZod` mutual recursion.
+ *
+ * Ref inlining already refuses to expand a cycle, but a schema can nest
+ * deeply without any `$ref` at all, and a remote server's schema is
+ * untrusted input. Past the ceiling the node is left permissive rather than
+ * the process being taken down by a stack overflow.
+ */
+const MAX_CONVERSION_DEPTH = 32
+
+function objectToZod(rawSchema: Record<string, unknown>, depth: number): z.ZodType {
+	// Flatten `allOf` here rather than only in the type switch: a root
+	// schema is converted through this function directly, so a tool whose
+	// whole input is `allOf: [...]` never reached the switch at all and was
+	// rendered as an object with no properties.
+	const allOf = rawSchema.allOf as unknown[] | undefined
+	const schema = Array.isArray(allOf) && allOf.length > 0 ? mergeAllOf(allOf, rawSchema) : rawSchema
+
+	const properties = schema.properties as Record<string, unknown> | undefined
+	if (!properties || Object.keys(properties).length === 0) {
+		return closeOrOpen(z.object({}), schema)
 	}
+	if (depth >= MAX_CONVERSION_DEPTH) return z.record(z.unknown())
 
 	const shape: Record<string, z.ZodType> = {}
-	const required = new Set(schema.required ?? [])
+	const required = new Set((schema.required as string[] | undefined) ?? [])
 
-	for (const [key, propSchema] of Object.entries(schema.properties)) {
-		let field = jsonSchemaPropertyToZod(propSchema)
-		if (!required.has(key)) {
-			field = field.optional()
-		}
-		shape[key] = field
+	for (const [key, propSchema] of Object.entries(properties)) {
+		const field = jsonSchemaPropertyToZod(propSchema, depth + 1)
+		shape[key] = required.has(key) ? field : field.optional()
 	}
 
-	return z.object(shape).passthrough()
+	return closeOrOpen(z.object(shape), schema)
+}
+
+/**
+ * Honor the server's `additionalProperties`, defaulting to closed.
+ *
+ * The old default was `.passthrough()`, which renders as
+ * `additionalProperties: true` — telling the model it may invent arguments
+ * the server never declared. Zod's default `.strip()` renders `false` and
+ * silently drops undeclared keys rather than rejecting them, so the
+ * contract shown to the model tightens without turning a server's
+ * incomplete schema into a hard validation failure.
+ */
+function closeOrOpen(obj: z.ZodObject<z.ZodRawShape>, schema: Record<string, unknown>): z.ZodType {
+	return schema.additionalProperties === true ? obj.passthrough() : obj
 }
 
-function jsonSchemaPropertyToZod(prop: unknown): z.ZodType {
+function jsonSchemaPropertyToZod(prop: unknown, depth = 0): z.ZodType {
 	if (typeof prop !== 'object' || prop === null) return z.unknown()
 	const schema = prop as Record<string, unknown>
 
-	switch (schema.type) {
+	let base = applyConstraints(baseTypeToZod(schema, depth), schema)
+
+	// `type: ['string', 'null']` is how a JSON Schema says nullable.
+	if (Array.isArray(schema.type) && schema.type.includes('null')) {
+		base = base.nullable()
+	}
+
+	const description = schema.description
+	if (typeof description === 'string' && description.length > 0) {
+		base = base.describe(description)
+	}
+
+	if (schema.default !== undefined) {
+		base = base.default(schema.default)
+	}
+
+	return base
+}
+
+const num = (value: unknown): number | undefined =>
+	typeof value === 'number' && Number.isFinite(value) ? value : undefined
+
+/**
+ * Carry the server's validation keywords onto the converted node.
+ *
+ * Only `description` and `default` used to survive, so `pattern`, the
+ * length and range bounds, `format` and `multipleOf` were all dropped —
+ * from what the model is SHOWN as much as from what is enforced. A server
+ * that carefully said "an ISO date, 10 characters, matching this pattern"
+ * had the model told "a string", and then namzu accepted whatever the model
+ * invented and let the server reject it a round trip later.
+ */
+function applyConstraints(base: z.ZodType, schema: Record<string, unknown>): z.ZodType {
+	if (base instanceof z.ZodString) {
+		let out = base
+		const minLength = num(schema.minLength)
+		const maxLength = num(schema.maxLength)
+		if (minLength !== undefined) out = out.min(minLength)
+		if (maxLength !== undefined) out = out.max(maxLength)
+		if (typeof schema.pattern === 'string') {
+			try {
+				out = out.regex(new RegExp(schema.pattern))
+			} catch {
+				// A server may use a regex dialect this engine cannot compile
+				// (named groups, lookbehind, POSIX classes). An unenforced
+				// pattern is a smaller loss than a tool that fails to register.
+			}
+		}
+		return applyStringFormat(out, schema.format)
+	}
+
+	if (base instanceof z.ZodNumber) {
+		let out = base
+		const minimum = num(schema.minimum)
+		const maximum = num(schema.maximum)
+		const exclusiveMinimum = num(schema.exclusiveMinimum)
+		const exclusiveMaximum = num(schema.exclusiveMaximum)
+		const multipleOf = num(schema.multipleOf)
+		if (minimum !== undefined) out = out.min(minimum)
+		if (maximum !== undefined) out = out.max(maximum)
+		if (exclusiveMinimum !== undefined) out = out.gt(exclusiveMinimum)
+		if (exclusiveMaximum !== undefined) out = out.lt(exclusiveMaximum)
+		if (multipleOf !== undefined && multipleOf > 0) out = out.multipleOf(multipleOf)
+		return out
+	}
+
+	if (base instanceof z.ZodArray) {
+		let out = base as z.ZodArray<z.ZodTypeAny>
+		const minItems = num(schema.minItems)
+		const maxItems = num(schema.maxItems)
+		if (minItems !== undefined) out = out.min(minItems)
+		if (maxItems !== undefined) out = out.max(maxItems)
+		return out
+	}
+
+	return base
+}
+
+function applyStringFormat(base: z.ZodString, format: unknown): z.ZodString {
+	switch (format) {
+		case 'email':
+			return base.email()
+		case 'uri':
+		case 'url':
+			return base.url()
+		case 'uuid':
+			return base.uuid()
+		case 'date-time':
+			return base.datetime({ offset: true })
+		default:
+			// Every other `format` is advisory in JSON Schema. The description
+			// already carries it to the model; inventing a validator for it
+			// would reject payloads the server would have accepted.
+			return base
+	}
+}
+
+function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
+	// An `enum` pins the value more tightly than `type` does, so it wins.
+	const enumValues = schema.enum
+	if (Array.isArray(enumValues) && enumValues.length > 0) {
+		return enumToZod(enumValues)
+	}
+	if (schema.const !== undefined) {
+		return z.literal(schema.const as z.Primitive)
+	}
+
+	const composite = (schema.anyOf ?? schema.oneOf) as unknown[] | undefined
+	if (Array.isArray(composite) && composite.length > 0) {
+		const members = composite.map((member) => jsonSchemaPropertyToZod(member, depth + 1))
+		return members.length === 1
+			? (members[0] as z.ZodType)
+			: z.union(members as [z.ZodType, z.ZodType, ...z.ZodType[]])
+	}
+
+	// `allOf` is how a schema generator says "this shape, plus that one".
+	// It reached the permissive branch, so an intersection of two fully
+	// described objects was shown to the model as "anything". Merged rather
+	// than intersected: an intersection re-renders as `allOf`, and a flat
+	// object is what a model can actually read.
+	const allOf = schema.allOf as unknown[] | undefined
+	if (Array.isArray(allOf) && allOf.length > 0) {
+		return objectToZod(mergeAllOf(allOf, schema), depth)
+	}
+
+	// A union type (`['string','null']`) resolves through its non-null half;
+	// `jsonSchemaPropertyToZod` adds `.nullable()` back on top.
+	const type = Array.isArray(schema.type)
+		? (schema.type as string[]).find((t) => t !== 'null')
+		: (schema.type as string | undefined)
+
+	switch (type) {
 		case 'string':
 			return z.string()
 		case 'number':
-		case 'integer':
 			return z.number()
+		case 'integer':
+			return z.number().int()
 		case 'boolean':
 			return z.boolean()
-		case 'array':
-			return z.array(z.unknown())
+		case 'null':
+			return z.null()
+		case 'array': {
+			const items = schema.items
+			// A tuple (`items` as an array) is rare in tool schemas; treat it
+			// as a heterogeneous list rather than pretending to model it.
+			if (Array.isArray(items)) return z.array(z.unknown())
+			return z.array(items === undefined ? z.unknown() : jsonSchemaPropertyToZod(items))
+		}
 		case 'object':
-			return z.record(z.unknown())
+			return objectToZod(schema, depth)
 		default:
 			return z.unknown()
 	}
 }
 
+/**
+ * Flatten `allOf` members into one object schema.
+ *
+ * Only `properties` and `required` are merged, which is what the keyword
+ * is used for in practice (a base shape plus an extension). A member that
+ * describes something else is skipped rather than approximated. On a
+ * property collision the later member wins, matching the reading order.
+ */
+function mergeAllOf(members: readonly unknown[], parent: Record<string, unknown>): JsonRecord {
+	const properties: JsonRecord = { ...((parent.properties as JsonRecord | undefined) ?? {}) }
+	const required = new Set((parent.required as string[] | undefined) ?? [])
+	let additionalProperties = parent.additionalProperties
+
+	for (const member of members) {
+		if (typeof member !== 'object' || member === null) continue
+		const part = member as Record<string, unknown>
+		Object.assign(properties, (part.properties as JsonRecord | undefined) ?? {})
+		for (const key of (part.required as string[] | undefined) ?? []) required.add(key)
+		if (part.additionalProperties !== undefined) additionalProperties = part.additionalProperties
+	}
+
+	return {
+		type: 'object',
+		properties,
+		required: [...required],
+		...(additionalProperties !== undefined ? { additionalProperties } : {}),
+	}
+}
+
+type JsonRecord = Record<string, unknown>
+
+function enumToZod(values: readonly unknown[]): z.ZodType {
+	if (values.every((v): v is string => typeof v === 'string')) {
+		return z.enum(values as [string, ...string[]])
+	}
+	const literals = values.map((v) => z.literal(v as z.Primitive))
+	return literals.length === 1
+		? (literals[0] as z.ZodType)
+		: z.union(literals as unknown as [z.ZodType, z.ZodType, ...z.ZodType[]])
+}
+
 export function zodToMCPJsonSchema(zodSchema: z.ZodType): MCPJsonSchema {
 	const jsonSchema = zodToJsonSchema(zodSchema, { target: 'openApi3' })
 	return {
@@ -70,6 +305,11 @@ export function mcpToolToToolDefinition(
 			? `[MCP:${serverName}] ${tool.description}`
 			: `[MCP:${serverName}] ${tool.name}`,
 		inputSchema,
+		// Carried as the server wrote it. It is shown to the model, never
+		// validated here, so rebuilding it would only lose fidelity.
+		...(tool.outputSchema
+			? { outputSchema: inlineSchemaRefs(tool.outputSchema as unknown as Record<string, unknown>) }
+			: {}),
 		category: 'network',
 		permissions: ['network_access'],
 		isReadOnly: () => tool.annotations?.readOnlyHint ?? false,
@@ -101,11 +341,58 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 		.map((block) => block.text)
 		.join('\n')
 
+	// Non-text blocks used to be filtered out and never seen again: a
+	// bridged MCP server returning a chart, a screenshot or a PDF had that
+	// content silently discarded, even though `types/connector/mcp.ts`
+	// modelled `image` and `resource` blocks all along. Pass them through
+	// as model-visible content when any are present.
+	const blocks: ToolResultBlock[] = []
+	for (const block of result.content) {
+		if (block.type === 'text') {
+			blocks.push({ type: 'text', text: block.text })
+		} else if (block.type === 'image' && block.data && block.mimeType) {
+			blocks.push({ type: 'image', data: block.data, mediaType: block.mimeType })
+		} else if (block.type === 'resource' && block.resource?.text) {
+			// A resource with inline text is readable content; one that is
+			// only a URI is a pointer the model cannot dereference, so it is
+			// named rather than pretended to be present.
+			blocks.push({ type: 'text', text: block.resource.text })
+		}
+	}
+	const hasRichContent = blocks.some((b) => b.type !== 'text')
+
+	// A server may answer with a structured payload and skip the
+	// compatibility text block. Serializing it is the difference between
+	// the model reading the answer and reading nothing at all — the call
+	// succeeded, so no error path would have caught it either. Text wins
+	// when both are present: the server wrote it for the model.
+	const output =
+		textContent.length > 0 || result.structuredContent === undefined
+			? textContent
+			: stringifyStructured(result.structuredContent)
+
 	return {
 		success: !result.isError,
-		output: textContent,
-		data: result.content,
-		error: result.isError ? textContent : undefined,
+		output,
+		...(hasRichContent ? { content: blocks } : {}),
+		// `data` is the host-side escape hatch, so it must carry what the
+		// server actually sent, not just the blocks half of it.
+		data:
+			result.structuredContent === undefined
+				? result.content
+				: { content: result.content, structuredContent: result.structuredContent },
+		error: result.isError ? output : undefined,
+	}
+}
+
+function stringifyStructured(value: unknown): string {
+	if (typeof value === 'string') return value
+	try {
+		return JSON.stringify(value, null, 2) ?? ''
+	} catch {
+		// Cyclic or otherwise unserializable. Naming it beats an empty
+		// result the model cannot distinguish from "nothing was found".
+		return '[structured result could not be serialized]'
 	}
 }
 

package/src/connector/mcp/client.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type {
+	MCPJsonRpcMessage,
+	MCPTransport,
+	MCPTransportUnion,
+} from '../../types/connector/index.js'
+import { MCPClient } from './client.js'
+
+/**
+ * `client.ts` had zero test coverage, and three ways to hang a run:
+ *
+ * - `request()` armed no timer, so a wedged stdio server left every caller
+ *   pending forever — no error, no `run_failed`, just a process that stopped.
+ * - Pending requests were only rejected by `disconnect()`, so a transport
+ *   that dropped on its own leaked them.
+ * - A frame carrying BOTH an id and a method (a server-initiated request:
+ *   `sampling/createMessage`, `elicitation/create`, `roots/list`, `ping`)
+ *   matched neither branch of `handleMessage` and was silently discarded,
+ *   leaving the server waiting for a reply that never came.
+ *
+ * This is a first-party MCP implementation with no `@modelcontextprotocol/sdk`
+ * dependency, so nothing is inherited from upstream.
+ */
+
+interface Harness {
+	client: MCPClient
+	sent: MCPJsonRpcMessage[]
+	/** Deliver a frame as if the server sent it. */
+	receive(msg: MCPJsonRpcMessage): void
+	closeTransport(): void
+	failTransport(err: Error): void
+}
+
+function harness(opts: { autoInitialize?: boolean; requestTimeoutMs?: number } = {}): Harness {
+	const sent: MCPJsonRpcMessage[] = []
+	let onMessage: ((m: MCPJsonRpcMessage) => void) | undefined
+	let onClose: (() => void) | undefined
+	let onError: ((e: Error) => void) | undefined
+
+	let open = true
+	const transport: MCPTransport = {
+		connect: async () => {},
+		close: async () => {
+			open = false
+		},
+		isConnected: () => open,
+		send: async (message) => {
+			sent.push(message)
+			// Answer `initialize` so `connect()` can complete.
+			if (opts.autoInitialize !== false && message.method === 'initialize') {
+				queueMicrotask(() =>
+					onMessage?.({
+						jsonrpc: '2.0',
+						id: message.id,
+						result: { serverInfo: { name: 'fake', version: '1' }, capabilities: {} },
+					}),
+				)
+			}
+		},
+		onMessage: (h) => {
+			onMessage = h
+		},
+		onClose: (h) => {
+			onClose = h
+		},
+		onError: (h) => {
+			onError = h
+		},
+	}
+
+	const client = new MCPClient({
+		serverName: 'fake',
+		transport: { type: 'stdio', command: 'noop' } as MCPTransportUnion,
+		...(opts.requestTimeoutMs !== undefined ? { requestTimeoutMs: opts.requestTimeoutMs } : {}),
+	})
+	// Swap in the fake transport; `createTransport` would spawn a process.
+	;(client as unknown as { transport: MCPTransport }).transport = transport
+
+	return {
+		client,
+		sent,
+		receive: (msg) => onMessage?.(msg),
+		closeTransport: () => onClose?.(),
+		failTransport: (err) => onError?.(err),
+	}
+}
+
+describe('MCPClient — a wedged server cannot hang the run', () => {
+	it('times out a request that is never answered', async () => {
+		const h = harness({ requestTimeoutMs: 25 })
+		await h.client.connect()
+
+		await expect(h.client.listTools()).rejects.toThrow(/timed out after 25ms/)
+	})
+
+	it('rejects in-flight requests when the transport closes on its own', async () => {
+		const h = harness({ requestTimeoutMs: 10_000 })
+		await h.client.connect()
+
+		const pending = h.client.listTools()
+		h.closeTransport()
+
+		await expect(pending).rejects.toThrow(/closed/)
+	})
+
+	it('rejects in-flight requests when the transport errors', async () => {
+		const h = harness({ requestTimeoutMs: 10_000 })
+		await h.client.connect()
+
+		const pending = h.client.listTools()
+		h.failTransport(new Error('broken pipe'))
+
+		await expect(pending).rejects.toThrow(/broken pipe/)
+	})
+
+	it('clears the timer on a normal reply — no late rejection', async () => {
+		const h = harness({ requestTimeoutMs: 50 })
+		await h.client.connect()
+
+		const pending = h.client.listTools()
+		h.receive({ jsonrpc: '2.0', id: 2, result: { tools: [{ name: 'a' }] } })
+
+		await expect(pending).resolves.toEqual([{ name: 'a' }])
+		// Outlive the timeout; a stale timer would surface as an unhandled
+		// rejection here.
+		await new Promise((r) => setTimeout(r, 80))
+	})
+})
+
+describe('MCPClient — server-initiated requests are answered, not dropped', () => {
+	it('replies -32601 to an unsupported server request instead of going silent', async () => {
+		const h = harness()
+		await h.client.connect()
+		h.sent.length = 0
+
+		h.receive({ jsonrpc: '2.0', id: 99, method: 'sampling/createMessage', params: {} })
+		await new Promise((r) => setTimeout(r, 0))
+
+		const reply = h.sent.find((m) => m.id === 99)
+		expect(reply).toBeDefined()
+		expect(reply?.error?.code).toBe(-32601)
+		expect(reply?.error?.message).toContain('sampling/createMessage')
+	})
+
+	it('still routes notifications (no id) to notification handlers', async () => {
+		const h = harness()
+		await h.client.connect()
+		const seen = vi.fn()
+		h.client.onNotification(seen)
+		h.sent.length = 0
+
+		h.receive({ jsonrpc: '2.0', method: 'notifications/tools/list_changed', params: {} })
+
+		expect(seen).toHaveBeenCalledWith('notifications/tools/list_changed', {})
+		// A notification must NOT be answered.
+		expect(h.sent).toHaveLength(0)
+	})
+})