@aventara/mcp 0.0.0-stage → 1.0.0-rc.1

package/dist/mcp.binder.js

@@ -0,0 +1,256 @@
+import { mcpFailureReporterOf } from "@aventara/core/internal";
+import { AvProtocol, } from "@aventara/core/protocol";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { authorizedAccess, jsonAnswer, loopbackAccess, metadataAnswer, metadataPathOf, } from "./endpoint-access.policy.js";
+import { translateOperationCall, translateTransactionCall, } from "./tool-call.translator.js";
+import { CONTRACT_RESOURCE_URI, compileToolCatalog, OPERATION_FAMILIES, TRANSACTION_TOOL, } from "./tool-catalog.compiler.js";
+import { internalFailureResult, refusedCallResult, toolResultOf, } from "./tool-result.encoder.js";
+const SERVER_INSTRUCTIONS = `This server reads and writes an application's data through Aventara. Read the resource ${CONTRACT_RESOURCE_URI} first: it describes every resource, its fields and the operations it offers. Then call a tool with { resource, variant, args }. A failed call answers isError with the outcome code and the issues to fix.`;
+export function bind(framework) {
+    const endpoint = framework.mcp;
+    if (endpoint === undefined) {
+        throw new Error("AvMcp.bind: this Framework's configuration has no `mcp`, so it serves no MCP endpoint. Add `mcp: '/mcp'` (or `{ path, authorization }`) to the configuration.");
+    }
+    const agent = framework.contracts.agent;
+    const protocol = AvProtocol.bind(framework, { origin: "agent" });
+    const bound = {
+        endpoint,
+        protocol,
+        identity: { version: agent.protocol.version, hash: agent.protocol.hash },
+        tools: compileToolCatalog({
+            surface: protocol.surface(),
+            maxTransactionOperations: agent.limits.maxTransactionOperations,
+        }),
+        contractDocument: protocol.encodeContract({
+            method: "GET",
+            path: "/_contract",
+            headers: {},
+            body: { kind: "raw", content: "" },
+        }).body,
+        maxRequestBytes: agent.limits.maxRequestBytes,
+        reportFailure: mcpFailureReporterOf(framework),
+    };
+    const routes = Object.freeze([
+        Object.freeze({
+            kind: "endpoint",
+            path: endpoint.path === "" ? "/" : endpoint.path,
+            methods: Object.freeze(["POST", "GET", "DELETE"]),
+        }),
+        ...(endpoint.authorization === undefined
+            ? []
+            : [
+                Object.freeze({
+                    kind: "metadata",
+                    path: metadataPathOf(endpoint.path),
+                    methods: Object.freeze(["GET"]),
+                }),
+            ]),
+    ]);
+    return Object.freeze({
+        surface: () => routes,
+        maxRequestBytes: bound.maxRequestBytes,
+        handleEndpoint: (request, options) => answerEndpoint(bound, request, options?.state),
+        encodeMetadata: (request) => answerMetadata(bound.endpoint, request),
+    });
+}
+function headerReader(headers) {
+    const lowered = new Map();
+    for (const [name, value] of Object.entries(headers)) {
+        const values = typeof value === "string" ? [value] : (value ?? []);
+        if (values.length > 0) {
+            const key = name.toLowerCase();
+            const before = lowered.get(key);
+            lowered.set(key, before === undefined
+                ? values.join(", ")
+                : `${before}, ${values.join(", ")}`);
+        }
+    }
+    return (name) => lowered.get(name.toLowerCase());
+}
+function urlOf(request) {
+    try {
+        return new URL(request.url);
+    }
+    catch {
+        return undefined;
+    }
+}
+const BAD_URL = () => jsonAnswer(400, {
+    error: "invalid_request",
+    error_description: "The request URL is not absolute.",
+});
+function answerMetadata(endpoint, request) {
+    const url = urlOf(request);
+    if (url === undefined) {
+        return BAD_URL();
+    }
+    if (endpoint.authorization === undefined) {
+        return jsonAnswer(404, {
+            error: "not_found",
+            error_description: "This MCP endpoint has no authorization.",
+        });
+    }
+    return metadataAnswer(request.method, url.origin, endpoint.path, endpoint.authorization);
+}
+const rpcRefusal = (status, message, headers = {}) => jsonAnswer(status, { jsonrpc: "2.0", error: { code: -32000, message }, id: null }, headers);
+async function answerEndpoint(bound, request, state) {
+    try {
+        const url = urlOf(request);
+        if (url === undefined) {
+            return BAD_URL();
+        }
+        const header = headerReader(request.headers);
+        const { authorization } = bound.endpoint;
+        const access = authorization === undefined
+            ? loopbackAccess(request.remoteAddress, header)
+            : await authorizedAccess(header("authorization"), url.origin, bound.endpoint.path, authorization);
+        if (!access.ok) {
+            return access.response;
+        }
+        if (request.method !== "POST") {
+            return rpcRefusal(405, "Method not allowed: this endpoint is stateless; use POST.", {
+                Allow: "POST",
+            });
+        }
+        const coding = header("content-encoding")?.trim().toLowerCase();
+        if (coding !== undefined && coding !== "" && coding !== "identity") {
+            return rpcRefusal(415, "Unsupported Content-Encoding.");
+        }
+        return await answerMessage(bound, request, url, seedOf(state, access.caller));
+    }
+    catch (error) {
+        bound.reportFailure(error);
+        return rpcRefusal(500, "Internal error.");
+    }
+}
+function seedOf(state, caller) {
+    if (state === undefined && caller === undefined) {
+        return undefined;
+    }
+    return async () => {
+        const seeded = state === undefined ? {} : await state();
+        return caller === undefined
+            ? seeded
+            : { ...seeded, mcp: { claims: caller.claims } };
+    };
+}
+const DROPPED_HEADERS = new Set([
+    "host",
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "upgrade",
+    "content-length",
+    "content-encoding",
+]);
+function webRequestOf(request, url) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (DROPPED_HEADERS.has(name.toLowerCase()) || value === undefined) {
+            continue;
+        }
+        for (const item of typeof value === "string" ? [value] : value) {
+            headers.append(name, item);
+        }
+    }
+    return new Request(url, {
+        method: "POST",
+        headers,
+        body: typeof request.body === "string"
+            ? request.body
+            : new Uint8Array(request.body),
+    });
+}
+async function answerMessage(bound, request, url, state) {
+    const server = serverFor(bound, request.headers, state);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        enableJsonResponse: true,
+        maxRequestBodySize: bound.maxRequestBytes,
+    });
+    try {
+        await server.connect(transport);
+        const response = await transport.handleRequest(webRequestOf(request, url));
+        const headers = {};
+        response.headers.forEach((value, name) => {
+            headers[name] = value;
+        });
+        return { status: response.status, headers, body: await response.text() };
+    }
+    finally {
+        await server.close();
+    }
+}
+function serverFor(bound, headers, state) {
+    const server = new Server({ name: "aventara", title: "Aventara", version: bound.identity.hash }, {
+        capabilities: { tools: {}, resources: {} },
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    const options = state === undefined ? {} : { state };
+    server.setRequestHandler(ListToolsRequestSchema, guarded(bound, () => ({ tools: bound.tools })));
+    server.setRequestHandler(CallToolRequestSchema, async (call) => {
+        const name = call.params.name;
+        if (!bound.tools.some((tool) => tool.name === name)) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+        }
+        try {
+            return await callTool(bound, name, call.params.arguments, headers, options);
+        }
+        catch (error) {
+            return internalFailureResult(bound.reportFailure(error));
+        }
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, guarded(bound, () => ({
+        resources: [
+            {
+                uri: CONTRACT_RESOURCE_URI,
+                name: "contract",
+                title: "Agent Contract",
+                description: "Every resource the tools reach: its fields and their types, what can be filtered, selected, created and updated, the operations it offers, and the request limits.",
+                mimeType: "application/json",
+            },
+        ],
+    })));
+    server.setRequestHandler(ReadResourceRequestSchema, guarded(bound, (read) => {
+        if (read.params.uri !== CONTRACT_RESOURCE_URI) {
+            throw new McpError(-32002, `Resource not found: ${read.params.uri}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: CONTRACT_RESOURCE_URI,
+                    mimeType: "application/json",
+                    text: bound.contractDocument,
+                },
+            ],
+        };
+    }));
+    return server;
+}
+function guarded(bound, handler) {
+    return async (...args) => {
+        try {
+            return await handler(...args);
+        }
+        catch (error) {
+            if (error instanceof McpError) {
+                throw error;
+            }
+            throw new McpError(ErrorCode.InternalError, bound.reportFailure(error).cause.message);
+        }
+    };
+}
+async function callTool(bound, name, input, headers, options) {
+    if (name === TRANSACTION_TOOL) {
+        const translated = await translateTransactionCall(input, headers, bound.identity);
+        return (translated.ok
+            ? toolResultOf(await bound.protocol.handleTransaction(translated.request, options))
+            : refusedCallResult(translated.message));
+    }
+    const family = OPERATION_FAMILIES.find((candidate) => candidate === name);
+    const translated = translateOperationCall(family, input, headers, bound.identity);
+    return (translated.ok
+        ? toolResultOf(await bound.protocol.handleOperation(translated.request, options))
+        : refusedCallResult(translated.message));
+}

package/dist/tool-call.translator.d.ts

@@ -0,0 +1,32 @@
+import { type AvProtocolRequest } from "@aventara/core/protocol";
+import { type OperationFamily } from "./tool-catalog.compiler.js";
+/** The Agent Contract's identity, sent as the protocol's identity headers. */
+export type AgentIdentity = {
+    readonly version: number;
+    readonly hash: string;
+};
+/** A tool call as the protocol request that runs it, or why it cannot be one. */
+export type TranslatedCall = {
+    readonly ok: true;
+    readonly kind: "operation" | "transaction";
+    readonly request: AvProtocolRequest;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * A family tool's call: `{ resource, variant, args? }` as the operation route
+ * `/_resources/<resource>/<family>/<variant>` with `args` (or `{}`) as its body.
+ * An unknown Resource or variant is the protocol's to refuse (`A2001`, `A2002`);
+ * only a call that names none as a string is refused here.
+ */
+export declare function translateOperationCall(family: OperationFamily, input: unknown, received: Readonly<Record<string, string | readonly string[] | undefined>>, identity: AgentIdentity): TranslatedCall;
+/**
+ * The transaction tool's call: `{ steps: [{ resource, family, variant, args? }] }`
+ * as the `/_transactions` plan `{ operations: [...] }`, each step carrying the
+ * fingerprint the protocol requires and each `{ $ref: { operation, path } }`
+ * the fingerprint of the step it names — computed here, since an agent cannot,
+ * by the protocol's own algorithm. A reference that names no earlier step is
+ * left as written, for the protocol to refuse.
+ */
+export declare function translateTransactionCall(input: unknown, received: Readonly<Record<string, string | readonly string[] | undefined>>, identity: AgentIdentity): Promise<TranslatedCall>;

package/dist/tool-call.translator.js

@@ -0,0 +1,169 @@
+import { computeOperationFingerprint } from "@aventara/core/internal";
+import { AvProtocol } from "@aventara/core/protocol";
+import { jsonTextOf } from "./json-text.writer.js";
+import { CONTRACT_RESOURCE_URI, OPERATION_FAMILIES, TRANSACTION_TOOL, } from "./tool-catalog.compiler.js";
+const REPLACED_HEADERS = new Set([
+    "content-type",
+    "content-length",
+    "content-encoding",
+    "transfer-encoding",
+    AvProtocol.headers.protocolVersion.toLowerCase(),
+    AvProtocol.headers.contractHash.toLowerCase(),
+]);
+function headersOf(received, identity) {
+    const headers = {};
+    for (const [name, value] of Object.entries(received)) {
+        if (!REPLACED_HEADERS.has(name.toLowerCase())) {
+            headers[name] = value;
+        }
+    }
+    headers["content-type"] = "application/json";
+    headers[AvProtocol.headers.protocolVersion] = String(identity.version);
+    headers[AvProtocol.headers.contractHash] = identity.hash;
+    return headers;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isFamily = (value) => OPERATION_FAMILIES.includes(value);
+function protocolRequest(path, body, headers) {
+    return {
+        method: "POST",
+        path,
+        headers,
+        body: { kind: "raw", content: jsonTextOf(body) },
+    };
+}
+export function translateOperationCall(family, input, received, identity) {
+    if (!isRecord(input)) {
+        return {
+            ok: false,
+            message: `${family}: the arguments must be an object.`,
+        };
+    }
+    const { resource, variant, args } = input;
+    if (typeof resource !== "string" || typeof variant !== "string") {
+        return {
+            ok: false,
+            message: `${family}: \`resource\` and \`variant\` must be strings (read ${CONTRACT_RESOURCE_URI}).`,
+        };
+    }
+    const path = `/_resources/${[resource, family, variant].map(encodeURIComponent).join("/")}`;
+    return {
+        ok: true,
+        kind: "operation",
+        request: protocolRequest(path, args === undefined ? {} : args, headersOf(received, identity)),
+    };
+}
+export async function translateTransactionCall(input, received, identity) {
+    if (!isRecord(input) || !Array.isArray(input.steps)) {
+        return {
+            ok: false,
+            message: `${TRANSACTION_TOOL}: the arguments must be { steps: [{ resource, family, variant, args }] }.`,
+        };
+    }
+    const fingerprints = [];
+    const operations = [];
+    for (const [index, step] of input.steps.entries()) {
+        if (!isRecord(step) ||
+            typeof step.resource !== "string" ||
+            !isFamily(step.family) ||
+            typeof step.variant !== "string") {
+            return {
+                ok: false,
+                message: `${TRANSACTION_TOOL}: step ${index} must be { resource, family, variant, args } with family one of ${OPERATION_FAMILIES.join(", ")}.`,
+            };
+        }
+        const args = referenced(step.args === undefined ? {} : step.args, fingerprints);
+        const node = {
+            resource: step.resource,
+            family: step.family,
+            variant: step.variant,
+            args,
+        };
+        const fingerprint = await fingerprintOf(node);
+        fingerprints.push(fingerprint ?? "");
+        operations.push(fingerprint === undefined ? node : { ...node, fingerprint });
+    }
+    return {
+        ok: true,
+        kind: "transaction",
+        request: protocolRequest("/_transactions", { operations }, headersOf(received, identity)),
+    };
+}
+async function fingerprintOf(node) {
+    try {
+        return await computeOperationFingerprint(node);
+    }
+    catch {
+        return undefined;
+    }
+}
+function referenced(value, fingerprints) {
+    const root = {};
+    const stack = [
+        {
+            source: value,
+            assign: (copy) => {
+                root.value = copy;
+            },
+        },
+    ];
+    while (stack.length > 0) {
+        const { source, assign } = stack.pop();
+        if (Array.isArray(source)) {
+            const copy = new Array(source.length);
+            assign(copy);
+            for (let index = source.length - 1; index >= 0; index -= 1) {
+                stack.push({
+                    source: source[index],
+                    assign: (item) => {
+                        copy[index] = item;
+                    },
+                });
+            }
+            continue;
+        }
+        if (!isRecord(source)) {
+            assign(source);
+            continue;
+        }
+        const reference = withFingerprint(source, fingerprints);
+        if (reference !== undefined) {
+            assign(reference);
+            continue;
+        }
+        const copy = {};
+        assign(copy);
+        const keys = Object.keys(source);
+        for (const key of keys) {
+            Object.defineProperty(copy, key, {
+                value: undefined,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        for (let index = keys.length - 1; index >= 0; index -= 1) {
+            const key = keys[index];
+            stack.push({
+                source: source[key],
+                assign: (member) => {
+                    copy[key] = member;
+                },
+            });
+        }
+    }
+    return root.value;
+}
+function withFingerprint(value, fingerprints) {
+    const reference = value.$ref;
+    if (Object.keys(value).length !== 1 || !isRecord(reference)) {
+        return undefined;
+    }
+    const operation = reference.operation;
+    const fingerprint = typeof operation === "number" && Number.isInteger(operation)
+        ? fingerprints[operation]
+        : undefined;
+    return fingerprint === undefined || fingerprint === ""
+        ? value
+        : { $ref: { ...reference, fingerprint } };
+}

package/dist/tool-catalog.compiler.d.ts

@@ -0,0 +1,44 @@
+import type { AvProtocolBinding } from "@aventara/core/protocol";
+/** The operation families, in the order the protocol defines them. */
+export declare const OPERATION_FAMILIES: readonly ["find", "create", "update", "delete", "upsert"];
+/** One operation family: the name of its MCP tool. */
+export type OperationFamily = (typeof OPERATION_FAMILIES)[number];
+/** The name of the tool that runs a plan of operations. */
+export declare const TRANSACTION_TOOL = "transaction";
+/** Every tool name the catalog can offer. */
+export type McpToolName = OperationFamily | typeof TRANSACTION_TOOL;
+/** An MCP tool's behaviour hints. */
+export type McpToolAnnotations = {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint?: boolean;
+    readonly openWorldHint: boolean;
+};
+/** A JSON Schema object, as MCP carries it. */
+export type JsonSchemaObject = {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, object>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+};
+/** One tool as `tools/list` answers it. */
+export type McpToolDefinition = {
+    readonly name: McpToolName;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly outputSchema: JsonSchemaObject;
+    readonly annotations: McpToolAnnotations;
+};
+/** The URI of the MCP resource that holds the Agent Contract. */
+export declare const CONTRACT_RESOURCE_URI = "aventara://contract";
+/** What the catalog is compiled from: the agent binding's surface, and its plan limit. */
+export type CatalogSource = {
+    readonly surface: ReturnType<AvProtocolBinding["surface"]>;
+    readonly maxTransactionOperations: number;
+};
+/**
+ * The tools the agent binding's surface supports: one per family it offers, in
+ * the protocol's family order, then `transaction` when the surface has the
+ * transactions route and at least one operation.
+ */
+export declare function compileToolCatalog(source: CatalogSource): readonly McpToolDefinition[];