@objectstack/connector-mcp 15.0.0 → 15.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/connector-mcp@15.0.0 build /home/runner/work/framework/framework/packages/connectors/connector-mcp
+> @objectstack/connector-mcp@15.1.0 build /home/runner/work/framework/framework/packages/connectors/connector-mcp
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     7.45 KB
-CJS dist/index.js.map 20.01 KB
-CJS ⚡️ Build success in 96ms
-ESM dist/index.mjs     5.81 KB
-ESM dist/index.mjs.map 18.62 KB
-ESM ⚡️ Build success in 96ms
+ESM dist/index.mjs     10.44 KB
+ESM dist/index.mjs.map 32.67 KB
+ESM ⚡️ Build success in 102ms
+CJS dist/index.js     12.20 KB
+CJS dist/index.js.map 34.21 KB
+CJS ⚡️ Build success in 103ms
 DTS Build start
-DTS ⚡️ Build success in 15675ms
-DTS dist/index.d.mts 6.71 KB
-DTS dist/index.d.ts  6.71 KB
+DTS ⚡️ Build success in 16336ms
+DTS dist/index.d.mts 10.93 KB
+DTS dist/index.d.ts  10.93 KB

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # @objectstack/connector-mcp
 
+## 15.1.0
+
+### Minor Changes
+
+- f531a26: feat(connectors): ADR-0096 — provider-bound declarative connector instances materialized at boot (#2977)
+
+  Declarative `connectors:` stack entries used to be **descriptor-only** (#2612):
+  registered as metadata but never dispatchable, the platform's one dead metadata
+  surface. An entry may now name a **`provider`** — an installed generic executor
+  (`openapi` / `mcp` / `rest`) — and the automation service **materializes** it
+  into a live, dispatchable connector at boot. AI can now wire an integration as
+  pure metadata and a flow `connector_action` calls it end-to-end.
+
+  - **Schema (`@objectstack/spec`).** `ConnectorSchema` gains `provider`,
+    `providerConfig`, and `auth` (a `credentialRef`-based instance-auth shape —
+    `ConnectorInstanceAuthSchema` — that references credentials, never inlines
+    them); `authentication` now defaults to `{ type: 'none' }` so a provider-bound
+    instance need not author it (loosening — existing connectors are unaffected).
+    `DeclarativeConnectorEntrySchema` (used by `stack.zod.ts`) rejects inline
+    secrets, orphan `providerConfig`/`auth`, and authored `actions`/`triggers` on a
+    provider-bound entry. A new `integration/connector-provider.ts` defines the
+    provider-factory contract as pure types.
+
+  - **Engine + boot (`@objectstack/service-automation`).** The engine adds a
+    connector-provider registry (`registerConnectorProvider`/`getConnectorProvider`)
+    and origin-tags registered connectors. At boot the service resolves each
+    provider-bound entry — looking up the factory, resolving `auth.credentialRef`
+    via a pluggable `CredentialResolver` (open-tier default: environment
+    variables), and registering the materialized connector. Boot **fails loudly**
+    for an unknown provider, invalid `providerConfig`, an unresolvable
+    `credentialRef`, or a name conflict with a plugin-registered connector (no
+    silent precedence).
+
+  - **Providers (`connector-rest` / `connector-openapi` / `connector-mcp`).** Each
+    plugin registers a provider factory in `init()` reusing its existing
+    generator/adapter API. Plugin options are now **optional**: with none the
+    plugin contributes only its provider factory; with instance options it also
+    registers a hand-wired connector (back-compat). `connector-openapi` adds a
+    `ConnectorOpenApiPlugin`.
+
+  Open tier: static auth (`none`/`api-key`/`basic`/`bearer`) with `credentialRef`
+  resolved from env vars. Managed vaulting, OAuth2 refresh, and per-tenant
+  connection lifecycle remain the enterprise tier (ADR-0015) — an enterprise host
+  injects a vault-backed `CredentialResolver` with no change to the materialization
+  path.
+
+- f531a26: feat(connectors): degrade + retry declarative instances whose upstream is unreachable (#3017)
+
+  ADR-0097 kept every declarative-connector materialization failure fatal at
+  boot. That is right for configuration faults (unknown provider, invalid
+  `providerConfig`, unresolvable `credentialRef`, name conflict) but wrong for
+  _operational_ ones: a `provider: 'mcp'` instance must contact its MCP server
+  (`tools/list`) to materialize, and a transient network blip aborted the whole
+  app boot.
+
+  - **spec**: a provider factory can now throw
+    `ConnectorUpstreamUnavailableError` (code `CONNECTOR_UPSTREAM_UNAVAILABLE`,
+    structural guard `isConnectorUpstreamUnavailable`) to mark a failure as
+    "upstream temporarily unreachable — degrade and retry" instead of fatal.
+  - **service-automation**: the reconcile degrades such an instance in both boot
+    and reload modes: it registers an action-less husk (`state: 'degraded'` +
+    `degradedReason` on the `GET /connectors` descriptor) so the instance is
+    visible instead of silently missing — or, on a changed-config
+    re-materialization, keeps the old connector serving. A `connector_action`
+    against a degraded instance fails with the reason and a "retries
+    automatically" pointer. Degraded instances retry on an exponential backoff
+    (5s → 5min, reset by config edits) and on every `metadata:reloaded`
+    reconcile; recovery swaps the husk for the live connector atomically.
+    Reconcile runs (boot / reload / retry timer) are now serialized.
+  - **connector-mcp**: the `mcp` provider classifies connect / `tools/list`
+    failures as upstream-unavailable; transport-shape validation stays a plain
+    (fatal) throw.
+
+  Configuration faults remain loud boot failures — the carve-out is only for the
+  unavailable marker.
+
+- f531a26: feat(connector-mcp)!: policy-gate declarative stdio transports — default-deny + host allowlist (#3055)
+
+  A declarative `provider: 'mcp'` entry with a stdio transport spawns a local
+  child process **from metadata** — which a runtime Studio publish can introduce.
+  Declarative stdio is now **denied by default**; hosts opt in deliberately:
+
+  ```ts
+  new ConnectorMcpPlugin({ declarativeStdio: ["my-mcp-server"] }); // command allowlist
+  new ConnectorMcpPlugin({ declarativeStdio: true }); // allow any (full trust)
+  ```
+
+  Behavior change: a declarative stdio instance that materialized before now
+  fails as a **configuration fault** (fatal at boot / skipped on reload) with an
+  actionable opt-in message, and is never classified upstream-unavailable — a
+  security rejection must not be retried into existence. `http` transports and
+  **hand-wired** connectors (plugin instance options / `createMcpConnector`) are
+  unaffected. This is the security precondition for shipping `connector-mcp` in
+  default presets (#3056); see ADR-0097 §"Declarative stdio policy" and
+  ADR-0024 §4.
+
+### Patch Changes
+
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [3fe9df1]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [4109153]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [627f225]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+  - @objectstack/spec@15.1.0
+  - @objectstack/core@15.1.0
+
 ## 15.0.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Connector } from '@objectstack/spec/integration';
+import { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -110,27 +110,104 @@ interface McpConnectorBundle {
  */
 declare function createMcpConnector(opts: McpConnectorOptions): Promise<McpConnectorBundle>;
 
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'mcp'` is materialized by this factory.
+ */
+declare const MCP_PROVIDER_KEY = "mcp";
+/**
+ * Host policy for **declarative** stdio transports (#3055). A stdio transport
+ * launches a local child process, and declarative entries arrive through
+ * metadata — including a runtime Studio publish — so spawning from them is
+ * gated OFF by default:
+ *
+ *  - `undefined` / `false` — deny (default): a `provider: 'mcp'` entry with a
+ *    stdio transport is rejected as a configuration fault.
+ *  - `string[]` — allowlist: the transport's `command` must strictly equal one
+ *    of the listed commands. NOTE this is a coarse trust boundary — listing a
+ *    launcher like `npx` effectively allows any package it can run; list the
+ *    specific server binaries you trust. Sandboxed execution is the enterprise
+ *    tier (ADR-0024 §4).
+ *  - `true` — allow any command (explicit full trust; hosts that treat every
+ *    metadata author as an operator).
+ *
+ * Hand-wired connectors (plugin instance options / `createMcpConnector`) are
+ * NOT subject to this policy: their command was written in host code, a
+ * different trust anchor than metadata.
+ */
+type McpDeclarativeStdioPolicy = boolean | string[];
+/** Injectable dependencies for {@link createMcpProviderFactory} (tests). */
+interface McpProviderDeps {
+    /** Injected MCP client factory; defaults to the SDK-backed client. */
+    clientFactory?: McpConnectorOptions['clientFactory'];
+    /** Policy for declarative stdio transports (#3055). Default: deny. */
+    declarativeStdio?: McpDeclarativeStdioPolicy;
+}
+/**
+ * Build the `mcp` {@link ConnectorProviderFactory} (ADR-0097 / ADR-0024). At boot
+ * the automation service invokes it for each `provider: 'mcp'` declarative
+ * instance: it connects to the MCP server named by `providerConfig.transport`,
+ * lists its tools, and produces the same `{ def, handlers, close }` bundle
+ * {@link createMcpConnector} builds for a hand-wired MCP connector — one action
+ * per tool, dispatched to the server's `tools/call`.
+ *
+ * Stdio transports on declarative instances are policy-gated (default deny) —
+ * see {@link McpDeclarativeStdioPolicy} (#3055).
+ *
+ * The connection is opened at materialization. Faults are classified (#3017):
+ * an invalid transport shape is a *configuration* fault and throws plain —
+ * fatal at boot per the ADR-0097 fail-loud contract — while a connect /
+ * `tools/list` failure (server down, refused, timed out) is an *operational*
+ * fault and throws {@link ConnectorUpstreamUnavailableError}, which the
+ * materializer turns into a degraded instance that is retried with backoff
+ * instead of aborting the whole app boot.
+ */
+declare function createMcpProviderFactory(deps?: McpProviderDeps): ConnectorProviderFactory;
+
 /**
  * Minimal surface of the automation engine this plugin depends on — the
- * connector registry from ADR-0018 §Addendum. Kept structural so the plugin
- * needs no runtime dependency on `@objectstack/service-automation`.
+ * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).
+ * Kept structural so the plugin needs no runtime dependency on
+ * `@objectstack/service-automation`.
  */
 interface ConnectorRegistrySurface {
     registerConnector(def: Connector, handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>): void;
     unregisterConnector(name: string): void;
+    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;
 }
-interface ConnectorMcpPluginOptions extends McpConnectorOptions {
+/**
+ * Options for {@link ConnectorMcpPlugin}. All optional (ADR-0097): with no
+ * `transport` the plugin contributes only the `mcp` provider factory — so a
+ * stack can declare `provider: 'mcp'` instances as pure metadata. Supply a
+ * `transport` to ALSO connect one hand-wired MCP server at `start()`.
+ */
+interface ConnectorMcpPluginOptions extends Partial<McpConnectorOptions> {
+    /**
+     * Policy for stdio transports on **declarative** `provider: 'mcp'`
+     * instances (#3055). Default **deny**: metadata (including a runtime Studio
+     * publish) must not spawn local processes unless the host opts in.
+     * `string[]` allowlists specific commands; `true` allows any. Hand-wired
+     * connectors configured via these plugin options are not subject to it —
+     * their command lives in host code, not metadata.
+     */
+    declarativeStdio?: McpDeclarativeStdioPolicy;
 }
 /**
- * ConnectorMcpPlugin — connects to an MCP server, discovers its tools, and
- * registers them as a single connector on the automation engine (ADR-0024).
- * One generic adapter, configured per server (transport + `include`), never
- * per-server code.
+ * ConnectorMcpPlugin — contributes the generic MCP adapter (ADR-0024) in two forms:
+ *
+ *  1. **Provider factory** (`mcp`, ADR-0097): registered at `init()` so the
+ *     automation service can materialize declarative `provider: 'mcp'`
+ *     `connectors:` entries — connecting to the server and mapping its tools to
+ *     connector actions — at boot.
+ *  2. **Hand-wired instance** (optional, back-compat): when constructed with a
+ *     `transport`, it also connects that one server at `start()` and registers
+ *     the resulting connector.
  *
- * Lifecycle: on `start()` it connects and builds the connector once; on
- * `stop()` it tears the MCP connection down. If no automation engine is present
- * — or the server is unreachable at boot — the plugin logs and skips: a missing
- * optional connector is not a fatal error (same posture as `ConnectorRestPlugin`).
+ * Lifecycle: on `start()` a configured instance connects and builds the
+ * connector once; on `destroy()` it tears the MCP connection down. If no
+ * automation engine is present — or the server is unreachable at boot — the
+ * hand-wired path logs and skips: a missing optional connector is not fatal
+ * (unlike a *declarative* provider-bound instance, which fails boot loudly).
  */
 declare class ConnectorMcpPlugin implements Plugin {
     name: string;
@@ -141,8 +218,8 @@ declare class ConnectorMcpPlugin implements Plugin {
     private connectorName?;
     private automation?;
     private close?;
-    constructor(options: ConnectorMcpPluginOptions);
-    init(_ctx: PluginContext): Promise<void>;
+    constructor(options?: ConnectorMcpPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     /**
      * Destroy phase — the kernel's shutdown hook (the `Plugin` lifecycle exposes
@@ -150,6 +227,7 @@ declare class ConnectorMcpPlugin implements Plugin {
      * connection down so no child process / socket is leaked.
      */
     destroy(): Promise<void>;
+    private tryGetAutomation;
 }
 
-export { ConnectorMcpPlugin, type ConnectorMcpPluginOptions, type ConnectorRegistrySurface, type McpClientLike, type McpConnectorBundle, type McpConnectorOptions, type McpToolDescriptor, type McpTransport, createMcpConnector };
+export { ConnectorMcpPlugin, type ConnectorMcpPluginOptions, type ConnectorRegistrySurface, MCP_PROVIDER_KEY, type McpClientLike, type McpConnectorBundle, type McpConnectorOptions, type McpDeclarativeStdioPolicy, type McpProviderDeps, type McpToolDescriptor, type McpTransport, createMcpConnector, createMcpProviderFactory };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Connector } from '@objectstack/spec/integration';
+import { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -110,27 +110,104 @@ interface McpConnectorBundle {
  */
 declare function createMcpConnector(opts: McpConnectorOptions): Promise<McpConnectorBundle>;
 
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'mcp'` is materialized by this factory.
+ */
+declare const MCP_PROVIDER_KEY = "mcp";
+/**
+ * Host policy for **declarative** stdio transports (#3055). A stdio transport
+ * launches a local child process, and declarative entries arrive through
+ * metadata — including a runtime Studio publish — so spawning from them is
+ * gated OFF by default:
+ *
+ *  - `undefined` / `false` — deny (default): a `provider: 'mcp'` entry with a
+ *    stdio transport is rejected as a configuration fault.
+ *  - `string[]` — allowlist: the transport's `command` must strictly equal one
+ *    of the listed commands. NOTE this is a coarse trust boundary — listing a
+ *    launcher like `npx` effectively allows any package it can run; list the
+ *    specific server binaries you trust. Sandboxed execution is the enterprise
+ *    tier (ADR-0024 §4).
+ *  - `true` — allow any command (explicit full trust; hosts that treat every
+ *    metadata author as an operator).
+ *
+ * Hand-wired connectors (plugin instance options / `createMcpConnector`) are
+ * NOT subject to this policy: their command was written in host code, a
+ * different trust anchor than metadata.
+ */
+type McpDeclarativeStdioPolicy = boolean | string[];
+/** Injectable dependencies for {@link createMcpProviderFactory} (tests). */
+interface McpProviderDeps {
+    /** Injected MCP client factory; defaults to the SDK-backed client. */
+    clientFactory?: McpConnectorOptions['clientFactory'];
+    /** Policy for declarative stdio transports (#3055). Default: deny. */
+    declarativeStdio?: McpDeclarativeStdioPolicy;
+}
+/**
+ * Build the `mcp` {@link ConnectorProviderFactory} (ADR-0097 / ADR-0024). At boot
+ * the automation service invokes it for each `provider: 'mcp'` declarative
+ * instance: it connects to the MCP server named by `providerConfig.transport`,
+ * lists its tools, and produces the same `{ def, handlers, close }` bundle
+ * {@link createMcpConnector} builds for a hand-wired MCP connector — one action
+ * per tool, dispatched to the server's `tools/call`.
+ *
+ * Stdio transports on declarative instances are policy-gated (default deny) —
+ * see {@link McpDeclarativeStdioPolicy} (#3055).
+ *
+ * The connection is opened at materialization. Faults are classified (#3017):
+ * an invalid transport shape is a *configuration* fault and throws plain —
+ * fatal at boot per the ADR-0097 fail-loud contract — while a connect /
+ * `tools/list` failure (server down, refused, timed out) is an *operational*
+ * fault and throws {@link ConnectorUpstreamUnavailableError}, which the
+ * materializer turns into a degraded instance that is retried with backoff
+ * instead of aborting the whole app boot.
+ */
+declare function createMcpProviderFactory(deps?: McpProviderDeps): ConnectorProviderFactory;
+
 /**
  * Minimal surface of the automation engine this plugin depends on — the
- * connector registry from ADR-0018 §Addendum. Kept structural so the plugin
- * needs no runtime dependency on `@objectstack/service-automation`.
+ * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).
+ * Kept structural so the plugin needs no runtime dependency on
+ * `@objectstack/service-automation`.
  */
 interface ConnectorRegistrySurface {
     registerConnector(def: Connector, handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>): void;
     unregisterConnector(name: string): void;
+    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;
 }
-interface ConnectorMcpPluginOptions extends McpConnectorOptions {
+/**
+ * Options for {@link ConnectorMcpPlugin}. All optional (ADR-0097): with no
+ * `transport` the plugin contributes only the `mcp` provider factory — so a
+ * stack can declare `provider: 'mcp'` instances as pure metadata. Supply a
+ * `transport` to ALSO connect one hand-wired MCP server at `start()`.
+ */
+interface ConnectorMcpPluginOptions extends Partial<McpConnectorOptions> {
+    /**
+     * Policy for stdio transports on **declarative** `provider: 'mcp'`
+     * instances (#3055). Default **deny**: metadata (including a runtime Studio
+     * publish) must not spawn local processes unless the host opts in.
+     * `string[]` allowlists specific commands; `true` allows any. Hand-wired
+     * connectors configured via these plugin options are not subject to it —
+     * their command lives in host code, not metadata.
+     */
+    declarativeStdio?: McpDeclarativeStdioPolicy;
 }
 /**
- * ConnectorMcpPlugin — connects to an MCP server, discovers its tools, and
- * registers them as a single connector on the automation engine (ADR-0024).
- * One generic adapter, configured per server (transport + `include`), never
- * per-server code.
+ * ConnectorMcpPlugin — contributes the generic MCP adapter (ADR-0024) in two forms:
+ *
+ *  1. **Provider factory** (`mcp`, ADR-0097): registered at `init()` so the
+ *     automation service can materialize declarative `provider: 'mcp'`
+ *     `connectors:` entries — connecting to the server and mapping its tools to
+ *     connector actions — at boot.
+ *  2. **Hand-wired instance** (optional, back-compat): when constructed with a
+ *     `transport`, it also connects that one server at `start()` and registers
+ *     the resulting connector.
  *
- * Lifecycle: on `start()` it connects and builds the connector once; on
- * `stop()` it tears the MCP connection down. If no automation engine is present
- * — or the server is unreachable at boot — the plugin logs and skips: a missing
- * optional connector is not a fatal error (same posture as `ConnectorRestPlugin`).
+ * Lifecycle: on `start()` a configured instance connects and builds the
+ * connector once; on `destroy()` it tears the MCP connection down. If no
+ * automation engine is present — or the server is unreachable at boot — the
+ * hand-wired path logs and skips: a missing optional connector is not fatal
+ * (unlike a *declarative* provider-bound instance, which fails boot loudly).
  */
 declare class ConnectorMcpPlugin implements Plugin {
     name: string;
@@ -141,8 +218,8 @@ declare class ConnectorMcpPlugin implements Plugin {
     private connectorName?;
     private automation?;
     private close?;
-    constructor(options: ConnectorMcpPluginOptions);
-    init(_ctx: PluginContext): Promise<void>;
+    constructor(options?: ConnectorMcpPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     /**
      * Destroy phase — the kernel's shutdown hook (the `Plugin` lifecycle exposes
@@ -150,6 +227,7 @@ declare class ConnectorMcpPlugin implements Plugin {
      * connection down so no child process / socket is leaked.
      */
     destroy(): Promise<void>;
+    private tryGetAutomation;
 }
 
-export { ConnectorMcpPlugin, type ConnectorMcpPluginOptions, type ConnectorRegistrySurface, type McpClientLike, type McpConnectorBundle, type McpConnectorOptions, type McpToolDescriptor, type McpTransport, createMcpConnector };
+export { ConnectorMcpPlugin, type ConnectorMcpPluginOptions, type ConnectorRegistrySurface, MCP_PROVIDER_KEY, type McpClientLike, type McpConnectorBundle, type McpConnectorOptions, type McpDeclarativeStdioPolicy, type McpProviderDeps, type McpToolDescriptor, type McpTransport, createMcpConnector, createMcpProviderFactory };

package/dist/index.js

@@ -31,7 +31,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ConnectorMcpPlugin: () => ConnectorMcpPlugin,
-  createMcpConnector: () => createMcpConnector
+  MCP_PROVIDER_KEY: () => MCP_PROVIDER_KEY,
+  createMcpConnector: () => createMcpConnector,
+  createMcpProviderFactory: () => createMcpProviderFactory
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -145,25 +147,128 @@ async function createMcpConnector(opts) {
   };
 }
 
+// src/mcp-provider.ts
+var import_integration = require("@objectstack/spec/integration");
+var MCP_PROVIDER_KEY = "mcp";
+function isStringRecord(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  return Object.values(v).every((x) => typeof x === "string");
+}
+function applyAuthToHeaders(auth, headers) {
+  if (!auth || auth.type === "none") return;
+  switch (auth.type) {
+    case "bearer":
+      headers["Authorization"] = `Bearer ${auth.token}`;
+      return;
+    case "basic":
+      headers["Authorization"] = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString("base64")}`;
+      return;
+    case "api-key":
+      if (!auth.paramName) headers[auth.headerName ?? "X-API-Key"] = auth.key;
+      return;
+  }
+}
+function normalizeTransport(raw, connectorName, auth) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error(
+      `connector-mcp provider: connector '${connectorName}' requires providerConfig.transport ({ kind: 'stdio', command, ... } or { kind: 'http', url, ... }).`
+    );
+  }
+  const t = raw;
+  if (t.kind === "stdio") {
+    if (typeof t.command !== "string" || t.command.length === 0) {
+      throw new Error(
+        `connector-mcp provider: connector '${connectorName}' stdio transport requires a 'command' string.`
+      );
+    }
+    return {
+      kind: "stdio",
+      command: t.command,
+      args: Array.isArray(t.args) ? t.args.map((a) => String(a)) : void 0,
+      env: isStringRecord(t.env) ? t.env : void 0
+    };
+  }
+  if (t.kind === "http") {
+    if (typeof t.url !== "string" || t.url.length === 0) {
+      throw new Error(
+        `connector-mcp provider: connector '${connectorName}' http transport requires a 'url' string.`
+      );
+    }
+    const headers = { ...isStringRecord(t.headers) ? t.headers : {} };
+    applyAuthToHeaders(auth, headers);
+    return { kind: "http", url: t.url, headers: Object.keys(headers).length > 0 ? headers : void 0 };
+  }
+  throw new Error(
+    `connector-mcp provider: connector '${connectorName}' providerConfig.transport.kind must be 'stdio' or 'http'.`
+  );
+}
+function assertDeclarativeStdioAllowed(policy, command, connectorName) {
+  if (policy === true) return;
+  if (Array.isArray(policy)) {
+    if (policy.includes(command)) return;
+    throw new Error(
+      `connector-mcp provider: connector '${connectorName}' declares a stdio transport with command '${command}', which is not in the host's declarativeStdio allowlist [${policy.join(", ")}]. Add the command to new ConnectorMcpPlugin({ declarativeStdio: [...] }) if this server is trusted (#3055).`
+    );
+  }
+  throw new Error(
+    `connector-mcp provider: connector '${connectorName}' declares a stdio transport (command '${command}'), but declarative stdio transports are disabled by default \u2014 a stdio transport launches a local process from stack metadata (including runtime Studio publishes). If this server is trusted, opt in deliberately: new ConnectorMcpPlugin({ declarativeStdio: ['${command}'] }) \u2014 or use an http transport (#3055, ADR-0024 \xA74).`
+  );
+}
+function createMcpProviderFactory(deps = {}) {
+  return async (ctx) => {
+    const cfg = ctx.providerConfig ?? {};
+    const transport = normalizeTransport(cfg.transport, ctx.name, ctx.auth);
+    if (transport.kind === "stdio") {
+      assertDeclarativeStdioAllowed(deps.declarativeStdio, transport.command, ctx.name);
+    }
+    const includeList = Array.isArray(cfg.include) ? cfg.include.filter((x) => typeof x === "string") : void 0;
+    const include = includeList ? (toolName) => includeList.includes(toolName) : void 0;
+    let bundle;
+    try {
+      bundle = await createMcpConnector({
+        name: ctx.name,
+        label: ctx.label,
+        description: ctx.description,
+        transport,
+        include,
+        clientFactory: deps.clientFactory
+      });
+    } catch (err) {
+      throw new import_integration.ConnectorUpstreamUnavailableError(
+        `connector-mcp provider: connector '${ctx.name}' could not reach its MCP server: ${err.message}`,
+        { cause: err }
+      );
+    }
+    return { def: bundle.def, handlers: bundle.handlers, close: bundle.close };
+  };
+}
+
 // src/connector-mcp-plugin.ts
 var ConnectorMcpPlugin = class {
-  constructor(options) {
+  constructor(options = {}) {
     this.name = "com.objectstack.connector.mcp";
     this.version = "1.0.0";
     this.type = "standard";
-    // Ensure the automation engine (and its connector registry) is started first.
+    // Ensure the automation engine (and its connector/provider registries) exist first.
     this.dependencies = ["com.objectstack.service-automation"];
     this.options = options;
   }
-  async init(_ctx) {
+  async init(ctx) {
+    const automation = this.tryGetAutomation(ctx);
+    if (automation && typeof automation.registerConnectorProvider === "function") {
+      automation.registerConnectorProvider(
+        MCP_PROVIDER_KEY,
+        createMcpProviderFactory({
+          clientFactory: this.options.clientFactory,
+          declarativeStdio: this.options.declarativeStdio
+        })
+      );
+      ctx.logger.info("ConnectorMcpPlugin: registered 'mcp' connector provider");
+    }
   }
   async start(ctx) {
-    let automation;
-    try {
-      automation = ctx.getService("automation");
-    } catch {
-      automation = void 0;
-    }
+    if (!this.options.transport) return;
+    const automation = this.tryGetAutomation(ctx);
     if (!automation || typeof automation.registerConnector !== "function") {
       ctx.logger.info("ConnectorMcpPlugin: no automation engine \u2014 MCP connector not registered");
       return;
@@ -204,10 +309,19 @@ var ConnectorMcpPlugin = class {
       }
     }
   }
+  tryGetAutomation(ctx) {
+    try {
+      return ctx.getService("automation");
+    } catch {
+      return void 0;
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConnectorMcpPlugin,
-  createMcpConnector
+  MCP_PROVIDER_KEY,
+  createMcpConnector,
+  createMcpProviderFactory
 });
 //# sourceMappingURL=index.js.map