@datacules/agent-identity-mcp-client 0.2.1

package/README.md

@@ -0,0 +1,109 @@
+# @datacules/agent-identity-mcp-client
+
+Outbound MCP integration for [`@datacules/agent-identity`](../../core). Consumes external MCP servers as `CredentialStore` implementations, allowing the credential router to pull credentials **from** any MCP-speaking secrets server — such as another `@datacules/agent-identity-mcp` instance, a Vault MCP server, a 1Password MCP server, or a custom server.
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `McpCredentialStore` | `CredentialStore` impl — fetches via MCP `list_credentials` tool |
+| `McpToolCaller` | Direct tool caller — `resolveCredential`, `health`, arbitrary tools |
+
+Both classes support `http` (SSE to a running server) and `stdio` (spawns a process) transports.
+
+## Usage — McpCredentialStore
+
+Drop it into any `CredentialRouter` with no other changes:
+
+```typescript
+import { McpCredentialStore } from '@datacules/agent-identity-mcp-client';
+import { createRouterFromStore } from '@datacules/agent-identity';
+
+// HTTP transport (connect to a running agent-identity-mcp server)
+const store = new McpCredentialStore({
+  transport: 'http',
+  serverUrl: 'http://vault-mcp.internal:3002',
+  authToken: process.env.MCP_AUTH_TOKEN,   // optional
+  cacheTtlMs: 30_000,                       // optional, default 60s
+});
+
+const router = createRouterFromStore(store, rules, logger);
+
+// Credential resolution is now backed by the remote MCP server
+const resolved = router.resolve(ctx);
+
+// Disconnect on shutdown
+process.on('SIGTERM', () => store.disconnect());
+```
+
+```typescript
+// stdio transport (spawn a local server process)
+const store = new McpCredentialStore({
+  transport: 'stdio',
+  command: 'npx',
+  args: ['@datacules/agent-identity-mcp'],
+  env: {
+    AGENT_IDENTITY_CREDENTIALS: process.env.AGENT_IDENTITY_CREDENTIALS!,
+    AGENT_IDENTITY_RULES: process.env.AGENT_IDENTITY_RULES!,
+  },
+});
+```
+
+## Usage — McpToolCaller
+
+For when you want to call the MCP server directly, without a local router:
+
+```typescript
+import { McpToolCaller } from '@datacules/agent-identity-mcp-client';
+
+const caller = new McpToolCaller({
+  transport: 'http',
+  serverUrl: 'http://localhost:3002',
+});
+
+// Typed helpers
+const result = await caller.resolveCredential({
+  userId: 'user-1', resourceId: 'kb-1', resourceKind: 'personal',
+  provider: 'anthropic', model: 'claude-sonnet-4-20250514',
+  action: 'read', traceId: 'trace-001',
+});
+console.log(result.credentialId, result.resolvedFor);
+
+const health = await caller.health();
+console.log(health.credentialsLoaded, health.rulesLoaded);
+
+// Arbitrary tool call
+const rules = await caller.callTool('list_rules', {});
+
+await caller.disconnect();
+```
+
+## Full MCP integration picture
+
+```
+┌──────────────────────────────────────────┐
+│        MCP Client                       │
+│  (Claude Desktop / Claude Code /       │
+│   Cursor / custom agent)               │
+└──────────────────────────────────────────┘
+         │ MCP tools (resolve_credential etc.)
+         ▼  INBOUND
+┌──────────────────────────────────────────┐
+│  @datacules/agent-identity-mcp         │
+│  (MCP Server — stdio or HTTP+SSE)      │
+└──────────────────────────────────────────┘
+         │ CredentialStore interface
+         ▼
+┌──────────────────────────────────────────┐
+│  @datacules/agent-identity-mcp-client  │
+│  McpCredentialStore                    │  OUTBOUND
+│  (fetches from external MCP servers)   │
+└──────────────────────────────────────────┘
+         │ MCP tools (list_credentials)
+         ▼
+┌──────────────────────────────────────────┐
+│  External MCP Credential Server        │
+│  (Vault MCP / 1Password MCP /          │
+│   custom secrets server)               │
+└──────────────────────────────────────────┘
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@datacules/agent-identity-mcp-client",
+  "version": "0.2.1",
+  "private": false,
+  "description": "MCP client adapter for @datacules/agent-identity — consume external MCP servers as CredentialStores",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@datacules/agent-identity": "^0.1.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0"
+  },
+  "devDependencies": {
+    "@datacules/agent-identity": "*",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent-identity",
+    "credential",
+    "datacules"
+  ]
+}

package/src/caller.ts

@@ -0,0 +1,150 @@
+/**
+ * McpToolCaller — utility for calling arbitrary tools on a connected
+ * agent-identity MCP server from application code.
+ *
+ * While McpCredentialStore handles the CredentialStore contract,
+ * McpToolCaller lets you call any tool (resolve_credential,
+ * resolve_migration_credential, health, etc.) directly — useful
+ * when you want the MCP server to perform the resolution and return
+ * the result without going through a local CredentialRouter.
+ *
+ * Example:
+ *   const caller = new McpToolCaller({ transport: 'http', serverUrl: 'http://localhost:3002' });
+ *   const result = await caller.resolveCredential({ userId: 'u1', ... });
+ *   await caller.disconnect();
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { McpCredentialStoreOptions } from './store.js';
+
+export type McpToolCallerOptions = McpCredentialStoreOptions;
+
+export interface ResolvedCredentialResult {
+  ok: boolean;
+  credentialId: string;
+  kind: 'fixed' | 'user-delegated';
+  resolvedFor: string;
+}
+
+export interface ResolvedMigrationResult {
+  ok: boolean;
+  migrationId: string;
+  source: ResolvedCredentialResult;
+  target: ResolvedCredentialResult;
+  expiresAt: string | null;
+}
+
+export interface HealthResult {
+  status: 'ok' | 'error';
+  credentialsLoaded: number;
+  rulesLoaded: number;
+  timestamp: string;
+}
+
+/**
+ * Thin wrapper around the MCP SDK Client for calling agent-identity
+ * MCP tools directly. Connection is lazy and cached after first call.
+ */
+export class McpToolCaller {
+  private client: Client | null = null;
+  private connectPromise: Promise<void> | null = null;
+  private readonly options: McpToolCallerOptions;
+
+  constructor(options: McpToolCallerOptions) {
+    this.options = options;
+  }
+
+  // ── High-level helpers ─────────────────────────────────────────────────────
+
+  /** Resolve a credential via the remote MCP server */
+  async resolveCredential(
+    ctx: Record<string, unknown>
+  ): Promise<ResolvedCredentialResult> {
+    return this.callTool<ResolvedCredentialResult>('resolve_credential', ctx);
+  }
+
+  /** Resolve a migration credential pair via the remote MCP server */
+  async resolveMigrationCredential(
+    ctx: Record<string, unknown>
+  ): Promise<ResolvedMigrationResult> {
+    return this.callTool<ResolvedMigrationResult>('resolve_migration_credential', ctx);
+  }
+
+  /** Check the health of the remote agent-identity MCP server */
+  async health(): Promise<HealthResult> {
+    return this.callTool<HealthResult>('health', {});
+  }
+
+  // ── Generic tool call ────────────────────────────────────────────────────────
+
+  async callTool<T = unknown>(
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureConnected();
+
+    const result = await this.client!.callTool({ name: toolName, arguments: args });
+
+    const text = (result.content as Array<{ type: string; text: string }>)
+      .filter((c) => c.type === 'text')
+      .map((c) => c.text)
+      .join('');
+
+    let parsed: T;
+    try {
+      parsed = JSON.parse(text) as T;
+    } catch {
+      throw new Error(
+        `[McpToolCaller] Tool "${toolName}" returned non-JSON: ${text.slice(0, 200)}`
+      );
+    }
+
+    if ((parsed as any)?.error) {
+      throw new Error(`[McpToolCaller] Tool "${toolName}" error: ${(parsed as any).error}`);
+    }
+
+    return parsed;
+  }
+
+  /** Disconnect from the remote MCP server */
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+    }
+  }
+
+  // ── Connection lifecycle ─────────────────────────────────────────────────
+
+  private async ensureConnected(): Promise<void> {
+    if (this.client) return;
+    if (!this.connectPromise) this.connectPromise = this._connect();
+    await this.connectPromise;
+    this.connectPromise = null;
+  }
+
+  private async _connect(): Promise<void> {
+    const opts = this.options;
+    this.client = new Client(
+      { name: opts.clientName ?? 'agent-identity-mcp-caller', version: opts.clientVersion ?? '0.1.0' },
+      { capabilities: {} }
+    );
+
+    if (opts.transport === 'http') {
+      const sseUrl = new URL('/sse', opts.serverUrl);
+      const headers: Record<string, string> = {};
+      if (opts.authToken) headers['Authorization'] = `Bearer ${opts.authToken}`;
+      await this.client.connect(new SSEClientTransport(sseUrl, { headers }));
+    } else {
+      await this.client.connect(
+        new StdioClientTransport({
+          command: opts.command,
+          args: opts.args ?? [],
+          env: opts.env,
+        })
+      );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @datacules/agent-identity-mcp-client
+ *
+ * Consumes external MCP servers as CredentialStores — the outbound direction
+ * of the agent-identity MCP integration.
+ *
+ * Exports:
+ *   McpCredentialStore   — CredentialStore impl that fetches credentials from
+ *                          any MCP server exposing a list_credentials tool
+ *   McpToolCaller        — thin client for calling any agent-identity MCP tool
+ *                          directly (resolve_credential, health, etc.)
+ *
+ * Both classes support two transports:
+ *   http   — SSE to a running HTTP+SSE agent-identity-mcp server
+ *   stdio  — spawns an MCP server process and communicates over stdio
+ *
+ * Example — plug McpCredentialStore into a CredentialRouter:
+ *
+ *   import { McpCredentialStore } from '@datacules/agent-identity-mcp-client';
+ *   import { createRouterFromStore } from '@datacules/agent-identity';
+ *
+ *   const store = new McpCredentialStore({
+ *     transport: 'http',
+ *     serverUrl: 'http://vault-mcp.internal:3002',
+ *     authToken: process.env.MCP_AUTH_TOKEN,
+ *   });
+ *
+ *   const router = createRouterFromStore(store, rules, logger);
+ *   const resolved = await router.resolveAsync(ctx);   // async path via store
+ *
+ *   // Clean up when done
+ *   process.on('SIGTERM', () => store.disconnect());
+ *
+ * Example — call the MCP server directly (no local router):
+ *
+ *   import { McpToolCaller } from '@datacules/agent-identity-mcp-client';
+ *
+ *   const caller = new McpToolCaller({
+ *     transport: 'http',
+ *     serverUrl: 'http://localhost:3002',
+ *   });
+ *   const result = await caller.resolveCredential({ userId: 'u1', ... });
+ *   await caller.disconnect();
+ */
+
+export { McpCredentialStore } from './store.js';
+export type { McpCredentialStoreOptions, McpCredentialStoreHttpOptions, McpCredentialStoreStdioOptions } from './store.js';
+export { McpToolCaller } from './caller.js';
+export type { McpToolCallerOptions, ResolvedCredentialResult, ResolvedMigrationResult, HealthResult } from './caller.js';

package/src/store.ts

@@ -0,0 +1,217 @@
+/**
+ * McpCredentialStore — CredentialStore implementation that fetches
+ * credentials from an external MCP server.
+ *
+ * Implements the full CredentialStore interface from @datacules/agent-identity
+ * so it can be dropped into any CredentialRouter without any other changes:
+ *
+ *   import { McpCredentialStore } from '@datacules/agent-identity-mcp-client';
+ *   import { createRouterFromStore } from '@datacules/agent-identity';
+ *
+ *   const store = new McpCredentialStore({
+ *     serverUrl: 'http://localhost:3002',
+ *     authToken: process.env.MCP_AUTH_TOKEN,
+ *   });
+ *   const router = createRouterFromStore(store, rules, logger);
+ *
+ * The MCP server this client connects to MUST expose a `list_credentials`
+ * tool (i.e. another @datacules/agent-identity-mcp instance, a Vault MCP
+ * server, a 1Password MCP server, or any custom server following the same
+ * tool contract).
+ *
+ * Transport:
+ *   - For a remote HTTP+SSE server: provide serverUrl
+ *   - For an in-process stdio server (test / monorepo): provide serverProcess
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { Credential, CredentialStore } from '@datacules/agent-identity';
+
+// ─── Options ───────────────────────────────────────────────────────────────────
+
+export interface McpCredentialStoreHttpOptions {
+  transport: 'http';
+  /**
+   * Base URL of the remote agent-identity MCP server.
+   * The SSE endpoint is expected at GET <serverUrl>/sse
+   * and messages at POST <serverUrl>/messages.
+   */
+  serverUrl: string;
+  /** Bearer token if the remote server requires auth */
+  authToken?: string;
+  /** Client name sent during MCP handshake (default: 'agent-identity-mcp-client') */
+  clientName?: string;
+  /** Client version (default: '0.1.0') */
+  clientVersion?: string;
+  /** TTL of the in-memory credential cache in ms (default: 60_000) */
+  cacheTtlMs?: number;
+}
+
+export interface McpCredentialStoreStdioOptions {
+  transport: 'stdio';
+  /** Command to spawn the MCP server process */
+  command: string;
+  /** Arguments passed to the spawned process */
+  args?: string[];
+  /** Environment variables for the spawned process */
+  env?: Record<string, string>;
+  clientName?: string;
+  clientVersion?: string;
+  cacheTtlMs?: number;
+}
+
+export type McpCredentialStoreOptions =
+  | McpCredentialStoreHttpOptions
+  | McpCredentialStoreStdioOptions;
+
+// ─── Cache entry ────────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  credentials: Credential[];
+  expiresAt: number;
+}
+
+// ─── McpCredentialStore ─────────────────────────────────────────────────────────
+
+/**
+ * CredentialStore implementation that pulls credentials from an external
+ * MCP server by calling its `list_credentials` tool.
+ *
+ * Credentials are cached in-memory for `cacheTtlMs` (default 60s) to avoid
+ * a round-trip on every router.resolve() call. Call invalidateCache() to
+ * force a fresh fetch on the next operation.
+ *
+ * The MCP client connection is lazy — the first store operation connects
+ * and caches the connection. Call disconnect() when the store is no longer
+ * needed (e.g. on process shutdown).
+ */
+export class McpCredentialStore implements CredentialStore {
+  private client: Client | null = null;
+  private cache: CacheEntry | null = null;
+  private readonly cacheTtlMs: number;
+  private readonly options: McpCredentialStoreOptions;
+  private connectPromise: Promise<void> | null = null;
+
+  constructor(options: McpCredentialStoreOptions) {
+    this.options = options;
+    this.cacheTtlMs = options.cacheTtlMs ?? 60_000;
+  }
+
+  // ── Public CredentialStore interface ────────────────────────────────────────
+
+  async findByRef(ref: string): Promise<Credential | null> {
+    const all = await this.listActive();
+    return all.find((c) => c.ref === ref && c.status === 'active') ?? null;
+  }
+
+  async listActive(): Promise<Credential[]> {
+    const cached = this.getFromCache();
+    if (cached) return cached.filter((c) => c.status === 'active');
+    const fresh = await this.fetchFromServer();
+    return fresh.filter((c) => c.status === 'active');
+  }
+
+  async listByKind(kind: Credential['kind']): Promise<Credential[]> {
+    const all = await this.listActive();
+    return all.filter((c) => c.kind === kind);
+  }
+
+  // ── Cache management ──────────────────────────────────────────────────────
+
+  /** Force the next store operation to fetch fresh credentials from the server */
+  invalidateCache(): void {
+    this.cache = null;
+  }
+
+  private getFromCache(): Credential[] | null {
+    if (!this.cache) return null;
+    if (Date.now() > this.cache.expiresAt) { this.cache = null; return null; }
+    return this.cache.credentials;
+  }
+
+  private setCache(credentials: Credential[]): void {
+    this.cache = { credentials, expiresAt: Date.now() + this.cacheTtlMs };
+  }
+
+  // ── MCP client lifecycle ─────────────────────────────────────────────────
+
+  private async ensureConnected(): Promise<void> {
+    if (this.client) return;
+    // Serialize concurrent callers so we only connect once
+    if (!this.connectPromise) this.connectPromise = this._connect();
+    await this.connectPromise;
+    this.connectPromise = null;
+  }
+
+  private async _connect(): Promise<void> {
+    const opts = this.options;
+    const clientName = opts.clientName ?? 'agent-identity-mcp-client';
+    const clientVersion = opts.clientVersion ?? '0.1.0';
+
+    this.client = new Client(
+      { name: clientName, version: clientVersion },
+      { capabilities: {} }
+    );
+
+    if (opts.transport === 'http') {
+      const sseUrl = new URL('/sse', opts.serverUrl);
+      const headers: Record<string, string> = {};
+      if (opts.authToken) headers['Authorization'] = `Bearer ${opts.authToken}`;
+
+      const transport = new SSEClientTransport(sseUrl, { headers });
+      await this.client.connect(transport);
+    } else {
+      const transport = new StdioClientTransport({
+        command: opts.command,
+        args: opts.args ?? [],
+        env: opts.env,
+      });
+      await this.client.connect(transport);
+    }
+  }
+
+  /** Disconnect the MCP client and clear the cache. Call on process shutdown. */
+  async disconnect(): Promise<void> {
+    this.invalidateCache();
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+    }
+  }
+
+  // ── Remote fetch ───────────────────────────────────────────────────────────
+
+  private async fetchFromServer(): Promise<Credential[]> {
+    await this.ensureConnected();
+
+    const result = await this.client!.callTool({
+      name: 'list_credentials',
+      arguments: {},
+    });
+
+    const text = (result.content as Array<{ type: string; text: string }>)
+      .filter((c) => c.type === 'text')
+      .map((c) => c.text)
+      .join('');
+
+    let parsed: { credentials?: Credential[] };
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error(
+        `[McpCredentialStore] MCP server returned non-JSON response from list_credentials: ${text.slice(0, 200)}`
+      );
+    }
+
+    if (!Array.isArray(parsed.credentials)) {
+      throw new Error(
+        '[McpCredentialStore] MCP server list_credentials response missing credentials array'
+      );
+    }
+
+    this.setCache(parsed.credentials);
+    return parsed.credentials;
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declarationOnly": false,
+    "outDir": "dist/esm",
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist/types",
+    "declaration": true,
+    "declarationOnly": true
+  },
+  "include": ["src"]
+}