feat(helius-mcp): Add an Optional Per-Request Context

helius-mcp/src/tools/laserstream.ts

@@ -100,7 +100,7 @@ export function registerLaserstreamTools(server: McpServer) {
 
       try {
         const network = getNetwork();
-        const endpoint = getLaserstreamUrl(params.region as 'ewr' | 'pitt' | 'slc' | 'lax' | 'lon' | 'ams' | 'fra' | 'tyo' | 'sgp');
+        const endpoint = getLaserstreamUrl(undefined, params.region as 'ewr' | 'pitt' | 'slc' | 'lax' | 'lon' | 'ams' | 'fra' | 'tyo' | 'sgp');
         const sub: any = {};
 
         if (params.subscribeSlots) sub.slots = { filterByCommitment: params.filterByCommitment };

helius-mcp/src/utils/helius.ts

@@ -2,8 +2,9 @@ import { createHelius, type HeliusClient } from 'helius-sdk';
 import { MCP_USER_AGENT } from '../http.js';
 import { getSharedApiKey } from './config.js';
 import { wrapClientWithResilience, withResilience, READ_TIMEOUT_MS } from './resilience.js';
-import { registerSecret } from './redact.js';
+import { registerSecret, API_KEY_PLACEHOLDER } from './redact.js';
 import { isSharedCredentialMode } from './runtime.js';
+import type { RequestContext } from './request-context.js';
 
 let sessionApiKey: string | null = null;
 let sessionNetwork: 'mainnet-beta' | 'devnet' = 'mainnet-beta';
@@ -55,7 +56,20 @@ export function setApiKey(apiKey: string): void {
   heliusClient = null; // Reset client so it picks up new key
 }
 
-export function getApiKey(): string {
+export function getApiKey(ctx?: RequestContext): string {
+  // A supplied context answers alone. Falling through to the deployment's
+  // credential on an empty caller key would bill the operator for a request
+  // that failed to authenticate.
+  if (ctx) {
+    if (!ctx.apiKey) {
+      throw new Error('NO_API_KEY: the request carried a context with no Helius API key');
+    }
+    // Deliberately not registered as a secret: the scrubber exists to keep the
+    // deployment's credential out of tool output, and this key is the caller's
+    // own. Registering it would scrub it from their own responses.
+    return ctx.apiKey;
+  }
+
   const apiKey = sessionApiKey || process.env.HELIUS_API_KEY || getSharedApiKey();
   if (!apiKey) {
     throw new Error('NO_API_KEY: Set HELIUS_API_KEY environment variable or use setHeliusApiKey tool');
@@ -65,16 +79,36 @@ export function getApiKey(): string {
   return apiKey;
 }
 
-export function hasApiKey(): boolean {
+export function hasApiKey(ctx?: RequestContext): boolean {
+  if (ctx) {
+    return !!ctx.apiKey;
+  }
   return !!(sessionApiKey || process.env.HELIUS_API_KEY || getSharedApiKey());
 }
 
-export function getHeliusClient(): HeliusClient {
+export function getHeliusClient(ctx?: RequestContext): HeliusClient {
+  // A caller-supplied context gets its own client. Caching per key would be a
+  // cross-tenant hazard for no gain: construction measures ~0.012ms, far below
+  // the network call it wraps.
+  if (ctx) {
+    return wrapClientWithResilience(
+      createHelius({
+        apiKey: getApiKey(ctx),
+        network: getNetwork(ctx) === 'devnet' ? 'devnet' : 'mainnet',
+        userAgent: MCP_USER_AGENT,
+      }),
+    );
+  }
+
   if (!heliusClient) {
     const apiKey = getApiKey();
     // Wrap so idempotent reads get a timeout + retry-with-backoff; writes,
     // sends, and streaming pass through untouched. See utils/resilience.ts.
-    heliusClient = wrapClientWithResilience(createHelius({ apiKey, userAgent: MCP_USER_AGENT }));
+    heliusClient = wrapClientWithResilience(createHelius({
+      apiKey,
+      network: getNetwork() === 'devnet' ? 'devnet' : 'mainnet',
+      userAgent: MCP_USER_AGENT,
+    }));
   }
   return heliusClient;
 }
@@ -84,34 +118,47 @@ export function setNetwork(network: 'mainnet-beta' | 'devnet'): void {
   sessionNetwork = network;
 }
 
-export function getNetwork(): 'mainnet-beta' | 'devnet' {
+export function getNetwork(ctx?: RequestContext): 'mainnet-beta' | 'devnet' {
+  if (ctx?.network) {
+    return ctx.network;
+  }
+
   const envNetwork = process.env.HELIUS_NETWORK;
   if (envNetwork === 'devnet' || envNetwork === 'mainnet-beta') {
     return envNetwork;
   }
   return sessionNetwork;
 }
 
-export function getEnhancedWebSocketUrl(): string {
-  const network = getNetwork();
+export function getEnhancedWebSocketUrl(ctx?: RequestContext): string {
+  const network = getNetwork(ctx);
   const host = network === 'devnet'
     ? 'wss://atlas-devnet.helius-rpc.com'
     : 'wss://atlas-mainnet.helius-rpc.com';
 
-  // Under a shared server-side credential this URL is tool output that reaches
-  // the caller, so it gets a placeholder the caller substitutes with their own
-  // key. Single-tenant stdio still returns a ready-to-use URL.
+  // Shared-credential mode and a per-caller context are contradictory states:
+  // the first says every caller shares the deployment's key, the second says
+  // this caller brought their own. The placeholder wins where they collide,
+  // because the alternative is worse — every response passes through
+  // `redactSecrets`, whose query-string rule rewrites *any* `api-key=` value in
+  // this mode, so returning the caller's key here yields `***REDACTED***` at the
+  // caller. An unusable URL that says what to substitute beats one that does
+  // not. The two settings become orthogonal when hosted mode is split out, and
+  // a bring-your-own-key deployment will run with redaction off.
   if (isSharedCredentialMode()) {
-    return `${host}/?api-key=YOUR_HELIUS_API_KEY`;
+    return `${host}/?api-key=${API_KEY_PLACEHOLDER}`;
   }
 
-  return `${host}/?api-key=${getApiKey()}`;
+  return `${host}/?api-key=${getApiKey(ctx)}`;
 }
 
-export function getLaserstreamUrl(region?: 'ewr' | 'pitt' | 'slc' | 'lax' | 'lon' | 'ams' | 'fra' | 'tyo' | 'sgp'): string {
+export function getLaserstreamUrl(
+  ctx?: RequestContext,
+  region?: 'ewr' | 'pitt' | 'slc' | 'lax' | 'lon' | 'ams' | 'fra' | 'tyo' | 'sgp',
+): string {
   // Endpoint host is public; clients pass apiKey separately (e.g. @helius/laserstream subscribe options).
   // Do not call getApiKey() here or docs tools like getLaserstreamInfo fail unnecessarily.
-  const network = getNetwork();
+  const network = getNetwork(ctx);
   if (network === 'devnet') {
     return `https://laserstream-devnet-ewr.helius-rpc.com`;
   }
@@ -161,8 +208,12 @@ export async function loadSignerOrFail(): Promise<{ secretKey: Uint8Array; walle
   return { secretKey, walletAddress };
 }
 
-export async function restRequest(endpoint: string, options: RequestInit = {}): Promise<any> {
-  const apiKey = getApiKey();
+export async function restRequest(
+  endpoint: string,
+  options: RequestInit = {},
+  ctx?: RequestContext,
+): Promise<any> {
+  const apiKey = getApiKey(ctx);
   const separator = endpoint.includes('?') ? '&' : '?';
   const url = `https://api.helius.xyz${endpoint}${separator}api-key=${apiKey}`;
 

helius-mcp/src/utils/redact.ts

@@ -12,10 +12,22 @@ import { isSharedCredentialMode } from './runtime.js';
  */
 
 const REDACTED = '***REDACTED***';
+/** Substitution instruction returned in shared-credential mode; see helius.ts. */
+export const API_KEY_PLACEHOLDER = 'YOUR_HELIUS_API_KEY';
 
 /** Matches `api-key=<value>` in a query string, however the URL is delimited. */
 const API_KEY_QUERY_RE = /([?&]api-key=)[^&\s'"`)\]}<]+/gi;
 
+/**
+ * Unbounded and process-global. One stdio caller registers one key, so this is
+ * fine today; a deployment serving many callers accumulates one entry per
+ * distinct key forever, and `redactSecrets` scans the whole set on every
+ * response. There is no cap, no TTL and no eviction.
+ *
+ * Making this request-local belongs with the removal of the other credential
+ * globals, not here — capping it in isolation would silently stop scrubbing an
+ * evicted key, which is worse than the growth.
+ */
 const secrets = new Set<string>();
 
 /**
@@ -39,7 +51,13 @@ export function redactSecrets(text: string): string {
     return text;
   }
 
-  let out = text.replace(API_KEY_QUERY_RE, `$1${REDACTED}`);
+  // The placeholder is instruction, not a leak. Rewriting it to ***REDACTED***
+  // turns "substitute your own key here" into an opaque string, which is how
+  // the Enhanced WebSocket URL reached callers before this guard.
+  let out = text.replace(API_KEY_QUERY_RE, (match, prefix: string) =>
+    match.endsWith(API_KEY_PLACEHOLDER) || match.endsWith(REDACTED)
+      ? match
+      : `${prefix}${REDACTED}`);
   for (const secret of secrets) {
     // split/join rather than RegExp so key contents need no escaping.
     out = out.split(secret).join(REDACTED);

helius-mcp/src/utils/request-context.ts

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Per-request credential and network state.
+ *
+ * Everything the tool layer needs to act *as one caller*. The stdio build has a
+ * single caller for the life of the process, so it resolves this from module
+ * state; a hosted build has a different caller every request and resolves it
+ * from the request itself.
+ *
+ * This type is deliberately small: it carries what identifies and authorises a
+ * caller, not a grab-bag of request metadata. Anything that is the same for
+ * every caller — public docs, the action catalogue — stays shared.
+ *
+ * Lives in `utils/` rather than `router/` because `utils/helius.ts` consumes it
+ * and `utils/` never imports from `router/`.
+ */
+export type RequestContext = {
+  /** The caller's own Helius API key. Downstream calls bill this key. */
+  apiKey: string;
+  /** Helius project the key belongs to, when the transport can resolve it. */
+  projectId?: string;
+  /**
+   * Absent when the request did not state one. That is not the same as
+   * mainnet: a self-hosted server with `HELIUS_NETWORK=devnet` and a middleware
+   * that sets a token but no network must keep answering on devnet, so the
+   * resolver falls through to env and session rather than defaulting here.
+   */
+  network?: 'mainnet-beta' | 'devnet';
+  /**
+   * Opaque, stable per caller — not per request.
+   *
+   * It buckets `expandResult` handles. Per-request would break expansion
+   * immediately, since a handle is issued by one request and redeemed by the
+   * next; per-caller means a handle survives exactly as long as the caller does
+   * and is invisible to everyone else.
+   *
+   * Note this duplicates a responsibility `RouterContext` currently holds:
+   * `getRouterContext()` takes no argument and hands `dispatch.ts` a
+   * process-global session key. Nothing bridges the two yet, and nothing can
+   * until call sites start passing a context. The migration that converts them
+   * is where `getRouterContext` learns to derive from this field; until then
+   * this is the declared intent and `RouterContext` is the live implementation.
+   */
+  sessionKey: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Stable, non-reversible bucket id, so the raw key is not also a map key. */
+function deriveSessionKey(apiKey: string, projectId?: string): string {
+  return createHash('sha256')
+    .update(`${projectId ?? ''}:${apiKey}`)
+    .digest('hex')
+    .slice(0, 32);
+}
+
+/**
+ * Build a context from the SDK's per-request `extra`, or `null` when the request
+ * carries no identity.
+ *
+ * `null` is the stdio case and is not an error: callers fall back to the module
+ * state that has always answered for them. A hosted entrypoint is expected to
+ * reject an unidentified request before dispatch ever reaches here.
+ */
+export function contextFromExtra(extra: unknown): RequestContext | null {
+  if (!isRecord(extra)) {
+    return null;
+  }
+
+  const authInfo = extra.authInfo;
+  if (!isRecord(authInfo)) {
+    return null;
+  }
+
+  // `extra.apiKey` first: `token` is the transport credential, and reading it
+  // as the Helius key couples the two. Once a hosted entrypoint fronts this
+  // with real OAuth, every access token would be appended as `?api-key=` to a
+  // Helius host. `token` stays as a fallback for a transport that authenticates
+  // with the Helius key itself, which is the shape we expect first.
+  const rawExtra = isRecord(authInfo.extra) ? authInfo.extra : undefined;
+  const fromExtra = typeof rawExtra?.apiKey === 'string' ? rawExtra.apiKey : '';
+  const apiKey = fromExtra || (typeof authInfo.token === 'string' ? authInfo.token : '');
+  if (!apiKey) {
+    return null;
+  }
+
+  // Both of ours live under `extra`, which the SDK documents as the home for
+  // additional token data. Deliberately not `clientId`: that identifies the
+  // OAuth client application, and a Helius project is not one.
+  const authExtra = isRecord(authInfo.extra) ? authInfo.extra : undefined;
+
+  const rawProjectId = authExtra?.projectId;
+  const projectId = typeof rawProjectId === 'string' && rawProjectId ? rawProjectId : undefined;
+
+  // Unknown values are refused rather than coerced. `'Devnet'` or `'testnet'`
+  // silently routing a caller's writes to mainnet is not a safe default.
+  const rawNetwork = authExtra?.network;
+  let network: 'mainnet-beta' | 'devnet' | undefined;
+  if (rawNetwork !== undefined) {
+    if (rawNetwork !== 'devnet' && rawNetwork !== 'mainnet-beta') {
+      throw new Error(
+        `INVALID_NETWORK: request declared network "${String(rawNetwork)}"; `
+        + 'expected "mainnet-beta" or "devnet".',
+      );
+    }
+    network = rawNetwork;
+  }
+
+  return {
+    apiKey,
+    projectId,
+    network,
+    sessionKey: deriveSessionKey(apiKey, projectId),
+  };
+}