@objectstack/connector-mcp 16.1.0 → 17.0.0-rc.1

package/src/mcp-provider.test.ts

@@ -1,193 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-//
-// ADR-0097 — the `mcp` provider factory: materialize a declarative
-// `provider: 'mcp'` connector instance by connecting to the server (an injected
-// fake client here), listing its tools, and mapping them to actions.
-
-import { describe, it, expect } from 'vitest';
-import type { ConnectorProviderContext } from '@objectstack/spec/integration';
-import { isConnectorUpstreamUnavailable } from '@objectstack/spec/integration';
-import type { McpClientLike, McpToolDescriptor, McpTransport } from './mcp-connector.js';
-import { createMcpProviderFactory, MCP_PROVIDER_KEY } from './mcp-provider.js';
-
-const TOOLS: McpToolDescriptor[] = [
-    { name: 'create_issue', description: 'Create an issue', inputSchema: { type: 'object' } },
-    { name: 'list_issues', description: 'List issues' },
-];
-
-/** Capture the transport the factory built, and serve fixed tools. */
-function fakeClientFactory() {
-    const seen: { transport?: McpTransport } = {};
-    let closed = false;
-    const factory = async (transport: McpTransport): Promise<McpClientLike> => {
-        seen.transport = transport;
-        return {
-            listTools: async () => TOOLS,
-            callTool: async () => ({ content: [{ type: 'text', text: 'ok' }] }),
-            close: async () => { closed = true; },
-        };
-    };
-    return { factory, seen, isClosed: () => closed };
-}
-
-function ctx(partial: Partial<ConnectorProviderContext> & Pick<ConnectorProviderContext, 'providerConfig'>): ConnectorProviderContext {
-    return { name: 'github', label: 'GitHub', type: 'api', ...partial };
-}
-
-describe('mcp provider factory (ADR-0097)', () => {
-    it('advertises the mcp provider key', () => {
-        expect(MCP_PROVIDER_KEY).toBe('mcp');
-    });
-
-    it('connects, lists tools, and maps them to actions', async () => {
-        const { factory: clientFactory } = fakeClientFactory();
-        // stdio on a declarative instance requires the host opt-in (#3055).
-        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: ['my-mcp'] });
-        const mat = await factory(ctx({ providerConfig: { transport: { kind: 'stdio', command: 'my-mcp' } } }));
-        expect(mat.def.name).toBe('github');
-        expect(Object.keys(mat.handlers).sort()).toEqual(['create_issue', 'list_issues']);
-        expect(typeof mat.close).toBe('function');
-    });
-
-    it('applies the tool allowlist from providerConfig.include', async () => {
-        const { factory: clientFactory } = fakeClientFactory();
-        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: ['my-mcp'] });
-        const mat = await factory(
-            ctx({ providerConfig: { transport: { kind: 'stdio', command: 'my-mcp' }, include: ['create_issue'] } }),
-        );
-        expect(Object.keys(mat.handlers)).toEqual(['create_issue']);
-    });
-
-    it('folds resolved bearer auth into an http transport header', async () => {
-        const captured = fakeClientFactory();
-        const factory = createMcpProviderFactory({ clientFactory: captured.factory });
-        await factory(
-            ctx({
-                providerConfig: { transport: { kind: 'http', url: 'https://mcp.example.com' } },
-                auth: { type: 'bearer', token: 'tok' },
-            }),
-        );
-        const t = captured.seen.transport;
-        expect(t?.kind).toBe('http');
-        expect(t?.kind === 'http' && t.headers?.Authorization).toBe('Bearer tok');
-    });
-
-    it('throws when the transport is missing', async () => {
-        const factory = createMcpProviderFactory();
-        await expect(factory(ctx({ providerConfig: {} }))).rejects.toThrow(/providerConfig\.transport/);
-    });
-
-    it('throws for an unknown transport kind', async () => {
-        const factory = createMcpProviderFactory();
-        await expect(
-            factory(ctx({ providerConfig: { transport: { kind: 'carrier-pigeon' } } })),
-        ).rejects.toThrow(/kind must be 'stdio' or 'http'/);
-    });
-});
-
-// ── #3017 — fault classification: config stays fatal, upstream degrades ─────
-
-describe('mcp provider fault classification (#3017)', () => {
-    const stdio = { transport: { kind: 'stdio', command: 'my-mcp' } };
-    const allowMyMcp = { declarativeStdio: ['my-mcp'] };
-
-    it('classifies a connect failure as upstream-unavailable (retryable), keeping the cause', async () => {
-        const boom = new Error('connect ECONNREFUSED 127.0.0.1:9999');
-        const clientFactory = async (): Promise<McpClientLike> => { throw boom; };
-        const factory = createMcpProviderFactory({ clientFactory, ...allowMyMcp });
-
-        const err = await factory(ctx({ providerConfig: stdio })).then(
-            () => { throw new Error('expected rejection'); },
-            (e: unknown) => e,
-        );
-        expect(isConnectorUpstreamUnavailable(err)).toBe(true);
-        expect((err as Error).message).toMatch(/'github' could not reach its MCP server/);
-        expect((err as Error).message).toContain('ECONNREFUSED');
-        expect((err as { cause?: unknown }).cause).toBe(boom);
-    });
-
-    it('classifies a tools/list failure as upstream-unavailable and closes the client', async () => {
-        let closed = false;
-        const clientFactory = async (): Promise<McpClientLike> => ({
-            listTools: async () => { throw new Error('request timed out'); },
-            callTool: async () => ({}),
-            close: async () => { closed = true; },
-        });
-        const factory = createMcpProviderFactory({ clientFactory, ...allowMyMcp });
-
-        const err = await factory(ctx({ providerConfig: stdio })).then(
-            () => { throw new Error('expected rejection'); },
-            (e: unknown) => e,
-        );
-        expect(isConnectorUpstreamUnavailable(err)).toBe(true);
-        expect(closed).toBe(true); // discovery failure must not leak the connection
-    });
-
-    it('keeps transport-shape faults plain — configuration errors stay fatal at boot', async () => {
-        const factory = createMcpProviderFactory();
-        const err = await factory(ctx({ providerConfig: {} })).then(
-            () => { throw new Error('expected rejection'); },
-            (e: unknown) => e,
-        );
-        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
-    });
-});
-
-// ── #3055 — declarative stdio policy: default-deny + host allowlist ─────────
-//
-// A declarative stdio transport spawns a local process from metadata (a Studio
-// publish reaches materialization at runtime), so it is gated OFF unless the
-// host opts in. Violations are CONFIGURATION faults: plain throw (fatal at
-// boot, skipped on reload) — never upstream-unavailable, which would retry a
-// security rejection into existence.
-
-describe('mcp provider declarative stdio policy (#3055)', () => {
-    const stdioCfg = { transport: { kind: 'stdio', command: 'my-mcp' } };
-
-    it('DENIES a declarative stdio transport by default, as a plain (non-retryable) fault', async () => {
-        const { factory: clientFactory, seen } = fakeClientFactory();
-        const factory = createMcpProviderFactory({ clientFactory }); // no policy
-        const err = await factory(ctx({ providerConfig: stdioCfg })).then(
-            () => { throw new Error('expected rejection'); },
-            (e: unknown) => e,
-        );
-        expect((err as Error).message).toMatch(/stdio transports are disabled by default/);
-        expect((err as Error).message).toContain("declarativeStdio: ['my-mcp']"); // actionable opt-in hint
-        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
-        expect(seen.transport).toBeUndefined(); // rejected before any connection attempt
-    });
-
-    it('allowlist admits exactly the listed command and rejects others', async () => {
-        const { factory: clientFactory } = fakeClientFactory();
-        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: ['npx', 'my-mcp'] });
-        const mat = await factory(ctx({ providerConfig: stdioCfg }));
-        expect(mat.def.name).toBe('github');
-
-        const err = await factory(
-            ctx({ providerConfig: { transport: { kind: 'stdio', command: 'bash' } } }),
-        ).then(
-            () => { throw new Error('expected rejection'); },
-            (e: unknown) => e,
-        );
-        expect((err as Error).message).toMatch(/not in the host's declarativeStdio allowlist \[npx, my-mcp\]/);
-        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
-    });
-
-    it('declarativeStdio: true allows any command (explicit full trust)', async () => {
-        const { factory: clientFactory } = fakeClientFactory();
-        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: true });
-        const mat = await factory(
-            ctx({ providerConfig: { transport: { kind: 'stdio', command: 'anything' } } }),
-        );
-        expect(Object.keys(mat.handlers).length).toBeGreaterThan(0);
-    });
-
-    it('http transports are NOT subject to the policy', async () => {
-        const { factory: clientFactory } = fakeClientFactory();
-        const factory = createMcpProviderFactory({ clientFactory }); // default-deny policy in force
-        const mat = await factory(
-            ctx({ providerConfig: { transport: { kind: 'http', url: 'https://mcp.example.com' } } }),
-        );
-        expect(mat.def.name).toBe('github');
-    });
-});

package/src/mcp-provider.ts

@@ -1,205 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { ConnectorProviderFactory, ResolvedConnectorAuth } from '@objectstack/spec/integration';
-import { ConnectorUpstreamUnavailableError } from '@objectstack/spec/integration';
-import { createMcpConnector, type McpConnectorOptions, type McpTransport } from './mcp-connector.js';
-
-/**
- * The provider key this package contributes (ADR-0097). A declarative
- * `connectors:` entry with `provider: 'mcp'` is materialized by this factory.
- */
-export 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.
- */
-export type McpDeclarativeStdioPolicy = boolean | string[];
-
-/** Injectable dependencies for {@link createMcpProviderFactory} (tests). */
-export 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;
-}
-
-/** Shape of `providerConfig` for a `provider: 'mcp'` declarative instance. */
-interface McpProviderConfig {
-  /** How to reach the MCP server (stdio or streamable-http). */
-  transport?: unknown;
-  /** Optional tool-name allowlist — only these tools become actions. */
-  include?: unknown;
-}
-
-function isStringRecord(v: unknown): v is Record<string, string> {
-  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
-  return Object.values(v as Record<string, unknown>).every((x) => typeof x === 'string');
-}
-
-/**
- * Fold the resolved instance `auth` into an MCP **http** transport's headers
- * (ADR-0024 keeps MCP credentials with the transport). `credentialRef` has
- * already been resolved upstream, so this only maps the static credential to the
- * right header. Not applied to stdio transports — a stdio server receives its
- * credentials through `transport.env`.
- */
-function applyAuthToHeaders(
-  auth: ResolvedConnectorAuth | undefined,
-  headers: Record<string, string>,
-): void {
-  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':
-      // Header-based only for MCP http (query-param keys are not part of the transport).
-      if (!auth.paramName) headers[auth.headerName ?? 'X-API-Key'] = auth.key;
-      return;
-  }
-}
-
-/** Validate + normalize `providerConfig.transport`, injecting resolved auth for http. */
-function normalizeTransport(
-  raw: unknown,
-  connectorName: string,
-  auth: ResolvedConnectorAuth | undefined,
-): McpTransport {
-  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 as Record<string, unknown>;
-  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)) : undefined,
-      env: isStringRecord(t.env) ? t.env : undefined,
-    };
-  }
-  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: Record<string, string> = { ...(isStringRecord(t.headers) ? t.headers : {}) };
-    applyAuthToHeaders(auth, headers);
-    return { kind: 'http', url: t.url, headers: Object.keys(headers).length > 0 ? headers : undefined };
-  }
-  throw new Error(
-    `connector-mcp provider: connector '${connectorName}' providerConfig.transport.kind must be 'stdio' or 'http'.`,
-  );
-}
-
-/**
- * Enforce the {@link McpDeclarativeStdioPolicy} for one declarative instance
- * (#3055). Throws a **plain** Error on violation: a security-policy rejection
- * is a configuration fault — fatal at boot, skipped+logged on reload — and must
- * never be classified upstream-unavailable (it cannot be retried into
- * existence).
- */
-function assertDeclarativeStdioAllowed(
-  policy: McpDeclarativeStdioPolicy | undefined,
-  command: string,
-  connectorName: string,
-): void {
-  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 — 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}'] }) — or use an http transport (#3055, ADR-0024 §4).`,
-  );
-}
-
-/**
- * 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.
- */
-export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorProviderFactory {
-  return async (ctx) => {
-    const cfg = (ctx.providerConfig ?? {}) as McpProviderConfig;
-    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): x is string => typeof x === 'string')
-      : undefined;
-    const include = includeList ? (toolName: string) => includeList.includes(toolName) : undefined;
-
-    let bundle;
-    try {
-      bundle = await createMcpConnector({
-        name: ctx.name,
-        label: ctx.label,
-        description: ctx.description,
-        transport,
-        include,
-        clientFactory: deps.clientFactory,
-      });
-    } catch (err) {
-      // Everything past transport validation is talking to the server (connect,
-      // handshake, tools/list) — operational, hence retryable. A credential the
-      // server rejects also lands here: indistinguishable from the outside, and
-      // retrying it is loud (logged per attempt), never silent.
-      throw new ConnectorUpstreamUnavailableError(
-        `connector-mcp provider: connector '${ctx.name}' could not reach its MCP server: ${(err as Error).message}`,
-        { cause: err },
-      );
-    }
-    return { def: bundle.def, handlers: bundle.handlers, close: bundle.close };
-  };
-}

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "types": ["node"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["dist", "node_modules", "**/*.test.ts"]
-}