web3-tools-mcp 2.0.2 → 3.1.0

package/src/http-server.ts

@@ -1,9 +1,11 @@
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js'
+import type { OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js'
 import { getOAuthProtectedResourceMetadataUrl, mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
-import express from 'express'
+import express, { type Express } from 'express'
 import type { WalletRelay } from 'web3-wallet-relay'
+import { HOSTED } from './hosted.js'
 import { SingleUserOAuthProvider } from './oauth.js'
 
 /**
@@ -31,24 +33,50 @@ export interface HttpServerOptions {
   /** Serve the signing page on this same server, so browser signing works when hosted. */
   walletRelay?: WalletRelay
   createMcpServer: () => McpServer
+  /**
+   * Who may connect, and as whom.
+   *
+   * The default authenticates the deployment rather than a person: one token, shared. A
+   * host serving several people supplies its own — logging them in however it likes, and
+   * putting the identity in the issued token's `extra`, which is where the tools read it
+   * from. `MCP_TOKEN` is then no longer required.
+   */
+  provider?: OAuthServerProvider
+  /** A host's own routes, mounted before the signing page claims whatever is left at the root. */
+  routes?: (app: Express) => void
 }
 
 export async function startHttpServer(options: HttpServerOptions): Promise<{ url: string; port: number; walletUrl?: string }> {
-  const port = options.port ?? Number(process.env.MCP_HTTP_PORT) ?? DEFAULT_PORT
+  // The guards a shared host needs — no `localhost` chain, no loopback tracing node, no
+  // browser opened on the server — were decided when the package loaded, and cannot be
+  // switched on from here.
+  if (!HOSTED) {
+    throw new Error(
+      'Serving over HTTP needs MCP_HOSTED=1 (or MCP_HTTP_PORT) in the environment before web3-tools-mcp is imported'
+    )
+  }
+
+  const port = options.port ?? (Number(process.env.MCP_HTTP_PORT) || DEFAULT_PORT)
   const host = options.host ?? process.env.MCP_HTTP_HOST ?? '0.0.0.0'
   const token = options.token ?? process.env.MCP_TOKEN
 
   // A reachable MCP server with a paired phone can push signing prompts at that phone. It
-  // never runs without a token.
-  if (!token) {
+  // never runs unauthenticated — either a host brought its own way to log people in, or
+  // there is a token.
+  if (!options.provider && !token) {
     throw new Error('MCP_TOKEN is required to serve MCP over HTTP — anyone reaching the URL could request signatures')
   }
 
   const publicUrl = options.publicUrl ?? process.env.MCP_PUBLIC_URL ?? `http://localhost:${port}`
   const issuer = new URL(publicUrl)
-  const provider = new SingleUserOAuthProvider(token)
+  const provider = options.provider ?? new SingleUserOAuthProvider(token as string)
 
   const app = express()
+  // The auth routes rate-limit per req.ip, which behind a platform proxy is the proxy's own
+  // address — every caller would share one bucket. Only trust as many hops as are really
+  // in front, or anyone could pick their own bucket with a forged X-Forwarded-For.
+  const proxyHops = Number(process.env.MCP_TRUST_PROXY)
+  if (proxyHops) app.set('trust proxy', proxyHops)
   app.use(express.json())
   // The login form posts a token, so the authorize route needs form bodies too.
   app.use(express.urlencoded({ extended: false }))
@@ -78,6 +106,8 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
     resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(new URL('/mcp', issuer))
   })
 
+  options.routes?.(app)
+
   app.all('/mcp', authenticate, async (req, res) => {
     const mcp = options.createMcpServer()
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
@@ -99,8 +129,8 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
   })
 
   const server = await new Promise<ReturnType<typeof app.listen>>((resolve, reject) => {
-    const listening = app.listen(port, host, () => resolve(listening))
-    listening.once('error', reject)
+    // Express 5 hands a listen error to this callback rather than leaving it to 'error'.
+    const listening = app.listen(port, host, (error?: Error) => (error ? reject(error) : resolve(listening)))
   })
 
   // The signing page rides on this same server, so a hosted deployment can offer browser
@@ -110,7 +140,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
   let walletUrl: string | undefined
   if (options.walletRelay) {
     options.walletRelay.attach(server, (relayApp) => app.use(relayApp))
-    walletUrl = `${publicUrl.replace(/\/$/, '')}/#t=${options.walletRelay.token}`
+    walletUrl = `${publicUrl.replace(/\/$/, '')}/#t=${options.walletRelay.signerToken}`
   }
 
   return { url: `${publicUrl.replace(/\/$/, '')}/mcp`, port: (server.address() as { port: number }).port, walletUrl }

package/src/index.ts

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
-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 { DEFAULT_IDENTITY } from './context.js'
 import { startHttpServer } from './http-server.js'
 import { attachLogServer } from './log.js'
-import { registerAllTools } from './tools/index.js'
+import { createMcpServer } from './mcp-server.js'
 import { parseCommandLineArgs } from './utils.js'
-import { getWalletClient } from './wallet-client.js'
+import { allWalletClients, configureWalletRelay, getWalletClient } from './wallet-client.js'
 
 // Parse configuration
 const config = parseCommandLineArgs()
@@ -42,12 +42,17 @@ ENVIRONMENT VARIABLES:
   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_HTTP_HOST                 Interface the HTTP server binds to (default: 0.0.0.0)
+  MCP_TRUST_PROXY               Proxy hops in front of the server, e.g. 1 on Fly/Render
+  MCP_HOSTED                    Apply the hosted guards without the CLI (library use)
   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
+  WALLET_TOKEN                  Secret the wallet relay signs its room tokens with
+  ANVIL_RPC_URL                 Node exposing debug_traceCall (default: 127.0.0.1:8545)
+  ANVIL_ALLOW_RESET             Let tracing re-fork that node, clearing its state
 
 SUPPORTED CHAINS:
   ${SUPPORTED_CHAINS.join(', ')}
@@ -92,12 +97,6 @@ if (config.customRpcUrls) {
 // Initialize client manager
 initializeClientManager(config)
 
-function createMcpServer() {
-  const server = new McpServer({ name: 'web3-tools-mcp', version: packageJson.version }, { capabilities: { logging: {} } })
-  registerAllTools(server)
-  return server
-}
-
 const httpMode = Boolean(process.env.MCP_HTTP_PORT)
 const httpPort = Number(process.env.MCP_HTTP_PORT)
 
@@ -114,7 +113,13 @@ 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 this process's own, on the platform's port. Set before any client
+// is made, so every identity's client reaches that one rather than starting its own.
+if (hostedRelay) configureWalletRelay({ port: httpPort, token: hostedRelay.token })
+
+// Outside any tool call, so this is the shared identity — the only one a self-hosted
+// server ever has, and the one a hosted server uses before anybody has authenticated.
+const wallet = getWalletClient(DEFAULT_IDENTITY)
 
 // Hosted, the relay is attached to the HTTP server, so connect only once that is listening.
 const walletReady = httpMode
@@ -131,7 +136,7 @@ async function shutdown(reason: string) {
   if (shuttingDown) return
   shuttingDown = true
   console.error(`[MCP] Shutting down (${reason})`)
-  await wallet.stop().catch(() => {})
+  await Promise.all(allWalletClients().map((client) => client.stop().catch(() => {})))
   process.exit(0)
 }
 
@@ -150,7 +155,9 @@ async function main() {
     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}`)
+    // Without its #t= token: platform logs are read by more people than may sign. The full
+    // link comes from wallet_status, which already requires MCP_TOKEN.
+    if (walletUrl) console.error(`Wallet interface available at ${walletUrl.split('#')[0]} (link with token via wallet_status)`)
 
     if (!config.walletConnectProjectId) {
       console.error('[MCP] No WalletConnect project id — phone signing is unavailable on this server')

package/src/kv-storage.ts

@@ -15,7 +15,8 @@ export interface KeyValueStorage {
   getKeys(): Promise<string[]>
   getEntries<T = unknown>(): Promise<[string, T][]>
   getItem<T = unknown>(key: string): Promise<T | undefined>
-  setItem<T = unknown>(key: string, value: T): Promise<void>
+  /** `ttl` (seconds) expires just this field, where the backend can. */
+  setItem<T = unknown>(key: string, value: T, ttl?: number): Promise<void>
   removeItem(key: string): Promise<void>
 }
 
@@ -30,7 +31,8 @@ class RedisKeyValueStorage implements KeyValueStorage {
     const response = await fetch(this.url, {
       method: 'POST',
       headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' },
-      body: JSON.stringify(parts)
+      body: JSON.stringify(parts),
+      signal: AbortSignal.timeout(5000)
     })
 
     if (!response.ok) {
@@ -62,8 +64,9 @@ class RedisKeyValueStorage implements KeyValueStorage {
     return value == null ? undefined : (JSON.parse(value) as T)
   }
 
-  async setItem<T = unknown>(key: string, value: T): Promise<void> {
+  async setItem<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
     await this.command('HSET', HASH_KEY, key, JSON.stringify(value))
+    if (ttl) await this.command('HEXPIRE', HASH_KEY, Math.ceil(ttl), 'FIELDS', 1, key)
   }
 
   async removeItem(key: string): Promise<void> {

package/src/lib.ts

@@ -0,0 +1,24 @@
+/**
+ * What this package offers a host that serves it to other people.
+ *
+ * The CLI at `index.ts` is a program: importing it parses argv, starts a relay and runs a
+ * server. This is the library half — nothing here has an effect until it is called, so a
+ * deployment can assemble its own server with its own way of deciding who may do what.
+ *
+ * The split in what each side owns is deliberate. This package knows how to talk to chains
+ * and wallets and how to keep one person's signing away from another's; it holds no opinion
+ * about who anybody is, what they are allowed, or what it costs. Those are policy, and they
+ * belong to whatever is doing the serving.
+ */
+
+export { initializeClientManager, SUPPORTED_CHAINS } from './client.js'
+export { DEFAULT_IDENTITY, identityFrom } from './context.js'
+export { type HttpServerOptions, startHttpServer } from './http-server.js'
+export { attachLogServer, log } from './log.js'
+export { createMcpServer } from './mcp-server.js'
+export { type Login, OAuthProvider, SingleUserOAuthProvider, tokenLogin } from './oauth.js'
+export { registerAllTools, type ToolGroup, type ToolMiddleware, toolGroup } from './tools/index.js'
+export type { ChainName, Config, ToolResult } from './types.js'
+export { parseCommandLineArgs } from './utils.js'
+export { allWalletClients, configureWalletRelay, getWalletClient, WalletClient } from './wallet-client.js'
+export { getPhoneSigner, PhoneSigner, qrSvg } from './walletconnect.js'

package/src/mcp-server.ts

@@ -0,0 +1,47 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import packageJson from '../package.json' with { type: 'json' }
+import { registerAllTools, type ToolMiddleware } from './tools/index.js'
+
+/**
+ * A server with every tool registered, ready to be connected to a transport.
+ *
+ * Exists so a host does not have to construct one itself. Reaching for the MCP SDK from
+ * outside would mean a second copy of it, and two copies of the same class are two
+ * unrelated types as far as a compiler is concerned — the error arrives at the seam rather
+ * than where the mistake was made.
+ */
+/**
+ * What a client shows for this server, when it has somewhere to fetch it from.
+ *
+ * Only when a public URL is known: the icon has to be same-origin with the MCP endpoint and
+ * fetchable without credentials, which is true of the signing page's own static files and
+ * not true of anything a stdio server could offer. A client that cannot resolve it falls
+ * back to a letter, which is what it already does.
+ */
+function identity() {
+  const publicUrl = process.env.MCP_PUBLIC_URL?.replace(/\/$/, '')
+  if (!publicUrl) return {}
+
+  return {
+    websiteUrl: publicUrl,
+    icons: [
+      { src: `${publicUrl}/icon.png`, mimeType: 'image/png', sizes: ['512x512'] },
+      { src: `${publicUrl}/icon.svg`, mimeType: 'image/svg+xml', sizes: ['any'] }
+    ]
+  }
+}
+
+export function createMcpServer(middleware?: ToolMiddleware): McpServer {
+  const server = new McpServer(
+    {
+      name: 'web3-tools-mcp',
+      version: packageJson.version,
+      title: 'Web3 Tools',
+      description: packageJson.description,
+      ...identity()
+    },
+    { capabilities: { logging: {} } }
+  )
+  registerAllTools(server, middleware)
+  return server
+}