@datacules/agent-identity-mcp 0.2.1

package/README.md

@@ -0,0 +1,101 @@
+# @datacules/agent-identity-mcp
+
+MCP server adapter for [`@datacules/agent-identity`](../../core). Exposes credential resolution as MCP tools so any MCP-capable client — **Claude Desktop, Claude Code, Cursor, Windsurf**, or a custom agent — can resolve credentials without touching the HTTP REST API.
+
+## Tools exposed
+
+| Tool | Description |
+|------|-------------|
+| `resolve_credential` | Resolve the correct credential for an `AgentRequestContext` |
+| `resolve_migration_credential` | Resolve source + target credential pair for a migration workflow |
+| `list_credentials` | List active credentials (safe metadata — no raw refs or secrets) |
+| `list_rules` | List routing rules ordered by priority |
+| `health` | Liveness check + loaded credential/rule counts |
+
+## Transports
+
+| Mode | Use case |
+|------|----------|
+| `stdio` (default) | Claude Desktop, Claude Code, Cursor, Windsurf config blocks |
+| `http+sse` | Hosted / networked deployments reachable over HTTP |
+
+## Quick start
+
+### As a library (stdio)
+
+```typescript
+import { createAgentIdentityMcpServer } from '@datacules/agent-identity-mcp';
+import type { Credential, RoutingRule } from '@datacules/agent-identity';
+
+const credentials: Credential[] = [ /* ... */ ];
+const rules: RoutingRule[] = [ /* ... */ ];
+
+const { start } = createAgentIdentityMcpServer({ credentials, rules });
+await start(); // reads from stdin, writes to stdout
+```
+
+### As a library (HTTP + SSE)
+
+```typescript
+const { start, stop } = createAgentIdentityMcpServer({
+  credentials,
+  rules,
+  transport: 'http',
+  httpPort: 3002,
+  httpAuthToken: process.env.MCP_AUTH_TOKEN, // optional
+});
+await start();
+// Server now accepts SSE at GET http://127.0.0.1:3002/sse
+// and tool calls at POST http://127.0.0.1:3002/messages?sessionId=<id>
+```
+
+### With a custom CredentialStore
+
+```typescript
+import { VaultCredentialStore } from '@datacules/agent-identity-store-vault';
+
+const store = new VaultCredentialStore({ address: process.env.VAULT_ADDR!, token: process.env.VAULT_TOKEN! });
+const { start } = createAgentIdentityMcpServer({ store, rules });
+await start();
+```
+
+## Claude Desktop config
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-identity": {
+      "command": "npx",
+      "args": ["@datacules/agent-identity-mcp"],
+      "env": {
+        "AGENT_IDENTITY_CREDENTIALS": "<base64-encoded JSON array of Credential objects>",
+        "AGENT_IDENTITY_RULES": "<base64-encoded JSON array of RoutingRule objects>"
+      }
+    }
+  }
+}
+```
+
+To encode your data:
+```bash
+echo '[{"id":"cred-1", ...}]' | base64
+```
+
+## Claude Code config
+
+```bash
+claude mcp add agent-identity -e AGENT_IDENTITY_CREDENTIALS=<base64> -e AGENT_IDENTITY_RULES=<base64> -- npx @datacules/agent-identity-mcp
+```
+
+## Environment variables (standalone CLI)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_IDENTITY_CREDENTIALS` | required | Base64-encoded JSON array of `Credential` objects |
+| `AGENT_IDENTITY_RULES` | required | Base64-encoded JSON array of `RoutingRule` objects |
+| `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `MCP_HTTP_PORT` | `3002` | HTTP port (only when `MCP_TRANSPORT=http`) |
+| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address |
+| `MCP_HTTP_AUTH_TOKEN` | — | Optional bearer token for HTTP auth |

package/bin/server.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Standalone CLI entry point for @datacules/agent-identity-mcp.
+ *
+ * Credentials and rules are loaded from environment variables:
+ *
+ *   AGENT_IDENTITY_CREDENTIALS  Base64-encoded JSON array of Credential objects
+ *   AGENT_IDENTITY_RULES        Base64-encoded JSON array of RoutingRule objects
+ *   MCP_TRANSPORT               'stdio' (default) | 'http'
+ *   MCP_HTTP_PORT               HTTP port when MCP_TRANSPORT=http (default: 3002)
+ *   MCP_HTTP_HOST               HTTP host (default: 127.0.0.1)
+ *   MCP_HTTP_AUTH_TOKEN         Optional bearer token for HTTP transport
+ *
+ * Example Claude Desktop config:
+ *   {
+ *     "mcpServers": {
+ *       "agent-identity": {
+ *         "command": "npx",
+ *         "args": ["@datacules/agent-identity-mcp"],
+ *         "env": {
+ *           "AGENT_IDENTITY_CREDENTIALS": "<base64-json>",
+ *           "AGENT_IDENTITY_RULES": "<base64-json>"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { createAgentIdentityMcpServer } from '../dist/esm/index.js';
+
+function loadBase64Json(envVar, name) {
+  const raw = process.env[envVar];
+  if (!raw) {
+    console.error(`[agent-identity-mcp] ${name}: ${envVar} is not set. Provide base64-encoded JSON.`);
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(Buffer.from(raw, 'base64').toString('utf8'));
+  } catch (e) {
+    console.error(`[agent-identity-mcp] ${name}: Failed to parse ${envVar} — ${e.message}`);
+    process.exit(1);
+  }
+}
+
+const credentials = loadBase64Json('AGENT_IDENTITY_CREDENTIALS', 'credentials');
+const rules       = loadBase64Json('AGENT_IDENTITY_RULES', 'rules');
+
+const transport    = process.env.MCP_TRANSPORT ?? 'stdio';
+const httpPort     = parseInt(process.env.MCP_HTTP_PORT ?? '3002', 10);
+const httpHost     = process.env.MCP_HTTP_HOST ?? '127.0.0.1';
+const httpAuthToken = process.env.MCP_HTTP_AUTH_TOKEN;
+
+const { start } = createAgentIdentityMcpServer({
+  credentials,
+  rules,
+  transport,
+  httpPort,
+  httpHost,
+  httpAuthToken,
+});
+
+process.on('uncaughtException', (err) => {
+  console.error('[agent-identity-mcp] uncaughtException:', err);
+  process.exit(1);
+});
+
+await start();

package/package.json

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

package/src/index.ts

@@ -0,0 +1,221 @@
+/**
+ * @datacules/agent-identity-mcp
+ *
+ * Exposes agent-identity credential resolution as an MCP server.
+ * Any MCP-capable client — Claude Desktop, Claude Code, Cursor,
+ * Windsurf, or a custom agent — can call the following tools:
+ *
+ *   resolve_credential           — resolves a credential for an AgentRequestContext
+ *   resolve_migration_credential — resolves source+target pair for MigrationContext
+ *   list_credentials             — lists active credentials (safe metadata only)
+ *   list_rules                   — lists routing rules (highest priority first)
+ *   health                       — liveness + loaded credential/rule counts
+ *
+ * Supports two transports:
+ *   stdio    — stdin/stdout, compatible with Claude Desktop / Claude Code / Cursor configs
+ *   http+sse — HTTP Server-Sent Events for hosted deployments
+ *
+ * Quick start (stdio):
+ *   import { createAgentIdentityMcpServer } from '@datacules/agent-identity-mcp';
+ *   const { start } = createAgentIdentityMcpServer({ credentials, rules });
+ *   await start();  // reads from stdin, writes to stdout
+ *
+ * Quick start (HTTP):
+ *   const { start } = createAgentIdentityMcpServer({
+ *     credentials, rules, transport: 'http', httpPort: 3002
+ *   });
+ *   await start();
+ *
+ * Claude Desktop config snippet (~/.claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "agent-identity": {
+ *         "command": "npx",
+ *         "args": ["@datacules/agent-identity-mcp"],
+ *         "env": {
+ *           "AGENT_IDENTITY_CREDENTIALS": "<base64-encoded JSON>",
+ *           "AGENT_IDENTITY_RULES": "<base64-encoded JSON>"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { AuditLogger, Credential, CredentialStore, RoutingRule } from '@datacules/agent-identity';
+import { MemoryCredentialStore } from '@datacules/agent-identity';
+import { ALL_TOOLS, type ToolDeps } from './tools.js';
+import { StdioServerTransport, startHttpMcpTransport } from './transports.js';
+import type { AgentIdentityMcpServerOptions } from './types.js';
+
+export * from './types.js';
+export { ALL_TOOLS } from './tools.js';
+
+// ─── Server factory ───────────────────────────────────────────────────────────
+
+export interface AgentIdentityMcpServerInit {
+  /**
+   * Credential array (convenience). Wrapped in a MemoryCredentialStore
+   * unless `store` is also provided, in which case `store` takes precedence.
+   */
+  credentials?: Credential[];
+  /** Custom CredentialStore (e.g. VaultCredentialStore, AwsCredentialStore) */
+  store?: CredentialStore;
+  rules: RoutingRule[];
+  logger?: AuditLogger;
+}
+
+export type AgentIdentityMcpServerConfig = AgentIdentityMcpServerInit & AgentIdentityMcpServerOptions;
+
+export interface AgentIdentityMcpServerHandle {
+  /** MCP Server instance (use to attach additional request handlers if needed) */
+  server: Server;
+  /** Start the server and connect the configured transport. Resolves when ready. */
+  start: () => Promise<void>;
+  /** Stop / clean up (closes HTTP server for http transport; no-op for stdio) */
+  stop: () => Promise<void>;
+}
+
+/**
+ * Create an agent-identity MCP server.
+ *
+ * @example
+ * // stdio (Claude Desktop / Claude Code config)
+ * const { start } = createAgentIdentityMcpServer({ credentials, rules });
+ * await start();
+ *
+ * @example
+ * // HTTP+SSE (hosted / networked)
+ * const { start } = createAgentIdentityMcpServer({
+ *   credentials, rules, transport: 'http', httpPort: 3002,
+ * });
+ * await start();
+ */
+export function createAgentIdentityMcpServer(
+  config: AgentIdentityMcpServerConfig
+): AgentIdentityMcpServerHandle {
+  const {
+    credentials,
+    store: customStore,
+    rules,
+    logger,
+    name = 'agent-identity',
+    version = '0.1.0',
+    transport = 'stdio',
+    httpPort = 3002,
+    httpHost = '127.0.0.1',
+    httpAuthToken,
+  } = config;
+
+  if (!customStore && !credentials) {
+    throw new Error('[agent-identity-mcp] Provide either credentials[] or a custom store.');
+  }
+
+  const store: CredentialStore =
+    customStore ?? new MemoryCredentialStore(credentials!);
+
+  const deps: ToolDeps = { store, rules, logger };
+
+  // Build the MCP server
+  const server = new Server(
+    { name, version },
+    { capabilities: { tools: {} } }
+  );
+
+  // Register tools/list handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: ALL_TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: {
+        type: 'object' as const,
+        // Convert Zod schema to JSON Schema via .shape introspection for
+        // simple objects; complex schemas fall back to an open object.
+        properties: extractJsonSchemaProperties(t.inputSchema),
+        required: extractRequiredKeys(t.inputSchema),
+      },
+    })),
+  }));
+
+  // Register tools/call handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = ALL_TOOLS.find((t) => t.name === request.params.name);
+    if (!tool) {
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify({ error: `Unknown tool: ${request.params.name}` }) }],
+        isError: true,
+      };
+    }
+    return tool.handler(request.params.arguments ?? {}, deps);
+  });
+
+  let stopFn: (() => void) | null = null;
+
+  const start = async (): Promise<void> => {
+    if (transport === 'stdio') {
+      const stdioTransport = new StdioServerTransport();
+      await server.connect(stdioTransport);
+    } else {
+      stopFn = await startHttpMcpTransport({
+        server,
+        port: httpPort,
+        host: httpHost,
+        authToken: httpAuthToken,
+      });
+    }
+  };
+
+  const stop = async (): Promise<void> => {
+    stopFn?.();
+    await server.close();
+  };
+
+  return { server, start, stop };
+}
+
+// ─── JSON Schema helpers (lightweight — no ajv dependency) ───────────────────
+
+function extractJsonSchemaProperties(schema: any): Record<string, unknown> {
+  try {
+    const shape = schema?._def?.shape?.() ?? schema?.shape ?? {};
+    const props: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(shape)) {
+      props[key] = zodToJsonSchemaNode(val);
+    }
+    return props;
+  } catch {
+    return {};
+  }
+}
+
+function extractRequiredKeys(schema: any): string[] {
+  try {
+    const shape = schema?._def?.shape?.() ?? schema?.shape ?? {};
+    return Object.entries(shape)
+      .filter(([, v]: [string, any]) => {
+        const typeName = v?._def?.typeName;
+        return typeName !== 'ZodOptional' && typeName !== 'ZodDefault';
+      })
+      .map(([k]) => k);
+  } catch {
+    return [];
+  }
+}
+
+function zodToJsonSchemaNode(zodNode: any): Record<string, unknown> {
+  const typeName = zodNode?._def?.typeName;
+  switch (typeName) {
+    case 'ZodString':  return { type: 'string' };
+    case 'ZodNumber':  return { type: 'number' };
+    case 'ZodBoolean': return { type: 'boolean' };
+    case 'ZodEnum':    return { type: 'string', enum: zodNode._def.values };
+    case 'ZodOptional':
+    case 'ZodDefault': return zodToJsonSchemaNode(zodNode._def.innerType);
+    case 'ZodObject':  return { type: 'object', properties: extractJsonSchemaProperties(zodNode) };
+    default:           return { type: 'string' };
+  }
+}

package/src/tools.ts

@@ -0,0 +1,217 @@
+/**
+ * MCP tool handler implementations for @datacules/agent-identity.
+ *
+ * Each exported function corresponds to one MCP tool:
+ *   resolve_credential        — resolves credential for AgentRequestContext
+ *   resolve_migration_credential — resolves source+target pair for MigrationContext
+ *   list_credentials          — lists active credentials (safe metadata, no raw refs)
+ *   list_rules                — lists routing rules
+ *   health                    — liveness check
+ *
+ * Tool schemas use Zod and are exported as McpToolSchema objects so the
+ * server index can register them with a single loop.
+ */
+
+import { z } from 'zod';
+import { createRouterFromStore, MemoryCredentialStore } from '@datacules/agent-identity';
+import type {
+  AuditLogger,
+  Credential,
+  CredentialStore,
+  RoutingRule,
+} from '@datacules/agent-identity';
+
+// ─── Shared Zod schemas ───────────────────────────────────────────────────────
+
+const SupportedProviderSchema = z.enum(['openai', 'anthropic', 'gemini', 'mistral', 'local']);
+const ResourceKindSchema = z.enum(['shared', 'personal']);
+const MigrationPhaseSchema = z.enum(['dry-run', 'extract', 'transform', 'load', 'verify', 'rollback']);
+
+const BaseContextSchema = z.object({
+  userId: z.string().min(1),
+  resourceId: z.string().min(1),
+  resourceKind: ResourceKindSchema,
+  provider: SupportedProviderSchema,
+  model: z.string().min(1),
+  action: z.string().min(1),
+  traceId: z.string().min(1),
+  sessionId: z.string().optional(),
+  requestedAt: z.string().optional(),
+  parentTraceId: z.string().optional(),
+  mcpSessionId: z.string().optional(),
+  mcpClientId: z.string().optional(),
+});
+
+const ResolveCredentialSchema = BaseContextSchema;
+
+const ResolveMigrationSchema = BaseContextSchema.extend({
+  migrationId: z.string().min(1),
+  phase: MigrationPhaseSchema,
+  sourceResourceId: z.string().min(1),
+  targetResourceId: z.string().min(1),
+  batchIndex: z.number().int().nonnegative().optional(),
+  totalBatches: z.number().int().positive().optional(),
+  dryRun: z.boolean(),
+});
+
+// ─── Tool descriptor type ─────────────────────────────────────────────────────
+
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: z.ZodTypeAny;
+  handler: (input: unknown, deps: ToolDeps) => Promise<McpToolResult>;
+}
+
+export interface McpToolResult {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}
+
+export interface ToolDeps {
+  store: CredentialStore;
+  rules: RoutingRule[];
+  logger?: AuditLogger;
+}
+
+// ─── Helper ───────────────────────────────────────────────────────────────────
+
+function ok(data: unknown): McpToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+function err(message: string): McpToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify({ error: message }) }], isError: true };
+}
+
+// ─── resolve_credential ───────────────────────────────────────────────────────
+
+const resolveCredentialTool: McpToolDefinition = {
+  name: 'resolve_credential',
+  description:
+    'Resolve the correct credential for an agent request. ' +
+    'Provide the full AgentRequestContext (userId, resourceId, resourceKind, provider, model, action, traceId). ' +
+    'Returns the resolved credential metadata — never the raw secret.',
+  inputSchema: ResolveCredentialSchema,
+  async handler(input, { store, rules, logger }) {
+    const parsed = ResolveCredentialSchema.safeParse(input);
+    if (!parsed.success) return err(`Validation error: ${parsed.error.message}`);
+
+    const ctx = {
+      ...parsed.data,
+      requestedAt: parsed.data.requestedAt ?? new Date().toISOString(),
+    };
+
+    const router = createRouterFromStore(store, rules, logger);
+    const resolved = router.resolve(ctx);
+    if (!resolved) return err('No credential resolved — no routing rule matched this context.');
+
+    return ok({
+      ok: true,
+      credentialId: resolved.credentialId,
+      kind: resolved.kind,
+      resolvedFor: resolved.resolvedFor,
+      // ref is intentionally omitted — never surface raw refs over MCP
+    });
+  },
+};
+
+// ─── resolve_migration_credential ─────────────────────────────────────────────
+
+const resolveMigrationCredentialTool: McpToolDefinition = {
+  name: 'resolve_migration_credential',
+  description:
+    'Resolve source and target credentials for a data migration workflow. ' +
+    'Requires a full MigrationContext including migrationId, phase, sourceResourceId, targetResourceId, and dryRun flag. ' +
+    'Returns both resolved credential metadata objects — never raw secrets.',
+  inputSchema: ResolveMigrationSchema,
+  async handler(input, { store, rules, logger }) {
+    const parsed = ResolveMigrationSchema.safeParse(input);
+    if (!parsed.success) return err(`Validation error: ${parsed.error.message}`);
+
+    const ctx = {
+      ...parsed.data,
+      requestedAt: parsed.data.requestedAt ?? new Date().toISOString(),
+    };
+
+    const router = createRouterFromStore(store, rules, logger);
+    const pair = router.resolvePair(ctx);
+    if (!pair) return err('No credential pair resolved — check that routing rules cover both sourceResourceId and targetResourceId.');
+
+    return ok({
+      ok: true,
+      migrationId: pair.migrationId,
+      source: { credentialId: pair.source.credentialId, kind: pair.source.kind, resolvedFor: pair.source.resolvedFor },
+      target: { credentialId: pair.target.credentialId, kind: pair.target.kind, resolvedFor: pair.target.resolvedFor },
+      expiresAt: pair.expiresAt ?? null,
+    });
+  },
+};
+
+// ─── list_credentials ─────────────────────────────────────────────────────────
+
+const listCredentialsTool: McpToolDefinition = {
+  name: 'list_credentials',
+  description:
+    'List all active credentials registered with this agent-identity server. ' +
+    'Returns safe metadata only (id, kind, name, scope, status, expiresAt). ' +
+    'Raw refs and secrets are never included.',
+  inputSchema: z.object({
+    kind: z.enum(['fixed', 'user-delegated']).optional().describe('Filter by credential kind'),
+  }),
+  async handler(input, { store }) {
+    const parsed = z.object({ kind: z.enum(['fixed', 'user-delegated']).optional() }).safeParse(input);
+    if (!parsed.success) return err(`Validation error: ${parsed.error.message}`);
+
+    const creds = parsed.data.kind
+      ? await store.listByKind(parsed.data.kind)
+      : await store.listActive();
+
+    const safe = creds.map(({ id, kind, name, scope, status, expiresAt }) => ({
+      id, kind, name, scope, status, expiresAt: expiresAt ?? null,
+    }));
+
+    return ok({ count: safe.length, credentials: safe });
+  },
+};
+
+// ─── list_rules ───────────────────────────────────────────────────────────────
+
+const listRulesTool: McpToolDefinition = {
+  name: 'list_rules',
+  description:
+    'List all routing rules registered with this agent-identity server, ' +
+    'ordered by priority (highest first). Useful for debugging credential routing.',
+  inputSchema: z.object({}),
+  async handler(_input, { rules }) {
+    const sorted = [...rules].sort((a, b) => b.priority - a.priority);
+    return ok({ count: sorted.length, rules: sorted });
+  },
+};
+
+// ─── health ───────────────────────────────────────────────────────────────────
+
+const healthTool: McpToolDefinition = {
+  name: 'health',
+  description: 'Check whether the agent-identity MCP server is healthy and how many credentials/rules are loaded.',
+  inputSchema: z.object({}),
+  async handler(_input, { store, rules }) {
+    const active = await store.listActive();
+    return ok({
+      status: 'ok',
+      credentialsLoaded: active.length,
+      rulesLoaded: rules.length,
+      timestamp: new Date().toISOString(),
+    });
+  },
+};
+
+// ─── Export all tools ─────────────────────────────────────────────────────────
+
+export const ALL_TOOLS: McpToolDefinition[] = [
+  resolveCredentialTool,
+  resolveMigrationCredentialTool,
+  listCredentialsTool,
+  listRulesTool,
+  healthTool,
+];

package/src/transports.ts

@@ -0,0 +1,118 @@
+/**
+ * Transport helpers for @datacules/agent-identity-mcp.
+ *
+ * Provides two transports:
+ *   - StdioServerTransport  : stdin/stdout, for Claude Desktop / Claude Code / Cursor config
+ *   - createHttpMcpTransport: HTTP + SSE, for hosted / networked deployments
+ *
+ * The HTTP transport adds optional bearer-token auth. The SSE endpoint at
+ * GET /sse initialises a session; the message endpoint at POST /messages
+ * receives client tool calls and posts responses back over the SSE stream.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export { StdioServerTransport };
+
+// ─── HTTP + SSE Transport ─────────────────────────────────────────────────────
+
+export interface HttpMcpTransportOptions {
+  /** MCP Server instance to connect the transport to */
+  server: Server;
+  /** TCP port to listen on (default: 3002) */
+  port?: number;
+  /** Bind address (default: '127.0.0.1') */
+  host?: string;
+  /**
+   * Optional static bearer token.
+   * Requests without a matching Authorization: Bearer <token> header are
+   * rejected with 401. Omit to allow unauthenticated connections (only
+   * appropriate on a private network / localhost).
+   */
+  authToken?: string;
+}
+
+/**
+ * Start an HTTP + SSE MCP transport.
+ *
+ * Session lifecycle:
+ *   1. Client opens GET /sse — transport creates an SSEServerTransport,
+ *      connects it to the MCP Server, and starts streaming.
+ *   2. Client POSTs tool calls to POST /messages?sessionId=<id>.
+ *   3. Transport routes each message to the correct session and replies
+ *      via the open SSE stream.
+ *
+ * Returns a cleanup function that closes the HTTP server.
+ */
+export async function startHttpMcpTransport(options: HttpMcpTransportOptions): Promise<() => void> {
+  const { server, port = 3002, host = '127.0.0.1', authToken } = options;
+
+  // Session registry: sessionId → active SSEServerTransport
+  const sessions = new Map<string, SSEServerTransport>();
+
+  const http = await import('node:http');
+
+  function authenticate(req: IncomingMessage, res: ServerResponse): boolean {
+    if (!authToken) return true;
+    const header = req.headers['authorization'] ?? '';
+    if (header === `Bearer ${authToken}`) return true;
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Unauthorized — valid Bearer token required' }));
+    return false;
+  }
+
+  const httpServer = http.createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? '/', `http://${host}:${port}`);
+
+    // CORS for browser-based MCP clients
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type');
+    if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
+
+    if (!authenticate(req, res)) return;
+
+    // ── SSE session init ──────────────────────────────────────────────────
+    if (req.method === 'GET' && url.pathname === '/sse') {
+      const transport = new SSEServerTransport('/messages', res);
+      sessions.set(transport.sessionId, transport);
+
+      req.on('close', () => sessions.delete(transport.sessionId));
+
+      await server.connect(transport);
+      return;
+    }
+
+    // ── Incoming tool call message ────────────────────────────────────────
+    if (req.method === 'POST' && url.pathname === '/messages') {
+      const sessionId = url.searchParams.get('sessionId') ?? '';
+      const transport = sessions.get(sessionId);
+
+      if (!transport) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `Session ${sessionId} not found or expired` }));
+        return;
+      }
+
+      await transport.handlePostMessage(req, res);
+      return;
+    }
+
+    // ── Health probe (GET /) ──────────────────────────────────────────────
+    if (req.method === 'GET' && url.pathname === '/') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, sessions: sessions.size, transport: 'http+sse' }));
+      return;
+    }
+
+    res.writeHead(404); res.end();
+  });
+
+  await new Promise<void>((resolve) => httpServer.listen(port, host, resolve));
+  console.error(`[agent-identity-mcp] HTTP+SSE transport listening on http://${host}:${port}`);
+
+  return () => httpServer.close();
+}

package/src/types.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP-specific type extensions for @datacules/agent-identity.
+ *
+ * McpRequestContext extends AgentRequestContext with the MCP session and
+ * client identifiers so audit logs can trace a credential resolution back
+ * to the exact MCP session that triggered it.
+ */
+
+import type { AgentRequestContext, MigrationContext } from '@datacules/agent-identity';
+
+// ─── MCP Request Context ──────────────────────────────────────────────────────
+
+/**
+ * AgentRequestContext enriched with MCP session metadata.
+ * Pass this to AgentIdentityMcpServer.resolve() for full audit trail.
+ */
+export interface McpRequestContext extends AgentRequestContext {
+  /** MCP session ID from the active transport session */
+  mcpSessionId: string;
+  /** MCP client identifier (e.g. 'claude-desktop', 'cursor', 'windsurf') */
+  mcpClientId?: string;
+  /** MCP protocol version negotiated during handshake */
+  mcpProtocolVersion?: string;
+}
+
+/**
+ * MigrationContext enriched with MCP session metadata.
+ */
+export interface McpMigrationContext extends MigrationContext {
+  mcpSessionId: string;
+  mcpClientId?: string;
+  mcpProtocolVersion?: string;
+}
+
+// ─── Tool I/O shapes (validated by Zod in tools.ts) ──────────────────────────
+
+export interface ResolveCredentialInput {
+  userId: string;
+  resourceId: string;
+  resourceKind: 'shared' | 'personal';
+  provider: 'openai' | 'anthropic' | 'gemini' | 'mistral' | 'local';
+  model: string;
+  action: string;
+  traceId: string;
+  sessionId?: string;
+  requestedAt?: string;
+  parentTraceId?: string;
+  // MCP extensions
+  mcpSessionId?: string;
+  mcpClientId?: string;
+}
+
+export interface ResolveMigrationInput {
+  userId: string;
+  resourceId: string;
+  resourceKind: 'shared' | 'personal';
+  provider: 'openai' | 'anthropic' | 'gemini' | 'mistral' | 'local';
+  model: string;
+  action: string;
+  traceId: string;
+  migrationId: string;
+  phase: 'dry-run' | 'extract' | 'transform' | 'load' | 'verify' | 'rollback';
+  sourceResourceId: string;
+  targetResourceId: string;
+  batchIndex?: number;
+  totalBatches?: number;
+  dryRun: boolean;
+  requestedAt?: string;
+  mcpSessionId?: string;
+  mcpClientId?: string;
+}
+
+// ─── MCP Server Options ───────────────────────────────────────────────────────
+
+export interface AgentIdentityMcpServerOptions {
+  /**
+   * Server name sent during MCP handshake.
+   * Appears in the client's tool list as the server label.
+   */
+  name?: string;
+  /** Semantic version string reported during handshake */
+  version?: string;
+  /**
+   * Transport mode.
+   * - 'stdio'    : reads from stdin / writes to stdout (default; use for
+   *               Claude Desktop, Claude Code, Cursor, Windsurf configs)
+   * - 'http'     : HTTP + SSE transport on the specified port
+   */
+  transport?: 'stdio' | 'http';
+  /** Port for HTTP+SSE transport (default: 3002) */
+  httpPort?: number;
+  /** Host for HTTP+SSE transport (default: '127.0.0.1') */
+  httpHost?: string;
+  /**
+   * Optional bearer token required in MCP HTTP requests.
+   * Ignored for stdio transport.
+   */
+  httpAuthToken?: string;
+}

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"]
+}