[nathanliow]

Stacked on #182. Base is nathan(helius-mcp)/add-request-context; GitHub retargets this to main once that merges. Review #182 first — the diff shown here is only this change.

Converts every tool handler that resolves credentials to pass the per-request context #182 added. 72 handlers across 20 files; zk-compression.ts alone accounts for 23.

Behaviour is unchanged: contextFromExtra returns null under stdio and the resolvers fall back to module state exactly as before. This is the migrate step of expand → migrate → contract; the globals come out two PRs from now.

The plan for this PR was wrong twice, in ways worth knowing

It said extra was already in scope. It is passed — action-handlers.ts:172 has handed it to every handler as the second argument since the router landed — but no handler declared the parameter, so nothing could read it. Each site therefore takes two edits rather than a one-token substitution:

-    async ({ address, hash }) => {
-      if (!hasApiKey()) return noApiKeyResponse();
+    async ({ address, hash }, extra) => {
+      const ctx = contextFromExtra(extra);
+      if (!hasApiKey(ctx)) return noApiKeyResponse();

It deferred accounts.ts and transactions.ts as module-level helpers. All fourteen of their call sites are direct in-handler calls of exactly the shape above, so they are migrated here.

A bug this introduced, and the guard that now prevents it

Eight handlers registered with {} as their schema were first written async (extra) => .... Both the SDK and ActionHandlerCollector invoke handlers as handler(args, extra), so that single parameter bound to args and the context was silently dropped.

Nothing caught it. TypeScript accepts a 1-arity function where a 2-arity signature is expected, contextFromExtra takes unknown, and this suite mocks the resolvers — so a handler that never receives a context still produces correct output. Against the real dispatch path, getEnhancedWebSocketInfo returned the machine's own on-disk key while a caller key was supplied. getAllWebhooks is the sharpest case: hosted, it would have listed the deployment's webhooks rather than the caller's.

tests/router-action-handlers.test.ts now asserts that every handler binding a context declares at least two parameters. Arity is the only observable signal here, and the assertion catches the class rather than the eight instances. Negative-tested — reverting getAllWebhooks alone fails with getAllWebhooks (arity 1), naming the tool.

Two signature adjustments

Resolvers accept RequestContext | null. contextFromExtra returns null for "this request carries no identity", which is meaningful rather than absent. Widening beats making 72 call sites write ?? undefined.

restRequest takes the context second, ahead of RequestInit. With options last the single call site read restRequest(url, undefined, ctx). Nothing passes options today, and restRequest is not in the package's public surface.

Deliberately not migrated

setHeliusApiKey (config.ts) stays context-free, with a comment saying why. It validates the key it was just handed via setApiKey; with a context the client it reads back would carry the caller's transport key instead, so the tool would report success for an invalid key. It is a mutator and never fitted this substitution.

config.ts:9 resolves at registration time, outside any request.

utils/ows.ts:82 — the one genuine deferral. getOwsSolanaAddress reads the network from module state inside a module-level helper, so staking.ts and transfers.ts are half-applied: the Helius client follows the caller's network while the OWS signer follows the server's. A devnet caller on a mainnet-default server therefore derives the wrong CAIP-2 account key through resolveOwsOrKeypairSigner. That is the next PR.

Verification

tsc --noEmit clean, pnpm validate passes, 340 tests green, no async (extra) remains in src/.

Two assertions in router-action-handlers.test.ts were updated: they asserted an exact argument list against a signature that gained a parameter, and now assert the null a context-free call actually passes.

The suite cannot see a context failing to arrive, so this was checked through the real callActionHandler path, against the {}-schema shape the first check never exercised:

getEnhancedWebSocketInfo
  with authInfo : wss://atlas-devnet.helius-rpc.com/?api-key=key-AAAA-1111
  no authInfo   : wss://atlas-mainnet.helius-rpc.com/?api-key=deployment-key-ZZZZ
getLaserstreamInfo
  with authInfo : https://laserstream-devnet-ewr.helius-rpc.com
  no authInfo   : https://laserstream-mainnet-ewr.helius-rpc.com

The caller's key and network both flow, and the no-context fallback is byte-identical to before — the two halves of "per-caller isolation works, stdio is unchanged" in one frame.

Reviewing this efficiently

The diff is large but has only four shapes: a handler signature gaining , extra; a const ctx = contextFromExtra(extra); line; a resolver call gaining (ctx); and one import per file. Anything that does not match one of those four is worth a second look — the arity bug and the setHeliusApiKey revert were both exactly that.

🤖 Generated with Claude Code

[0xIchigo]

The transaction is now submitted under the caller's key via getHeliusClient(ctx), but resolveOwsOrKeypairSigner still picks the signer based only on the HELIUS_MCP_SHARED_CREDENTIAL env flag. A per-request deployment that authenticates via authInfo without that flag, with a keypair on disk, signs every caller's send with the operator's wallet. The signer resolution needs to refuse the disk keypair whenever ctx is present, and not just when the env flag is set

[0xIchigo]

Further down on 215, hasApiKey(ctx) gates on the caller and then getJwt() reads the host's on-disk session and returns the operator's plan, credits, and project. The identity check and the data belong to different principals. The same shape is at auth.ts:340

We need to either thread a JWT through the context or refuse when ctx is present. Fixing the getAccountPlan label in #181 makes this consistent

[0xIchigo]

An omitted wallet still defaults to the host keypair's address even when a context is supplied. We should return missingParamError when ctx is present

[0xIchigo]

Splitting on the literal server.tool( and matching a single-quoted name means a double-quoted name or a renamed extra silently drops out of threading. A registration-time handler.length >= 2 check in ActionHandlerCollector.tool does the same job without parsing source

[0xIchigo]

new URL(...).pathname keeps percent-encoding. We should use fileURLToPath or a checkout under a path with a space fails with ENOENT

[0xIchigo]

LGTM