web3-tools-mcp 1.6.0 → 2.0.0

package/src/index.ts

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 
-import packageJson from "../package.json" with { type: "json" };
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { initializeClientManager } from "./client.js";
-import { registerAllTools } from "./tools/index.js";
-import { parseCommandLineArgs } from "./utils.js";
-import { getWalletClient } from "./wallet-client.js";
-import { startHttpServer } from "./http-server.js";
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { WalletRelay } from 'web3-wallet-relay'
+import packageJson from '../package.json' with { type: 'json' }
+import { initializeClientManager, SUPPORTED_CHAINS } from './client.js'
+import { startHttpServer } from './http-server.js'
+import { registerAllTools } from './tools/index.js'
+import { parseCommandLineArgs } from './utils.js'
+import { getWalletClient } from './wallet-client.js'
 
 // Parse configuration
-const config = parseCommandLineArgs();
+const config = parseCommandLineArgs()
 
 // Show help if requested
 if (config.showHelp) {
@@ -38,15 +39,17 @@ ENVIRONMENT VARIABLES:
   INFURA_API_KEY                Alternative to --infura-api-key
   HYPERSYNC_API_KEY             Alternative to --hypersync-api-key
   WALLETCONNECT_PROJECT_ID      Alternative to --walletconnect-project-id
+  CUSTOM_RPC                    Alternative to --custom-rpc
   MCP_HTTP_PORT                 Serve MCP over HTTP on this port instead of stdio
   MCP_TOKEN                     Bearer token required by the HTTP transport
+  MCP_PUBLIC_URL                Public URL of this server, advertised in OAuth metadata
   UPSTASH_REDIS_REST_URL        Keep WalletConnect sessions in Redis, not on disk
   UPSTASH_REDIS_REST_TOKEN
   WALLET_SERVER_URL             URL of a hosted wallet relay (omit to run one locally)
   WALLET_TOKEN                  Shared pairing token for the wallet relay
 
 SUPPORTED CHAINS:
-  mainnet, arbitrum, avalanche, base, bnb, gnosis, sonic, optimism, polygon, zksync, linea, unichain, localhost
+  ${SUPPORTED_CHAINS.join(', ')}
 
 EXAMPLES:
   # Use with npx (recommended)
@@ -64,87 +67,108 @@ DOCUMENTATION:
   Issues: ${packageJson.bugs.url}
 
 For MCP client configuration, see the README.md file.
-`);
-  process.exit(0);
+`)
+  process.exit(0)
 }
 
 // Log configuration info
 if (config.etherscanApiKey) {
-  console.error("[MCP] Etherscan API key configured");
+  console.error('[MCP] Etherscan API key configured')
 }
 if (config.alchemyApiKey) {
-  console.error("[MCP] Alchemy API key configured");
+  console.error('[MCP] Alchemy API key configured')
 }
 if (config.infuraApiKey) {
-  console.error("[MCP] Infura API key configured");
+  console.error('[MCP] Infura API key configured')
 }
 if (config.walletConnectProjectId) {
-  console.error("[MCP] WalletConnect project id configured — phone signing available");
+  console.error('[MCP] WalletConnect project id configured — phone signing available')
 }
 if (config.customRpcUrls) {
-  console.error("[MCP] Custom RPC URLs:", Object.keys(config.customRpcUrls));
+  console.error('[MCP] Custom RPC URLs:', Object.keys(config.customRpcUrls))
 }
 
 // Initialize client manager
-initializeClientManager(config);
+initializeClientManager(config)
 
 function createMcpServer() {
   const server = new McpServer({
-    name: "web3-tools-mcp",
-    version: packageJson.version,
-  });
-  registerAllTools(server);
-  return server;
+    name: 'web3-tools-mcp',
+    version: packageJson.version
+  })
+  registerAllTools(server)
+  return server
 }
 
-// Serving over HTTP means there is no browser on this machine to open, so the wallet relay
-// is skipped and signing goes to a paired phone over WalletConnect.
-const httpMode = Boolean(process.env.MCP_HTTP_PORT);
-
-const wallet = getWalletClient();
+const httpMode = Boolean(process.env.MCP_HTTP_PORT)
+const httpPort = Number(process.env.MCP_HTTP_PORT)
+
+/**
+ * Hosted, the signing page rides on the same port as /mcp, so a browser wallet works from
+ * a deployment too — the platform gives one port and both fit on it.
+ *
+ * Its token is minted per boot rather than persisted. A hosted relay is reachable from
+ * anywhere, and the pairing URL is fetched through wallet_status, which already needs
+ * MCP_TOKEN — so nobody types this token, and a short-lived one costs nothing. Locally the
+ * token stays on disk, because several editor sessions have to find the same relay.
+ */
+const hostedRelay = httpMode
+  ? new WalletRelay({ token: process.env.WALLET_TOKEN, publicUrl: process.env.MCP_PUBLIC_URL })
+  : undefined
+
+const wallet = getWalletClient(hostedRelay ? { port: httpPort, token: hostedRelay.token } : undefined)
+
+// Hosted, the relay is attached to the HTTP server, so connect only once that is listening.
 const walletReady = httpMode
   ? Promise.resolve()
   : wallet.connect().catch((error) => {
-      console.error("[MCP] Wallet relay unavailable:", error.message);
-      console.error("[MCP] Transaction signing features will not be available");
-    });
+      console.error('[MCP] Wallet relay unavailable:', error.message)
+      console.error('[MCP] Transaction signing features will not be available')
+    })
 
 // The wallet relay's listening socket keeps the event loop alive, so this process would
 // outlive the client that spawned it and go on holding its port. Leave when the client does.
-let shuttingDown = false;
+let shuttingDown = false
 async function shutdown(reason: string) {
-  if (shuttingDown) return;
-  shuttingDown = true;
-  console.error(`[MCP] Shutting down (${reason})`);
-  await wallet.stop().catch(() => {});
-  process.exit(0);
+  if (shuttingDown) return
+  shuttingDown = true
+  console.error(`[MCP] Shutting down (${reason})`)
+  await wallet.stop().catch(() => {})
+  process.exit(0)
 }
 
-process.stdin.on("end", () => shutdown("client disconnected"));
-process.stdin.on("close", () => shutdown("client disconnected"));
-process.on("SIGTERM", () => shutdown("SIGTERM"));
-process.on("SIGINT", () => shutdown("SIGINT"));
+process.stdin.on('end', () => shutdown('client disconnected'))
+process.stdin.on('close', () => shutdown('client disconnected'))
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))
 
 // Start server
 async function main() {
   if (httpMode) {
-    const { url } = await startHttpServer({ createMcpServer });
-    console.error(`Web3 Tools MCP Server listening on ${url}`);
+    const { url, walletUrl } = await startHttpServer({ createMcpServer, walletRelay: hostedRelay })
+    console.error(`Web3 Tools MCP Server listening on ${url}`)
+
+    // Join the relay now that it is listening, so browser signing is available here too.
+    await wallet.connect().catch((error) => {
+      console.error('[MCP] Could not join the wallet relay:', error.message)
+    })
+    if (walletUrl) console.error(`Wallet interface available at ${walletUrl}`)
+
     if (!config.walletConnectProjectId) {
-      console.error("[MCP] No WalletConnect project id — a hosted server has no way to sign transactions");
+      console.error('[MCP] No WalletConnect project id — phone signing is unavailable on this server')
     }
-    return;
+    return
   }
 
-  const transport = new StdioServerTransport();
-  await createMcpServer().connect(transport);
-  console.error("Web3 Tools MCP Server running on stdio");
+  const transport = new StdioServerTransport()
+  await createMcpServer().connect(transport)
+  console.error('Web3 Tools MCP Server running on stdio')
   // The relay may still be picking a free port, and its URL carries the pairing token.
-  await walletReady;
-  console.error(`Wallet interface available at ${wallet.getUrl()}`);
+  await walletReady
+  console.error(`Wallet interface available at ${wallet.getUrl()}`)
 }
 
 main().catch((error) => {
-  console.error("Fatal error:", error);
-  process.exit(1);
-});
+  console.error('Fatal error:', error)
+  process.exit(1)
+})

package/src/oauth.ts

@@ -0,0 +1,270 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js'
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js'
+import type { AuthorizationParams, OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js'
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'
+import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js'
+import type { Response } from 'express'
+import { getKeyValueStorage, type KeyValueStorage } from './kv-storage.js'
+
+/**
+ * OAuth for clients that will not send a static bearer token — claude.ai connectors, and
+ * so anything driving them from a browser or phone, only speak the OAuth flow the MCP spec
+ * defines.
+ *
+ * There are no user accounts here: the single credential is MCP_TOKEN, the same one this
+ * server already requires. The authorize step is a one-field page that asks for it, so a
+ * self-hoster needs no identity provider and no extra configuration.
+ */
+
+const CODE_TTL = 10 * 60 * 1000
+const TOKEN_TTL = 30 * 24 * 60 * 60
+
+interface StoredCode {
+  clientId: string
+  codeChallenge: string
+  redirectUri: string
+  resource?: string
+  scopes: string[]
+  expiresAt: number
+}
+
+interface StoredToken {
+  clientId: string
+  scopes: string[]
+  expiresAt: number
+}
+
+/** Redis where configured, a JSON file otherwise — issued tokens must outlive a restart. */
+class Store {
+  private redis: KeyValueStorage | undefined
+  private file: string
+  private cache: Record<string, unknown> | undefined
+
+  constructor() {
+    this.redis = getKeyValueStorage()
+    const dir = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'web3-tools-mcp')
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    this.file = join(dir, 'oauth.json')
+  }
+
+  private read(): Record<string, unknown> {
+    if (!this.cache) {
+      try {
+        this.cache = JSON.parse(readFileSync(this.file, 'utf8'))
+      } catch {
+        this.cache = {}
+      }
+    }
+    return this.cache as Record<string, unknown>
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    if (this.redis) return this.redis.getItem<T>(`oauth:${key}`)
+    return this.read()[key] as T | undefined
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    if (this.redis) return this.redis.setItem(`oauth:${key}`, value)
+    const data = this.read()
+    data[key] = value
+    writeFileSync(this.file, JSON.stringify(data), { mode: 0o600 })
+  }
+
+  async remove(key: string): Promise<void> {
+    if (this.redis) return this.redis.removeItem(`oauth:${key}`)
+    const data = this.read()
+    delete data[key]
+    writeFileSync(this.file, JSON.stringify(data), { mode: 0o600 })
+  }
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string)
+}
+
+function constantTimeEquals(a: string, b: string): boolean {
+  const left = Buffer.from(a)
+  const right = Buffer.from(b)
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+function loginPage(params: { error?: string; fields: Record<string, string> }): string {
+  // The SDK's authorize handler reads its parameters from the body on POST, so the form
+  // has to carry the whole authorization request back, not just the token.
+  const hidden = Object.entries(params.fields)
+    .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+    .join('\n  ')
+
+  return `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect to web3-tools-mcp</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 26rem;
+         margin: 12vh auto; padding: 0 1.25rem; }
+  h1 { font-size: 1.15rem; margin-bottom: .25rem; }
+  p { color: #667; margin-top: 0; }
+  input, button { font: inherit; width: 100%; padding: .7rem .8rem; border-radius: .5rem;
+                  box-sizing: border-box; }
+  input { border: 1px solid #ccd; font-family: ui-monospace, monospace; }
+  button { margin-top: .75rem; border: 0; background: #3856d6; color: #fff; font-weight: 600; }
+  .error { color: #b3251d; font-weight: 600; }
+</style>
+<h1>Connect to web3-tools-mcp</h1>
+<p>Paste this server's access token to authorise the client.</p>
+${params.error ? `<p class="error">${params.error}</p>` : ''}
+<form method="post">
+  ${hidden}
+  <input name="token" type="password" placeholder="MCP_TOKEN" autocomplete="off" autofocus>
+  <button type="submit">Authorise</button>
+</form>`
+}
+
+export class SingleUserOAuthProvider implements OAuthServerProvider {
+  private store = new Store()
+
+  constructor(private accessToken: string) {}
+
+  get clientsStore(): OAuthRegisteredClientsStore {
+    const store = this.store
+    return {
+      async getClient(clientId) {
+        return store.get<OAuthClientInformationFull>(`client:${clientId}`)
+      },
+      // Registration is open because MCP clients register themselves before anyone can
+      // log in; holding MCP_TOKEN is what actually grants access.
+      async registerClient(client) {
+        const registered: OAuthClientInformationFull = {
+          ...client,
+          client_id: randomBytes(16).toString('hex'),
+          client_id_issued_at: Math.floor(Date.now() / 1000)
+        }
+        await store.set(`client:${registered.client_id}`, registered)
+        return registered
+      }
+    }
+  }
+
+  /**
+   * GET renders the token prompt; POST checks it and redirects back with a code. Handling
+   * both here keeps the whole login inside the SDK's authorize route.
+   */
+  async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void> {
+    const request = res.req
+    const submitted = (request.body as { token?: string } | undefined)?.token ?? ''
+
+    // Everything except the token itself is replayed into the form, so the handler sees a
+    // complete authorization request when the form posts back.
+    const fields = Object.fromEntries(
+      Object.entries({ ...(request.query as Record<string, string>), ...(request.body as Record<string, string>) }).filter(
+        ([name, value]) => name !== 'token' && typeof value === 'string'
+      )
+    ) as Record<string, string>
+
+    if (request.method !== 'POST') {
+      res.setHeader('content-type', 'text/html; charset=utf-8').send(loginPage({ fields }))
+      return
+    }
+
+    if (!constantTimeEquals(submitted, this.accessToken)) {
+      res
+        .status(401)
+        .setHeader('content-type', 'text/html; charset=utf-8')
+        .send(loginPage({ fields, error: 'That token was not accepted.' }))
+      return
+    }
+
+    const code = randomBytes(24).toString('hex')
+    await this.store.set<StoredCode>(`code:${code}`, {
+      clientId: client.client_id,
+      codeChallenge: params.codeChallenge,
+      redirectUri: params.redirectUri,
+      resource: params.resource?.href,
+      scopes: params.scopes ?? [],
+      expiresAt: Date.now() + CODE_TTL
+    })
+
+    const redirect = new URL(params.redirectUri)
+    redirect.searchParams.set('code', code)
+    if (params.state) redirect.searchParams.set('state', params.state)
+    res.redirect(redirect.href)
+  }
+
+  async challengeForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+    const stored = await this.store.get<StoredCode>(`code:${authorizationCode}`)
+    if (!stored || stored.expiresAt < Date.now()) throw new Error('Authorization code is invalid or expired')
+    return stored.codeChallenge
+  }
+
+  async exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<OAuthTokens> {
+    const stored = await this.store.get<StoredCode>(`code:${authorizationCode}`)
+    if (!stored || stored.expiresAt < Date.now()) throw new Error('Authorization code is invalid or expired')
+    if (stored.clientId !== client.client_id) throw new Error('Authorization code was issued to a different client')
+
+    // One use only: a replayed code must not mint a second token.
+    await this.store.remove(`code:${authorizationCode}`)
+    return this.issue(client.client_id, stored.scopes)
+  }
+
+  async exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[]): Promise<OAuthTokens> {
+    const stored = await this.store.get<StoredToken>(`refresh:${refreshToken}`)
+    if (!stored) throw new Error('Refresh token is invalid')
+    if (stored.clientId !== client.client_id) throw new Error('Refresh token was issued to a different client')
+
+    await this.store.remove(`refresh:${refreshToken}`)
+    return this.issue(client.client_id, scopes ?? stored.scopes)
+  }
+
+  private async issue(clientId: string, scopes: string[]): Promise<OAuthTokens> {
+    const accessToken = randomBytes(32).toString('hex')
+    const refreshToken = randomBytes(32).toString('hex')
+    const expiresAt = Math.floor(Date.now() / 1000) + TOKEN_TTL
+
+    await this.store.set<StoredToken>(`token:${accessToken}`, { clientId, scopes, expiresAt })
+    await this.store.set<StoredToken>(`refresh:${refreshToken}`, { clientId, scopes, expiresAt })
+
+    return {
+      access_token: accessToken,
+      token_type: 'Bearer',
+      expires_in: TOKEN_TTL,
+      refresh_token: refreshToken,
+      scope: scopes.join(' ')
+    }
+  }
+
+  /** Accepts an issued token, or MCP_TOKEN itself so a client that can send a header still works. */
+  async verifyAccessToken(token: string): Promise<AuthInfo> {
+    if (constantTimeEquals(token, this.accessToken)) {
+      // requireBearerAuth refuses a token with no expiry, and this one never expires.
+      return { token, clientId: 'static', scopes: [], expiresAt: Math.floor(Date.now() / 1000) + TOKEN_TTL }
+    }
+
+    // Must be InvalidTokenError specifically: the SDK turns anything else into a 500, and
+    // a client needs the 401 to know it should authenticate again.
+    const stored = await this.store.get<StoredToken>(`token:${token}`)
+    if (!stored) throw new InvalidTokenError('Invalid access token')
+    if (stored.expiresAt * 1000 < Date.now()) {
+      await this.store.remove(`token:${token}`)
+      throw new InvalidTokenError('Access token has expired')
+    }
+
+    return { token, clientId: stored.clientId, scopes: stored.scopes, expiresAt: stored.expiresAt }
+  }
+
+  async revokeToken(_client: OAuthClientInformationFull, request: { token: string }): Promise<void> {
+    await this.store.remove(`token:${request.token}`)
+    await this.store.remove(`refresh:${request.token}`)
+  }
+}
+
+/** PKCE helper, used by the tests to drive the flow the way a real client would. */
+export function pkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString('base64url')
+  const challenge = createHash('sha256').update(verifier).digest('base64url')
+  return { verifier, challenge }
+}

package/src/preview.ts

@@ -1,17 +1,8 @@
-import {
-  type Abi,
-  type AbiFunction,
-  type Address,
-  decodeFunctionData,
-  formatEther,
-  formatUnits,
-  parseAbiItem,
-  toFunctionSelector
-} from 'viem'
+import { type AbiFunction, type Address, decodeFunctionData, formatEther, formatUnits, toFunctionSelector } from 'viem'
 import { simulateBlocks } from 'viem/actions'
-import { getClientManager } from './client.js'
 import { addressLabel, loadAbi, tokenMeta, UNLIMITED_THRESHOLD } from './chain-meta.js'
 import { lookupContract, protocolLabel, resolveClearSigning } from './clear-signing.js'
+import { getClientManager } from './client.js'
 import type { ChainName } from './types.js'
 
 export interface PreviewField {
@@ -266,7 +257,7 @@ export async function buildTxPreview(chain: ChainName, tx: RawTx, from?: string)
     chain,
     to: tx.to,
     toLabel,
-    explorer: `https://${getClientManager().getEtherscanDomain(chain)}`,
+    explorer: getClientManager().explorerUrl(chain),
     value,
     valueFormatted: value && value !== '0' ? formatEther(BigInt(value)) : undefined,
     decoded,