feat(mcp): Sprint B — on-chain tools (submit_pr) — GHB-187

CLAUDE.md

@@ -49,3 +49,16 @@ This is a **pnpm workspace**, not npm. Use `pnpm` and `pnpm --filter @ghbounty/<
 ## Linear issues
 
 Issues are tracked in Linear. The repo branch naming convention is `<github-handle>/<issue-slug>` (e.g. `gastonfoncea09/ghb-188-mcp-frontend-onboarding`). Commit messages should reference the Linear issue (`— GHB-188`).
+
+### Linear-tracked work always goes on its own branch
+
+**Never commit directly to `main`** (or any base branch) when implementing a Linear issue. This applies to **everything** tied to the issue: spec docs, implementation plans, code, migrations, tests, runbooks. All of it lives on the feature branch and reaches `main` only via a merged PR.
+
+Workflow when starting a Linear issue:
+
+1. Move the Linear issue to **In Progress** (and re-assign to yourself if needed).
+2. Create the feature branch using the Linear-provided `gitBranchName` (Linear shows it on the issue page). `git checkout -b <branch>`.
+3. All commits for the issue go on that branch — including the spec/plan docs in `docs/superpowers/`.
+4. Open a PR when ready. Merge only after review + CI green.
+
+The only commits that may land on `main` directly are repo-wide chores not tied to a Linear issue (workflow docs, root README typos, etc.) — and even then, prefer a branch + PR when in doubt.

apps/mcp/lib/errors.ts

@@ -14,6 +14,7 @@ export type McpErrorCode =
   | "NotFound"
   | "Conflict"
   | "RpcError"
+  | "ServiceUnavailable"
   | "InternalError"
   | "InvalidInput";
 

apps/mcp/lib/gas-station/server.ts

@@ -0,0 +1,62 @@
+/**
+ * Server-side SolanaGasStation singleton for the MCP app.
+ *
+ * Rather than going through the frontend's HTTP endpoint at
+ * /api/gas-station/sponsor, the MCP app uses the SolanaGasStation class
+ * directly — no extra network hop, no service-to-service auth token needed,
+ * and full control over error handling.
+ *
+ * Wired in GHB-187 (submissions.create / submit_pr).
+ */
+
+import { Connection } from "@solana/web3.js";
+import {
+  SolanaGasStation,
+  GasStationError,
+  loadGasStationKeypair,
+  makeConnectionRpcSubmitter,
+} from "@ghbounty/shared";
+import type { ChainId } from "@ghbounty/shared";
+
+let cached: SolanaGasStation | null = null;
+
+function get(): SolanaGasStation {
+  if (cached) return cached;
+
+  const rpcUrl = process.env.SOLANA_RPC_URL;
+  if (!rpcUrl) throw new Error("SOLANA_RPC_URL must be set");
+
+  const chainId = (process.env.CHAIN_ID ?? "solana-devnet") as ChainId;
+
+  cached = new SolanaGasStation({
+    chainId,
+    keypair: loadGasStationKeypair(),
+    rpc: makeConnectionRpcSubmitter(new Connection(rpcUrl, "confirmed")),
+  });
+  return cached;
+}
+
+export async function submitSponsoredTx(
+  signedTxBytes: Uint8Array
+): Promise<{ ok: true; signature: string } | { ok: false; reason: string }> {
+  const gasStation = get();
+  const chainId = (process.env.CHAIN_ID ?? "solana-devnet") as ChainId;
+  try {
+    const result = await gasStation.sponsor({
+      chainId,
+      payload: {
+        kind: "solana",
+        partiallySignedTxB64: Buffer.from(signedTxBytes).toString("base64"),
+      },
+    });
+    return { ok: true, signature: result.txHash };
+  } catch (err: unknown) {
+    // Return only safe, structured codes — never raw error messages that may
+    // contain internal details (pubkeys, discriminator codes, RPC responses).
+    const reason =
+      err instanceof GasStationError
+        ? err.code // "validator_rejected" | "rpc_error" | "unsupported_chain" — safe
+        : "unexpected_error";
+    return { ok: false, reason };
+  }
+}