Files
reverse-engineering-anything/src/server/serverInstructions.ts
T
morluto a4da4e7230 docs(mcp): clarify tool selection and recovery guidance (#9817)
* docs(mcp): clarify tool selection and recovery guidance

* test(mcp): prune wording assertions and preserve scope checks
2026-11-10 07:49:23 -05:00

48 lines
2.8 KiB
TypeScript

import { toolFamilyId } from "../contracts/toolFamilies.js";
import { UNTRUSTED_CONTENT_INSTRUCTIONS } from "./toolResultEncoding.js";
import { recoveryInstructions } from "./recoveryInstructions.js";
const TARGET_FREE_INSTRUCTIONS =
"REA provides reverse-engineering tools for local artifacts, native binaries, managed code, browser pages, and runtimes. Use the tool that directly answers the question; discover targets or inspect inventory only when needed. Tool results include inline Evidence and report their coverage and limitations.";
// Only advertise the lifecycle when `session` is in scope: otherwise
// `open_binary` and `close_binary` are disabled and the guidance would direct
// initialization to a call that always fails.
const SESSION_LIFECYCLE_INSTRUCTIONS =
"An opened target persists across turns. When finished, export needed Evidence and call close_binary; its snapshot_path can retain analysis.";
const ACTIVE_TARGET_INSTRUCTIONS =
"REA analyzes the active reverse-engineering target. Use the analysis tool that answers the question directly. Search or list symbols when discovery is needed.";
// Only name the enhanced-family dossier tool when that family is in scope:
// otherwise `analyze_function` is disabled and the recommendation always fails.
const FUNCTION_DOSSIER_INSTRUCTIONS =
"analyze_function provides a function dossier, and focused procedure tools return individual facets.";
const EVIDENCE_INTERPRETATION_INSTRUCTIONS =
"Preserve caller-selected paths and returned IDs; do not rebase REA host paths onto the client workspace. An unresolved lookup or exhausted page with partial source coverage does not establish target absence.";
/** Whether the scope advertises the family that owns a named tool. */
const advertisesToolFamily = (
advertisedToolFamilies: ReadonlySet<string> | undefined,
tool: string,
): boolean => {
if (advertisedToolFamilies === undefined) return true;
const family = toolFamilyId(tool);
return family !== undefined && advertisedToolFamilies.has(family);
};
export const serverInstructions = (
hasSession: boolean,
advertisedToolFamilies: ReadonlySet<string> | undefined,
): string => {
const guidance = (tool: string, text: string): string =>
advertisesToolFamily(advertisedToolFamilies, tool) ? ` ${text}` : "";
const recovery = recoveryInstructions(
advertisesToolFamily(advertisedToolFamilies, "update_analysis_settings"),
);
if (!hasSession)
return `${ACTIVE_TARGET_INSTRUCTIONS}${guidance("analyze_function", FUNCTION_DOSSIER_INSTRUCTIONS)} ${EVIDENCE_INTERPRETATION_INSTRUCTIONS} ${recovery} ${UNTRUSTED_CONTENT_INSTRUCTIONS}`;
return `${TARGET_FREE_INSTRUCTIONS}${guidance("close_binary", SESSION_LIFECYCLE_INSTRUCTIONS)} ${EVIDENCE_INTERPRETATION_INSTRUCTIONS} ${recovery} ${UNTRUSTED_CONTENT_INSTRUCTIONS}`;
};