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

package/dist/tool-catalog.compiler.js

@@ -0,0 +1,210 @@
+export const OPERATION_FAMILIES = [
+    "find",
+    "create",
+    "update",
+    "delete",
+    "upsert",
+];
+export const TRANSACTION_TOOL = "transaction";
+const VARIANT_ORDER = {
+    find: ["first", "unique", "many", "count"],
+    create: ["one", "many", "count"],
+    update: ["first", "unique", "many", "count"],
+    delete: ["first", "unique", "many", "count"],
+    upsert: ["unique"],
+};
+const VARIANT_ARGUMENTS = {
+    find: {
+        first: "where?, orderBy?, select? | include?",
+        unique: "where (an identifier), select? | include?",
+        many: "where?, orderBy?, limit?, offset?, cursor?, select? | include?",
+        count: "where?",
+    },
+    create: {
+        one: "data, select? | include?",
+        many: "data (a list), select? | include?",
+        count: "data (a list)",
+    },
+    update: {
+        first: "where?, orderBy?, data, select? | include?",
+        unique: "where (an identifier), data, select? | include?",
+        many: "where?, data, select? | include?",
+        count: "where?, data",
+    },
+    delete: {
+        first: "where?, orderBy?, select? | include?",
+        unique: "where (an identifier), select? | include?",
+        many: "where?, select? | include?",
+        count: "where?",
+    },
+    upsert: {
+        unique: "where (an identifier), create, update, select? | include?",
+    },
+};
+const FAMILY_SUMMARY = {
+    find: "Reads records of one resource.",
+    create: "Creates records in one resource.",
+    update: "Changes existing records of one resource.",
+    delete: "Deletes records of one resource.",
+    upsert: "Updates the record an identifier names in one resource, or creates it when there is none.",
+};
+const ANNOTATIONS = {
+    find: { readOnlyHint: true, openWorldHint: false },
+    create: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    update: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    delete: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    upsert: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    transaction: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
+};
+export const CONTRACT_RESOURCE_URI = "aventara://contract";
+const ENVELOPE_SCHEMA = {
+    type: "object",
+    properties: {
+        data: {
+            description: "The operation's result (for a transaction, each step's in order), in the protocol's wire forms.",
+        },
+        code: {
+            type: "string",
+            description: "The outcome code: A1xxx for a success.",
+        },
+        cause: {
+            description: "Why the call failed: a message, and the issues (path, code, check, params, message) to fix before retrying. null on success.",
+        },
+    },
+    required: ["code"],
+};
+const READ_THE_CONTRACT = `Read the resource ${CONTRACT_RESOURCE_URI} first: it lists each resource's fields, which of them can be filtered, selected, created and updated, and which variants each resource offers.`;
+function offersOf(surface) {
+    const collected = new Map();
+    for (const route of surface) {
+        if (route.kind !== "operation") {
+            continue;
+        }
+        const family = route.family;
+        const byResource = collected.get(family) ?? new Map();
+        collected.set(family, byResource);
+        const variants = byResource.get(route.resource) ?? [];
+        byResource.set(route.resource, variants);
+        variants.push(route.variant);
+    }
+    return new Map([...collected].map(([family, byResource]) => [
+        family,
+        new Map([...byResource].map(([resource, variants]) => [
+            resource,
+            ordered(family, variants),
+        ])),
+    ]));
+}
+function ordered(family, variants) {
+    const present = new Set(variants);
+    return VARIANT_ORDER[family].filter((variant) => present.has(variant));
+}
+function familyTool(family, offer) {
+    const resources = [...offer.keys()];
+    const variants = ordered(family, [...offer.values()].flat());
+    const offered = [...offer]
+        .map(([resource, list]) => `${resource} (${list.join(", ")})`)
+        .join("; ");
+    const argumentsLine = variants
+        .map((variant) => `${family} ${variant}: ${VARIANT_ARGUMENTS[family][variant]}`)
+        .join(". ");
+    return {
+        name: family,
+        title: `${family[0]?.toUpperCase()}${family.slice(1)} records`,
+        description: [
+            FAMILY_SUMMARY[family],
+            READ_THE_CONTRACT,
+            `Offered: ${offered}.`,
+            `Arguments by variant: ${argumentsLine}.`,
+            "A failed call answers isError with the outcome code and the issues to fix; an issue's path starts at `arguments`, this call's args. Fix them and call again.",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                resource: {
+                    type: "string",
+                    enum: resources,
+                    description: "The resource, a key of the contract's resources.",
+                },
+                variant: {
+                    type: "string",
+                    enum: variants,
+                    description: `The ${family} variant; each resource offers the variants listed in the description.`,
+                },
+                args: {
+                    type: "object",
+                    description: "The operation's arguments as the protocol defines them (where, orderBy, limit, offset, cursor, select, include, data, create, update), in the contract's field names. {} when there are none.",
+                },
+            },
+            required: ["resource", "variant"],
+            additionalProperties: false,
+        },
+        outputSchema: ENVELOPE_SCHEMA,
+        annotations: ANNOTATIONS[family],
+    };
+}
+function transactionTool(offers, maxTransactionOperations) {
+    const families = OPERATION_FAMILIES.filter((family) => offers.has(family));
+    const resources = [
+        ...new Set([...offers.values()].flatMap((offer) => [...offer.keys()])),
+    ];
+    const variants = [
+        ...new Set(families.flatMap((family) => ordered(family, [...(offers.get(family)?.values() ?? [])].flat()))),
+    ];
+    return {
+        name: TRANSACTION_TOOL,
+        title: "Run operations in one transaction",
+        description: [
+            "Runs a list of operations in one database transaction: every step commits, or none does.",
+            READ_THE_CONTRACT,
+            "Each step is { resource, family, variant, args }, with the args of that family's tool.",
+            'A step may use a value an earlier step returned: put { "$ref": { "operation": <the earlier step\'s index>, "path": ["<a field that step selected>"] } } where the value goes. The server adds the fingerprints the protocol requires.',
+            `At most ${maxTransactionOperations} steps.`,
+            "A failed plan answers isError with the failing step's index (cause.operation), its code and its issues; an issue's path starts at operations[<step>].args.",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                steps: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: maxTransactionOperations,
+                    items: {
+                        type: "object",
+                        properties: {
+                            resource: { type: "string", enum: resources },
+                            family: { type: "string", enum: families },
+                            variant: { type: "string", enum: variants },
+                            args: { type: "object" },
+                        },
+                        required: ["resource", "family", "variant"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["steps"],
+            additionalProperties: false,
+        },
+        outputSchema: ENVELOPE_SCHEMA,
+        annotations: ANNOTATIONS.transaction,
+    };
+}
+export function compileToolCatalog(source) {
+    const offers = offersOf(source.surface);
+    const tools = [];
+    for (const family of OPERATION_FAMILIES) {
+        const offer = offers.get(family);
+        if (offer !== undefined) {
+            tools.push(familyTool(family, offer));
+        }
+    }
+    if (offers.size > 0 &&
+        source.surface.some((route) => route.kind === "transactions")) {
+        tools.push(transactionTool(offers, source.maxTransactionOperations));
+    }
+    return Object.freeze(tools);
+}

package/dist/tool-result.encoder.d.ts

@@ -0,0 +1,27 @@
+import type { AvOperationFailureResponse } from "@aventara/core";
+import type { AvProtocolResponse } from "@aventara/core/protocol";
+/** A tool call's result, as `tools/call` answers it. */
+export type McpToolResult = {
+    readonly content: readonly [{
+        readonly type: "text";
+        readonly text: string;
+    }];
+    readonly structuredContent?: Readonly<Record<string, unknown>>;
+    readonly isError: boolean;
+};
+/**
+ * The protocol's answer to a tool call as its MCP result: the envelope's JSON
+ * text as text content, the envelope itself as structured content, and
+ * `isError` exactly when the protocol answered a failure status. Nothing is
+ * read into the envelope or added to it: the code, the data in its wire forms
+ * and the cause are the protocol's.
+ */
+export declare function toolResultOf(response: AvProtocolResponse): McpToolResult;
+/** A tool call refused before it became a protocol request: an MCP tool error with its reason. */
+export declare function refusedCallResult(message: string): McpToolResult;
+/**
+ * The server's own failure inside a tool call as its MCP result: core's generic
+ * `A3000` envelope as a tool error, in the form `toolResultOf` gives the
+ * protocol's own `A3000`. Nothing of the thrown error is in it.
+ */
+export declare function internalFailureResult(envelope: AvOperationFailureResponse): McpToolResult;

package/dist/tool-result.encoder.js

@@ -0,0 +1,29 @@
+export function toolResultOf(response) {
+    const envelope = parsedObject(response.body);
+    return {
+        content: [{ type: "text", text: response.body }],
+        ...(envelope === undefined ? {} : { structuredContent: envelope }),
+        isError: response.status >= 400,
+    };
+}
+export function refusedCallResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function internalFailureResult(envelope) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+function parsedObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@aventara/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.2",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "The MCP server for an Aventara application: its agent layer as Model Context Protocol tools.",
+  "type": "module",
+  "engines": {
+    "node": "^22.18.0 || >=24.2.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE-ADDITIONAL-PERMISSION.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@aventara/core": "1.0.0-rc.2",
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@aventara/testing": "1.0.0-rc.2"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
+    "lint": "biome lint src"
+  }
 }