@rickydata/agent0-mcp 0.1.0

package/dist/tools/reputation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reputation.js","sourceRoot":"","sources":["../../src/tools/reputation.ts"],"names":[],"mappings":"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"}

package/dist/utils/chains.d.ts

@@ -0,0 +1,10 @@
+/** Known chain configurations for ERC-8004 agent registry lookups. */
+export interface ChainConfig {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    explorerUrl: string;
+}
+export declare const CHAINS: Record<number, ChainConfig>;
+export declare function getChain(chainId: number): ChainConfig | undefined;
+export declare function getChainName(chainId: number): string;

package/dist/utils/chains.js

@@ -0,0 +1,33 @@
+export const CHAINS = {
+    1: {
+        chainId: 1,
+        name: "Ethereum Mainnet",
+        rpcUrl: "https://eth.llamarpc.com",
+        explorerUrl: "https://etherscan.io",
+    },
+    8453: {
+        chainId: 8453,
+        name: "Base",
+        rpcUrl: "https://mainnet.base.org",
+        explorerUrl: "https://basescan.org",
+    },
+    42161: {
+        chainId: 42161,
+        name: "Arbitrum One",
+        rpcUrl: "https://arb1.arbitrum.io/rpc",
+        explorerUrl: "https://arbiscan.io",
+    },
+    10: {
+        chainId: 10,
+        name: "Optimism",
+        rpcUrl: "https://mainnet.optimism.io",
+        explorerUrl: "https://optimistic.etherscan.io",
+    },
+};
+export function getChain(chainId) {
+    return CHAINS[chainId];
+}
+export function getChainName(chainId) {
+    return CHAINS[chainId]?.name ?? `Chain ${chainId}`;
+}
+//# sourceMappingURL=chains.js.map

package/dist/utils/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../../src/utils/chains.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,MAAM,GAAgC;IACjD,CAAC,EAAE;QACD,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,kBAAkB;QACxB,MAAM,EAAE,0BAA0B;QAClC,WAAW,EAAE,sBAAsB;KACpC;IACD,IAAI,EAAE;QACJ,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,0BAA0B;QAClC,WAAW,EAAE,sBAAsB;KACpC;IACD,KAAK,EAAE;QACL,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,8BAA8B;QACtC,WAAW,EAAE,qBAAqB;KACnC;IACD,EAAE,EAAE;QACF,OAAO,EAAE,EAAE;QACX,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,6BAA6B;QACrC,WAAW,EAAE,iCAAiC;KAC/C;CACF,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,SAAS,OAAO,EAAE,CAAC;AACrD,CAAC"}

package/dist/utils/trust-labels.d.ts

@@ -0,0 +1,10 @@
+export interface TrustLabel {
+    emoji: string;
+    label: string;
+    display: string;
+}
+/**
+ * Compute a human-readable trust label from review count and average score.
+ * First-match-wins rules (order matters).
+ */
+export declare function computeTrustLabel(count: number, avg: number): TrustLabel;

package/dist/utils/trust-labels.js

@@ -0,0 +1,48 @@
+/**
+ * Compute a human-readable trust label from review count and average score.
+ * First-match-wins rules (order matters).
+ */
+export function computeTrustLabel(count, avg) {
+    if (count >= 5 && avg < -50)
+        return {
+            emoji: "\u{1F534}",
+            label: "Untrusted",
+            display: `\u{1F534} Untrusted -- ${avg}/100 (${count} reviews)`,
+        };
+    if (avg < 0)
+        return {
+            emoji: "\u{1F7E0}",
+            label: "Caution",
+            display: `\u{1F7E0} Caution -- ${avg}/100 (${count} reviews)`,
+        };
+    if (count >= 20 && avg >= 80)
+        return {
+            emoji: "\u2B50",
+            label: "Highly Trusted",
+            display: `\u2B50 Highly Trusted -- ${avg}/100 (${count} reviews)`,
+        };
+    if (count >= 10 && avg >= 70)
+        return {
+            emoji: "\u{1F7E2}",
+            label: "Trusted",
+            display: `\u{1F7E2} Trusted -- ${avg}/100 (${count} reviews)`,
+        };
+    if (count >= 5 && avg >= 50)
+        return {
+            emoji: "\u{1F7E2}",
+            label: "Established",
+            display: `\u{1F7E2} Established -- ${avg}/100 (${count} reviews)`,
+        };
+    if (count > 0)
+        return {
+            emoji: "\u{1F535}",
+            label: "Emerging",
+            display: `\u{1F535} Emerging -- ${avg}/100 (${count} reviews)`,
+        };
+    return {
+        emoji: "\u26AA",
+        label: "No Data",
+        display: "\u26AA No Data -- 0/100 (0 reviews)",
+    };
+}
+//# sourceMappingURL=trust-labels.js.map

package/dist/utils/trust-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-labels.js","sourceRoot":"","sources":["../../src/utils/trust-labels.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,GAAW;IAC1D,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE;QACzB,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,WAAW;YAClB,OAAO,EAAE,0BAA0B,GAAG,SAAS,KAAK,WAAW;SAChE,CAAC;IACJ,IAAI,GAAG,GAAG,CAAC;QACT,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,SAAS;YAChB,OAAO,EAAE,wBAAwB,GAAG,SAAS,KAAK,WAAW;SAC9D,CAAC;IACJ,IAAI,KAAK,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE;QAC1B,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,gBAAgB;YACvB,OAAO,EAAE,4BAA4B,GAAG,SAAS,KAAK,WAAW;SAClE,CAAC;IACJ,IAAI,KAAK,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE;QAC1B,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,SAAS;YAChB,OAAO,EAAE,wBAAwB,GAAG,SAAS,KAAK,WAAW;SAC9D,CAAC;IACJ,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE;QACzB,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,aAAa;YACpB,OAAO,EAAE,4BAA4B,GAAG,SAAS,KAAK,WAAW;SAClE,CAAC;IACJ,IAAI,KAAK,GAAG,CAAC;QACX,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,UAAU;YACjB,OAAO,EAAE,yBAAyB,GAAG,SAAS,KAAK,WAAW;SAC/D,CAAC;IACJ,OAAO;QACL,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,qCAAqC;KAC/C,CAAC;AACJ,CAAC"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Validate an Ethereum address (basic checksum-agnostic check).
+ */
+export declare function isValidAddress(address: string): boolean;
+/**
+ * Validate a bytes32 hex string (e.g., agent ID).
+ */
+export declare function isValidBytes32(hex: string): boolean;
+/**
+ * Validate a positive integer chain ID.
+ */
+export declare function isValidChainId(chainId: number): boolean;

package/dist/utils/validation.js

@@ -0,0 +1,19 @@
+/**
+ * Validate an Ethereum address (basic checksum-agnostic check).
+ */
+export function isValidAddress(address) {
+    return /^0x[0-9a-fA-F]{40}$/.test(address);
+}
+/**
+ * Validate a bytes32 hex string (e.g., agent ID).
+ */
+export function isValidBytes32(hex) {
+    return /^0x[0-9a-fA-F]{64}$/.test(hex);
+}
+/**
+ * Validate a positive integer chain ID.
+ */
+export function isValidChainId(chainId) {
+    return Number.isInteger(chainId) && chainId > 0;
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC;AAClD,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rickydata/agent0-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP server wrapping Agent0 SDK for ERC-8004 trustless agent operations",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "agent0-sdk": "^1.7.1",
+    "cors": "^2.8.5",
+    "ethers": "^6.16.0",
+    "express": "^4.21.2",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@noble/hashes": "^1.7.0",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}

package/src/auth/sdk-client.ts

@@ -0,0 +1,171 @@
+/**
+ * Agent0 SDK client management.
+ *
+ * Provides read-only and authenticated SDK instances for ERC-8004 operations.
+ *
+ * Key resolution order:
+ * 1. ERC8004_PRIVATE_KEY env var (explicit private key)
+ * 2. ERC8004_DERIVED_KEY env var (previously derived key from wallet signature)
+ * 3. Prompt user for wallet signature derivation (via configure_wallet tool)
+ */
+import { SDK, type SDKConfig } from "agent0-sdk";
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const DEFAULT_CHAIN_ID = parseInt(process.env.AGENT0_CHAIN_ID || "11155111", 10);
+const RPC_URL = process.env.AGENT0_RPC_URL;
+const IPFS_PROVIDER = (process.env.AGENT0_IPFS_PROVIDER || "pinata") as
+  | "pinata"
+  | "helia"
+  | "node"
+  | "filecoinPin";
+const PINATA_JWT = process.env.PINATA_JWT;
+
+// ============================================================================
+// SDK CLIENT STATE
+// ============================================================================
+
+let _readOnlySDK: SDK | null = null;
+let _authenticatedSDK: SDK | null = null;
+let _currentPrivateKey: string | null = null;
+let _currentChainId: number = DEFAULT_CHAIN_ID;
+
+/**
+ * Resolve the private key from environment or stored state.
+ * Returns null if no key is available (read-only mode).
+ */
+function resolvePrivateKey(): string | null {
+  // 1. Explicit private key
+  if (process.env.ERC8004_PRIVATE_KEY) {
+    return process.env.ERC8004_PRIVATE_KEY;
+  }
+  // 2. Previously derived key
+  if (process.env.ERC8004_DERIVED_KEY) {
+    return process.env.ERC8004_DERIVED_KEY;
+  }
+  // 3. Stored from configure_wallet
+  return _currentPrivateKey;
+}
+
+/**
+ * Build SDK config for the given chain.
+ */
+function buildConfig(
+  chainId: number,
+  privateKey?: string | null,
+): SDKConfig {
+  const config: SDKConfig = { chainId };
+
+  if (RPC_URL) config.rpcUrl = RPC_URL;
+  if (privateKey) config.privateKey = privateKey;
+
+  // Only configure IPFS when we have a private key (write operations need IPFS)
+  if (privateKey && PINATA_JWT) {
+    config.ipfs = IPFS_PROVIDER;
+    config.pinataJwt = PINATA_JWT;
+  }
+
+  return config;
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+/**
+ * Get a read-only SDK instance (no signing capabilities).
+ * Suitable for search, discovery, and reputation queries.
+ */
+export function getReadOnlySDK(chainId?: number): SDK {
+  const targetChain = chainId ?? _currentChainId;
+
+  // Cache the read-only SDK for the current chain
+  if (_readOnlySDK && targetChain === _currentChainId) {
+    return _readOnlySDK;
+  }
+
+  _readOnlySDK = new SDK(buildConfig(targetChain));
+  if (!chainId) _currentChainId = targetChain;
+  return _readOnlySDK;
+}
+
+/**
+ * Get an authenticated SDK instance (with signing capabilities).
+ * Returns null if no private key is available.
+ */
+export function getAuthenticatedSDK(chainId?: number): SDK | null {
+  const privateKey = resolvePrivateKey();
+  if (!privateKey) return null;
+
+  const targetChain = chainId ?? _currentChainId;
+
+  // Return cached if key and chain haven't changed
+  if (
+    _authenticatedSDK &&
+    _currentPrivateKey === privateKey &&
+    targetChain === _currentChainId
+  ) {
+    return _authenticatedSDK;
+  }
+
+  _authenticatedSDK = new SDK(buildConfig(targetChain, privateKey));
+  _currentPrivateKey = privateKey;
+  _currentChainId = targetChain;
+  return _authenticatedSDK;
+}
+
+/**
+ * Set the derived private key (from wallet signature derivation).
+ * Clears cached authenticated SDK so it's rebuilt on next access.
+ */
+export function setDerivedKey(privateKey: string): void {
+  _currentPrivateKey = privateKey;
+  _authenticatedSDK = null;
+}
+
+/**
+ * Check if an authenticated SDK is available (has a private key).
+ */
+export function hasAuthentication(): boolean {
+  return resolvePrivateKey() !== null;
+}
+
+/**
+ * Get the current chain ID.
+ */
+export function getCurrentChainId(): number {
+  return _currentChainId;
+}
+
+/**
+ * Set the current chain ID (clears cached SDK instances).
+ */
+export function setChainId(chainId: number): void {
+  _currentChainId = chainId;
+  _readOnlySDK = null;
+  _authenticatedSDK = null;
+}
+
+/**
+ * Get authentication status information.
+ */
+export function getAuthStatus(): {
+  hasKey: boolean;
+  chainId: number;
+  source: "env:ERC8004_PRIVATE_KEY" | "env:ERC8004_DERIVED_KEY" | "derived" | "none";
+  isReadOnly: boolean;
+} {
+  let source: "env:ERC8004_PRIVATE_KEY" | "env:ERC8004_DERIVED_KEY" | "derived" | "none" = "none";
+  if (process.env.ERC8004_PRIVATE_KEY) source = "env:ERC8004_PRIVATE_KEY";
+  else if (process.env.ERC8004_DERIVED_KEY) source = "env:ERC8004_DERIVED_KEY";
+  else if (_currentPrivateKey) source = "derived";
+
+  return {
+    hasKey: source !== "none",
+    chainId: _currentChainId,
+    source,
+    isReadOnly: source === "none",
+  };
+}

package/src/auth/token.ts

@@ -0,0 +1,19 @@
+/**
+ * Re-exports for auth module.
+ */
+export {
+  getDerivationMessage,
+  deriveWalletFromSignature,
+  verifyDerivationSignature,
+  type DerivedWallet,
+} from "./wallet-derivation.js";
+
+export {
+  getReadOnlySDK,
+  getAuthenticatedSDK,
+  setDerivedKey,
+  hasAuthentication,
+  getCurrentChainId,
+  setChainId,
+  getAuthStatus,
+} from "./sdk-client.js";

package/src/auth/wallet-derivation.ts

@@ -0,0 +1,91 @@
+/**
+ * Wallet derivation for ERC-8004 agent identity.
+ *
+ * Derives a deterministic private key from a wallet signature using HKDF.
+ * This allows an MCP client user to derive a signing key for ERC-8004 operations
+ * without exposing their main wallet private key.
+ *
+ * Flow:
+ * 1. User signs a deterministic message with their wallet
+ * 2. HKDF extracts a derived key from the signature
+ * 3. The derived key is used for agent0-sdk write operations
+ */
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha2";
+import { ethers } from "ethers";
+
+export interface DerivedWallet {
+  address: string;
+  privateKey: string;
+}
+
+/**
+ * The deterministic signing message used to derive the key.
+ * CRITICAL: This MUST NOT contain nonces, timestamps, or any variable data.
+ * If changed, all previously derived keys become invalid.
+ */
+const DERIVATION_MESSAGE =
+  "Sign this message to derive your ERC-8004 agent key.\n\n" +
+  "This signature will be used to create a deterministic private key " +
+  "for managing your on-chain agent identity. " +
+  "This does not grant access to your funds.";
+
+/**
+ * Get the deterministic message that must be signed for key derivation.
+ */
+export function getDerivationMessage(): string {
+  return DERIVATION_MESSAGE;
+}
+
+/**
+ * Derive an ERC-8004 agent wallet from a wallet signature.
+ *
+ * Uses HKDF-SHA256 to extract a 32-byte private key from the signature.
+ * The same signature always produces the same derived key.
+ *
+ * @param signature - The wallet's signature of DERIVATION_MESSAGE (hex string with 0x prefix)
+ * @returns DerivedWallet with address and privateKey
+ */
+export function deriveWalletFromSignature(signature: string): DerivedWallet {
+  if (!signature || !signature.startsWith("0x")) {
+    throw new Error("Invalid signature: must be a hex string starting with 0x");
+  }
+
+  // Convert signature to bytes
+  const sigBytes = ethers.getBytes(signature);
+
+  // HKDF: extract + expand
+  // salt: "agent0-erc8004" (domain separation)
+  // info: "agent-key-v1" (versioned derivation context)
+  const salt = new TextEncoder().encode("agent0-erc8004");
+  const info = new TextEncoder().encode("agent-key-v1");
+  const derivedKeyBytes = hkdf(sha256, sigBytes, salt, info, 32);
+
+  // Create ethers wallet from derived key
+  const privateKey = ethers.hexlify(derivedKeyBytes);
+  const wallet = new ethers.Wallet(privateKey);
+
+  return {
+    address: wallet.address,
+    privateKey,
+  };
+}
+
+/**
+ * Verify that a signature was produced by the expected wallet address.
+ *
+ * @param signature - The signature to verify
+ * @param expectedAddress - The wallet address that should have signed
+ * @returns true if the signature was produced by expectedAddress
+ */
+export function verifyDerivationSignature(
+  signature: string,
+  expectedAddress: string,
+): boolean {
+  try {
+    const recovered = ethers.verifyMessage(DERIVATION_MESSAGE, signature);
+    return recovered.toLowerCase() === expectedAddress.toLowerCase();
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,184 @@
+import { randomUUID } from "node:crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import express from "express";
+import cors from "cors";
+import { TOOLS, handleToolCall } from "./tools/index.js";
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const RESPONSE_MAX_LENGTH = parseInt(
+  process.env.RESPONSE_MAX_LENGTH || "200000",
+  10,
+);
+const SERVER_NAME = "agent0-mcp";
+const SERVER_VERSION = "0.1.0";
+
+// ============================================================================
+// RESPONSE CAPPING
+// ============================================================================
+
+function truncateResponse(result: unknown): string {
+  const text =
+    typeof result === "string" ? result : JSON.stringify(result, null, 2);
+  if (text.length <= RESPONSE_MAX_LENGTH) return text;
+  return (
+    text.slice(0, RESPONSE_MAX_LENGTH) +
+    `\n\n--- Response truncated (${text.length} chars, limit ${RESPONSE_MAX_LENGTH}) ---`
+  );
+}
+
+// ============================================================================
+// MCP HANDLER SETUP
+// ============================================================================
+
+function setupMCPHandlers(server: Server): void {
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    let result: unknown;
+
+    try {
+      result = await handleToolCall(name, args);
+    } catch (error: unknown) {
+      const message =
+        error instanceof Error ? error.message : String(error);
+      result = { success: false, error: message };
+    }
+
+    const content = truncateResponse(result);
+    return {
+      content: [{ type: "text" as const, text: content }],
+    };
+  });
+}
+
+// ============================================================================
+// SESSION MANAGEMENT (HTTP mode)
+// ============================================================================
+
+interface MCPSession {
+  server: Server;
+  transport: StreamableHTTPServerTransport;
+  createdAt: number;
+}
+
+const sessions = new Map<string, MCPSession>();
+
+// Clean up sessions older than 2 hours
+setInterval(
+  () => {
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      if (now - session.createdAt > 2 * 60 * 60 * 1000) {
+        session.transport.close();
+        session.server.close();
+        sessions.delete(id);
+      }
+    }
+  },
+  5 * 60 * 1000,
+);
+
+function createServer(): Server {
+  return new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: { listChanged: false } } },
+  );
+}
+
+// ============================================================================
+// TRANSPORT: HTTP (StreamableHTTP)
+// ============================================================================
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+app.get("/health", (_req, res) => {
+  res.json({
+    status: "ok",
+    server: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: TOOLS.length,
+    sessions: sessions.size,
+  });
+});
+
+app.post("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+  if (sessionId && sessions.has(sessionId)) {
+    const session = sessions.get(sessionId)!;
+    await session.transport.handleRequest(req, res, req.body);
+  } else {
+    const newId = randomUUID();
+    const server = createServer();
+    setupMCPHandlers(server);
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => newId,
+    });
+    await server.connect(transport);
+
+    sessions.set(newId, { server, transport, createdAt: Date.now() });
+    await transport.handleRequest(req, res, req.body);
+  }
+});
+
+app.get("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string | undefined;
+  if (!sessionId || !sessions.has(sessionId)) {
+    res.status(400).json({
+      error: "Invalid or missing session. Send initialize first via POST.",
+    });
+    return;
+  }
+  await sessions.get(sessionId)!.transport.handleRequest(req, res);
+});
+
+app.delete("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string | undefined;
+  if (sessionId && sessions.has(sessionId)) {
+    const session = sessions.get(sessionId)!;
+    await session.transport.handleRequest(req, res);
+    session.transport.close();
+    session.server.close();
+    sessions.delete(sessionId);
+  } else {
+    res.status(400).json({ error: "Invalid or missing session." });
+  }
+});
+
+// ============================================================================
+// START
+// ============================================================================
+
+const isStdio = process.argv.includes("--stdio");
+
+if (isStdio) {
+  // In stdio mode, redirect console.log to stderr so it doesn't pollute the MCP JSON stream
+  console.log = console.error;
+  const server = createServer();
+  setupMCPHandlers(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`${SERVER_NAME} running on stdio (${TOOLS.length} tools)`);
+} else {
+  const port = parseInt(process.env.PORT || "8080", 10);
+  app.listen(port, () => {
+    console.log(`${SERVER_NAME} running on port ${port}`);
+    console.log(`Tools: ${TOOLS.length}`);
+    console.log(`Endpoints: /health /mcp`);
+  });
+}