Group repeated session tool availability and provider capability facts, preserve complete named contracts and ordered limitations, and remove duplicate catalog descriptors. Update consumers and migration guidance. Validated by all 31 CI jobs, focused source checks, and actual Claude Code/Linux Hopper/native Windows Ghidra small-target workflows on the current integration tree. Refs #723. BREAKING CHANGE: binary_session no longer includes server_identity.catalog.tools; tool_availability and provider capabilities use grouped facts documented in docs/mcp-contracts.md. Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
456 lines
15 KiB
TypeScript
456 lines
15 KiB
TypeScript
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 =
|
|
'<?xml version="1.0" encoding="UTF-8"?><plist version="1.0"><dict><key>CFBundleName</key><string>Fixture</string></dict></plist>';
|
|
|
|
const toolNames = async (client: Client): Promise<string[]> =>
|
|
(await client.listTools()).tools.map(({ name }) => name);
|
|
|
|
const openTarget = async (client: Client, path: string): Promise<void> => {
|
|
const opened = await client.callTool({
|
|
name: "open_binary",
|
|
arguments: { path },
|
|
});
|
|
expect(opened.isError ?? false).toBe(false);
|
|
};
|
|
|
|
const activeTargetReasons = async (
|
|
client: Client,
|
|
): Promise<Record<string, unknown>> => {
|
|
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<void> => {
|
|
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<void> => {
|
|
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,
|
|
},
|
|
},
|
|
});
|
|
};
|