@namzu/sdk 14.0.7 → 15.0.0

package/src/connector/mcp/__tests__/prompts-and-lifecycle.test.ts

@@ -1,286 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-import { JSON_RPC_METHOD_NOT_FOUND } from '../../../constants/mcp/index.js'
-import type {
-	MCPJsonRpcMessage,
-	MCPPromptDefinition,
-	MCPPromptMessage,
-	MCPTransport,
-} from '../../../types/connector/index.js'
-import { MCPClient } from '../client.js'
-import { MCPServer } from '../server.js'
-import type { MCPServerPromptProvider, MCPServerToolProvider } from '../server.js'
-
-/**
- * The half of MCP that is not tools.
- *
- * `MCPPromptDefinition` and `MCPPromptArgument` were declared when the types
- * were written; no client method ever asked for a prompt and no server branch
- * ever served one. `MCPLifecycleEvent` and `MCPEventListener` were declared
- * beside them and nothing ever emitted one, so a host could learn that a
- * server had died only by noticing calls had started failing.
- */
-
-function fakeTransport(): {
-	transport: MCPTransport
-	sent: MCPJsonRpcMessage[]
-	deliver: (m: MCPJsonRpcMessage) => void
-} {
-	const sent: MCPJsonRpcMessage[] = []
-	let onMessage: ((m: MCPJsonRpcMessage) => void) | undefined
-	const transport: MCPTransport = {
-		connect: async () => undefined,
-		close: async () => undefined,
-		send: async (m: MCPJsonRpcMessage) => {
-			sent.push(m)
-		},
-		onMessage: (h: (m: MCPJsonRpcMessage) => void) => {
-			onMessage = h
-		},
-		onClose: () => undefined,
-		onError: () => undefined,
-	} as unknown as MCPTransport
-	return { transport, sent, deliver: (m) => onMessage?.(m) }
-}
-
-const toolProvider: MCPServerToolProvider = {
-	listTools: () => [],
-	callTool: async () => ({ content: [{ type: 'text', text: 'ok' }] }),
-}
-
-function promptProvider(over: Partial<MCPServerPromptProvider> = {}): MCPServerPromptProvider {
-	const prompts: MCPPromptDefinition[] = [
-		{
-			name: 'summarize',
-			description: 'Summarize a file',
-			arguments: [
-				{ name: 'path', required: true },
-				{ name: 'style', required: false },
-			],
-		},
-	]
-	const messages: MCPPromptMessage[] = [
-		{ role: 'user', content: { type: 'text', text: 'summarize it' } },
-	]
-	return {
-		listPrompts: () => prompts,
-		getPrompt: async () => ({ description: 'Summarize a file', messages }),
-		...over,
-	}
-}
-
-async function ask(
-	t: ReturnType<typeof fakeTransport>,
-	method: string,
-	params: Record<string, unknown> = {},
-) {
-	t.deliver({ jsonrpc: '2.0', id: 1, method, params } as MCPJsonRpcMessage)
-	await new Promise((r) => setTimeout(r, 0))
-	return t.sent.at(-1) as MCPJsonRpcMessage & {
-		result?: unknown
-		error?: { code: number; message: string }
-	}
-}
-
-describe('a server serves the prompts it publishes', () => {
-	it('lists them', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/list')
-
-		expect((reply.result as { prompts: MCPPromptDefinition[] }).prompts[0]?.name).toBe('summarize')
-	})
-
-	it('returns the messages the server composed', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/get', {
-			name: 'summarize',
-			arguments: { path: 'a.ts' },
-		})
-
-		expect((reply.result as { messages: MCPPromptMessage[] }).messages[0]?.content).toEqual({
-			type: 'text',
-			text: 'summarize it',
-		})
-	})
-
-	it('advertises the capability only when something is behind it', async () => {
-		const withPrompts = fakeTransport()
-		const without = fakeTransport()
-		const a = new MCPServer({ name: 'a' }, toolProvider, undefined, promptProvider())
-		const b = new MCPServer({ name: 'b' }, toolProvider)
-		await a.start(withPrompts.transport)
-		await b.start(without.transport)
-
-		const withCap = await ask(withPrompts, 'initialize')
-		const withoutCap = await ask(without, 'initialize')
-
-		// A capability advertised without a provider is a promise the next
-		// call breaks.
-		expect(
-			(withCap.result as { capabilities: Record<string, unknown> }).capabilities.prompts,
-		).toBeDefined()
-		expect(
-			(withoutCap.result as { capabilities: Record<string, unknown> }).capabilities.prompts,
-		).toBeUndefined()
-	})
-
-	it('refuses a required argument the caller omitted', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/get', { name: 'summarize', arguments: {} })
-
-		// Checked from the declaration, so every provider does not have to
-		// re-implement it or forget to.
-		expect(reply.error?.message).toContain('path')
-	})
-
-	it('accepts an optional argument being absent', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/get', {
-			name: 'summarize',
-			arguments: { path: 'a.ts' },
-		})
-
-		expect(reply.error).toBeUndefined()
-	})
-
-	it('refuses a prompt it does not publish', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/get', { name: 'nonexistent' })
-
-		expect(reply.error?.message).toContain('nonexistent')
-	})
-})
-
-describe('"none" and "not here" are different answers', () => {
-	it('says method-not-found for prompts when there is no provider', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider)
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/list')
-
-		expect(reply.error?.code).toBe(JSON_RPC_METHOD_NOT_FOUND)
-	})
-
-	it('says method-not-found for resources when there is no provider', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider)
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'resources/list')
-
-		// This used to answer `{ resources: [] }` for a capability
-		// `initialize` never advertised — telling a client "none" where the
-		// truth is "not here". The two send a client in opposite directions.
-		expect(reply.error?.code).toBe(JSON_RPC_METHOD_NOT_FOUND)
-	})
-
-	it('uses the protocol code for an unknown method, not a generic failure', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer({ name: 'srv' }, toolProvider)
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'completely/unknown')
-
-		expect(reply.error?.code).toBe(JSON_RPC_METHOD_NOT_FOUND)
-	})
-
-	it('still reports a provider failure as an internal error', async () => {
-		const t = fakeTransport()
-		const server = new MCPServer(
-			{ name: 'srv' },
-			toolProvider,
-			undefined,
-			promptProvider({
-				listPrompts: () => {
-					throw new Error('provider exploded')
-				},
-			}),
-		)
-		await server.start(t.transport)
-
-		const reply = await ask(t, 'prompts/list')
-
-		// A broken provider is not the same as an unimplemented method, and
-		// collapsing the two would tell a client to stop asking for something
-		// that works tomorrow.
-		expect(reply.error?.code).toBe(-32603)
-	})
-})
-
-describe('a client says out loud what it already knew', () => {
-	function failingClient() {
-		// `connect` failing is the simplest path that actually emits. A
-		// never-connected client's `disconnect` returns early and emits
-		// nothing — an easy way to write a test that proves nothing, which is
-		// what the first version of these did.
-		return new MCPClient({
-			serverName: 'srv',
-			transport: { type: 'stdio', command: 'definitely-not-a-real-binary-xyz', args: [] },
-		})
-	}
-
-	/**
-	 * Covered here: the transport-error emitter. `connect`'s own catch emits
-	 * the same event and is NOT pinned — a spawn failure surfaces through the
-	 * transport first, so the catch is the second line of defence rather than
-	 * the path this reaches. Reaching it needs a connection that opens and
-	 * then fails negotiation, which this fake cannot stage; said rather than
-	 * left for a mutation run to discover.
-	 */
-	it('reports a failure to whoever is listening', async () => {
-		const client = failingClient()
-		const seen: string[] = []
-		client.onLifecycle((e) => seen.push(e.type))
-
-		await client.connect().catch(() => undefined)
-
-		expect(seen).toContain('mcp_client_error')
-	})
-
-	it('stops reporting once the listener unsubscribes', async () => {
-		const client = failingClient()
-		const seen = vi.fn()
-
-		const off = client.onLifecycle(seen)
-		off()
-		await client.connect().catch(() => undefined)
-
-		// `onNotification` returns nothing, so a listener registered there
-		// cannot be removed and keeps a disposed host object alive for as
-		// long as the client. This is that bug not repeated.
-		expect(seen).not.toHaveBeenCalled()
-	})
-
-	it('leaves other listeners working when one throws', async () => {
-		const client = failingClient()
-		const survivor = vi.fn()
-		client.onLifecycle(() => {
-			throw new Error('observer bug')
-		})
-		client.onLifecycle(survivor)
-
-		await client.connect().catch(() => undefined)
-
-		// These fire from inside transport callbacks and from `connect`'s
-		// failure path, so an escaping exception would surface as a connection
-		// error — blaming the server for a bug in the host's own observer, and
-		// silencing every listener registered after the broken one.
-		expect(survivor).toHaveBeenCalled()
-	})
-})

package/src/connector/mcp/__tests__/protocol-negotiation.test.ts

@@ -1,105 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import {
-	MCP_PROTOCOL_VERSION,
-	MCP_SUPPORTED_PROTOCOL_VERSIONS,
-} from '../../../constants/mcp/index.js'
-import type {
-	MCPJsonRpcMessage,
-	MCPTransport,
-	MCPTransportUnion,
-} from '../../../types/connector/index.js'
-import { MCPClient } from '../client.js'
-
-/**
- * A server answers `initialize` with the version IT will speak, which need
- * not be the one the client asked for — that is how the handshake is
- * specified. namzu ignored the answer entirely and carried on regardless,
- * so a server responding with a version this client cannot speak looked
- * exactly like a healthy connection until something downstream broke in a
- * confusing way.
- */
-
-function harness(protocolVersion: string | undefined) {
-	const sent: MCPJsonRpcMessage[] = []
-	let onMessage: ((m: MCPJsonRpcMessage) => void) | undefined
-
-	const transport: MCPTransport = {
-		connect: async () => {},
-		close: async () => {},
-		isConnected: () => true,
-		send: async (message) => {
-			sent.push(message)
-			if (message.method === 'initialize') {
-				queueMicrotask(() =>
-					onMessage?.({
-						jsonrpc: '2.0',
-						id: message.id,
-						result: {
-							...(protocolVersion !== undefined ? { protocolVersion } : {}),
-							serverInfo: { name: 'fake', version: '1' },
-							capabilities: {},
-						},
-					}),
-				)
-			}
-		},
-		onMessage: (h) => {
-			onMessage = h
-		},
-		onClose: () => {},
-		onError: () => {},
-	}
-
-	const client = new MCPClient({
-		serverName: 'fake',
-		transport: { type: 'stdio', command: 'noop' } as MCPTransportUnion,
-	})
-	;(client as unknown as { transport: MCPTransport }).transport = transport
-
-	return { client, sent }
-}
-
-describe('MCP protocol negotiation', () => {
-	it('advertises the version this client actually implements', () => {
-		// Advertising a newer version whose requirements are unimplemented
-		// is worse than advertising an older one honestly: the server
-		// tailors its behavior to the claim.
-		expect(MCP_SUPPORTED_PROTOCOL_VERSIONS).toContain(MCP_PROTOCOL_VERSION)
-	})
-
-	it('sends the advertised version on initialize', async () => {
-		const h = harness(MCP_PROTOCOL_VERSION)
-		await h.client.connect()
-
-		const init = h.sent.find((m) => m.method === 'initialize')
-		expect((init?.params as { protocolVersion: string }).protocolVersion).toBe(MCP_PROTOCOL_VERSION)
-	})
-
-	it('accepts a server that answers with the version we asked for', async () => {
-		const h = harness(MCP_PROTOCOL_VERSION)
-		await expect(h.client.connect()).resolves.toBeDefined()
-		expect(h.client.isConnected()).toBe(true)
-	})
-
-	it('REFUSES a server that negotiates a version this client cannot speak', async () => {
-		const h = harness('2099-01-01')
-		await expect(h.client.connect()).rejects.toThrow(/negotiated protocol version "2099-01-01"/)
-		expect(h.client.isConnected()).toBe(false)
-	})
-
-	it('names the versions it can speak, so the failure is actionable', async () => {
-		const h = harness('1999-01-01')
-		await expect(h.client.connect()).rejects.toThrow(
-			new RegExp(MCP_SUPPORTED_PROTOCOL_VERSIONS.join(', ')),
-		)
-	})
-
-	it('tolerates a server that omits the version rather than failing the connection', async () => {
-		// Lenient about an ABSENT version, strict about an unsupported one.
-		// A missing field is a server being sloppy; a version we cannot
-		// speak is a real incompatibility.
-		const h = harness(undefined)
-		await expect(h.client.connect()).resolves.toBeDefined()
-	})
-})

package/src/connector/mcp/__tests__/schema-fidelity.test.ts

@@ -1,250 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { zodToJsonSchema } from 'zod-to-json-schema'
-
-import type { MCPJsonSchema } from '../../../types/connector/index.js'
-import { mcpJsonSchemaToZod } from '../adapter.js'
-import { inlineSchemaRefs } from '../schema-refs.js'
-
-/**
- * A bridged tool's schema makes a round trip — server JSON Schema → Zod →
- * JSON Schema on the wire — so whatever the conversion drops is dropped
- * from what the MODEL is shown, not just from what is enforced.
- *
- * Two losses were total. A `$ref` hit the permissive branch and became
- * "anything"; since that node is inherently optional in Zod, a `$ref`'d
- * field the server listed as required stopped being required as well, so
- * an empty payload validated clean and reached the server. And every
- * validation keyword except `description` and `default` was discarded.
- */
-
-const asSchema = (schema: unknown) => schema as MCPJsonSchema
-/** Walking a rendered schema; every node is `unknown` at the type level. */
-// biome-ignore lint/suspicious/noExplicitAny: assertions index arbitrary depth
-type RenderedSchema = Record<string, any>
-
-const render = (schema: unknown) =>
-	zodToJsonSchema(mcpJsonSchemaToZod(asSchema(schema)), {
-		target: 'openApi3',
-	}) as RenderedSchema
-
-describe('a schema built from $defs', () => {
-	const schema = {
-		type: 'object',
-		properties: { location: { $ref: '#/$defs/Location' } },
-		required: ['location'],
-		$defs: {
-			Location: {
-				type: 'object',
-				properties: {
-					city: { type: 'string', description: 'City name' },
-					lat: { type: 'number' },
-				},
-				required: ['city'],
-			},
-		},
-	}
-
-	it('shows the model the shape instead of an empty object', () => {
-		const rendered = render(schema)
-		expect(rendered.properties.location.type).toBe('object')
-		expect(rendered.properties.location.properties.city.type).toBe('string')
-		expect(rendered.properties.location.properties.city.description).toBe('City name')
-	})
-
-	it('keeps a $ref field required', () => {
-		// The real damage: an unknown node is optional in Zod, so the
-		// executor's "Required: <field>" hint never fired and an empty
-		// payload was forwarded to the server as if it were valid.
-		const parsed = mcpJsonSchemaToZod(asSchema(schema)).safeParse({})
-		expect(parsed.success).toBe(false)
-	})
-
-	it('enforces the referenced shape', () => {
-		const zod = mcpJsonSchemaToZod(asSchema(schema))
-		expect(zod.safeParse({ location: { city: 'Ankara' } }).success).toBe(true)
-		expect(zod.safeParse({ location: { lat: 39.9 } }).success).toBe(false)
-	})
-
-	it('drops the definition dictionary once its pointers are inlined', () => {
-		// Asserted on the inliner's own output, not the rendered schema: the
-		// Zod conversion reads only `properties`/`required`, so `$defs` could
-		// never have shown up downstream and the assertion would have been
-		// unable to fail.
-		const inlined = inlineSchemaRefs(schema)
-		expect(inlined.$defs).toBeUndefined()
-		expect(Object.keys(inlined)).toEqual(['type', 'properties', 'required'])
-	})
-
-	it('reads the legacy definitions keyword too', () => {
-		const rendered = render({
-			type: 'object',
-			properties: { who: { $ref: '#/definitions/Person' } },
-			definitions: { Person: { type: 'object', properties: { name: { type: 'string' } } } },
-		})
-		expect(rendered.properties.who.properties.name.type).toBe('string')
-	})
-})
-
-describe('pointers that cannot be followed', () => {
-	it('stops at a self-referential schema instead of recursing forever', () => {
-		const schema = {
-			type: 'object',
-			properties: { node: { $ref: '#/$defs/Node' } },
-			$defs: {
-				Node: {
-					type: 'object',
-					properties: {
-						value: { type: 'string' },
-						child: { $ref: '#/$defs/Node' },
-					},
-				},
-			},
-		}
-
-		// The outer level still expands — only the repeat is cut short, so a
-		// recursive type costs one branch rather than the whole document.
-		const rendered = render(schema)
-		expect(rendered.properties.node.properties.value.type).toBe('string')
-	})
-
-	it('expands the same pointer twice when the uses are siblings, not a cycle', () => {
-		const rendered = render({
-			type: 'object',
-			properties: { from: { $ref: '#/$defs/P' }, to: { $ref: '#/$defs/P' } },
-			$defs: { P: { type: 'object', properties: { id: { type: 'string' } } } },
-		})
-		expect(rendered.properties.from.properties.id.type).toBe('string')
-		expect(rendered.properties.to.properties.id.type).toBe('string')
-	})
-
-	it('leaves a dangling pointer permissive rather than guessing', () => {
-		expect(() =>
-			render({ type: 'object', properties: { x: { $ref: '#/$defs/Missing' } } }),
-		).not.toThrow()
-	})
-
-	it('leaves a pointer into another document alone', () => {
-		expect(() =>
-			render({ type: 'object', properties: { x: { $ref: 'https://example.test/s.json' } } }),
-		).not.toThrow()
-	})
-
-	it('lets a sibling keyword override the target', () => {
-		const inlined = inlineSchemaRefs({
-			$defs: { P: { type: 'string', description: 'from the definition' } },
-			properties: { a: { $ref: '#/$defs/P', description: 'from the use site' } },
-		}) as unknown as { properties: { a: { type: string; description: string } } }
-
-		expect(inlined.properties.a.type).toBe('string')
-		expect(inlined.properties.a.description).toBe('from the use site')
-	})
-
-	it('decodes an escaped pointer token', () => {
-		const inlined = inlineSchemaRefs({
-			$defs: { 'a/b': { type: 'number' } },
-			properties: { x: { $ref: '#/$defs/a~1b' } },
-		}) as unknown as { properties: { x: { type: string } } }
-
-		expect(inlined.properties.x.type).toBe('number')
-	})
-})
-
-describe('validation keywords', () => {
-	it('carries string bounds, pattern and format through', () => {
-		const rendered = render({
-			type: 'object',
-			properties: {
-				code: { type: 'string', minLength: 3, maxLength: 8, pattern: '^[A-Z]+$' },
-				contact: { type: 'string', format: 'email' },
-			},
-		})
-
-		expect(rendered.properties.code.minLength).toBe(3)
-		expect(rendered.properties.code.maxLength).toBe(8)
-		expect(rendered.properties.code.pattern).toBe('^[A-Z]+$')
-		expect(rendered.properties.contact.format).toBe('email')
-	})
-
-	it('enforces them, so a bad argument is caught before the round trip', () => {
-		const zod = mcpJsonSchemaToZod(
-			asSchema({
-				type: 'object',
-				properties: { code: { type: 'string', pattern: '^[A-Z]+$' } },
-				required: ['code'],
-			}),
-		)
-		expect(zod.safeParse({ code: 'ABC' }).success).toBe(true)
-		expect(zod.safeParse({ code: 'abc' }).success).toBe(false)
-	})
-
-	it('carries numeric bounds through', () => {
-		const rendered = render({
-			type: 'object',
-			properties: {
-				count: { type: 'integer', minimum: 1, maximum: 100, multipleOf: 5 },
-			},
-		})
-		expect(rendered.properties.count.minimum).toBe(1)
-		expect(rendered.properties.count.maximum).toBe(100)
-		expect(rendered.properties.count.multipleOf).toBe(5)
-	})
-
-	it('carries array bounds through', () => {
-		const rendered = render({
-			type: 'object',
-			properties: { tags: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 3 } },
-		})
-		expect(rendered.properties.tags.minItems).toBe(1)
-		expect(rendered.properties.tags.maxItems).toBe(3)
-	})
-
-	it('ignores a pattern this engine cannot compile rather than failing to register', () => {
-		// A server may use a regex dialect Node's engine rejects. An
-		// unenforced pattern is a smaller loss than a tool that vanishes.
-		expect(() =>
-			render({ type: 'object', properties: { x: { type: 'string', pattern: '[a-' } } }),
-		).not.toThrow()
-	})
-
-	it('does not invent a validator for an advisory format', () => {
-		const zod = mcpJsonSchemaToZod(
-			asSchema({ type: 'object', properties: { when: { type: 'string', format: 'duration' } } }),
-		)
-		expect(zod.safeParse({ when: 'whatever the server accepts' }).success).toBe(true)
-	})
-})
-
-describe('allOf', () => {
-	it('is flattened into one readable shape', () => {
-		const rendered = render({
-			type: 'object',
-			allOf: [
-				{ type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-				{ type: 'object', properties: { note: { type: 'string' } } },
-			],
-		})
-
-		expect(rendered.properties.id.type).toBe('string')
-		expect(rendered.properties.note.type).toBe('string')
-		expect(rendered.required).toEqual(['id'])
-	})
-
-	it('resolves refs inside its members', () => {
-		const rendered = render({
-			type: 'object',
-			allOf: [{ $ref: '#/$defs/Base' }],
-			$defs: { Base: { type: 'object', properties: { id: { type: 'string' } } } },
-		})
-		expect(rendered.properties.id.type).toBe('string')
-	})
-})
-
-describe('depth', () => {
-	it('converts a deeply nested schema without exhausting the stack', () => {
-		let node: Record<string, unknown> = { type: 'string' }
-		for (let i = 0; i < 200; i++) {
-			node = { type: 'object', properties: { next: node } }
-		}
-		expect(() => mcpJsonSchemaToZod(asSchema(node))).not.toThrow()
-	})
-})