mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 13:45:30 +00:00
* refactor(contracts): move the CLI command name owner into src/contracts * refactor(contracts): own catalog identity in contracts and server identity in process (#11435) * refactor(contracts): move catalog identity into contracts and server identity into process * refactor(contracts): own the advertised MCP schema presentation in contracts * test(mcp): import the advertised presentation from contracts in toolSchemaValidity * test(release): expect the catalog identity at its contracts path in the canary * test(mcp): import the catalog identity from contracts in syntheticContractSurfaces * refactor(contracts): import CLI command names from contracts in the capability conformance test
166 lines
6.0 KiB
TypeScript
166 lines
6.0 KiB
TypeScript
import type { RegisteredTool } from "@modelcontextprotocol/server";
|
|
import type { z } from "zod";
|
|
import {
|
|
AnalysisInputError,
|
|
AnalysisResourceConstraintError,
|
|
} from "../domain/analysisErrorCore.js";
|
|
import { ownedJsonObjectSchema } from "../domain/jsonValue.js";
|
|
import { encodeToolResult } from "./toolResultEncoding.js";
|
|
import type { ToolResultDelivery } from "./ToolResultDelivery.js";
|
|
import {
|
|
DISCOVER_TOOLS,
|
|
HOT_TOOL_NAMES,
|
|
progressiveCatalogIdentity,
|
|
type CatalogIdentity,
|
|
} from "../contracts/catalog/catalogDiscovery.js";
|
|
|
|
/** Per-connection visibility; canonical SDK handles retain validation and authority. */
|
|
export class ProgressiveToolCatalog {
|
|
readonly identity: CatalogIdentity;
|
|
private readonly tools: ReadonlyMap<
|
|
string,
|
|
{ registered: RegisteredTool; description: string; search: string }
|
|
>;
|
|
|
|
constructor(
|
|
registrations: ReadonlyMap<string, RegisteredTool>,
|
|
identity: CatalogIdentity,
|
|
private readonly batchChanges: (change: () => void) => void,
|
|
private readonly delivery: () => ToolResultDelivery,
|
|
) {
|
|
this.identity = progressiveCatalogIdentity(identity);
|
|
// Disabled family registrations are outside the discoverable scope. Never
|
|
// let discovery re-enable a tool the caller excluded from this server.
|
|
this.tools = new Map(
|
|
[...registrations]
|
|
.filter(([, tool]) => tool.enabled)
|
|
.map(([name, registered]) => [
|
|
name,
|
|
{
|
|
registered,
|
|
description: (registered.description ?? "").slice(0, 240),
|
|
search:
|
|
`${name} ${name.replaceAll("_", " ")} ${registered.description ?? ""}`.toLowerCase(),
|
|
},
|
|
]),
|
|
);
|
|
this.reset();
|
|
}
|
|
|
|
/** A reused HTTP server starts each new transport with the hot inventory. */
|
|
reset(): void {
|
|
this.batchChanges(() => {
|
|
for (const [name, { registered }] of this.tools) {
|
|
if (registered.enabled && !HOT_TOOL_NAMES.has(name))
|
|
registered.disable();
|
|
}
|
|
});
|
|
}
|
|
|
|
discover(input: z.infer<typeof DISCOVER_TOOLS.inputSchema>) {
|
|
const names =
|
|
input.names === undefined ? undefined : [...new Set(input.names)];
|
|
const unknown = names?.filter((name) => !this.tools.has(name)) ?? [];
|
|
if (unknown.length > 0)
|
|
return this.delivery().toErrorToolResult(
|
|
new AnalysisInputError(
|
|
DISCOVER_TOOLS.name,
|
|
{
|
|
userMessage:
|
|
"Unknown or excluded tool names. No tools were loaded.",
|
|
remediationAction:
|
|
"Search with query to find exact in-scope names.",
|
|
conformsToInputContract: true,
|
|
},
|
|
unknown.map((name) => ({
|
|
path: ["names"],
|
|
reason: "invalid_value",
|
|
message: name,
|
|
})),
|
|
),
|
|
false,
|
|
);
|
|
const words = (input.query ?? "")
|
|
.toLowerCase()
|
|
.split(/\s+/u)
|
|
.filter(Boolean);
|
|
const matches =
|
|
names ??
|
|
[...this.tools]
|
|
.filter(([, tool]) => words.every((word) => tool.search.includes(word)))
|
|
.map(([name]) => name)
|
|
.sort((left, right) => {
|
|
const score = (name: string) =>
|
|
words.filter((word) => name.includes(word)).length;
|
|
return (
|
|
score(right) - score(left) ||
|
|
(left < right ? -1 : left > right ? 1 : 0)
|
|
);
|
|
});
|
|
const page =
|
|
names ?? matches.slice(input.offset, input.offset + input.limit);
|
|
const selected = page.map((name) => ({ name, ...this.tools.get(name)! }));
|
|
const result: z.infer<typeof DISCOVER_TOOLS.outputSchema> = {
|
|
profile: "hot-cold",
|
|
inventory_count: this.tools.size + 1,
|
|
loaded_count:
|
|
1 +
|
|
[...this.tools.values()].filter(({ registered }) => registered.enabled)
|
|
.length +
|
|
selected.filter(({ registered }) => !registered.enabled).length,
|
|
total_matches: matches.length,
|
|
next_offset:
|
|
names === undefined && input.offset + page.length < matches.length
|
|
? input.offset + page.length
|
|
: null,
|
|
tools: selected.map(({ name, description, registered }) => ({
|
|
name,
|
|
description,
|
|
input_schema: registered.inputSchema?.["~standard"].jsonSchema.input({
|
|
target: "draft-2020-12",
|
|
}) ?? { type: "object" },
|
|
})),
|
|
next_step:
|
|
selected.length === 0
|
|
? matches.length === 0
|
|
? "No matches. Try fewer or different task keywords, or browse without query."
|
|
: "No remaining matches at this offset. Use offset 0 to restart this query, or select an earlier offset."
|
|
: "Call the returned tool by its original name using input_schema. Your client must refresh tools/list first; if it cannot, reconnect with REA_MCP_TOOL_CATALOG_PROFILE=full.",
|
|
};
|
|
// This reply borrows read-only SDK schema projections for synchronous
|
|
// encoding; validate the new reply without copying their complete trees.
|
|
const payload = ownedJsonObjectSchema.parse(result);
|
|
const delivery = this.delivery();
|
|
const encoded = encodeToolResult(payload, delivery.resultBudgetBytes);
|
|
if (!encoded.ok)
|
|
return delivery.toErrorToolResult(
|
|
new AnalysisResourceConstraintError(
|
|
DISCOVER_TOOLS.name,
|
|
"transport",
|
|
"The discovery page exceeds the reply budget. No tools were loaded.",
|
|
{
|
|
result_budget_bytes: delivery.resultBudgetBytes,
|
|
response_bytes_at_least: encoded.bytesAtLeast,
|
|
constraint: encoded.constraint,
|
|
},
|
|
{
|
|
remediationAction:
|
|
"Reduce limit or request fewer exact names, then retry.",
|
|
},
|
|
),
|
|
false,
|
|
);
|
|
// Visibility changes only after both reply representations fit. A failed
|
|
// page can be retried without silently enabling unreported definitions.
|
|
this.batchChanges(() => {
|
|
for (const { registered } of selected) {
|
|
if (!registered.enabled) registered.enable();
|
|
}
|
|
});
|
|
return {
|
|
content: [{ type: "text" as const, text: encoded.text }],
|
|
structuredContent: payload,
|
|
};
|
|
}
|
|
}
|