@miragon/mcp-toolkit-core 0.10.1

package/dist/types/step.d.ts

@@ -0,0 +1,51 @@
+import type { PipelineContext, StepOutput } from "./context.js";
+/**
+ * Soft input declaration — a key the step reads from `context.keys` if present
+ * but does not strictly need to run. Surfaced in `getFrameworkManifest` so an
+ * LLM constructing `render-view` knows the step accepts these scoping keys
+ * even though they don't appear in `requires`.
+ */
+export interface OptionalKeyDeclaration {
+    /** Namespaced key (e.g. `analytics:processDefinitionKey`). */
+    key: string;
+    /** One-line description of what the key controls. */
+    description?: string;
+    /**
+     * Allowed values when the input is constrained to an enum. Useful for the LLM
+     * to construct valid `keys` without guessing (e.g. period: 1d|7d|30d|90d).
+     */
+    enum?: readonly (string | number)[];
+}
+export interface PipelineStepDefinition<TConfig = unknown> {
+    id: string;
+    /**
+     * One-line human description of what the step does. Surfaced in
+     * `getFrameworkManifest` so an LLM picks the right step for a widget without
+     * having to guess from the id.
+     */
+    description?: string;
+    /**
+     * The data type this step produces.
+     * e.g. "lexoffice:invoice", "camunda7:processInstance", "analytics:kpis"
+     * Widgets that accept the same dataType can render this data.
+     */
+    dataType: string;
+    /**
+     * Keys that must already exist in the pipeline context before this step can run.
+     * e.g. ["lexoffice:invoiceNumber"] or ["camunda7:processInstanceId"]
+     */
+    requires: string[];
+    /**
+     * Keys the step reads from `context.keys` if present but tolerates absence
+     * of. The step still runs without them (typically with a default or aggregated
+     * scope). Distinct from `requires`, which gates execution.
+     */
+    optionalKeys?: OptionalKeyDeclaration[];
+    /**
+     * Keys this step produces into the context.
+     * Prefix with the app name to avoid collisions, e.g. ["lexoffice:invoice", "lexoffice:lines"].
+     */
+    produces: string[];
+    execute: (context: PipelineContext, appConfig: TConfig) => Promise<StepOutput>;
+}
+//# sourceMappingURL=step.d.ts.map

package/dist/types/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/types/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAA;IACX,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB,CAAC,OAAO,GAAG,OAAO;IACvD,EAAE,EAAE,MAAM,CAAA;IAEV;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAElB;;;;OAIG;IACH,YAAY,CAAC,EAAE,sBAAsB,EAAE,CAAA;IAEvC;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAElB,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CAC/E"}

package/dist/types/step.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=step.js.map

package/dist/types/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/types/step.ts"],"names":[],"mappings":""}

package/dist/types/view-data.d.ts

@@ -0,0 +1,67 @@
+import type { LayoutConfig } from "../framework/layout-types.js";
+import type { PipelineStepRef } from "./pipeline.js";
+/**
+ * Per-step slice of a view's `structuredContent`. Each entry carries the
+ * step's `data` payload plus the routing fields the browser-side
+ * `adaptDataWidget` reads to pick the right widget component:
+ *   - `_app` — the app the step (or eager builder) belongs to,
+ *   - `_dataType` — the data type the widget is registered against.
+ *
+ * Both routing fields are optional because not every producer sets them
+ * (e.g. a bare key-only view), but the view builders and `render-view`
+ * always populate them for real widget data.
+ */
+export interface StepDataEntry {
+    data: unknown;
+    keys: Record<string, unknown>;
+    _app?: string;
+    _dataType?: string;
+}
+/**
+ * The view input echoed back so the in-iframe refresh button can re-issue the
+ * exact same `render-view` call. Only `render-view` emits this; the eager view
+ * builders omit it (their callers re-run the originating `*_show_*` tool).
+ */
+export interface RefreshParams {
+    keys?: Record<string, unknown>;
+    steps?: PipelineStepRef[];
+    layout: LayoutConfig;
+    title?: string;
+}
+/**
+ * The `structuredContent` envelope a view tool returns. This is the wire
+ * contract between the producers — `render-view` and the eager
+ * `view-builders` (`buildSingleWidgetView` / `buildComposedView`) — and the
+ * `McpAppView` shell / `adaptDataWidget` in `@miragon/mcp-toolkit-ui` that
+ * consumes it. The text channel carries only a short model-facing summary; the
+ * full payload lives here.
+ *
+ * Optional fields reflect which producer emitted the envelope: `render-view`
+ * sets `_refreshParams`, while the eager view builders leave it out.
+ */
+export interface ViewStructuredContent {
+    [key: string]: unknown;
+    _refreshParams?: RefreshParams;
+    title?: string;
+    context: {
+        keys: Record<string, unknown>;
+        stepIds: string[];
+        stepData: Record<string, StepDataEntry>;
+        errors: {
+            stepId: string;
+            reason: string;
+        }[];
+    };
+    layout: LayoutConfig;
+    /**
+     * Whether the in-iframe visual builder is actually usable on this server —
+     * i.e. `app.builder` is enabled and the app-only `get-builder-catalogue`
+     * tool is registered. `render-view` derives it from `createFrameworkApp`'s
+     * `app.builder` and the `McpAppView` shell gates its Build/edit affordance
+     * on it, so the button never appears against a server that can't service it.
+     * Absent on payloads from the eager view builders (which don't run the
+     * builder platform).
+     */
+    builderAvailable?: boolean;
+}
+//# sourceMappingURL=view-data.d.ts.map

package/dist/types/view-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-data.d.ts","sourceRoot":"","sources":["../../src/types/view-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,KAAK,CAAC,EAAE,eAAe,EAAE,CAAA;IACzB,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IAKpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,cAAc,CAAC,EAAE,aAAa,CAAA;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC7B,OAAO,EAAE,MAAM,EAAE,CAAA;QACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;QACvC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAC7C,CAAA;IACD,MAAM,EAAE,YAAY,CAAA;IACpB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B"}

package/dist/types/view-data.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=view-data.js.map

package/dist/types/view-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-data.js","sourceRoot":"","sources":["../../src/types/view-data.ts"],"names":[],"mappings":""}

package/dist/types/widget.d.ts

@@ -0,0 +1,57 @@
+import type { PipelineContext } from "./context.js";
+export interface WidgetProps {
+    keys: Record<string, unknown>;
+    context: PipelineContext;
+    /**
+     * Per-instance props supplied by the layout cell (`row[].props`). Lets the
+     * same widget render multiple times in one view with different scoping
+     * (e.g. `{ processDefinitionKey: "miraveloLeasing" }` for a per-process tab).
+     * Adapters (see `adaptDataWidget` in `packages/ui/src/app/adapt-data-widget.tsx`)
+     * forward these as named props onto the underlying single-data widget.
+     */
+    widgetProps?: Record<string, unknown>;
+}
+export type WidgetSize = "quarter" | "third" | "half" | "full" | "header";
+/**
+ * A widget the app contributes to the framework. The widget's React component
+ * is baked into the host's app-bundle at build time: the framework looks it up
+ * in the `widgets` map passed to `McpAppView` — no resource read at render
+ * time.
+ */
+export interface WidgetDefinition {
+    id: string;
+    /**
+     * One-line human description of what the widget shows. Surfaced verbatim in
+     * `getFrameworkManifest` so an LLM constructing a `render-view` knows what
+     * to put in which slot without inferring intent from the widget id.
+     */
+    description?: string;
+    /**
+     * Keys that must be present in the pipeline context for this widget to render.
+     * e.g. ["lexoffice:invoice"] or ["camunda7:instance", "camunda7:activityTree"]
+     * Widgets read their data from the keys map passed via WidgetProps.
+     */
+    requires: string[];
+    /**
+     * Step `dataType`s the widget can consume. Surfaces the widget→step binding
+     * (which lives implicitly inside `adaptDataWidget(Widget, dataType)` in
+     * `packages/ui/src/app/adapt-data-widget.tsx`) so the manifest tells an LLM
+     * exactly which steps populate this widget. Empty or
+     * omitted for widgets that don't read pipeline data (e.g. interactive
+     * controls that drive their own fetches via `useToolQuery`).
+     */
+    consumes?: string[];
+    size: WidgetSize;
+    /**
+     * Optional JSON Schema describing the per-instance props the widget accepts
+     * via the layout cell's `props` field. Surfaced verbatim in
+     * `getFrameworkManifest` so an LLM constructing a `render-view` call can
+     * discover valid props per widget without guessing — same JSON-Schema
+     * contract the LLM already understands from MCP tool input schemas.
+     *
+     * Generate it from a Zod object with `z.toJSONSchema(schema)` so the
+     * documentation lives next to the widget code.
+     */
+    propsSchema?: Record<string, unknown>;
+}
+//# sourceMappingURL=widget.d.ts.map

package/dist/types/widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../../src/types/widget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,OAAO,EAAE,eAAe,CAAA;IACxB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACtC;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,IAAI,EAAE,UAAU,CAAA;IAChB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACtC"}

package/dist/types/widget.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=widget.js.map

package/dist/types/widget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../../src/types/widget.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@miragon/mcp-toolkit-core",
+  "version": "0.10.1",
+  "description": "Framework runtime for MCP servers: plugin contract, step/widget registries, pipeline executor, render-view helpers.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
+    },
+    "./rest": {
+      "types": "./dist/rest/index.d.ts",
+      "import": "./dist/rest/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "mcp-use": "1.34.5",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@types/node": "26.1.1",
+    "mcp-use": "1.34.5",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "zod": "4.4.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --max-warnings 0",
+    "lint:fix": "eslint src --fix"
+  }
+}