@frontmcp/adapters 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/adapters",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Adapters for the FrontMCP framework",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -64,15 +64,15 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@frontmcp/auth": "1.3.0",
-    "@frontmcp/di": "1.3.0",
-    "@frontmcp/utils": "1.3.0",
-    "@frontmcp/sdk": "1.3.0",
+    "@frontmcp/auth": "1.4.1",
+    "@frontmcp/di": "1.4.1",
+    "@frontmcp/sdk": "1.4.1",
+    "@frontmcp/utils": "1.4.1",
     "js-yaml": "^4.1.0",
-    "openapi-types": "^12.1.3",
-    "mcp-from-openapi": "2.3.0"
+    "mcp-from-openapi": "2.3.0",
+    "openapi-types": "^12.1.3"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.3.0"
+    "@frontmcp/lazy-zod": "1.4.1"
   }
 }

package/skills/classifier/classification-registry.d.ts

@@ -0,0 +1,59 @@
+import type { ClassifiedOperation } from './openapi-classify';
+import { type BuildNotificationResult } from './resource-change-notification';
+/** Snapshot view returned by `getAll()`. */
+export interface ClassificationRegistrySnapshot {
+    toolName: string;
+    classification: ClassifiedOperation;
+}
+/**
+ * In-memory registry keyed by tool name. The tool name follows the
+ * `${specId}.${operationId}` convention produced by
+ * `OperationToolFactory.operationToolName()` in `plugin-skilled-openapi`.
+ *
+ * Designed as a *storage* primitive — no protocol behaviour, no DI tokens,
+ * no decorators. The deploy pipeline owns population; the runtime
+ * dispatcher owns lookup + notification building.
+ */
+export declare class ClassificationRegistry {
+    private readonly byToolName;
+    /**
+     * Register (or replace) a classification for a tool name. Returns the
+     * previous classification if one existed.
+     *
+     * Useful for hot-reload: the deploy pipeline re-builds classifications
+     * from the new bundle and overwrites in place.
+     */
+    register(toolName: string, classification: ClassifiedOperation): ClassifiedOperation | undefined;
+    /**
+     * Bulk-register an array of classifications keyed by `${specId}.${operationId}`.
+     * Returns the count of newly-added entries (existing entries are overwritten
+     * but not counted toward `added`).
+     */
+    registerAll(classifications: ReadonlyArray<ClassifiedOperation>): {
+        added: number;
+        replaced: number;
+    };
+    /** Look up the classification for a tool. */
+    lookup(toolName: string): ClassifiedOperation | undefined;
+    /** Remove a single classification. Returns true if it was present. */
+    unregister(toolName: string): boolean;
+    /** Drop every registration; used by the loader on full re-deploy. */
+    clear(): void;
+    /** Current size — handy for tests and metrics. */
+    size(): number;
+    /** Snapshot of every (toolName, classification) pair in insertion order. */
+    getAll(): ClassificationRegistrySnapshot[];
+    /**
+     * Convenience: in one step, look up the classification for `toolName`
+     * and build the resource-change notification it should produce after a
+     * successful call with `args`. Returns `{ notification: null }` when the
+     * tool has no classification (e.g. it's not an openapi-derived tool) or
+     * when its classification has no `emit`.
+     *
+     * The dispatcher is expected to call this from a successful-call hook
+     * and forward the resulting notification through whichever notification
+     * channel the host provides.
+     */
+    buildNotificationForCall(toolName: string, args: unknown): BuildNotificationResult;
+}
+//# sourceMappingURL=classification-registry.d.ts.map

package/skills/classifier/classification-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification-registry.d.ts","sourceRoot":"","sources":["../../../src/skills/classifier/classification-registry.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAmC,KAAK,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE/G,4CAA4C;AAC5C,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,mBAAmB,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0C;IAErE;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,mBAAmB,GAAG,mBAAmB,GAAG,SAAS;IAShG;;;;OAIG;IACH,WAAW,CAAC,eAAe,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAarG,6CAA6C;IAC7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIzD,sEAAsE;IACtE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIrC,qEAAqE;IACrE,KAAK,IAAI,IAAI;IAIb,kDAAkD;IAClD,IAAI,IAAI,MAAM;IAId,4EAA4E;IAC5E,MAAM,IAAI,8BAA8B,EAAE;IAQ1C;;;;;;;;;;OAUG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,uBAAuB;CAKnF"}

package/skills/classifier/openapi-classify.d.ts

@@ -0,0 +1,67 @@
+/**
+ * HTTP methods the classifier recognises. Anything else (HEAD, OPTIONS,
+ * TRACE) is passed through with `expose: 'tool'` and no emit.
+ */
+export type ClassifiableHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** A single OpenAPI operation as fed to the classifier. */
+export interface InputOperation {
+    operationId: string;
+    method: string;
+    path: string;
+}
+export type ExposeKind = 'tool' | 'resource' | 'both';
+export interface MutationEmit {
+    /** Which MCP notification fires on a successful call. */
+    kind: 'updated' | 'listChanged';
+    /** Path template the emit URI is rendered from (e.g. `/users/{id}`). */
+    pathTemplate: string;
+    /** Fully-rendered URI template (e.g. `mcp+op://acme/users/{id}`). */
+    resourceUriTemplate: string;
+}
+export interface ClassifiedOperation {
+    operationId: string;
+    method: string;
+    path: string;
+    specId: string;
+    expose: ExposeKind;
+    /** Present only when the path itself is reachable as a resource. */
+    resourceUriTemplate?: string;
+    /** Present only for mutations that should fire a notification. */
+    emit?: MutationEmit;
+}
+/**
+ * Classify every operation in a single spec.
+ *
+ * @param specId - The spec identifier (e.g. `acme-api`). Used to build URIs.
+ * @param ops   - All operations in the spec; the classifier scans the full
+ *                list to decide "matching GET" for each path.
+ */
+export declare function classifyOperations(specId: string, ops: ReadonlyArray<InputOperation>): ClassifiedOperation[];
+/**
+ * Classify a single operation in the context of its spec's GET path set.
+ *
+ * Exposed so callers that already have a pre-built `pathsWithGet` can reuse
+ * it instead of recomputing per call.
+ */
+export declare function classifyOne(specId: string, op: InputOperation, pathsWithGet: ReadonlySet<string>): ClassifiedOperation;
+export interface ClassificationOverrideRule {
+    /**
+     * Pattern: `METHOD path-glob`. The glob uses `*` for single-segment
+     * wildcards and `**` for multi-segment. Example (avoiding literal
+     * star-slash in this docstring): `POST <STAR><STAR>/reset-password`.
+     */
+    match: string;
+    /** Override the MCP surface. */
+    expose?: ExposeKind;
+    /** Override the emit target. `none` clears any default. */
+    emits?: 'self' | 'parent' | 'none';
+}
+/**
+ * Apply manifest overrides on top of a list of already-classified ops.
+ *
+ * Rules are evaluated in declaration order; the first match wins per op.
+ * A rule with both `expose` and `emits` undefined is a no-op (rejected by
+ * the schema upstream but tolerated here for forward-compat).
+ */
+export declare function applyClassificationOverrides(classified: ReadonlyArray<ClassifiedOperation>, rules: ReadonlyArray<ClassificationOverrideRule>): ClassifiedOperation[];
+//# sourceMappingURL=openapi-classify.d.ts.map

package/skills/classifier/openapi-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-classify.d.ts","sourceRoot":"","sources":["../../../src/skills/classifier/openapi-classify.ts"],"names":[],"mappings":"AAiCA;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjF,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,IAAI,EAAE,SAAS,GAAG,aAAa,CAAC;IAChC,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,mBAAmB,EAAE,CAe5G;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,cAAc,EAClB,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,mBAAmB,CAsFrB;AAMD,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAC9C,KAAK,EAAE,aAAa,CAAC,0BAA0B,CAAC,GAC/C,mBAAmB,EAAE,CAWvB"}

package/skills/classifier/render-resource-uri.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Outcome of attempting to render a URI template.
+ *
+ *   { ok: true,  uri }    — every placeholder had a value in `args`
+ *   { ok: false, missing } — at least one placeholder was unresolved; `missing`
+ *                            lists the placeholder names in source order
+ */
+export type RenderResult = {
+    ok: true;
+    uri: string;
+} | {
+    ok: false;
+    missing: string[];
+};
+/**
+ * Render a URI template by substituting `{name}` placeholders from `args`.
+ *
+ * - Coerces values to strings (numbers, booleans accepted; objects rejected
+ *   as missing since there's no sensible string projection).
+ * - URL-encodes each substituted value with `encodeURIComponent`.
+ * - Returns `{ ok: false, missing }` if any placeholder has no resolvable
+ *   value — the caller decides whether to drop the notification or log.
+ *
+ * @param template The URI template, e.g. `mcp+op://acme/users/{id}`.
+ * @param args     The call arguments object the placeholders refer to.
+ */
+export declare function renderResourceUri(template: string, args: unknown): RenderResult;
+//# sourceMappingURL=render-resource-uri.d.ts.map

package/skills/classifier/render-resource-uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-resource-uri.d.ts","sourceRoot":"","sources":["../../../src/skills/classifier/render-resource-uri.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAIxF;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAoC/E"}

package/skills/classifier/resource-change-notification.d.ts

@@ -0,0 +1,41 @@
+import type { ClassifiedOperation } from './openapi-classify';
+/**
+ * MCP `notifications/resources/updated` shape — JSON-RPC notification with
+ * the affected resource URI in params.
+ */
+export interface ResourceUpdatedNotification {
+    method: 'notifications/resources/updated';
+    params: {
+        uri: string;
+    };
+}
+/**
+ * MCP `notifications/resources/list_changed` shape. The spec defines it as
+ * carrying no params; we don't synthesize extras so subscribers see the
+ * canonical event.
+ */
+export interface ResourcesListChangedNotification {
+    method: 'notifications/resources/list_changed';
+    params?: Record<string, never>;
+}
+export type ResourceChangeNotification = ResourceUpdatedNotification | ResourcesListChangedNotification;
+/**
+ * Reason `buildResourceChangeNotification` returned `null`. Surfaced so the
+ * dispatcher can log + observe at the audit layer.
+ */
+export type SuppressedReason = 'no-emit' | 'unresolved-template';
+export interface BuildNotificationResult {
+    notification: ResourceChangeNotification | null;
+    reason?: SuppressedReason;
+    /** Names of placeholders that could not be resolved, if any. */
+    missing?: string[];
+}
+/**
+ * Build the resource-change notification for a successful tool call.
+ *
+ * @param classification The classified operation produced by `classifyOperations`.
+ * @param args           The arguments the tool was invoked with (used to
+ *                       resolve URI template placeholders).
+ */
+export declare function buildResourceChangeNotification(classification: Pick<ClassifiedOperation, 'emit'>, args: unknown): BuildNotificationResult;
+//# sourceMappingURL=resource-change-notification.d.ts.map

package/skills/classifier/resource-change-notification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-change-notification.d.ts","sourceRoot":"","sources":["../../../src/skills/classifier/resource-change-notification.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,iCAAiC,CAAC;IAC1C,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,sCAAsC,CAAC;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAChC;AAED,MAAM,MAAM,0BAA0B,GAAG,2BAA2B,GAAG,gCAAgC,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,qBAAqB,CAAC;AAE1B,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAChD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,cAAc,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,EACjD,IAAI,EAAE,OAAO,GACZ,uBAAuB,CA0BzB"}