import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { ok as resultOk } from "../../../src/domain/result.js"; import { readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { describe, expect, it } from "vitest"; import { z } from "zod"; import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { machoImage } from "../../../src/artifacts/apple/MachoImage.fixture.js"; import { CATALOG_IDENTITY } from "../../../src/catalogIdentity.js"; import { CLI_COMMAND_NAMES } from "../../../src/cliCommandNames.js"; import { PACKAGE_METADATA } from "../../../src/generatedPackageMetadata.js"; import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../../../src/identity.js"; import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js"; import { expandToolAvailability, sessionProvider, } from "../../../src/contracts/toolOutputSchemaPrimitives.js"; import { PROMPT_CONTRACTS } from "../../../src/contracts/promptContracts.js"; import { createServer } from "../../../src/server/createServer.js"; import { createServerIdentity } from "../../../src/serverIdentity.js"; import { observed } from "../../fixtures/analysisExecution.js"; import { buildCapabilityInventory } from "../../../src/application/CapabilityInventory.js"; import type { AnalysisProvider, CapabilityDescriptor, } from "../../../src/application/AnalysisProvider.js"; const availabilityProvider = ( operations: readonly CapabilityDescriptor["operation"][] = [ "current_address", ], ): AnalysisProvider => { const identity = { id: "fixture", name: "Fixture", version: "1" }; const capability = ( operation: CapabilityDescriptor["operation"], ): CapabilityDescriptor => ({ provider: identity, operation, available: true, reason: null, effects: { mutatesArtifact: false, launchesProcess: false, mayShowUi: false, mayAccessNetwork: false, mayWriteFilesystem: false, changesPermissions: false, requiresRoot: false, }, limitations: [], }); return { identity: () => identity, capabilities: () => operations.map(capability), createClient: () => ({ health: () => Promise.resolve(), execute: () => Promise.resolve(observed(null)), close: () => Promise.resolve(resultOk(null)), }), }; }; const statusCapability = ( operation: string, availability: | { readonly available: true } | { readonly available: false; readonly availability_code: "unsupported_host"; readonly reason: string; } = { available: true }, ) => ({ provider: { id: "status-fixture", name: "Status fixture", version: null }, shared_limitations: [], groups: [ { operations: [operation], effects: [], limitations: [], ...(availability.available ? { available: true as const, reason: null, availability_code: null } : availability), }, ], }); describe("server and catalog identity", () => { it("derives package and SDK versions from canonical package metadata", async () => { const packageJson = JSON.parse(await readFile("package.json", "utf8")); const packageLock = JSON.parse(await readFile("package-lock.json", "utf8")); expect(PACKAGE_METADATA).toMatchObject({ name: packageJson.name, version: packageJson.version, serverSdkVersion: packageJson.dependencies["@modelcontextprotocol/server"], clientSdkVersion: packageJson.dependencies["@modelcontextprotocol/client"], coreSdkVersion: packageLock.packages["node_modules/@modelcontextprotocol/core"].version, }); expect(PRODUCT_IDENTITY.packageVersion).toBe(packageJson.version); expect(SDK_IDENTITY.server).toBe( packageJson.dependencies["@modelcontextprotocol/server"], ); expect(new Set(CLI_COMMAND_NAMES).size).toBe(CLI_COMMAND_NAMES.length); expect(CATALOG_IDENTITY.counts).toEqual({ cli_commands: CLI_COMMAND_NAMES.length, mcp_tools: TOOL_CONTRACTS.length, mcp_prompts: PROMPT_CONTRACTS.length, }); expect(CATALOG_IDENTITY.digests.combined_sha256).toMatch(/^[a-f0-9]{64}$/u); }); it("reports unknown without a live comparison and distinguishes aligned from stale", () => { const unknown = createServerIdentity({ startedAt: "2026-07-13T00:00:00.000Z", }); expect(unknown.alignment.state).toBe("unknown"); const aligned = createServerIdentity({ startedAt: "2026-07-13T00:00:00.000Z", expected: { package_version: PRODUCT_IDENTITY.packageVersion, catalog_digest: CATALOG_IDENTITY.digests.combined_sha256, server_path: process.argv[1] ?? "unknown", }, }); expect(aligned.alignment).toMatchObject({ state: "aligned", reasons: [] }); const stale = createServerIdentity({ startedAt: "2026-07-13T00:00:00.000Z", expected: { package_version: "1.2.0", catalog_digest: "0".repeat(64), }, }); expect(stale.alignment).toMatchObject({ state: "mcp_server_restart_required", reasons: ["package_version_mismatch", "catalog_digest_mismatch"], }); }); it("reports composed, host, and target-specific availability truthfully", () => { const policy = { processCaptureEnabled: true, investigationInputRoots: 1, }; const composed = buildCapabilityInventory( { open: true, kind: "executable", format: "mach-o", capabilities: [ "list_segments", "list_documents", "list_procedures", "list_strings", ].map((operation) => statusCapability(operation)), }, policy, ); expect(composed).toContainEqual( expect.objectContaining({ name: "binary_overview", available: true }), ); const artifactTarget = buildCapabilityInventory( { open: true, kind: "artifact", format: "javascript", capabilities: [statusCapability("current_address")], }, policy, ); expect(artifactTarget).toContainEqual( expect.objectContaining({ name: "current_address", available: false, reason: "target_unsupported", }), ); const unsupportedHost = buildCapabilityInventory( { open: true, kind: "executable", format: "elf", capabilities: [ statusCapability("inspect_macho", { available: false, availability_code: "unsupported_host", reason: "Native macOS utilities require macOS.", }), ], }, policy, ); expect(unsupportedHost).toContainEqual( expect.objectContaining({ name: "inspect_macho", available: false, reason: "unsupported_host", }), ); }); }); describe("live server identity over MCP", () => { it("exposes live identity, a stable catalog, and changing availability", async () => { const session = createTestBinarySession(availabilityProvider()); const server = createServer({ kind: "session", session }); const client = new Client( { name: "identity-test", version: "9" }, { capabilities: { elicitation: { form: {} }, }, }, ); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); let toolListChanges = 0; client.setNotificationHandler("notifications/tools/list_changed", () => { toolListChanges += 1; }); try { await server.connect(serverTransport); await client.connect(clientTransport); await assertLiveIdentity(client); await assertSessionIdentity(client); expect( (await client.listTools()).tools.map(({ name }) => name), ).toContain("current_address"); await client.callTool({ name: "open_binary", arguments: { path: process.execPath }, }); expect(toolListChanges).toBe(0); expect( (await client.listTools()).tools.map(({ name }) => name), ).toContain("current_address"); } finally { await Promise.allSettled([ client.close(), server.close(), session.close(), ]); } }, 10_000); }); describe("active-target availability over MCP", () => { it("advertises active-target tools only when a matching target is open", async () => { const session = createTestBinarySession( availabilityProvider(["inspect_macho", "inspect_artifact"]), ); const server = createServer({ kind: "session", session }); const client = new Client({ name: "availability-test", version: "1" }); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); const directory = await createTestTempDirectory("rea-target-availability-"); const executable = join(directory, "tool"); const plist = join(directory, "Info.plist"); await writeFile(executable, machoImage({})); await writeFile(plist, PLIST_XML); try { await server.connect(serverTransport); await client.connect(clientTransport); const listed = await toolNames(client); expect(await activeTargetReasons(client)).toEqual({ inspect_macho: "target_required", inspect_artifact: "target_required", inspect_managed_artifact: "available", }); const call = await client.callTool({ name: "inspect_macho", arguments: {}, }); expect(parseMcpToolError(call)).toMatchObject({ error: { code: "target_unavailable" }, }); await openTarget(client, plist); expect(await activeTargetReasons(client)).toEqual({ inspect_macho: "target_unsupported", inspect_artifact: "available", inspect_managed_artifact: "available", }); await client.callTool({ name: "close_binary", arguments: {} }); await openTarget(client, executable); expect(await activeTargetReasons(client)).toEqual({ inspect_macho: "available", inspect_artifact: "available", inspect_managed_artifact: "available", }); await client.callTool({ name: "close_binary", arguments: {} }); expect((await activeTargetReasons(client)).inspect_macho).toBe( "target_required", ); expect(await toolNames(client)).toEqual(listed); } finally { await Promise.allSettled([ client.close(), server.close(), session.close(), ]); } }, 10_000); }); const PLIST_XML = 'CFBundleNameFixture'; const toolNames = async (client: Client): Promise => (await client.listTools()).tools.map(({ name }) => name); const openTarget = async (client: Client, path: string): Promise => { const opened = await client.callTool({ name: "open_binary", arguments: { path }, }); expect(opened.isError ?? false).toBe(false); }; const activeTargetReasons = async ( client: Client, ): Promise> => { const status = await client.callTool({ name: "binary_session", arguments: {}, }); const availability = expandToolAvailability( z.object({ result: sessionProvider }).parse(status.structuredContent).result .tool_availability, ); return Object.fromEntries( ["inspect_macho", "inspect_artifact", "inspect_managed_artifact"].map( (name) => [name, availability.find((tool) => tool.name === name)?.reason], ), ); }; const assertLiveIdentity = async (client: Client): Promise => { const identity = await client.callTool({ name: "binary_session", arguments: {}, }); const status = z .object({ result: sessionProvider }) .parse(identity.structuredContent).result; expect(Object.keys(status.server_identity.catalog).sort()).toEqual([ "counts", "digests", ]); const availability = expandToolAvailability(status.tool_availability); expect(availability.map(({ name }) => name).sort()).toEqual( TOOL_CONTRACTS.map(({ name }) => name).sort(), ); for (const contract of TOOL_CONTRACTS) { expect(availability).toContainEqual( expect.objectContaining({ name: contract.name, surface: contract.kind, effects: contract.effects, annotations: { read_only: contract.annotations.readOnlyHint ?? false, destructive: contract.annotations.destructiveHint ?? false, idempotent: contract.annotations.idempotentHint ?? false, open_world: contract.annotations.openWorldHint ?? true, }, }), ); } expect(identity.structuredContent).toMatchObject({ result: { server_identity: { package: { version: PRODUCT_IDENTITY.packageVersion }, server: { version: PRODUCT_IDENTITY.packageVersion }, sdk: { server: SDK_IDENTITY.server, client_test: PACKAGE_METADATA.clientSdkVersion, }, client: { name: "identity-test", version: "9" }, negotiated_protocol_version: expect.any(String), catalog: CATALOG_IDENTITY, alignment: { state: "unknown" }, }, }, }); }; const assertSessionIdentity = async (client: Client): Promise => { const status = await client.callTool({ name: "binary_session", arguments: { expected_package_version: "1.2.0" }, }); const parsed = z .object({ result: sessionProvider }) .parse(status.structuredContent); expect({ result: { ...parsed.result, tool_availability: expandToolAvailability( parsed.result.tool_availability, ), }, }).toMatchObject({ result: { server_identity: { catalog: { counts: { mcp_tools: TOOL_CONTRACTS.length, cli_commands: CLI_COMMAND_NAMES.length, }, }, alignment: { state: "mcp_server_restart_required" }, }, tool_availability: expect.arrayContaining([ expect.objectContaining({ name: "current_address", available: false, reason: "target_required", }), expect.objectContaining({ name: "capture_process_scenario", available: process.platform !== "win32", reason: process.platform === "win32" ? "unsupported_host" : "available", client_requirements: { required: [], optional: [], missing_required: [], missing_optional: [], }, }), expect.objectContaining({ name: "inspect_web_page", available: false, reason: "provider_missing", }), expect.objectContaining({ name: "analyze_javascript_application", available: true, reason: "available", remediation: null, }), ]), client_features: { elicitation_form: true, elicitation_url: false, roots: false, sampling: false, }, }, }); };