@executor-js/plugin-mcp 0.0.2 → 0.2.1

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
 export { mcpSourcePlugin, createMcpSourcePlugin } from "./source-plugin";
 export type { McpSourcePluginOptions } from "./source-plugin";
 export { McpClient } from "./client";
-export { probeMcpEndpoint, addMcpSource, removeMcpSource, refreshMcpSource, } from "./atoms";
+export { probeMcpEndpoint, addMcpSource, removeMcpSource, refreshMcpSource } from "./atoms";

package/dist/react/plugin-client.d.ts

@@ -0,0 +1,9 @@
+export interface McpClientConfig {
+    /**
+     * Mirrors `dangerouslyAllowStdioMCP` on the server-side plugin. When
+     * false, the AddMcpSource UI hides the stdio tab and stdio presets.
+     * Defaults to false — same default as the server flag.
+     */
+    readonly allowStdio?: boolean;
+}
+export default function createMcpClientPlugin(config?: McpClientConfig): import("@executor-js/sdk/client").ClientPluginSpec<"mcp">;

package/dist/react/source-plugin.d.ts

@@ -1,4 +1,4 @@
-import type { SourcePlugin } from "@executor-js/react/plugins/source-plugin";
+import type { SourcePlugin } from "@executor-js/sdk/client";
 export interface McpSourcePluginOptions {
     /**
      * Enable the stdio transport in the add-source UI (tab + presets).

package/dist/sdk/binding-store.d.ts

@@ -21,12 +21,117 @@ export declare const mcpSchema: {
                 readonly type: "json";
                 readonly required: true;
             };
+            readonly auth_kind: {
+                readonly type: ["none", "header", "oauth2"];
+                readonly required: true;
+                readonly defaultValue: "none";
+            };
+            readonly auth_header_name: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_header_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_header_prefix: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_connection_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_client_id_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_client_secret_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
             readonly created_at: {
                 readonly type: "date";
                 readonly required: true;
             };
         };
     };
+    readonly mcp_source_header: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly kind: {
+                readonly type: ["text", "binding"];
+                readonly required: true;
+            };
+            readonly text_value: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly slot_key: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly prefix: {
+                readonly type: "string";
+                readonly required: false;
+            };
+        };
+    };
+    readonly mcp_source_query_param: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly kind: {
+                readonly type: ["text", "binding"];
+                readonly required: true;
+            };
+            readonly text_value: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly slot_key: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly prefix: {
+                readonly type: "string";
+                readonly required: false;
+            };
+        };
+    };
     readonly mcp_binding: {
         readonly fields: {
             readonly id: {
@@ -65,6 +170,10 @@ export interface McpStoredSource {
     readonly config: McpStoredSourceData;
 }
 export interface McpBindingStore {
+    readonly listBindingsBySource: (namespace: string, scope: string) => Effect.Effect<ReadonlyArray<{
+        readonly toolId: string;
+        readonly binding: McpToolBinding;
+    }>, StorageFailure>;
     readonly getBinding: (toolId: string, scope: string) => Effect.Effect<{
         readonly binding: McpToolBinding;
         readonly namespace: string;
@@ -79,4 +188,4 @@ export interface McpBindingStore {
     readonly putSource: (source: McpStoredSource) => Effect.Effect<void, StorageFailure>;
     readonly removeSource: (namespace: string, scope: string) => Effect.Effect<void, StorageFailure>;
 }
-export declare const makeMcpStore: ({ adapter: db, }: StorageDeps<McpSchema>) => McpBindingStore;
+export declare const makeMcpStore: ({ adapter: db }: StorageDeps<McpSchema>) => McpBindingStore;

package/dist/sdk/index.d.ts

@@ -1,3 +1,3 @@
 export { mcpPlugin, type McpPluginExtension, type McpPluginOptions, type McpSourceConfig, type McpRemoteSourceConfig, type McpStdioSourceConfig, type McpProbeResult, type McpUpdateSourceInput, } from "./plugin";
 export { makeMcpStore, mcpSchema, type McpBindingStore, type McpSchema, type McpStoredSource, } from "./binding-store";
-export { McpConnectionAuth } from "./types";
+export { ConfiguredMcpCredentialValue, MCP_HEADER_AUTH_SLOT, MCP_OAUTH_CLIENT_ID_SLOT, MCP_OAUTH_CLIENT_SECRET_SLOT, MCP_OAUTH_CONNECTION_SLOT, McpConnectionAuth, McpConnectionAuthInput, McpCredentialInput, McpSourceBindingInput, McpSourceBindingRef, mcpHeaderSlot, mcpQueryParamSlot, type McpSourceBindingValue, } from "./types";

package/dist/sdk/invoke.d.ts

@@ -8,6 +8,8 @@ export interface InvokeMcpToolInput {
     readonly toolName: string;
     readonly args: unknown;
     readonly sourceData: McpStoredSourceData;
+    readonly sourceId: string;
+    readonly sourceScope: string;
     /** Innermost executor scope id at invoke time. Mixed into the
      *  connection cache key so per-user OAuth/secret resolution doesn't
      *  collapse multiple users onto one shared connection. */

package/dist/sdk/manifest.d.ts

@@ -1,9 +1,11 @@
+import { McpToolAnnotations } from "./types";
 export interface McpToolManifestEntry {
     readonly toolId: string;
     readonly toolName: string;
     readonly description: string | null;
     readonly inputSchema?: unknown;
     readonly outputSchema?: unknown;
+    readonly annotations?: McpToolAnnotations;
 }
 export interface McpServerMetadata {
     readonly name: string | null;

package/dist/sdk/plugin.d.ts

@@ -1,8 +1,10 @@
-import { Effect } from "effect";
+import { Effect, Layer } from "effect";
+import type { HttpClient } from "effect/unstable/http";
 import { type StorageFailure } from "@executor-js/sdk/core";
 import { type McpBindingStore, type McpStoredSource } from "./binding-store";
 import { McpConnectionError, McpToolDiscoveryError } from "./errors";
-import { type McpConnectionAuth, type SecretBackedValue } from "./types";
+import { type McpShapeProbeResult } from "./probe-shape";
+import { McpSourceBindingInput, McpSourceBindingRef, type McpConnectionAuthInput, type McpCredentialInput, type SecretBackedValue } from "./types";
 import { type ConfigFileSink } from "@executor-js/config";
 /**
  * Executor scope id that owns a newly-added MCP source row. Must be one
@@ -18,10 +20,15 @@ export interface McpRemoteSourceConfig extends McpSourceScopeField {
     readonly name: string;
     readonly endpoint: string;
     readonly remoteTransport?: "streamable-http" | "sse" | "auto";
-    readonly queryParams?: Record<string, SecretBackedValue>;
-    readonly headers?: Record<string, SecretBackedValue>;
+    readonly queryParams?: Record<string, McpCredentialInput>;
+    readonly headers?: Record<string, McpCredentialInput>;
     readonly namespace?: string;
-    readonly auth?: McpConnectionAuth;
+    readonly auth?: McpConnectionAuthInput;
+    /**
+     * Scope that owns any direct credentials supplied on this call. Required
+     * whenever headers/queryParams/auth carry direct secret or connection ids.
+     */
+    readonly credentialTargetScope?: string;
 }
 export interface McpStdioSourceConfig extends McpSourceScopeField {
     readonly transport: "stdio";
@@ -36,6 +43,7 @@ export type McpSourceConfig = McpRemoteSourceConfig | McpStdioSourceConfig;
 export interface McpProbeResult {
     readonly connected: boolean;
     readonly requiresOAuth: boolean;
+    readonly supportsDynamicRegistration: boolean;
     readonly name: string;
     readonly namespace: string;
     readonly toolCount: number | null;
@@ -44,15 +52,25 @@ export interface McpProbeResult {
 export interface McpUpdateSourceInput {
     readonly name?: string;
     readonly endpoint?: string;
-    readonly headers?: Record<string, SecretBackedValue>;
-    readonly queryParams?: Record<string, SecretBackedValue>;
-    readonly auth?: McpConnectionAuth;
+    readonly headers?: Record<string, McpCredentialInput>;
+    readonly queryParams?: Record<string, McpCredentialInput>;
+    readonly credentialTargetScope?: string;
+    readonly auth?: McpConnectionAuthInput;
 }
 export interface McpProbeEndpointInput {
     readonly endpoint: string;
     readonly headers?: Record<string, SecretBackedValue>;
     readonly queryParams?: Record<string, SecretBackedValue>;
 }
+/** Translate a non-MCP probe outcome into a message a user can act on.
+ *  The technical `reason` (`401 without Bearer WWW-Authenticate — not an
+ *  MCP auth challenge`, etc.) stays in telemetry via the probe span; the
+ *  user gets a sentence pointing at their next step. Exported for tests. */
+export declare const userFacingProbeMessage: (shape: Extract<McpShapeProbeResult, {
+    kind: "not-mcp";
+} | {
+    kind: "unreachable";
+}>) => string;
 export interface McpPluginOptions {
     /**
      * Allow configuring stdio-transport MCP sources. Off by default.
@@ -61,11 +79,43 @@ export interface McpPluginOptions {
      * `process.env`. Only enable for trusted single-user contexts.
      */
     readonly dangerouslyAllowStdioMCP?: boolean;
+    readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient>;
     /** If provided, source add/remove is mirrored to executor.jsonc
      *  (best-effort — file errors are logged, not raised). */
     readonly configFile?: ConfigFileSink;
 }
-export declare const mcpPlugin: import("@executor-js/sdk/core").ConfiguredPlugin<"mcp", McpPluginExtension, McpBindingStore, McpPluginOptions, {
+export declare const mcpPlugin: import("@executor-js/sdk/core").ConfiguredPlugin<"mcp", {
+    probeEndpoint: (input: string | McpProbeEndpointInput) => Effect.Effect<{
+        connected: true;
+        requiresOAuth: false;
+        supportsDynamicRegistration: false;
+        name: string;
+        namespace: string;
+        toolCount: number;
+        serverName: string | null;
+    } | {
+        connected: false;
+        requiresOAuth: true;
+        supportsDynamicRegistration: boolean;
+        name: string;
+        namespace: string;
+        toolCount: null;
+        serverName: null;
+    }, StorageFailure | McpConnectionError, never>;
+    addSource: (config: McpSourceConfig) => Effect.Effect<{
+        toolCount: number;
+        namespace: string;
+    }, StorageFailure | McpConnectionError | McpToolDiscoveryError, never>;
+    removeSource: (namespace: string, scope: string) => Effect.Effect<void, StorageFailure, never>;
+    refreshSource: (namespace: string, scope: string) => Effect.Effect<{
+        toolCount: number;
+    }, StorageFailure | McpConnectionError | McpToolDiscoveryError, never>;
+    getSource: (namespace: string, scope: string) => Effect.Effect<McpStoredSource | null, StorageFailure, never>;
+    updateSource: (namespace: string, scope: string, input: McpUpdateSourceInput) => Effect.Effect<void, StorageFailure | McpConnectionError, never>;
+    listSourceBindings: (sourceId: string, sourceScope: string) => Effect.Effect<readonly McpSourceBindingRef[], StorageFailure, never>;
+    setSourceBinding: (input: McpSourceBindingInput) => Effect.Effect<McpSourceBindingRef, StorageFailure, never>;
+    removeSourceBinding: (sourceId: string, sourceScope: string, slot: string, scope: string) => Effect.Effect<void, StorageFailure, never>;
+}, McpBindingStore, McpPluginOptions, {
     readonly mcp_source: {
         readonly fields: {
             readonly id: {
@@ -85,12 +135,117 @@ export declare const mcpPlugin: import("@executor-js/sdk/core").ConfiguredPlugin
                 readonly type: "json";
                 readonly required: true;
             };
+            readonly auth_kind: {
+                readonly type: ["none", "header", "oauth2"];
+                readonly required: true;
+                readonly defaultValue: "none";
+            };
+            readonly auth_header_name: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_header_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_header_prefix: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_connection_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_client_id_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly auth_client_secret_slot: {
+                readonly type: "string";
+                readonly required: false;
+            };
             readonly created_at: {
                 readonly type: "date";
                 readonly required: true;
             };
         };
     };
+    readonly mcp_source_header: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly kind: {
+                readonly type: ["text", "binding"];
+                readonly required: true;
+            };
+            readonly text_value: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly slot_key: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly prefix: {
+                readonly type: "string";
+                readonly required: false;
+            };
+        };
+    };
+    readonly mcp_source_query_param: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly kind: {
+                readonly type: ["text", "binding"];
+                readonly required: true;
+            };
+            readonly text_value: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly slot_key: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly prefix: {
+                readonly type: "string";
+                readonly required: false;
+            };
+        };
+    };
     readonly mcp_binding: {
         readonly fields: {
             readonly id: {
@@ -117,7 +272,7 @@ export declare const mcpPlugin: import("@executor-js/sdk/core").ConfiguredPlugin
             };
         };
     };
-}>;
+}, undefined, Layer.Layer<unknown, never, never>, import("effect/unstable/httpapi/HttpApiGroup").Any>;
 /**
  * Errors any MCP extension method may surface. The first four are
  * plugin-domain tagged errors that flow directly to clients (4xx, each
@@ -141,5 +296,8 @@ export interface McpPluginExtension {
     }, McpExtensionFailure>;
     readonly getSource: (namespace: string, scope: string) => Effect.Effect<McpStoredSource | null, McpExtensionFailure>;
     readonly updateSource: (namespace: string, scope: string, input: McpUpdateSourceInput) => Effect.Effect<void, McpExtensionFailure>;
+    readonly listSourceBindings: (sourceId: string, sourceScope: string) => Effect.Effect<readonly McpSourceBindingRef[], StorageFailure>;
+    readonly setSourceBinding: (input: McpSourceBindingInput) => Effect.Effect<McpSourceBindingRef, StorageFailure>;
+    readonly removeSourceBinding: (sourceId: string, sourceScope: string, slot: string, scope: string) => Effect.Effect<void, StorageFailure>;
 }
 export {};

package/dist/sdk/probe-shape-real-servers.live.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/probe-shape.d.ts

@@ -1,4 +1,18 @@
-import { Effect } from "effect";
+import { Effect, Layer } from "effect";
+import { HttpClient } from "effect/unstable/http";
+/** Why the probe rejected an endpoint as not-MCP.
+ *
+ *  - `auth-required` — server returned 401. We don't know for sure it's
+ *    an MCP server (no spec-compliant Bearer challenge or the body
+ *    isn't JSON-RPC), but the right next step for the user is the same
+ *    either way: provide credentials and retry. This is what
+ *    misclassifies real MCP servers like cubic.dev (no
+ *    resource_metadata) or ref.tools (no WWW-Authenticate at all)
+ *    without the URL-token fallback at the detect layer.
+ *  - `wrong-shape` — endpoint responded but with a body or status that
+ *    doesn't match any MCP shape (200 HTML, 400 GraphQL, 404 from a
+ *    static host, etc.). User action: this URL probably isn't MCP. */
+export type McpProbeRejectCategory = "auth-required" | "wrong-shape";
 export type McpShapeProbeResult = 
 /** Server answered initialize successfully — either a 2xx with a
  *  JSON-RPC payload, or a 401 + WWW-Authenticate: Bearer (RFC 6750
@@ -11,6 +25,7 @@ export type McpShapeProbeResult =
  | {
     readonly kind: "not-mcp";
     readonly reason: string;
+    readonly category: McpProbeRejectCategory;
 }
 /** Transport-level failure (DNS, TLS, timeout, abort, ...). */
  | {
@@ -18,10 +33,9 @@ export type McpShapeProbeResult =
     readonly reason: string;
 };
 export interface ProbeOptions {
-    /** Injected for tests. Defaults to the global `fetch`. */
-    readonly fetch?: typeof fetch;
     /** Abort the request after this many ms. Default 8000. */
     readonly timeoutMs?: number;
+    readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient>;
     readonly headers?: Record<string, string>;
     readonly queryParams?: Record<string, string>;
 }

package/dist/sdk/stored-source.d.ts

@@ -1,17 +1,20 @@
 import { Schema } from "effect";
 declare const McpStoredSourceSchema_base: Schema.Class<McpStoredSourceSchema, Schema.Struct<{
     readonly namespace: Schema.String;
+    readonly scope: Schema.brand<Schema.String, "ScopeId">;
     readonly name: Schema.String;
     readonly config: Schema.Union<readonly [Schema.Struct<{
         readonly transport: Schema.Literal<"remote">;
         readonly endpoint: Schema.String;
         readonly remoteTransport: Schema.withConstructorDefault<Schema.optionalKey<Schema.Literals<readonly ["streamable-http", "sse", "auto"]>>>;
         readonly queryParams: Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Struct<{
-            readonly secretId: Schema.String;
+            readonly kind: Schema.Literal<"binding">;
+            readonly slot: Schema.String;
             readonly prefix: Schema.optional<Schema.String>;
         }>]>>>;
         readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Struct<{
-            readonly secretId: Schema.String;
+            readonly kind: Schema.Literal<"binding">;
+            readonly slot: Schema.String;
             readonly prefix: Schema.optional<Schema.String>;
         }>]>>>;
         readonly auth: Schema.Union<readonly [Schema.Struct<{
@@ -19,13 +22,13 @@ declare const McpStoredSourceSchema_base: Schema.Class<McpStoredSourceSchema, Sc
         }>, Schema.Struct<{
             readonly kind: Schema.Literal<"header">;
             readonly headerName: Schema.String;
-            readonly secretId: Schema.String;
+            readonly secretSlot: Schema.String;
             readonly prefix: Schema.optional<Schema.String>;
         }>, Schema.Struct<{
             readonly kind: Schema.Literal<"oauth2">;
-            readonly connectionId: Schema.String;
-            readonly clientIdSecretId: Schema.optional<Schema.String>;
-            readonly clientSecretSecretId: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly connectionSlot: Schema.String;
+            readonly clientIdSlot: Schema.optional<Schema.String>;
+            readonly clientSecretSlot: Schema.optional<Schema.String>;
         }>]>;
     }>, Schema.Struct<{
         readonly transport: Schema.Literal<"stdio">;