@projectsolo/solo-mission-mcp 0.19.2 → 0.20.1

package/.env.example

@@ -1,2 +1,2 @@
 SOLO_AGENT_KEY=your-agent-api-key-here
-SOLO_MISSION_API_URL=https://api.mission.projectsolo.xyz
+SOLO_MISSION_API_URL=https://api.mission.projectsolo.ai

package/.github/workflows/release.yml

@@ -1,14 +1,21 @@
 name: Release
 
+# Tag prefix picks the runner: v1.2.3 runs on GitHub-hosted ubuntu-latest as
+# before; u1.2.3 runs the identical job on our self-hosted VPS runner
+# instead (registered with labels self-hosted,solo_mission_mcp-vps), to
+# avoid burning GitHub-hosted runner minutes. Same steps, same OIDC identity
+# for npm Trusted Publishing either way — the OIDC token is issued by
+# GitHub's Actions service to the job, not tied to which runner executes it.
 on:
   push:
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'u[0-9]+.[0-9]+.[0-9]+'
 
 jobs:
   publish:
     name: Build & Publish to npm
-    runs-on: ubuntu-latest
+    runs-on: ${{ startsWith(github.ref_name, 'u') && fromJSON('["self-hosted","solo_mission_mcp-vps"]') || 'ubuntu-latest' }}
     permissions:
       contents: read
       id-token: write
@@ -37,12 +44,15 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Check tool coverage against live API spec
+        run: npx tsx src/scripts/check-tools-against-spec.ts
+
       - name: Verify tag matches package.json version
         run: |
-          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          TAG_VERSION="${GITHUB_REF_NAME#[uv]}"
           PKG_VERSION="$(node -p "require('./package.json').version")"
           if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
-            echo "Tag v$TAG_VERSION does not match package.json version $PKG_VERSION"
+            echo "Tag $GITHUB_REF_NAME does not match package.json version $PKG_VERSION"
             exit 1
           fi
 

package/dist/chunk-NXOOPOSF.js

@@ -0,0 +1,79 @@
+// src/config.ts
+import "dotenv/config";
+var config = {
+  agentKey: process.env.SOLO_AGENT_KEY ?? "",
+  apiUrl: process.env.SOLO_MISSION_API_URL ?? "https://api.mission.projectsolo.ai"
+};
+if (!config.agentKey) {
+  console.warn("Warning: SOLO_AGENT_KEY is not set. Only register_agent will work until a key is configured.");
+}
+
+// src/api/client.ts
+var DEFAULT_HEADERS = {
+  "Content-Type": "application/json",
+  "X-Agent-Key": config.agentKey
+};
+var ApiResponseError = class extends Error {
+  status;
+  data;
+  constructor(status, data) {
+    const msg = data?.message || data?.error || `Request failed with status ${status}`;
+    super(status === 429 ? "Rate limit exceeded. Please slow down and retry after a moment." : msg);
+    this.status = status;
+    this.data = data;
+  }
+};
+async function parseErrorResponse(response) {
+  const data = await response.json().catch(() => ({}));
+  throw new ApiResponseError(response.status, data);
+}
+async function apiGet(path, params) {
+  const url = new URL(`${config.apiUrl}${path}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value != null) url.searchParams.set(key, String(value));
+    }
+  }
+  const response = await fetch(url.toString(), {
+    headers: DEFAULT_HEADERS,
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json();
+}
+async function apiPost(path, body) {
+  const response = await fetch(`${config.apiUrl}${path}`, {
+    method: "POST",
+    headers: DEFAULT_HEADERS,
+    body: body !== void 0 ? JSON.stringify(body) : void 0,
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json();
+}
+async function apiDelete(path) {
+  const response = await fetch(`${config.apiUrl}${path}`, {
+    method: "DELETE",
+    headers: DEFAULT_HEADERS,
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json();
+}
+async function publicApiPost(path, body) {
+  const response = await fetch(`${config.apiUrl}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: body !== void 0 ? JSON.stringify(body) : void 0,
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json();
+}
+
+export {
+  apiGet,
+  apiPost,
+  apiDelete,
+  publicApiPost
+};

package/dist/client-2NLDPRAH.js

@@ -0,0 +1,12 @@
+import {
+  apiDelete,
+  apiGet,
+  apiPost,
+  publicApiPost
+} from "./chunk-NXOOPOSF.js";
+export {
+  apiDelete,
+  apiGet,
+  apiPost,
+  publicApiPost
+};

package/dist/index.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import {
+  apiDelete,
+  apiGet,
+  apiPost,
+  publicApiPost
+} from "./chunk-NXOOPOSF.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -8,79 +14,6 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
-// src/config.ts
-import "dotenv/config";
-var config = {
-  agentKey: process.env.SOLO_AGENT_KEY ?? "",
-  apiUrl: process.env.SOLO_MISSION_API_URL ?? "https://api.mission.projectsolo.ai"
-};
-if (!config.agentKey) {
-  console.warn("Warning: SOLO_AGENT_KEY is not set. Only register_agent will work until a key is configured.");
-}
-
-// src/api/client.ts
-var DEFAULT_HEADERS = {
-  "Content-Type": "application/json",
-  "X-Agent-Key": config.agentKey
-};
-var ApiResponseError = class extends Error {
-  status;
-  data;
-  constructor(status, data) {
-    const msg = data?.message || data?.error || `Request failed with status ${status}`;
-    super(status === 429 ? "Rate limit exceeded. Please slow down and retry after a moment." : msg);
-    this.status = status;
-    this.data = data;
-  }
-};
-async function parseErrorResponse(response) {
-  const data = await response.json().catch(() => ({}));
-  throw new ApiResponseError(response.status, data);
-}
-async function apiGet(path, params) {
-  const url = new URL(`${config.apiUrl}${path}`);
-  if (params) {
-    for (const [key, value] of Object.entries(params)) {
-      if (value != null) url.searchParams.set(key, String(value));
-    }
-  }
-  const response = await fetch(url.toString(), {
-    headers: DEFAULT_HEADERS,
-    signal: AbortSignal.timeout(3e4)
-  });
-  if (!response.ok) return parseErrorResponse(response);
-  return response.json();
-}
-async function apiPost(path, body) {
-  const response = await fetch(`${config.apiUrl}${path}`, {
-    method: "POST",
-    headers: DEFAULT_HEADERS,
-    body: body !== void 0 ? JSON.stringify(body) : void 0,
-    signal: AbortSignal.timeout(3e4)
-  });
-  if (!response.ok) return parseErrorResponse(response);
-  return response.json();
-}
-async function apiDelete(path) {
-  const response = await fetch(`${config.apiUrl}${path}`, {
-    method: "DELETE",
-    headers: DEFAULT_HEADERS,
-    signal: AbortSignal.timeout(3e4)
-  });
-  if (!response.ok) return parseErrorResponse(response);
-  return response.json();
-}
-async function publicApiPost(path, body) {
-  const response = await fetch(`${config.apiUrl}${path}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: body !== void 0 ? JSON.stringify(body) : void 0,
-    signal: AbortSignal.timeout(3e4)
-  });
-  if (!response.ok) return parseErrorResponse(response);
-  return response.json();
-}
-
 // src/tools/missions.ts
 var missionTools = [
   {
@@ -982,8 +915,182 @@ async function handleTrackTool(name, args) {
   }
 }
 
+// src/tools/solana.ts
+var solanaTools = [
+  {
+    name: "get_solana_config",
+    description: "Read the Solana escrow deployment: program id, cluster, RPC endpoint, accepted mints and their decimals, and the minimum first payout. Call this before funding so you use a whitelisted mint \u2014 a mint that is not whitelisted is rejected on chain, not by the API. Requires no wallet.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "get_solana_wallet",
+    description: "Show your Solana wallet address and its balances. Reports SOL (needed for transaction fees and for account rent) and the token balance for a given mint (the mission budget). Use this before funding: an agent needs BOTH, and the rent line has no equivalent on Base. Rent is a refundable deposit, not a fee \u2014 most of it returns when the task is closed. If no wallet is configured this explains how to set one up.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mint: {
+          type: "string",
+          description: "Mint to report a balance for. Defaults to the deployment payout mint from get_solana_config."
+        }
+      }
+    }
+  },
+  {
+    name: "fund_solana_mission",
+    description: "Fund a Solana mission end to end: the backend builds the escrow transaction, this tool DECODES AND VERIFIES it against the parameters you expect, signs it locally with your wallet, and submits it. Your key never leaves this process.\n\nVerification is not optional and cannot be skipped. On Solana the backend builds the transaction rather than publishing a parameter set for you to rebuild, so without a decode you would be signing bytes you cannot read. This tool refuses to sign if anything differs from what you expect \u2014 a substituted mint, an altered budget, an extra instruction, a vault that is not a program-derived address \u2014 and returns the discrepancies instead.\n\nCall create_mission with chain='solana' first; pass that mission's id here.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: 'Mission created with chain="solana".' },
+        expected_budget: {
+          type: "number",
+          description: "The total budget in whole tokens (e.g. 10 for 10 USDC) you expect to escrow. Verified against the transaction before signing. Pass what you intended, NOT what the API told you \u2014 comparing the API to itself proves nothing."
+        },
+        expected_mint: {
+          type: "string",
+          description: "The mint you expect the budget to be taken in. Verified before signing. Defaults to the deployment payout mint."
+        },
+        dry_run: {
+          type: "boolean",
+          description: "Build and verify, then stop without signing or submitting. Use this to inspect what would be signed. Nothing is escrowed and no fee is paid."
+        }
+      },
+      required: ["mission_id", "expected_budget"]
+    }
+  }
+];
+function toRawAmount(amount, decimals) {
+  const s = amount.toString();
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new Error(`amount must be a non-negative decimal number, got ${s}`);
+  }
+  const [whole, frac = ""] = s.split(".");
+  if (frac.length > decimals) {
+    throw new Error(
+      `amount ${s} has ${frac.length} decimal places but the mint has only ${decimals}`
+    );
+  }
+  return (whole + frac.padEnd(decimals, "0")).replace(/^0+(?=\d)/, "");
+}
+var SOLANA_TOOL_NAMES = new Set(solanaTools.map((t) => t.name));
+async function handleSolanaTool(name, args) {
+  const { apiGet: apiGet2, apiPost: apiPost2 } = await import("./client-2NLDPRAH.js");
+  switch (name) {
+    case "get_solana_config":
+      return apiGet2("/agent/solana/config");
+    case "get_solana_wallet": {
+      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress } = await import("./wallet-IUQWBW6F.js");
+      if (!hasSolanaWallet()) {
+        return {
+          configured: false,
+          how_to_configure: {
+            option_1: "SOLO_SOLANA_KEYPAIR \u2014 JSON byte array, as `solana-keygen new` writes it",
+            option_2: "SOLO_SOLANA_KEYPAIR_PATH \u2014 path to that file, e.g. ~/.config/solana/id.json"
+          },
+          what_you_need: "SOL for transaction fees and account rent, plus the payout token for the budget. Rent is a refundable deposit, not a fee \u2014 most of it returns on close_task. Roughly $0.58 is locked per mission and about $0.24 is permanent, which buys the on-chain record that makes the escrow verifiable by anyone."
+        };
+      }
+      const wallet = await loadSolanaWallet();
+      const cfg = await apiGet2("/agent/solana/config");
+      const symbol = Object.keys(cfg.mints)[0];
+      const mint = args.mint ?? cfg.mints[symbol];
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      const rpc = async (method, params) => {
+        const res = await fetch(cfg.rpc_url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
+        });
+        return await res.json();
+      };
+      const solRes = await rpc("getBalance", [wallet.publicKey]);
+      const tokRes = await rpc("getTokenAccountBalance", [tokenAccount]);
+      const lamports = solRes.result?.value ?? 0;
+      const decimals = cfg.decimals[symbol] ?? 6;
+      return {
+        configured: true,
+        address: wallet.publicKey,
+        sol: lamports / 1e9,
+        // A token account only exists once tokens first arrive. create_task reads it, so funding
+        // fails without one — and the on-chain error names the account rather than the missing
+        // balance, which is confusing enough to call out explicitly.
+        token_account: tokenAccount,
+        token_account_exists: !tokRes.error,
+        token_balance: tokRes.result?.value?.uiAmountString ?? "0",
+        mint,
+        can_pay_fees: lamports > 1e7,
+        // ~0.01 SOL — comfortably covers rent plus fees
+        note: lamports === 0 ? 'No SOL. Funding will fail with "Attempt to debit an account but found no record of a prior credit", which does not mention SOL.' : void 0,
+        _decimals: decimals
+      };
+    }
+    case "fund_solana_mission": {
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-IUQWBW6F.js");
+      const { verifyFundingTransaction } = await import("./verify-KAETIGV5.js");
+      const wallet = await loadSolanaWallet();
+      const cfg = await apiGet2("/agent/solana/config");
+      const symbol = Object.keys(cfg.mints)[0];
+      const mint = args.expected_mint ?? cfg.mints[symbol];
+      const decimals = cfg.decimals[symbol] ?? 6;
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      const built = await apiPost2(
+        `/agent/solana/missions/${args.mission_id}/funding-transaction`,
+        { sponsor_wallet: wallet.publicKey, sponsor_token_account: tokenAccount }
+      );
+      const expectedBudgetRaw = toRawAmount(args.expected_budget, decimals);
+      const verdict = await verifyFundingTransaction({
+        transaction_base64: built.transaction_base64,
+        declared: built.declared,
+        accounts: built.accounts,
+        expected: {
+          budget_raw: expectedBudgetRaw,
+          // base_pool is derived by the backend from reward × max_humans. The agent's check on it
+          // is the quoted value against the encoded bytes, which verifyFundingTransaction does —
+          // asserting a locally recomputed figure would require duplicating that arithmetic here
+          // and would fail on a legitimately rounded reward.
+          base_pool_raw: String(built.declared.base_pool),
+          lottery_winner_count: Number(built.declared.lottery_winner_count),
+          lottery_prize_per_winner_raw: String(built.declared.lottery_prize_per_winner),
+          qualify_deadline: Number(built.declared.qualify_deadline),
+          settlement_deadline: Number(built.declared.settlement_deadline),
+          mint,
+          sponsor: wallet.publicKey
+        },
+        expected_program_id: cfg.program_id
+      });
+      if (!verdict.ok) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: verdict.problems,
+          summary: verdict.summary,
+          what_this_means: "The transaction does not match what you asked for, so it was NOT signed and nothing was escrowed. This is the verifier doing its job. Do not retry blindly \u2014 the discrepancy above is either a bug or an attempt to have you authorise something else."
+        };
+      }
+      if (args.dry_run) {
+        return {
+          funded: false,
+          dry_run: true,
+          verified: true,
+          task_id: built.task_id,
+          summary: verdict.summary,
+          would_escrow: `${args.expected_budget} (${expectedBudgetRaw} raw) of ${mint}`
+        };
+      }
+      const signed = await signTransaction(built.transaction_base64, wallet);
+      const confirmed = await apiPost2(
+        `/agent/solana/missions/${args.mission_id}/confirm-funding`,
+        { signed_transaction: signed, task_id: built.task_id }
+      );
+      return { funded: true, verified: true, ...confirmed };
+    }
+    default:
+      throw new Error(`Unknown Solana tool: ${name}`);
+  }
+}
+
 // src/index.ts
-var ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools];
+var ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools, ...solanaTools];
 var AGENT_TOOL_NAMES = new Set(agentTools.map((t) => t.name));
 var MISSION_TOOL_NAMES = new Set(missionTools.map((t) => t.name));
 var HUMAN_TOOL_NAMES = new Set(humanTools.map((t) => t.name));
@@ -1013,6 +1120,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       result = await handleRealtimeTool(name, args);
     } else if (TRACK_TOOL_NAMES.has(name)) {
       result = await handleTrackTool(name, args);
+    } else if (SOLANA_TOOL_NAMES.has(name)) {
+      result = await handleSolanaTool(name, args);
     } else {
       return {
         content: [{ type: "text", text: `Unknown tool: ${name}` }],

package/dist/verify-KAETIGV5.js

@@ -0,0 +1,136 @@
+// src/solana/verify.ts
+var eqAmount = (a, b) => {
+  try {
+    return BigInt(a) === BigInt(b);
+  } catch {
+    return false;
+  }
+};
+async function verifyFundingTransaction(input) {
+  const { Transaction, PublicKey } = await import("@solana/web3.js");
+  const problems = [];
+  const tx = Transaction.from(Buffer.from(input.transaction_base64, "base64"));
+  if (tx.instructions.length !== 1) {
+    problems.push(
+      `expected exactly 1 instruction, found ${tx.instructions.length} \u2014 additional instructions would be authorised by the same signature`
+    );
+  }
+  const ix = tx.instructions[0];
+  const programId = ix?.programId?.toBase58() ?? "(none)";
+  if (programId !== input.expected_program_id) {
+    problems.push(`program is ${programId}, expected ${input.expected_program_id}`);
+  }
+  if (programId !== input.accounts.program_id) {
+    problems.push(
+      `transaction program ${programId} disagrees with the quoted accounts.program_id ${input.accounts.program_id}`
+    );
+  }
+  const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
+  if (signers.length !== 1 || signers[0] !== input.expected.sponsor) {
+    problems.push(
+      `expected the sponsor ${input.expected.sponsor} to be the only signer, found [${signers.join(", ")}]`
+    );
+  }
+  if (tx.feePayer?.toBase58() !== input.expected.sponsor) {
+    problems.push(
+      `fee payer is ${tx.feePayer?.toBase58() ?? "(unset)"}, expected ${input.expected.sponsor}`
+    );
+  }
+  const keyList = (ix?.keys ?? []).map((k) => k.pubkey.toBase58());
+  for (const [label, expected] of [
+    ["mint", input.expected.mint],
+    ["sponsor", input.expected.sponsor]
+  ]) {
+    if (!keyList.includes(expected)) {
+      problems.push(`${label} ${expected} does not appear in the transaction's accounts`);
+    }
+  }
+  if (input.accounts.mint !== input.expected.mint) {
+    problems.push(`quoted mint ${input.accounts.mint}, expected ${input.expected.mint}`);
+  }
+  if (input.accounts.vault === input.accounts.sponsor_token_account) {
+    problems.push("escrow vault equals the sponsor token account \u2014 the budget would not be escrowed");
+  }
+  try {
+    for (const [label, addr] of [
+      ["task", input.accounts.task],
+      ["vault", input.accounts.vault]
+    ]) {
+      if (PublicKey.isOnCurve(new PublicKey(addr).toBytes())) {
+        problems.push(`${label} ${addr} is not a program-derived address \u2014 someone holds its key`);
+      }
+    }
+  } catch {
+    problems.push("task or vault is not a valid address");
+  }
+  const d = input.declared;
+  const e = input.expected;
+  if (!eqAmount(d.budget, e.budget_raw)) {
+    problems.push(`budget is ${d.budget}, expected ${e.budget_raw}`);
+  }
+  if (!eqAmount(d.base_pool, e.base_pool_raw)) {
+    problems.push(`base_pool is ${d.base_pool}, expected ${e.base_pool_raw}`);
+  }
+  if (d.lottery_winner_count !== e.lottery_winner_count) {
+    problems.push(
+      `lottery_winner_count is ${d.lottery_winner_count}, expected ${e.lottery_winner_count}`
+    );
+  }
+  if (!eqAmount(d.lottery_prize_per_winner, e.lottery_prize_per_winner_raw)) {
+    problems.push(
+      `lottery_prize_per_winner is ${d.lottery_prize_per_winner}, expected ${e.lottery_prize_per_winner_raw}`
+    );
+  }
+  if (!eqAmount(d.qualify_deadline, String(e.qualify_deadline))) {
+    problems.push(`qualify_deadline is ${d.qualify_deadline}, expected ${e.qualify_deadline}`);
+  }
+  if (!eqAmount(d.settlement_deadline, String(e.settlement_deadline))) {
+    problems.push(
+      `settlement_deadline is ${d.settlement_deadline}, expected ${e.settlement_deadline}`
+    );
+  }
+  if (!/^[0-9a-f]{64}$/i.test(d.seed_commit)) {
+    problems.push(`seed_commit is not 32 bytes of hex: ${d.seed_commit}`);
+  }
+  const data = ix?.data ?? Buffer.alloc(0);
+  if (data.length !== 8 + 8 + 8 + 4 + 8 + 8 + 8 + 32) {
+    problems.push(
+      `instruction data is ${data.length} bytes, expected 84 for create_task \u2014 this is not the instruction it claims to be`
+    );
+  } else {
+    const encoded = {
+      budget: data.readBigUInt64LE(8).toString(),
+      base_pool: data.readBigUInt64LE(16).toString(),
+      lottery_winner_count: data.readUInt32LE(24),
+      lottery_prize_per_winner: data.readBigUInt64LE(28).toString(),
+      qualify_deadline: data.readBigInt64LE(36).toString(),
+      settlement_deadline: data.readBigInt64LE(44).toString(),
+      seed_commit: data.subarray(52, 84).toString("hex")
+    };
+    for (const key of Object.keys(encoded)) {
+      const inBytes = String(encoded[key]);
+      const quoted = String(d[key]);
+      const same = key === "seed_commit" || key === "lottery_winner_count" ? inBytes.toLowerCase() === quoted.toLowerCase() : eqAmount(inBytes, quoted);
+      if (!same) {
+        problems.push(
+          `the transaction encodes ${key}=${inBytes} but the response quoted ${quoted} \u2014 the backend described one thing and built another`
+        );
+      }
+    }
+  }
+  return {
+    ok: problems.length === 0,
+    problems,
+    summary: {
+      program_id: programId,
+      instruction_count: tx.instructions.length,
+      signers,
+      budget: d.budget,
+      mint: input.accounts.mint,
+      task: input.accounts.task
+    }
+  };
+}
+export {
+  verifyFundingTransaction
+};

package/dist/wallet-IUQWBW6F.js

@@ -0,0 +1,90 @@
+// src/solana/wallet.ts
+import { readFileSync } from "fs";
+var SolanaWalletUnavailable = class extends Error {
+  constructor(reason) {
+    super(
+      `Solana wallet unavailable: ${reason}
+
+Set one of:
+  SOLO_SOLANA_KEYPAIR       - JSON byte array, as \`solana-keygen\` writes it
+  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json)
+
+The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a
+refundable deposit, not a fee: most of it returns when the task is closed.`
+    );
+    this.name = "SolanaWalletUnavailable";
+  }
+};
+function parseKeypairBytes(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("[")) {
+    throw new SolanaWalletUnavailable(
+      "value is not a JSON byte array \u2014 this is the format `solana-keygen new` writes"
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new SolanaWalletUnavailable("value looks like a JSON array but does not parse");
+  }
+  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === "number")) {
+    throw new SolanaWalletUnavailable("JSON array must contain only numbers");
+  }
+  const bytes = Uint8Array.from(parsed);
+  if (bytes.length !== 64) {
+    throw new SolanaWalletUnavailable(
+      `expected 64 bytes, got ${bytes.length}` + (bytes.length === 32 ? " \u2014 this is the seed alone, not the full keypair" : "")
+    );
+  }
+  return bytes;
+}
+async function loadSolanaWallet() {
+  const inline = process.env.SOLO_SOLANA_KEYPAIR;
+  const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
+  let raw;
+  if (inline && inline.trim() !== "") {
+    raw = inline;
+  } else if (path && path.trim() !== "") {
+    try {
+      raw = readFileSync(path.replace(/^~/, process.env.HOME ?? "~"), "utf8");
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${path}: ${e.message}`);
+    }
+  } else {
+    throw new SolanaWalletUnavailable("neither SOLO_SOLANA_KEYPAIR nor SOLO_SOLANA_KEYPAIR_PATH is set");
+  }
+  const secretKey = parseKeypairBytes(raw);
+  const { Keypair } = await import("@solana/web3.js");
+  const kp = Keypair.fromSecretKey(secretKey);
+  return { publicKey: kp.publicKey.toBase58(), secretKey };
+}
+function hasSolanaWallet() {
+  return Boolean(
+    (process.env.SOLO_SOLANA_KEYPAIR ?? "").trim() || (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? "").trim()
+  );
+}
+async function associatedTokenAddress(mint, owner) {
+  const { PublicKey } = await import("@solana/web3.js");
+  const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+  const [address] = PublicKey.findProgramAddressSync(
+    [new PublicKey(owner).toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), new PublicKey(mint).toBuffer()],
+    ASSOCIATED_TOKEN_PROGRAM_ID
+  );
+  return address.toBase58();
+}
+async function signTransaction(transactionBase64, wallet) {
+  const { Keypair, Transaction } = await import("@solana/web3.js");
+  const kp = Keypair.fromSecretKey(wallet.secretKey);
+  const tx = Transaction.from(Buffer.from(transactionBase64, "base64"));
+  tx.partialSign(kp);
+  return tx.serialize().toString("base64");
+}
+export {
+  SolanaWalletUnavailable,
+  associatedTokenAddress,
+  hasSolanaWallet,
+  loadSolanaWallet,
+  signTransaction
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@projectsolo/solo-mission-mcp",
-  "version": "0.19.2",
-  "description": "MCP server for Solo Mission Platform — lets AI agents create missions, browse humans, and chat.",
+  "version": "0.20.1",
+  "description": "MCP server for Solo Mission Platform \u2014 lets AI agents create missions, browse humans, and chat.",
   "type": "module",
   "main": "dist/index.js",
   "publishConfig": {
@@ -14,17 +14,20 @@
     "build": "tsup src/index.ts --format esm --dts --clean",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@solana/web3.js": "^1.98.4",
     "dotenv": "^16.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=20"