@electric-ax/agents-mcp 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,515 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { OAuthClientInformationMixed } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+
+//#region src/types.d.ts
+/** Persisted-token shape — surfaces in OAuth callbacks (`onTokensChanged`). */
+/** Persisted-token shape — surfaces in OAuth callbacks (`onTokensChanged`). */
+interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  /** Unix seconds. */
+  expiresAt?: number;
+  tokenType?: string;
+  scope?: string;
+}
+/** DCR-registered (or pre-registered) OAuth client — surfaces in `onClientRegistered`. */
+interface OAuthClientInfo {
+  clientId: string;
+  clientSecret?: string;
+  redirectUris?: string[];
+  /** Unix seconds. */
+  registeredAt?: number;
+}
+type McpAuthMode = `none` | `apiKey` | `clientCredentials` | `authorizationCode`;
+type McpAuthConfig = {
+  mode: `none`;
+} | {
+  mode: `apiKey`;
+  /** Raw secret. Inline at the call site (e.g. `process.env.X_API_KEY`). */
+  key: string;
+  headerName?: string;
+  valuePrefix?: string;
+} | {
+  mode: `clientCredentials`;
+  tokenUrl: string;
+  /** Inline at the call site (e.g. `process.env.X_CLIENT_ID`). */
+  clientId: string;
+  /** Inline at the call site (e.g. `process.env.X_CLIENT_SECRET`). */
+  clientSecret: string;
+  scopes?: string[];
+  audience?: string;
+  resource?: string;
+} | {
+  mode: `authorizationCode`;
+  scopes?: string[];
+  resource?: string;
+  /** Override redirect URI; default `${publicUrl}/oauth/callback/<server>`. */
+  redirectUri?: string;
+  /**
+   * Pre-registered OAuth client. When present, RFC 7591 Dynamic Client
+   * Registration is skipped. Sourced from the operator's secret system.
+   */
+  client?: OAuthClientInfo;
+  /**
+   * Pre-existing tokens to seed the registry's in-process cache on
+   * boot. When present, the OAuth flow is skipped and the SDK uses
+   * these directly. Refresh-token rotation still happens transparently.
+   */
+  tokens?: OAuthTokens;
+  /**
+   * Fires after initial-auth and on every refresh-token rotation.
+   * Wire to a persistence layer (keychain, file, vault, ...) if you
+   * want tokens to survive process restarts. Optional — without it,
+   * tokens live only for the lifetime of the registry.
+   */
+  onTokensChanged?: (tokens: OAuthTokens) => void | Promise<void>;
+  /**
+   * Fires once after Dynamic Client Registration completes. Pair
+   * with `client` on the next boot to skip DCR.
+   */
+  onClientRegistered?: (client: OAuthClientInfo) => void | Promise<void>;
+  /**
+   * Reference into a per-process map of pre-built OAuthClientProvider
+   * instances. Escape hatch for embedders with non-standard requirements
+   * (mTLS, OIDC quirks, etc.).
+   */
+  oauthProviderRef?: string;
+};
+interface McpHttpServerConfig {
+  name: string;
+  transport: `http`;
+  url: string;
+  auth: McpAuthConfig;
+  /** Per-server timeout override in ms. Default 30000. */
+  timeoutMs?: number;
+}
+interface McpStdioServerConfig {
+  name: string;
+  transport: `stdio`;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  auth?: McpAuthConfig;
+  /** Per-server timeout override in ms. Default 30000. */
+  timeoutMs?: number;
+}
+type McpServerConfig = McpHttpServerConfig | McpStdioServerConfig;
+type McpServerStatus = `connecting` | `authenticating` | `ready` | `error` | `disabled`;
+type McpToolErrorKind = `auth_unavailable` | `transport_error` | `timeout` | `server_error` | `tool_not_found`;
+interface McpToolError {
+  kind: McpToolErrorKind;
+  message: string;
+  details?: unknown;
+}
+type AddServerResult = {
+  state: `ready`;
+  id: string;
+  toolCount: number;
+} | {
+  state: `authenticating`;
+  id: string;
+  authUrl: string;
+} | {
+  state: `error`;
+  id: string;
+  error: McpToolError;
+}; //#endregion
+//#region src/tools.d.ts
+declare const MCP_TOOLS_SENTINEL: unique symbol;
+interface McpToolsSentinel {
+  [MCP_TOOLS_SENTINEL]: true;
+  /** `undefined` means every registered server. */
+  allowlist?: string[];
+}
+declare function isMcpToolsSentinel(x: unknown): x is McpToolsSentinel;
+declare const mcp: {
+  /**
+   * Returns a sentinel array for `tools: [...mcp.tools()]`.
+   * Resolution happens at wake time via the runtime's tool-provider
+   * hook. Pass an array to restrict to specific servers; omit for
+   * every registered server.
+   */
+  tools(allowlist?: string[]): McpToolsSentinel[];
+};
+declare function filterByAllowlist(serverNames: string[], allowlist: string[] | undefined): string[];
+
+//#endregion
+//#region src/credentials/auth-store.d.ts
+/**
+ * Internal token + client cache used by the registry. Created per-registry,
+ * never crossed by the public API. Seeded from `auth.tokens` / `auth.client`
+ * on `addServer`; mutated as the SDK refreshes / completes DCR. Calls into
+ * the per-server `onTokensChanged` / `onClientRegistered` callbacks declared
+ * on the auth config so the operator can persist if they want.
+ */
+interface AuthStore {
+  getOAuthTokens(server: string): OAuthTokens | undefined;
+  saveOAuthTokens(server: string, tokens: OAuthTokens): Promise<void>;
+  getOAuthClientInfo(server: string): OAuthClientInfo | undefined;
+  saveOAuthClientInfo(server: string, info: OAuthClientInfo): Promise<void>;
+}
+/** Per-server hooks registered on `addServer` and invoked on cache mutations. */
+interface AuthStoreHooks {
+  onTokensChanged?: (tokens: OAuthTokens) => void | Promise<void>;
+  onClientRegistered?: (client: OAuthClientInfo) => void | Promise<void>;
+}
+interface InternalAuthStore extends AuthStore {
+  /** Pre-seed the cache with tokens read from `auth.tokens`. */
+  seedTokens(server: string, tokens: OAuthTokens): void;
+  /** Pre-seed the cache with a pre-registered OAuth client. */
+  seedClient(server: string, client: OAuthClientInfo): void;
+  /** Register per-server hooks declared on the auth config. */
+  registerHooks(server: string, hooks: AuthStoreHooks): void;
+  /**
+   * Drop only the cached tokens + DCR client info for a server. Hooks
+   * stay registered, so future `saveOAuthTokens` / `saveOAuthClientInfo`
+   * calls still notify the operator's persistence callbacks. Used by
+   * `Registry.reauthorize` to force a fresh OAuth flow without losing
+   * the persistence wiring.
+   */
+  clearCredentials(server: string): void;
+  /** Drop everything we know about a server (used by `removeServer`). */
+  forget(server: string): void;
+}
+
+//#endregion
+//#region src/transports/types.d.ts
+interface McpTransport {
+  client: Client;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+}
+
+//#endregion
+//#region src/auth/sdk-provider.d.ts
+/**
+ * Adapter that implements the MCP SDK's `OAuthClientProvider` and reads/writes
+ * the registry's internal `AuthStore`. The SDK handles PKCE, DCR (RFC 7591),
+ * discovery (RFC 9728), token exchange, refresh, and 401-retry; this adapter
+ * just plumbs reads and writes. Cross-process persistence (if any) happens
+ * via the `onTokensChanged` / `onClientRegistered` hooks the registry wires
+ * into the store from the per-server auth config.
+ */
+interface SdkOAuthProvider extends OAuthClientProvider {
+  /** Always implemented — persists the DCR response via the internal AuthStore. */
+  saveClientInformation(clientInformation: OAuthClientInformationMixed): void | Promise<void>;
+  /** Returns the most recent authorize URL captured by redirectToAuthorization. */
+  peekAuthUrl(): string | undefined;
+  /** Resets the captured authorize URL. */
+  clearAuthUrl(): void;
+}
+
+//#endregion
+//#region src/config/loader.d.ts
+interface McpConfig {
+  servers: McpServerConfig[];
+  raw: unknown;
+}
+declare function parseConfig(raw: unknown, env?: NodeJS.ProcessEnv): McpConfig;
+declare function loadConfig(path: string, env?: NodeJS.ProcessEnv): Promise<McpConfig>;
+
+//#endregion
+//#region src/registry.d.ts
+interface Entry {
+  config: McpServerConfig;
+  configHash: string;
+  status: McpServerStatus;
+  error?: McpToolError;
+  authUrl?: string;
+  transport?: McpTransport;
+  tools: Array<{
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+  }>;
+  capabilities?: unknown;
+  provider?: SdkOAuthProvider;
+}
+interface RegistryOpts {
+  /** Base URL of this registry process, used to construct OAuth redirect URIs. */
+  publicUrl?: string;
+  transportFactoryOverride?: (cfg: McpServerConfig, hp?: HeaderProvider, provider?: SdkOAuthProvider) => McpTransport;
+  /**
+   * Called when an authorizationCode-flow server first needs the user
+   * to consent — receives the SDK-generated authorize URL plus the
+   * server name. The default implementation logs the URL; the desktop
+   * app overrides this to open the URL in a sandboxed BrowserWindow
+   * (and intercept the redirect_uri navigation to call `finishAuth`).
+   *
+   * Headless / non-Electron embedders that want to drive the flow
+   * themselves can read the URL from the `authenticating` envelope of
+   * `addServer` instead — this hook is purely a convenience for
+   * "open this URL right now" callers.
+   */
+  openAuthorizeUrl?: (url: string, server: string) => void;
+  /**
+   * Internal hook used by tests to seed / inspect the registry's private
+   * auth store. Not part of the public contract — production callers should
+   * use the per-server `auth.tokens` / `auth.client` fields and the
+   * `onTokensChanged` / `onClientRegistered` hooks instead.
+   * @internal
+   */
+  authStore?: InternalAuthStore;
+}
+type HeaderProvider = () => Promise<{
+  name: string;
+  value: string;
+} | undefined>;
+interface ListedEntry {
+  name: string;
+  status: McpServerStatus;
+  toolCount: number;
+  /** `http` or `stdio`. Surfaces in UI for badges + per-status affordances. */
+  transport?: string;
+  /** `none` | `apiKey` | `clientCredentials` | `authorizationCode`. */
+  authMode?: string;
+  authUrl?: string;
+  error?: McpToolError;
+  tools: Entry[`tools`];
+  capabilities?: unknown;
+}
+/** State snapshot delivered to subscribers on every registry mutation. */
+interface RegistrySnapshot {
+  /** Monotonic per-registry counter; useful for detecting dropped events. */
+  seq: number;
+  servers: ReadonlyArray<ListedEntry>;
+}
+type RegistrySubscriber = (snapshot: RegistrySnapshot) => void;
+interface Registry {
+  addServer(cfg: McpServerConfig): Promise<AddServerResult>;
+  applyConfig(cfg: McpConfig): Promise<AddServerResult[]>;
+  removeServer(name: string): Promise<void>;
+  list(): ReadonlyArray<ListedEntry>;
+  get(name: string): Entry | undefined;
+  finishAuth(serverName: string, code: string, state?: string): Promise<AddServerResult>;
+  disable(name: string): Promise<void>;
+  enable(name: string): Promise<AddServerResult>;
+  /**
+   * Force a fresh OAuth flow for a server. Closes the current transport,
+   * forgets cached tokens (and DCR client info) for this server, and
+   * rebuilds the transport in place — keeping the entry visible in
+   * snapshots throughout, so renderers don't see a brief
+   * "server gone, server back" blip the way `removeServer` + `addServer`
+   * would. The SDK provider then has nothing to authenticate with on the
+   * next connect, and surfaces a fresh authorize URL via the
+   * `openAuthorizeUrl` hook.
+   *
+   * No-op when the server is unknown, not authorizationCode, or
+   * disabled.
+   */
+  reauthorize(name: string): Promise<void>;
+  /**
+   * Subscribe to registry state changes. The handler is invoked
+   * synchronously with the current snapshot on subscribe (so callers
+   * can render an initial UI without a round-trip), and again on every
+   * mutation: addServer / removeServer / applyConfig / finishAuth /
+   * disable / enable / connection-state transitions.
+   *
+   * Returns an unsubscribe function.
+   */
+  subscribe(handler: RegistrySubscriber): () => void;
+  /**
+   * Close every transport, clear all entries, and emit a final empty
+   * snapshot to subscribers.
+   */
+  close(): Promise<void>;
+}
+declare function createRegistry(opts: RegistryOpts): Registry;
+
+//#endregion
+//#region src/config/watcher.d.ts
+interface WatchOpts {
+  onChange: (cfg: McpConfig) => void;
+  onError?: (err: unknown) => void;
+  debounceMs?: number;
+  env?: NodeJS.ProcessEnv;
+}
+/**
+ * Start watching `path` for changes. Each modification triggers
+ * `loadConfig(path)` (debounced) and forwards the parsed config to
+ * `onChange`, or any error to `onError`. The caller is responsible
+ * for performing the initial load — `watchConfig` only sets up the
+ * subscription so the caller can fully await its first apply before
+ * subsequent change events start firing.
+ */
+declare function watchConfig(path: string, opts: WatchOpts): Promise<() => void>;
+
+//#endregion
+//#region src/bridge/tool-bridge.d.ts
+declare function prefixToolName(server: string, tool: string): string;
+/**
+ * Coerce an MCP tool's inputSchema into a shape downstream LLM adapters can
+ * consume safely. Some servers send `{ type: 'object' }` with no `properties`
+ * for no-arg tools; pi-agent-core walks `inputSchema.properties` and crashes on
+ * undefined. We default `properties` to `{}` and `required` to `[]` for object
+ * schemas; non-object schemas pass through unchanged.
+ */
+
+interface BridgeToolOpts {
+  server: string;
+  tool: {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+  };
+  /**
+   * Subset of the MCP SDK Client used here.
+   *
+   * The real signature of Client.callTool in @modelcontextprotocol/sdk ≥ 1.10 is:
+   *   callTool(params, resultSchema?, options?)
+   * where the SECOND argument is a Zod schema (defaults to CallToolResultSchema) and
+   * the THIRD argument is a RequestOptions bag that may include { signal, onProgress }.
+   *
+   * We model this correctly here so that invoke() never passes signal/onProgress as
+   * the resultSchema (which would cause "v3Schema.safeParse is not a function").
+   */
+  client: {
+    callTool: (args: {
+      name: string;
+      arguments?: unknown;
+    }, resultSchema?: unknown, opts?: {
+      onProgress?: (p: unknown) => void;
+      signal?: AbortSignal;
+    }) => Promise<unknown>;
+  };
+  timeoutMs?: number;
+  /** Optional progress notification callback forwarded to the SDK. */
+  onProgress?: (p: unknown) => void;
+  /** Optional AbortSignal forwarded to the SDK callTool. */
+  signal?: AbortSignal;
+}
+interface BridgedTool {
+  name: string;
+  server: string;
+  description?: string;
+  /** MCP wire shape — JSON schema. */
+  inputSchema: unknown;
+  /** pi-ai/pi-agent expects `parameters` (same JSON schema, different field). */
+  parameters: unknown;
+  /** Display label used by pi-agent UI bridges. */
+  label: string;
+  /** Direct MCP-style call. */
+  call(args: unknown): Promise<unknown>;
+  /** pi-agent execute signature. Wraps `call` and returns AgentToolResult-shaped output. */
+  execute: (toolCallId: string, params: unknown, signal?: AbortSignal) => Promise<{
+    content: Array<{
+      type: string;
+      text?: string;
+    }>;
+    details: unknown;
+  }>;
+}
+declare function bridgeMcpTool(opts: BridgeToolOpts): BridgedTool;
+
+//#endregion
+//#region src/bridge/resource-bridge.d.ts
+interface BuildResourceToolsOpts {
+  server: string;
+  client: {
+    listResources: () => Promise<unknown>;
+    readResource: (args: {
+      uri: string;
+    }) => Promise<unknown>;
+  };
+  timeoutMs?: number;
+}
+declare function buildResourceTools(opts: BuildResourceToolsOpts): BridgedTool[];
+
+//#endregion
+//#region src/bridge/prompt-bridge.d.ts
+interface BuildPromptToolsOpts {
+  server: string;
+  client: {
+    listPrompts: () => Promise<unknown>;
+    getPrompt: (args: {
+      name: string;
+      arguments?: Record<string, unknown>;
+    }) => Promise<unknown>;
+  };
+  timeoutMs?: number;
+}
+declare function buildPromptTools(opts: BuildPromptToolsOpts): BridgedTool[];
+
+//#endregion
+//#region src/persistence/keychain.d.ts
+interface KeychainBackend {
+  get(service: string, account: string): Promise<string | undefined>;
+  set(service: string, account: string, value: string): Promise<void>;
+}
+interface KeychainPersistenceOpts {
+  /** Server name; used as the account-id portion of the keychain entry. */
+  server: string;
+  /** Keychain service identifier. Default `'electric-agents'`. */
+  service?: string;
+  /** Override for tests — inject a backend instead of shelling out. */
+  backend?: KeychainBackend;
+}
+/**
+ * Opt-in helper for OAuth-mode `auth` configs. Loads any persisted tokens
+ * and DCR client info from the OS keychain on startup, and returns the
+ * matching `onTokensChanged` / `onClientRegistered` callbacks so the SDK
+ * writes refreshed material back.
+ *
+ *   const honeycomb = await keychainPersistence({ server: 'honeycomb' })
+ *   await mcpRegistry.addServer({
+ *     name: 'honeycomb',
+ *     transport: 'http',
+ *     url: 'https://mcp.honeycomb.io/mcp',
+ *     auth: {
+ *       mode: 'authorizationCode',
+ *       flow: 'browser',
+ *       scopes: ['mcp:read'],
+ *       ...honeycomb,
+ *     },
+ *   })
+ *
+ * Backend is chosen by `process.platform`:
+ *   - darwin → `/usr/bin/security` (no extra deps)
+ *   - linux  → `secret-tool` from libsecret-tools (apt: libsecret-tools)
+ *   - win32  → not implemented yet — falls back to no-op callbacks
+ *
+ * If the chosen CLI isn't installed (e.g. minimal Linux container without
+ * libsecret), reads/writes throw on first use; the registry surfaces
+ * that as a connect-time error and the OAuth flow continues without
+ * persistence.
+ */
+declare function keychainPersistence(opts: KeychainPersistenceOpts): Promise<{
+  tokens?: OAuthTokens;
+  client?: OAuthClientInfo;
+  onTokensChanged: (t: OAuthTokens) => Promise<void>;
+  onClientRegistered: (c: OAuthClientInfo) => Promise<void>;
+}>;
+
+//#endregion
+//#region src/persistence/file.d.ts
+interface FilePersistenceOpts {
+  /** Path on disk; mode-0600 JSON. Created on first write. */
+  path: string;
+  /** Server name (key inside the file). */
+  server: string;
+}
+/**
+ * Opt-in helper for OAuth-mode `auth` configs. Mirrors `keychainPersistence`
+ * but persists to a JSON file on disk (mode 0600). Right tool when no OS
+ * keychain is available — CI runners, minimal Linux containers, etc.
+ *
+ *   const honeycomb = await filePersistence({
+ *     path: './.electric-agents/credentials.json',
+ *     server: 'honeycomb',
+ *   })
+ *   await mcpRegistry.addServer({ ..., auth: { ..., ...honeycomb } })
+ */
+declare function filePersistence(opts: FilePersistenceOpts): Promise<{
+  tokens?: OAuthTokens;
+  client?: OAuthClientInfo;
+  onTokensChanged: (t: OAuthTokens) => Promise<void>;
+  onClientRegistered: (c: OAuthClientInfo) => Promise<void>;
+}>;
+
+//#endregion
+//#region src/index.d.ts
+declare const VERSION = "0.1.0";
+
+//#endregion
+export { AddServerResult, BridgeToolOpts, BridgedTool, BuildPromptToolsOpts, BuildResourceToolsOpts, FilePersistenceOpts, HeaderProvider, KeychainPersistenceOpts, ListedEntry, MCP_TOOLS_SENTINEL, McpAuthConfig, McpAuthMode, McpConfig, McpHttpServerConfig, McpServerConfig, McpServerStatus, McpStdioServerConfig, McpToolError, McpToolErrorKind, McpToolsSentinel, OAuthClientInfo, OAuthTokens, Registry, RegistryOpts, RegistrySnapshot, RegistrySubscriber, VERSION, WatchOpts, bridgeMcpTool, buildPromptTools, buildResourceTools, createRegistry, filePersistence, filterByAllowlist, isMcpToolsSentinel, keychainPersistence, loadConfig, mcp, parseConfig, prefixToolName, watchConfig };