feat(connector-mcp): adopt MCP servers as connectors (ADR-0024) (#1424)

* feat(connector-mcp): adopt MCP servers as connectors (ADR-0024)

Add @objectstack/connector-mcp — a single generic adapter that turns any
Model Context Protocol server into an ordinary type:'api' connector on the
automation engine, with no per-server code.

- createMcpConnector(): connect over stdio or streamable-HTTP, call
  tools/list, map each tool to a connector action (name→key,
  description→label/description, inputSchema→inputSchema), and dispatch
  connector_action calls to tools/call. Results normalise to the shared
  { ok, content, ... } envelope; logical tool errors surface as ok:false.
- ConnectorMcpPlugin: registers via the existing engine.registerConnector()
  path (no new engine surface, no mcp_call node) and tears the MCP connection
  down on destroy(). Fail-soft when the server or automation engine is absent.
- Credentials stay with the MCP server (transport env/headers), never in
  ConnectorSchema or the discovery-exposed def.
- Mirrors the connector-rest/connector-slack conventions; the real MCP SDK
  client is lazily imported and injectable so unit tests stay hermetic.

https://claude.ai/code/session_01G9v2WA48voVBSkQ7sjFkqC

* chore(connector-mcp): add to Changesets fixed group

Keeps @objectstack/connector-mcp versioned in lockstep with the rest of the
public monorepo, satisfying scripts/check-changeset-fixed.mjs (the Validate
Package Dependencies CI gate).

https://claude.ai/code/session_01G9v2WA48voVBSkQ7sjFkqC

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/config.json

@@ -38,6 +38,7 @@
       "@objectstack/plugin-sharing",
       "@objectstack/plugin-webhooks",
       "@objectstack/plugin-trigger-record-change",
+      "@objectstack/connector-mcp",
       "@objectstack/connector-rest",
       "@objectstack/connector-slack",
       "@objectstack/express",

.changeset/connector-mcp.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/connector-mcp": minor
+---
+
+MCP Connector (ADR-0024) — adopt any Model Context Protocol server as a connector.
+
+Adds `@objectstack/connector-mcp`, a single generic adapter that turns *any*
+MCP server into an ordinary `type: 'api'` connector on the automation engine —
+no per-server code:
+
+- `createMcpConnector({ transport, include?, … })` connects over **stdio** or
+  **streamable-HTTP**, calls `tools/list`, and maps each tool to a connector
+  action (`name → key`, `description → label/description`,
+  `inputSchema → inputSchema`). Handlers dispatch to `tools/call` and normalise
+  the result to the shared `{ ok, content, … }` envelope (logical tool errors
+  surface as `ok: false` rather than throwing).
+- `ConnectorMcpPlugin` registers the connector via the existing
+  `engine.registerConnector()` path (no new engine surface, no `mcp_call` node)
+  and tears the MCP connection down on shutdown. Fail-soft: an unreachable
+  server or missing automation engine is logged and skipped.
+- Credentials live with the MCP server (transport `env`/`headers`), never in
+  `ConnectorSchema` and never in the serialized, discovery-exposed `def`.
+
+Open-tier scope: client adapter + operator-supplied static credentials. A
+curated server registry, managed secrets, per-tenant lifecycle, and sandboxed
+stdio execution remain the enterprise tier.

packages/connectors/connector-mcp/LICENSE

@@ -0,0 +1,93 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             ObjectStack AI LLC
+Licensed Work:        ObjectStack Runtime: the BSL-licensed packages
+                      of the ObjectStack monorepo as listed in LICENSING.md.
+                      Copyright (c) 2026 ObjectStack AI LLC.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      Your use does not include offering the Licensed Work to third
+                      parties on a hosted or embedded basis in order to compete with 
+                      ObjectStack AI LLC's paid version(s) of the Licensed Work. For purposes 
+                      of this license:
+
+                      A "competitive offering" is a Product that is offered to third
+                      parties on a paid basis, including through paid support 
+                      arrangements, that significantly overlaps with the capabilities 
+                      of ObjectStack AI LLC's paid version(s) of the Licensed Work. If Your 
+                      Product is not a competitive offering when You first make it 
+                      generally available, it will not become a competitive offering
+                      later due to ObjectStack AI LLC releasing a new version of the Licensed 
+                      Work with additional capabilities. In addition, Products that 
+                      are not provided on a paid basis are not competitive.
+
+                      "Product" means software that is offered to end users to manage 
+                      in their own environments or offered as a service on a hosted 
+                      basis.
+
+                      "Embedded" means including the source code or executable code 
+                      from the Licensed Work in a competitive offering. "Embedded" 
+                      also means packaging the competitive offering in such a way 
+                      that the Licensed Work must be accessed or downloaded for the 
+                      competitive offering to operate.
+
+                      Hosting or using the Licensed Work(s) for internal purposes 
+                      within an organization is not considered a competitive 
+                      offering. ObjectStack AI LLC considers your organization to include all 
+                      of your affiliates under common control.
+
+                      For binding interpretive guidance on using ObjectStack AI LLC products 
+                      under the Business Source License, please visit our FAQ. 
+                      (see LICENSING.md in this repository)
+Change Date:          Four years from the date the Licensed Work is published.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@objectstack.dev.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

packages/connectors/connector-mcp/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@objectstack/connector-mcp",
+  "version": "7.3.0",
+  "license": "Apache-2.0",
+  "description": "Model Context Protocol (MCP) connector for ObjectStack — a generic adapter that turns any MCP server's tools into a connector's actions on the automation engine's connector registry (ADR-0024).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@objectstack/core": "workspace:*",
+    "@objectstack/spec": "workspace:*"
+  },
+  "devDependencies": {
+    "@objectstack/service-automation": "workspace:*",
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "objectstack",
+    "connector",
+    "mcp",
+    "model-context-protocol",
+    "integration",
+    "ai",
+    "tools"
+  ]
+}

packages/connectors/connector-mcp/src/connector-mcp-plugin.test.ts

@@ -0,0 +1,96 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { LiteKernel } from '@objectstack/core';
+import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/service-automation';
+import { ConnectorMcpPlugin } from './connector-mcp-plugin.js';
+import type { McpClientLike, McpToolDescriptor } from './mcp-connector.js';
+
+const TOOLS: McpToolDescriptor[] = [
+    {
+        name: 'create_issue',
+        description: 'Create a GitHub issue',
+        inputSchema: {
+            type: 'object',
+            properties: { repo: { type: 'string' }, title: { type: 'string' } },
+            required: ['repo', 'title'],
+        },
+    },
+];
+
+/** A fake MCP client recording calls; injected via the plugin's clientFactory. */
+function fakeClient() {
+    const calls: Array<{ name: string; args: Record<string, unknown> }> = [];
+    let closed = false;
+    const client: McpClientLike = {
+        listTools: async () => TOOLS,
+        callTool: async (name, args) => {
+            calls.push({ name, args });
+            return { content: [{ type: 'text', text: 'created #42' }], structuredContent: { number: 42 } };
+        },
+        close: async () => { closed = true; },
+    };
+    return { client, calls, isClosed: () => closed };
+}
+
+describe('ConnectorMcpPlugin — end to end with the automation engine', () => {
+    it('registers the MCP-backed connector so a connector_action flow dispatches to tools/call', async () => {
+        const { client, calls, isClosed } = fakeClient();
+
+        const kernel = new LiteKernel();
+        kernel.use(new AutomationServicePlugin());
+        kernel.use(
+            new ConnectorMcpPlugin({
+                name: 'github_mcp',
+                label: 'GitHub MCP',
+                transport: { kind: 'stdio', command: 'noop' },
+                clientFactory: async () => client,
+            }),
+        );
+        await kernel.bootstrap();
+
+        const engine = kernel.getService<AutomationEngine>('automation');
+
+        // The baseline node and the MCP-backed connector are both present; to the
+        // registry it is an ordinary connector.
+        expect(engine.getRegisteredNodeTypes()).toContain('connector_action');
+        expect(engine.getRegisteredConnectors()).toContain('github_mcp');
+
+        engine.registerFlow('open_issue', {
+            name: 'open_issue',
+            label: 'Open an issue via MCP',
+            type: 'autolaunched',
+            variables: [{ name: 'call.structuredContent', type: 'json', isOutput: true }],
+            nodes: [
+                { id: 'start', type: 'start', label: 'Start' },
+                {
+                    id: 'call',
+                    type: 'connector_action',
+                    label: 'create_issue',
+                    connectorConfig: {
+                        connectorId: 'github_mcp',
+                        actionId: 'create_issue',
+                        input: { repo: 'acme/app', title: 'Bug' },
+                    },
+                },
+                { id: 'end', type: 'end', label: 'End' },
+            ],
+            edges: [
+                { id: 'e1', source: 'start', target: 'call' },
+                { id: 'e2', source: 'call', target: 'end' },
+            ],
+        });
+
+        const result = await engine.execute('open_issue');
+
+        expect(result.success).toBe(true);
+        // The MCP connector handled the dispatch: one tools/call with the input.
+        expect(calls).toEqual([{ name: 'create_issue', args: { repo: 'acme/app', title: 'Bug' } }]);
+        // The normalised structuredContent propagated back into the flow.
+        expect(result.output).toEqual({ 'call.structuredContent': { number: 42 } });
+
+        // Shutdown tears the MCP connection down.
+        await kernel.shutdown();
+        expect(isClosed()).toBe(true);
+    });
+});

packages/connectors/connector-mcp/src/connector-mcp-plugin.ts

@@ -0,0 +1,104 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { Connector } from '@objectstack/spec/integration';
+import { createMcpConnector, type McpConnectorOptions } from './mcp-connector.js';
+
+/**
+ * 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`.
+ */
+export interface ConnectorRegistrySurface {
+    registerConnector(
+        def: Connector,
+        handlers: Record<
+            string,
+            (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>
+        >,
+    ): void;
+    unregisterConnector(name: string): void;
+}
+
+export interface ConnectorMcpPluginOptions extends McpConnectorOptions {}
+
+/**
+ * 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.
+ *
+ * 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`).
+ */
+export class ConnectorMcpPlugin implements Plugin {
+    name = 'com.objectstack.connector.mcp';
+    version = '1.0.0';
+    type = 'standard' as const;
+    // Ensure the automation engine (and its connector registry) is started first.
+    dependencies = ['com.objectstack.service-automation'];
+
+    private readonly options: ConnectorMcpPluginOptions;
+    private connectorName?: string;
+    private automation?: ConnectorRegistrySurface;
+    private close?: () => Promise<void>;
+
+    constructor(options: ConnectorMcpPluginOptions) {
+        this.options = options;
+    }
+
+    async init(_ctx: PluginContext): Promise<void> {
+        // No services to register; the connector is registered in start() once
+        // the automation engine is available and the MCP server has been queried.
+    }
+
+    async start(ctx: PluginContext): Promise<void> {
+        let automation: ConnectorRegistrySurface | undefined;
+        try {
+            automation = ctx.getService<ConnectorRegistrySurface>('automation');
+        } catch {
+            automation = undefined;
+        }
+
+        if (!automation || typeof automation.registerConnector !== 'function') {
+            ctx.logger.info('ConnectorMcpPlugin: no automation engine — MCP connector not registered');
+            return;
+        }
+
+        let bundle;
+        try {
+            bundle = await createMcpConnector(this.options);
+        } catch (err) {
+            // The MCP server is unreachable / failed discovery at boot. Skip the
+            // optional connector rather than failing the whole bootstrap.
+            ctx.logger.warn(
+                `ConnectorMcpPlugin: could not connect to MCP server — connector not registered: ${(err as Error).message}`,
+            );
+            return;
+        }
+
+        automation.registerConnector(bundle.def, bundle.handlers);
+        this.automation = automation;
+        this.connectorName = bundle.def.name;
+        this.close = bundle.close;
+        ctx.logger.info(
+            `ConnectorMcpPlugin: MCP connector '${bundle.def.name}' registered with ${bundle.def.actions?.length ?? 0} action(s)`,
+        );
+    }
+
+    /**
+     * Destroy phase — the kernel's shutdown hook (the `Plugin` lifecycle exposes
+     * `destroy()`, not `stop()`). Unregister the connector and tear the MCP
+     * connection down so no child process / socket is leaked.
+     */
+    async destroy(): Promise<void> {
+        if (this.automation && this.connectorName) {
+            try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }
+        }
+        if (this.close) {
+            try { await this.close(); } catch { /* ignore */ }
+        }
+    }
+}