fix: harden MCP authorization and tool contracts

Author: ccbbccbb

README.md

@@ -1,7 +1,5 @@
 # MCP 2026-07-28 Upgrade
 
-Branch: `ccbbccbb/mcp-2026-07-28-upgrade`
-
 This repository targets the final MCP `2026-07-28` specification through the released TypeScript SDK v2 packages. The release-candidate compatibility adapter has been removed.
 
 ## Authoritative Sources
@@ -16,6 +14,7 @@ This repository targets the final MCP `2026-07-28` specification through the rel
 - Replaced `@modelcontextprotocol/sdk` v1 with:
   - `@modelcontextprotocol/server` v2
   - `@modelcontextprotocol/node` v2
+  - `@modelcontextprotocol/express` v2
   - Zod v4.2 or newer
 - Replaced the local JSON-RPC adapter with SDK-native `createMcpHandler` and `serveStdio`.
 - Kept stdio dual-era:
@@ -30,9 +29,28 @@ This repository targets the final MCP `2026-07-28` specification through the rel
   - `Mcp-Method`
   - `Mcp-Name`
 - Added Host and Origin validation before the HTTP MCP handler.
+- Added MCP OAuth resource-server support for HTTP:
+  - localhost can run without authorization
+  - non-local binds fail closed unless OAuth is configured
+  - authorization-server metadata discovery and RFC 7662 token introspection
+  - baseline `mcp`, wallet-write `evm:write`, and signing `evm:sign` scopes
 - Configured all static list capabilities with `listChanged: false`; resource subscriptions remain disabled.
-- Configured one-hour public cache hints for discovery, list operations, resource templates, and resource reads.
+- Configured one-hour public cache hints for discovery, static list operations, resource templates, and the public `evm://networks` resource. Unannotated future resources retain conservative cache defaults.
 - Migrated MCP-bound schemas to Zod 4 object schemas so the SDK emits JSON Schema 2020-12.
+- Added an `outputSchema` to all 25 tools. Every successful tool call returns equivalent JSON in both `structuredContent` and a pretty-printed text content block; bigint values are represented as decimal strings.
+- Added native MCP multi-round-trip confirmation to the six wallet-backed operations:
+  - `write_contract`
+  - `transfer_native`
+  - `transfer_erc20`
+  - `approve_token_spending`
+  - `sign_message`
+  - `sign_typed_data`
+- Integrity-protected confirmation continuation state with the SDK HMAC codec:
+  - binds the complete tool arguments and current HTTP bearer token
+  - expires after five minutes
+  - is consumed once per process before wallet access
+  - rejects tampering, argument changes, cross-token use, and replay
+- Bounded `wait_for_transaction` with `timeoutSeconds` from 1 through 90, defaulting to 90 seconds so it returns before the 120-second HTTP transport timeout.
 - Kept process diagnostics on `stderr`, including the npm CLI startup line, so stdio `stdout` contains protocol messages only.
 
 ## Final-Spec Differences from the RC
@@ -47,11 +65,35 @@ The repository no longer carries RC behavior for the following changes:
 
 ## Compatibility Decisions
 
-- HTTP remains strict `2026-07-28` to preserve the RC branch's modern-only deployment decision.
+- HTTP remains strict `2026-07-28` to preserve the existing modern-only deployment decision.
 - Stdio serves both modern and legacy clients because local hosts commonly require gradual negotiation.
 - The static tool, prompt, and resource surfaces do not advertise change notifications.
-- `wait_for_transaction` remains a normal synchronous tool. The Tasks extension is not advertised.
-- The server does not implement MCP OAuth. It uses environment-configured RPC and wallet credentials.
+- `wait_for_transaction` remains a bounded synchronous tool. The Tasks extension is not advertised because the released v2 SDK removed its experimental server runtime; the extension currently has no supported TypeScript runtime integration to adopt.
+- Wallet-backed operations are not executed until the client accepts the tool's MCP `input_required` confirmation. Prompts and server instructions do not request a second conversational confirmation.
+- OAuth is HTTP-only. Stdio continues to obtain wallet and RPC credentials from its environment.
+
+## HTTP OAuth Configuration
+
+The HTTP process acts as an OAuth resource server; it does not issue access tokens. With the default local `MCP_HOST=127.0.0.1`, omitting `MCP_OAUTH_ISSUER_URL` keeps OAuth disabled. Setting it enables OAuth locally. Binding to a non-local interface requires OAuth and aborts startup if the configuration is incomplete.
+
+Required when OAuth is enabled:
+
+- `MCP_OAUTH_ISSUER_URL`: exact HTTPS authorization-server issuer without a query or fragment
+- `MCP_PUBLIC_URL`: exact externally reachable MCP endpoint with the `/mcp` path and no query or fragment; non-local deployments require HTTPS
+- `MCP_OAUTH_CLIENT_ID`: RFC 7662 introspection client ID
+- `MCP_OAUTH_CLIENT_SECRET`: RFC 7662 introspection client secret
+
+Optional overrides:
+
+- `MCP_OAUTH_METADATA_URL`: authorization-server metadata URL; defaults to the RFC 8414 URL derived from the issuer, including correct well-known path insertion for issuers with a path
+- `MCP_OAUTH_INTROSPECTION_URL`: introspection endpoint when metadata does not publish `introspection_endpoint`
+- `MCP_OAUTH_AUDIENCE`: expected token audience/resource; defaults to `MCP_PUBLIC_URL`
+- `MCP_OAUTH_SCOPES`: additional advertised scopes; the minimal built-in `mcp` scope is always advertised
+- `MCP_OAUTH_REQUIRED_SCOPES`: additional scopes required for every MCP request; the baseline `mcp` scope is always required
+
+Introspection must return an active token with a client identity, expiration, the expected audience/resource, and appropriate scopes. In addition to the baseline scope, transaction and approval tools require `evm:write`; signing tools require `evm:sign`.
+
+Authorization-server metadata must support the authorization-code response type and PKCE `S256`. The issuer, metadata URL, and every authorization-server endpoint must use HTTPS. Metadata discovery and introspection reject redirects and use a 10-second deadline.
 
 ## Verification
 
@@ -60,9 +102,13 @@ The automated MCP integration tests cover:
 - final `server/discover` shape and server identity metadata
 - optional `clientInfo`
 - deterministic tool listing and closed no-argument schemas
+- output schemas and structured tool results
+- confirmation requests and declines for all six wallet-backed operations, plus shared-helper coverage for argument binding, tamper rejection, and single-use replay prevention
+- bounded transaction waiting
 - cache hints on discovery, list, and resource results
 - resource reads and a read-only tool call
 - final `HeaderMismatch` and `UnsupportedProtocolVersion` error codes
+- local authorization opt-out, remote fail-closed behavior, OAuth metadata validation, RFC 7662 introspection, audience checks, and scopes
 
 Release checks:
 
@@ -77,6 +123,5 @@ bun run build:http
 
 These are enhancements, not compliance blockers:
 
-- Add `outputSchema` and `structuredContent` to high-value read tools while preserving text content for older clients.
-- Adopt the Tasks extension only if transaction confirmation regularly exceeds practical request timeouts.
-- Add MCP OAuth before exposing wallet-backed write tools through a shared remote deployment.
+- Revisit the Tasks extension only after the official SDK provides a released server runtime for the final extension protocol.
+- Add deployment-specific rate limiting, audit logging, secret management, and authorization-server operational guidance before hosting a shared production endpoint.

bun.lock

@@ -1,9 +1,8 @@
 {
   "name": "@mcpdotdirect/evm-mcp-server",
-  "module": "src/index.ts",
   "type": "module",
   "version": "2.0.4",
-  "description": "MCP server for interacting with EVM-compatible blockchains - supports 25 tools and 10 prompts across 60+ networks",
+  "description": "MCP server with 25 tools and 10 prompts across 55 EVM chains",
   "bin": {
     "evm-mcp-server": "./bin/cli.js"
   },
@@ -29,7 +28,7 @@
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
     "changelog:latest": "conventional-changelog -p angular -r 1 > RELEASE_NOTES.md",
     "inspect": "npx @modelcontextprotocol/inspector node build/index.js",
-    "test:mcp": "bun test test/mcp-2026.test.ts"
+    "test:mcp": "bun test test/mcp-2026.test.ts test/auth.test.ts test/http-auth.test.ts"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -41,6 +40,7 @@
     "typescript": "^5.8.2"
   },
   "dependencies": {
+    "@modelcontextprotocol/express": "^2.0.0",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "express": "^5.2.1",

docs/mcp-2026-07-28-upgrade.md

@@ -61,7 +61,6 @@ import {
 } from 'viem/chains';
 
 // Default configuration values
-export const DEFAULT_RPC_URL = 'https://eth.llamarpc.com';
 export const DEFAULT_CHAIN_ID = 1;
 
 // Map chain IDs to chains
@@ -288,49 +287,34 @@ export const rpcUrlMap: Record<number, string> = {
  * @returns The resolved chain ID
  */
 export function resolveChainId(chainIdentifier: number | string): number {
-  if (typeof chainIdentifier === 'number') {
+  if (typeof chainIdentifier === 'string') {
+    const normalizedIdentifier = chainIdentifier.toLowerCase();
+    const namedChainId = networkNameMap[normalizedIdentifier];
+    if (namedChainId !== undefined) {
+      return namedChainId;
+    }
+
+    if (/^\d+$/.test(normalizedIdentifier)) {
+      const numericChainId = Number(normalizedIdentifier);
+      if (Number.isSafeInteger(numericChainId) && chainMap[numericChainId]) {
+        return numericChainId;
+      }
+    }
+  } else if (Number.isSafeInteger(chainIdentifier) && chainMap[chainIdentifier]) {
     return chainIdentifier;
   }
-  
-  // Convert to lowercase for case-insensitive matching
-  const networkName = chainIdentifier.toLowerCase();
-  
-  // Check if the network name is in our map
-  const chainId = networkNameMap[networkName];
-  if (chainId !== undefined) {
-    return chainId;
-  }
-  
-  // Try parsing as a number
-  const parsedId = parseInt(networkName);
-  if (!isNaN(parsedId)) {
-    return parsedId;
-  }
-  
-  // Default to mainnet if not found
-  return DEFAULT_CHAIN_ID;
+
+  throw new Error(`Unsupported network: ${chainIdentifier}`);
 }
 
 /**
  * Returns the chain configuration for the specified chain ID or network name
  * @param chainIdentifier Chain ID (number) or network name (string)
  * @returns The chain configuration
- * @throws Error if the network is not supported (when string is provided)
+ * @throws Error if the network or chain ID is not supported
  */
 export function getChain(chainIdentifier: number | string = DEFAULT_CHAIN_ID): Chain {
-  if (typeof chainIdentifier === 'string') {
-    const networkName = chainIdentifier.toLowerCase();
-    // Try to get from direct network name mapping first
-    if (networkNameMap[networkName]) {
-      return chainMap[networkNameMap[networkName]] || mainnet;
-    }
-    
-    // If not found, throw an error
-    throw new Error(`Unsupported network: ${chainIdentifier}`);
-  }
-  
-  // If it's a number, return the chain from chainMap
-  return chainMap[chainIdentifier] || mainnet;
+  return chainMap[resolveChainId(chainIdentifier)];
 }
 
 /**
@@ -339,19 +323,21 @@ export function getChain(chainIdentifier: number | string = DEFAULT_CHAIN_ID): C
  * @returns The RPC URL for the specified chain
  */
 export function getRpcUrl(chainIdentifier: number | string = DEFAULT_CHAIN_ID): string {
-  const chainId = typeof chainIdentifier === 'string' 
-    ? resolveChainId(chainIdentifier) 
-    : chainIdentifier;
-    
-  return rpcUrlMap[chainId] || DEFAULT_RPC_URL;
+  return rpcUrlMap[resolveChainId(chainIdentifier)];
 }
 
 /**
- * Get a list of supported networks
- * @returns Array of supported network names (excluding short aliases)
+ * Get the configured network names and aliases.
+ * @returns Array of supported network names and aliases
  */
 export function getSupportedNetworks(): string[] {
   return Object.keys(networkNameMap)
-    .filter(name => name.length > 2) // Filter out short aliases
     .sort();
-} 
+}
+
+/**
+ * Get the number of distinct configured chain IDs.
+ */
+export function getSupportedChainCount(): number {
+  return Object.keys(chainMap).length;
+}