feat: default preset ships the three generic connector executors + live provider:'mcp' showcase demo (#3056)

Closes the last authoring gap in ADR-0097's 'expressible AND executable as
pure metadata' promise, and lands the provider:'mcp' acceptance demo the ADR
originally envisioned (deferred at #3017).

create-objectstack (blank template):
- plugins: gains new ConnectorRestPlugin() / ConnectorOpenApiPlugin() /
  ConnectorMcpPlugin() (zero-arg = provider factory only), so a scaffolded
  app materializes declarative provider-bound connectors with no
  plugin-wiring step. README documents the default providers, credentialRef
  rule, and the #3055 declarativeStdio opt-in. Deps added at ^15.0.0.

examples/app-showcase (live mcp demo):
- scripts/mcp-fixture.mjs — tiny in-repo stdio MCP server (one deterministic
  echo_upper tool): no network, no ports, no boot-ordering coupling, so the
  demo is CI-deterministic.
- DevToolsMcpConnector (provider: 'mcp', stdio transport 'node
  ./scripts/mcp-fixture.mjs') + ShowcaseMcpConnectorEchoFlow dispatching
  echo_upper end-to-end; coverage notes updated.
- objectstack.config.ts wires new ConnectorMcpPlugin({ declarativeStdio:
  ['node'] }) — dogfooding the #3055 default-deny opt-in, with the
  coarse-boundary caveat spelled out.

dogfood:
- showcase-declarative-mcp.dogfood.test.ts boots the REAL showcase (chdir to
  the app root, exactly how os dev runs), injects the three executors, and
  pins: GET /connectors lists showcase_mcp_tools origin=declarative
  state=ready with echo_upper (rest + openapi siblings ready too; catalog
  descriptor absent), and the flow trigger round-trips OBJECTSTACK from the
  fixture's tools/call into the run output.

docs: flows.mdx explains where connector_action connectors come from, the
default preset, and the stdio opt-in.

Verified: dogfood proof 2/2; turbo test dogfood+showcase+create-objectstack
63 tasks green; showcase validate (23 flows / 8 plugins) + typecheck clean;
eslint clean; lockfile updated for the new deps.

Refs #3056 (template + showcase + demo + docs; issue also tracks nothing
further after this — see closing comment)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pbmw3pMqNJfPbkvwh9Fkjs

Author: claude

.changeset/adr-0097-default-preset.md

@@ -0,0 +1,15 @@
+---
+'create-objectstack': minor
+---
+
+feat(create-objectstack): scaffold ships the three generic connector executors (#3056)
+
+The blank template's `plugins:` now includes `new ConnectorRestPlugin()`,
+`new ConnectorOpenApiPlugin()`, and `new ConnectorMcpPlugin()` (zero-arg =
+provider factory only, no hand-wired connector), so a scaffolded app can
+declare provider-bound `connectors:` entries (ADR-0097) — `provider: 'rest' |
+'openapi' | 'mcp'` — as pure metadata and have them materialize into live,
+dispatchable connectors at boot, with no plugin-wiring step. The template
+README documents the default providers, the `credentialRef` rule, and the
+#3055 `declarativeStdio` opt-in (declarative stdio transports stay denied by
+default). Remove unwanted executors by deleting a line from `plugins:`.

content/docs/automation/flows.mdx

@@ -117,6 +117,8 @@ Each node performs a specific action in the flow.
 | `map` | Sequential multi-instance — run a per-item subflow for each element, one at a time (each may pause); batch approval (ADR-0039) |
 | `connector_action` | Execute an external connector action |
 
+`connector_action` dispatches against the runtime **connector registry**, which connector plugins populate. Scaffolded apps ship the three **generic executors** — `rest`, `openapi`, and `mcp` — in their default `plugins:` (remove any you don't want), so a declarative `connectors:` entry that names a `provider` is materialized into a live, dispatchable connector at boot with no plugin code (ADR-0097). Brand connectors (Slack, …) are installed separately. One security note: a declarative `mcp` instance using a **stdio** transport spawns a local process from metadata and is therefore denied by default — the host opts in with `new ConnectorMcpPlugin({ declarativeStdio: ['<trusted-command>'] })`; `http` transports need no opt-in.
+
 ### Node Structure
 
 ```typescript

examples/app-showcase/objectstack.config.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { defineStack } from '@objectstack/spec';
+import { ConnectorMcpPlugin } from '@objectstack/connector-mcp';
 import { ConnectorOpenApiPlugin } from '@objectstack/connector-openapi';
 import { ConnectorRestPlugin } from '@objectstack/connector-rest';
 import { ConnectorSlackPlugin } from '@objectstack/connector-slack';
@@ -112,8 +113,19 @@ export default defineStack({
   //               (ADR-0097), which materializes the StatusOpenApiConnector
   //               declarative instance below — its OpenAPI document is a
   //               package-relative FILE PATH read at boot (#3016).
+  //   • mcp     → contributes the `mcp` provider factory, which materializes
+  //               the DevToolsMcpConnector declarative instance from the
+  //               in-repo stdio fixture (scripts/mcp-fixture.mjs). The
+  //               `declarativeStdio` allowlist is the #3055 security opt-in:
+  //               declarative stdio transports spawn a local process from
+  //               METADATA, so they are denied by default; this host
+  //               deliberately trusts `node` to run the in-repo fixture.
+  //               (A coarse boundary by design — trusting `node` trusts what
+  //               it is asked to run; real deployments should list specific
+  //               server binaries.)
   plugins: [
     new ConnectorOpenApiPlugin(),
+    new ConnectorMcpPlugin({ declarativeStdio: ['node'] }),
     new ConnectorRestPlugin({
       name: 'rest',
       baseUrl: process.env.SHOWCASE_SELF_URL ?? 'http://127.0.0.1:3000',

examples/app-showcase/package.json

@@ -22,7 +22,9 @@
     "test:smoke": "playwright test --config=playwright.config.ts"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@objectstack/cloud-connection": "workspace:*",
+    "@objectstack/connector-mcp": "workspace:*",
     "@objectstack/connector-openapi": "workspace:*",
     "@objectstack/connector-rest": "workspace:*",
     "@objectstack/connector-slack": "workspace:*",

examples/app-showcase/scripts/mcp-fixture.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Tiny in-repo MCP server (stdio) — the deterministic target for the
+// showcase's declarative `provider: 'mcp'` connector instance (#3056,
+// completing the live demo deferred from #3017 / ADR-0097 §6).
+//
+// Why a fixture instead of a real server: the demo must materialize during
+// BOOT in CI (the Dogfood Regression Gate), so the target has to exist with
+// no network, no ports, and no boot-ordering coupling. A stdio child process
+// spawned at materialization is exactly that. The spawn is allowlisted by the
+// host via `new ConnectorMcpPlugin({ declarativeStdio: ['node'] })` in
+// objectstack.config.ts — dogfooding the #3055 opt-in.
+//
+// One deliberately boring, deterministic tool: `echo_upper` upper-cases the
+// input text, so the flow run's captured output proves the whole chain
+// (metadata entry → mcp provider factory → tools/list → connector_action
+// dispatch → tools/call) with zero flakiness.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'showcase-mcp-fixture', version: '1.0.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'echo_upper',
+      description: 'Upper-case the input text (deterministic showcase demo tool).',
+      inputSchema: {
+        type: 'object',
+        properties: { text: { type: 'string', description: 'Text to upper-case' } },
+        required: ['text'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name !== 'echo_upper') {
+    return { content: [{ type: 'text', text: `unknown tool: ${req.params.name}` }], isError: true };
+  }
+  const text = String(req.params.arguments?.text ?? '');
+  const upper = text.toUpperCase();
+  return {
+    content: [{ type: 'text', text: upper }],
+    structuredContent: { upper },
+  };
+});
+
+await server.connect(new StdioServerTransport());

examples/app-showcase/src/automation/flows/index.ts

@@ -445,6 +445,55 @@ export const ShowcaseDeclarativeConnectorPingFlow = defineFlow({
   ],
 });
 
+/**
+ * MCP Connector Echo (ADR-0097 / #3056) — dispatches through the DECLARATIVE
+ * MCP instance `showcase_mcp_tools` (src/system/connectors/index.ts), which the
+ * `mcp` provider materialized at boot from the in-repo stdio fixture server:
+ * its `tools/list` became the action list, and this `connector_action` invokes
+ * the `echo_upper` tool via `tools/call`. The run's captured output
+ * (`structuredContent.upper === 'OBJECTSTACK'`) proves the full chain —
+ * metadata entry → provider factory → MCP handshake → flow dispatch — with no
+ * external dependency. Completes the `provider: 'mcp'` acceptance demo from
+ * ADR-0097 §6, deferred at #3017.
+ */
+export const ShowcaseMcpConnectorEchoFlow = defineFlow({
+  name: 'showcase_mcp_connector_echo',
+  label: 'MCP Connector Echo (ADR-0097)',
+  description:
+    'Dispatches the echo_upper tool of showcase_mcp_tools — a declarative MCP connector instance materialized ' +
+    'at boot from the in-repo stdio fixture (scripts/mcp-fixture.mjs).',
+  type: 'autolaunched',
+  // Surface the tool result on the run output, so the flow run view (and the
+  // dogfood proof) can assert the MCP round-trip observably.
+  variables: [{ name: 'echo.structuredContent', type: 'json', isOutput: true }],
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Task Created',
+      config: {
+        objectName: 'showcase_task',
+        triggerType: 'record-after-create',
+      },
+    },
+    {
+      id: 'echo',
+      type: 'connector_action',
+      label: 'echo_upper via MCP (declarative)',
+      connectorConfig: {
+        connectorId: 'showcase_mcp_tools',
+        actionId: 'echo_upper',
+        input: { text: 'objectstack' },
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'echo' },
+    { id: 'e2', source: 'echo', target: 'end' },
+  ],
+});
+
 /**
  * Task Follow-up Reminder — the worked `wait` (durable timer) example.
  *
@@ -1327,6 +1376,7 @@ export const allFlows = [
   ScheduledDigestFlow,
   TaskCompletedRestPingFlow,
   ShowcaseDeclarativeConnectorPingFlow,
+  ShowcaseMcpConnectorEchoFlow,
   TaskFollowUpFlow,
   NotifyOwnerSubflow,
   TaskDoneNotifyOwnerFlow,

examples/app-showcase/src/coverage.ts

@@ -184,7 +184,7 @@ export const STACK_COLLECTION_COVERAGE: Record<string, KindCoverage> = {
     status: 'demonstrated',
     files: ['src/system/connectors/index.ts', 'src/automation/flows/index.ts'],
     notes:
-      'Both connector kinds are demonstrated. (1) Provider-bound INSTANCES (ADR-0097 / #2977): StatusApiConnector declares `provider: rest` (inline config) and StatusOpenApiConnector declares `provider: openapi` with its OpenAPI document referenced as a package-relative FILE PATH (#3016, read at boot and confined to the package root) — both are materialized into live, dispatchable connectors at boot; ShowcaseDeclarativeConnectorPingFlow calls the rest instance via connector_action and both appear in GET /connectors. (2) Catalog DESCRIPTOR (#2612): ErpCatalogConnector has no provider, so it stays inert metadata; enabled:false marks the deliberate catalog entry and silences the boot audit. Plugin-registered connectors (ConnectorRestPlugin/ConnectorSlackPlugin in objectstack.config.ts) are also exercised by the connector flows.',
+      'Both connector kinds are demonstrated. (1) Provider-bound INSTANCES (ADR-0097 / #2977) cover all three generic executors: StatusApiConnector declares `provider: rest` (inline config), StatusOpenApiConnector declares `provider: openapi` with its OpenAPI document referenced as a package-relative FILE PATH (#3016, read at boot and confined to the package root), and DevToolsMcpConnector declares `provider: mcp` against the in-repo stdio fixture (scripts/mcp-fixture.mjs, #3056) — spawned under the host declarativeStdio allowlist (#3055) and mapped tools/list → actions. All three are materialized into live, dispatchable connectors at boot; ShowcaseDeclarativeConnectorPingFlow calls the rest instance and ShowcaseMcpConnectorEchoFlow calls the mcp instance via connector_action, and all appear in GET /connectors. (2) Catalog DESCRIPTOR (#2612): ErpCatalogConnector has no provider, so it stays inert metadata; enabled:false marks the deliberate catalog entry and silences the boot audit. Plugin-registered connectors (ConnectorRestPlugin/ConnectorSlackPlugin in objectstack.config.ts) are also exercised by the connector flows.',
   },
 };
 

examples/app-showcase/src/system/connectors/index.ts

@@ -91,6 +91,45 @@ export const StatusOpenApiConnector = defineConnector({
   auth: { type: 'none' },
 });
 
+/**
+ * ADR-0097 provider-bound instance, **mcp** form (#3056, completing the live
+ * demo deferred from #3017): the entry points at the tiny in-repo MCP fixture
+ * server (`scripts/mcp-fixture.mjs`) over a **stdio** transport. At boot the
+ * `mcp` provider factory (ConnectorMcpPlugin in objectstack.config.ts) spawns
+ * the fixture, calls `tools/list`, and maps its one deterministic tool
+ * (`echo_upper`) to a connector action — no network, no ports, no boot-ordering
+ * coupling, so the demo is CI-deterministic.
+ *
+ * Two platform behaviors are dogfooded here:
+ * - **#3055 stdio policy**: a declarative stdio transport spawns a local
+ *   process from metadata, so it is denied by default; the host opts in via
+ *   `new ConnectorMcpPlugin({ declarativeStdio: ['node'] })` in
+ *   objectstack.config.ts. Remove that option and boot fails loudly with the
+ *   opt-in instructions — try it.
+ * - **#3049 degrade + retry**: if the fixture were unreachable (e.g. the
+ *   script path wrong), boot would NOT crash — the instance registers
+ *   `state: 'degraded'` on GET /connectors and the platform retries with
+ *   backoff until it heals.
+ */
+export const DevToolsMcpConnector = defineConnector({
+  name: 'showcase_mcp_tools',
+  label: 'Dev Tools (Declarative MCP Instance)',
+  type: 'api',
+  description:
+    'Provider-bound declarative connector instance (ADR-0097) backed by a Model Context Protocol server: the ' +
+    'in-repo stdio fixture (scripts/mcp-fixture.mjs). Its tools/list becomes the action list — echo_upper is ' +
+    'dispatched end-to-end by ShowcaseMcpConnectorEchoFlow.',
+  provider: 'mcp',
+  providerConfig: {
+    // Spawned at materialization; the path is relative to the app's working
+    // directory (`os dev`/`serve` run from the app root). The command must be
+    // allowlisted by the host's declarativeStdio policy (#3055) — see
+    // objectstack.config.ts.
+    transport: { kind: 'stdio', command: 'node', args: ['./scripts/mcp-fixture.mjs'] },
+  },
+  auth: { type: 'none' },
+});
+
 export const ErpCatalogConnector = defineConnector({
   name: 'showcase_erp_catalog',
   label: 'ERP Integration (Catalog Descriptor)',
@@ -143,4 +182,9 @@ export const ErpCatalogConnector = defineConnector({
   enabled: false,
 });
 
-export const allConnectors: Connector[] = [StatusApiConnector, StatusOpenApiConnector, ErpCatalogConnector];
+export const allConnectors: Connector[] = [
+  StatusApiConnector,
+  StatusOpenApiConnector,
+  DevToolsMcpConnector,
+  ErpCatalogConnector,
+];

packages/create-objectstack/src/templates/blank/README.md

@@ -26,6 +26,27 @@ curl -b cookies.txt "http://localhost:3000/api/v1/data/<your_object>"
 - `objectstack.config.ts` — environment manifest (objects, API, plugins)
 - `src/objects/` — object definitions (one file per object)
 
+## Connectors (default providers)
+
+The template ships the three generic connector executors — `rest`, `openapi`,
+and `mcp` — in `plugins:`. With them installed, a declarative `connectors:`
+entry that names a `provider` becomes a live, dispatchable connector at boot
+(pure metadata, no plugin code):
+
+```ts
+connectors: [{
+  name: 'billing',
+  provider: 'openapi',
+  providerConfig: { spec: './specs/billing-openapi.json', baseUrl: 'https://billing.example.com' },
+  auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' },  // env var name — never an inline secret
+}]
+```
+
+Remove executors you don't want from `plugins:`. Note: a declarative `mcp`
+instance over a **stdio** transport spawns a local process from metadata and is
+denied by default — opt in with
+`new ConnectorMcpPlugin({ declarativeStdio: ['<trusted-command>'] })`.
+
 ## Verify your changes
 
 After editing any metadata, run:

packages/create-objectstack/src/templates/blank/objectstack.config.ts

@@ -1,4 +1,7 @@
 import { defineStack } from '@objectstack/spec';
+import { ConnectorMcpPlugin } from '@objectstack/connector-mcp';
+import { ConnectorOpenApiPlugin } from '@objectstack/connector-openapi';
+import { ConnectorRestPlugin } from '@objectstack/connector-rest';
 import * as objects from './src/objects/index.js';
 
 export default defineStack({
@@ -16,4 +19,19 @@ export default defineStack({
     engines: { protocol: '^15' },
   },
   objects: Object.values(objects),
+
+  // The three GENERIC connector executors (rest / openapi / mcp) ship in the
+  // default preset (#3056, ADR-0097): with them installed, a declarative
+  // `connectors:` entry that names a `provider` materializes into a live,
+  // dispatchable connector at boot — integrations stay pure metadata, no
+  // plugin code required. Zero-arg = each contributes only its provider
+  // factory (an unused factory costs nothing at runtime). Remove any you
+  // don't want; brand connectors (Slack, …) are installed separately.
+  //
+  // Security note (#3055): a declarative `mcp` instance with a STDIO
+  // transport spawns a local process from metadata, so it is denied by
+  // default — opt in per host with
+  // `new ConnectorMcpPlugin({ declarativeStdio: ['<trusted-command>'] })`.
+  // http transports need no opt-in.
+  plugins: [new ConnectorRestPlugin(), new ConnectorOpenApiPlugin(), new ConnectorMcpPlugin()],
 });