@projectsolo/solo-mission-mcp 0.19.0

package/dist/index.js

@@ -0,0 +1,1040 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  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.xyz"
+};
+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 = [
+  {
+    name: "create_mission",
+    description: "Create a new mission. Off-chain missions (no budget field) are always free \u2014 no payment, no escrow. For paid missions with EscrowVault escrow, include the budget field \u2014 the response will contain funding_params for you to call createTask() on the contract.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["coffee_chat", "opinion", "survey", "general", "media_review"],
+          description: 'Type of mission. Use "media_review" for audio/music rating missions.'
+        },
+        title: { type: "string", description: "Mission title (max 100 chars)" },
+        description: { type: "string", description: "Detailed mission description (max 2000 chars). Supports Markdown \u2014 use ## headings, - bullet lists, and **bold** to structure your content. The platform renders it as formatted text." },
+        requirements: {
+          type: "object",
+          description: "Optional participant requirements",
+          properties: {
+            skills: { type: "array", items: { type: "string" } },
+            location: { type: "string" },
+            languages: { type: "array", items: { type: "string" } },
+            min_rating: { type: "number", minimum: 0, maximum: 5 }
+          }
+        },
+        reward_usdt: { type: "number", minimum: 0, description: "Deprecated \u2014 ignored for off-chain missions (which are always free). Has no effect. Omit this field." },
+        max_participants: { type: "number", minimum: 1, description: "Maximum number of participants" },
+        expires_in_hours: { type: "number", minimum: 1, description: "Hours until mission expires" },
+        budget: { type: "number", description: "Total mission budget in USDC. Enables on-chain escrow. Must satisfy: base_reward * max_humans + lottery_prize_per_winner * lottery_winner_count <= budget." },
+        max_humans: { type: "number", minimum: 1, description: "On-chain: maximum number of participants (both base-reward and lottery entrants)." },
+        base_reward: { type: "number", minimum: 0, description: "Per-participant base reward in USDC paid to every qualified human. Defaults to 0. Set to 0 for pure-lottery missions." },
+        reward_per_human: { type: "number", minimum: 0, description: "Deprecated \u2014 use base_reward instead." },
+        lottery_winner_count: { type: "integer", minimum: 1, description: "Number of winners randomly selected from all qualified participants. Must be <= max_humans. Must be paired with lottery_prize_per_winner. Winners are chosen deterministically from the on-chain seed reveal \u2014 auditable by anyone." },
+        lottery_prize_per_winner: { type: "number", minimum: 0, description: "Additional prize in USDC paid to each lottery winner on top of base_reward. Must be paired with lottery_winner_count." },
+        hiring_duration_hours: { type: "number", minimum: 1, description: "How long (hours) the mission accepts applications and the agent hires/rejects. The hiring window closes at now + hiring_duration_hours. Finalize-qualification cannot be called before this." },
+        work_duration_hours: { type: "number", minimum: 2, description: "How long (hours) hired participants have to complete the work. Agent must call settle_mission before this period ends. Minimum is 2, not 1 \u2014 the contract requires at least 1 hour of settlement window remaining when finalize_qualification is called, and finalize can only happen after the hiring window already closes, so a value of exactly 1 leaves no reachable window at all." },
+        auto_accept_applicants: { type: "boolean", description: "When true, applicants are automatically hired when they apply \u2014 no manual hire_participant call needed. First-come first-served up to max_humans. Face verification is still required. Ideal for open media_review missions." }
+      },
+      required: ["type", "title", "description"]
+    }
+  },
+  {
+    name: "list_missions",
+    description: "List missions created by this agent. Filter by status to manage your mission portfolio.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["pending_funding", "active", "qualifying", "completed", "refundable", "refunded", "cancelled", "expired"],
+          description: "Filter by status"
+        },
+        limit: { type: "number", description: "Max results (default 20)" },
+        page: { type: "number", description: "Page number (default 1)" }
+      }
+    }
+  },
+  {
+    name: "get_mission",
+    description: 'Get details of a specific mission by ID, including all participants. Each participant includes a conversation_id once the human has tapped "Say Hi" \u2014 use it directly with watch_conversation or send_message. Each participant also includes an agent_rating field ({ rating: 1\u20135, comment?: string, updated_at }) if that human has rated the agent; null if not rated or if the 7-day rating window after mission completion has closed.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "confirm_funding",
+    description: `After calling createTask() on the EscrowVault contract, confirm the funding via the SOLO API. The backend verifies the transaction on-chain. Mission transitions from pending_funding \u2192 active. tx_hash is optional \u2014 backend reconciles from the contract if omitted. For media_review missions: returns 409 if no tracks are confirmed yet \u2014 call add_mission_track first. Also returns 409 if the on-chain task's budget, lottery, deadline, or seed_commit values do not match what create_mission originally quoted (e.g. createTask() was called with hand-typed or re-derived values instead of the exact funding_params fields) \u2014 unlike the "not yet FUNDED" 409, this one is NOT retryable: the task_id can never be confirmed. Call cancelTask() on-chain to reclaim the full escrow, then call create_mission again.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        tx_hash: { type: "string", description: "Transaction hash of createTask() call (optional)" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "hire_participant",
+    description: "Accept a human applicant for a mission. Only applied humans can be hired. Hired humans can start work via conversations. Only valid while mission is active.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        uid: { type: "string", description: "Firebase UID of the applicant to hire" }
+      },
+      required: ["mission_id", "uid"]
+    }
+  },
+  {
+    name: "reject_participant",
+    description: "Reject a human applicant or hired participant. Valid for applied or hired status, before finalize_qualification is called.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        uid: { type: "string", description: "Firebase UID of the participant to reject" }
+      },
+      required: ["mission_id", "uid"]
+    }
+  },
+  {
+    name: "finalize_qualification",
+    description: "Lock in the qualified participants after reviewing their work. For standard missions provide an explicit list of UIDs whose work was accepted. For media_review missions pass an empty body \u2014 qualified_human_uids is ignored and the backend auto-qualifies anyone who rated every track. For on-chain missions, the backend calls finalizeQualification() on EscrowVault. Mission transitions to qualifying.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        qualified_human_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Firebase UIDs of humans whose work was accepted. Ignored for media_review missions (auto-derived from rating completion)."
+        }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "settle_mission",
+    description: "Settle the mission after finalize_qualification. For on-chain missions, calls settleTask() on EscrowVault only (aggregate payout numbers, no per-wallet computation); mission transitions to completed or refundable. Rewards are NOT immediately claimable \u2014 a separate batched process publishes the Merkle root that makes them claimable, which can take anywhere from minutes to over an hour depending on the review window. For free (off-chain) missions, marks qualified participants as completed \u2014 no payment is involved.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "cancel_mission",
+    description: "Cancel an off-chain mission directly. Valid when status is active or qualifying. For on-chain missions, use get_cancel_params instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_cancel_params",
+    description: "Get on-chain transaction parameters to cancel a funded mission via cancelTask() on EscrowVault. Only valid before qualify_deadline. After qualify_deadline, use get_emergency_refund_params instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "confirm_cancel",
+    description: "After executing cancelTask() on EscrowVault, confirm the cancellation on the SOLO platform. Mission transitions to cancelled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        tx_hash: { type: "string", description: "Transaction hash of cancelTask() (optional)" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_emergency_refund_params",
+    description: "Get on-chain transaction parameters to force-refund a mission after the settlement_deadline has passed without settlement. Returns eligible: true with params if eligible, or eligible: false with retry_after if not yet past the deadline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "confirm_emergency_refund",
+    description: "After executing emergencyRefund() on EscrowVault, confirm on the SOLO platform. Mission transitions to cancelled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        tx_hash: { type: "string", description: "Transaction hash of emergencyRefund() (optional)" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_refund_params",
+    description: "Get on-chain transaction parameters to claim unused budget via claimRefund() on EscrowVault. Only valid when mission is in refundable state (settled with leftover budget).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "confirm_refund",
+    description: "After executing claimRefund() on EscrowVault, confirm the refund on the SOLO platform. Mission transitions to refunded.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        tx_hash: { type: "string", description: "Transaction hash of claimRefund() (optional)" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "rate_participant",
+    description: "Leave a rating and optional comment for a mission participant. Requires the mission to be settled (completed, refundable, or refunded) and must be submitted within 7 days of mission completion. Limited to one rating per participant per mission; calling again overwrites the previous rating/comment.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" },
+        uid: { type: "string", description: "Participant UID" },
+        rating: { type: "number", minimum: 1, maximum: 5, description: "Rating 1-5" },
+        comment: { type: "string", description: "Optional comment (max 500 chars). Shown publicly on the participant's profile." }
+      },
+      required: ["mission_id", "uid", "rating"]
+    }
+  }
+];
+async function handleMissionTool(name, args) {
+  switch (name) {
+    case "create_mission":
+      return apiPost("/agent/missions", args);
+    case "list_missions": {
+      const params = {};
+      if (args.status) params.status = args.status;
+      if (args.limit) params.limit = args.limit;
+      if (args.page) params.page = args.page;
+      return apiGet("/agent/missions", params);
+    }
+    case "get_mission":
+      return apiGet(`/agent/missions/${args.mission_id}`);
+    case "confirm_funding":
+      return apiPost(`/agent/missions/${args.mission_id}/confirm-funding`, { tx_hash: args.tx_hash });
+    case "hire_participant":
+      return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/hire`);
+    case "reject_participant":
+      return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/reject`);
+    case "finalize_qualification":
+      return apiPost(`/agent/missions/${args.mission_id}/finalize-qualification`, {
+        qualified_human_uids: args.qualified_human_uids
+      });
+    case "settle_mission":
+      return apiPost(`/agent/missions/${args.mission_id}/settle`);
+    case "cancel_mission":
+      return apiPost(`/agent/missions/${args.mission_id}/cancel`);
+    case "get_cancel_params":
+      return apiGet(`/agent/missions/${args.mission_id}/cancel-params`);
+    case "confirm_cancel":
+      return apiPost(`/agent/missions/${args.mission_id}/confirm-cancel`, { tx_hash: args.tx_hash });
+    case "get_emergency_refund_params":
+      return apiGet(`/agent/missions/${args.mission_id}/emergency-refund-params`);
+    case "confirm_emergency_refund":
+      return apiPost(`/agent/missions/${args.mission_id}/confirm-emergency-refund`, { tx_hash: args.tx_hash });
+    case "get_refund_params":
+      return apiGet(`/agent/missions/${args.mission_id}/refund-params`);
+    case "confirm_refund":
+      return apiPost(`/agent/missions/${args.mission_id}/confirm-refund`, { tx_hash: args.tx_hash });
+    case "rate_participant":
+      return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/comment`, {
+        rating: args.rating,
+        comment: args.comment
+      });
+    default:
+      throw new Error(`Unknown mission tool: ${name}`);
+  }
+}
+
+// src/tools/humans.ts
+var humanTools = [
+  {
+    name: "browse_humans",
+    description: "Browse face-verified humans on the Solo platform. Filter by skills, location, languages, and more.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skills: { type: "string", description: 'Comma-separated skill keywords (e.g. "Software Development,Data Analysis")' },
+        location: { type: "string", description: "Filter by city or country" },
+        languages: { type: "string", description: 'Comma-separated languages (e.g. "English,Spanish")' },
+        min_rating: { type: "number", minimum: 0, maximum: 5, description: "Minimum average rating (0\u20135)" },
+        max_hourly_rate: { type: "number", description: "Maximum hourly rate in USD" },
+        min_tier: { type: "number", minimum: 1, description: "Minimum contribution tier (1=Scout, 2=Curator, 3=Oracle)" },
+        sort_by: { type: "string", enum: ["tier", "avg_rating", "completed_count"], description: "Sort results by this field (descending)" },
+        limit: { type: "number", description: "Max results (default 20)" },
+        page: { type: "number", description: "Page number (default 1)" }
+      }
+    }
+  },
+  {
+    name: "get_human_profile",
+    description: "Get the full mission profile of a specific human by their user_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "The human's user_id (from browse_humans results)" }
+      },
+      required: ["user_id"]
+    }
+  }
+];
+async function handleHumanTool(name, args) {
+  switch (name) {
+    case "browse_humans": {
+      const params = {};
+      if (args.skills) params.skills = args.skills;
+      if (args.location) params.location = args.location;
+      if (args.languages) params.languages = args.languages;
+      if (args.min_rating !== void 0) params.min_rating = args.min_rating;
+      if (args.max_hourly_rate !== void 0) params.max_hourly_rate = args.max_hourly_rate;
+      if (args.min_tier !== void 0) params.min_tier = args.min_tier;
+      if (args.sort_by) params.sort_by = args.sort_by;
+      if (args.limit) params.limit = args.limit;
+      if (args.page) params.page = args.page;
+      return apiGet("/agent/humans", params);
+    }
+    case "get_human_profile":
+      return apiGet(`/agent/humans/${args.user_id}`);
+    default:
+      throw new Error(`Unknown human tool: ${name}`);
+  }
+}
+
+// src/realtime/poller.ts
+var watches = /* @__PURE__ */ new Map();
+var FIBONACCI_MS = [
+  1e3,
+  1e3,
+  2e3,
+  3e3,
+  5e3,
+  8e3,
+  13e3,
+  21e3,
+  34e3,
+  55e3,
+  89e3,
+  144e3,
+  233e3,
+  377e3,
+  6e5
+];
+function getFibMs(step) {
+  return FIBONACCI_MS[Math.min(step, FIBONACCI_MS.length - 1)];
+}
+function scheduleNext(conversationId, state) {
+  state.timeoutId = setTimeout(() => pollOnce(conversationId, state), getFibMs(state.fibStep));
+}
+async function pollOnce(conversationId, state) {
+  if (!watches.has(conversationId)) return;
+  try {
+    const data = await apiGet(
+      `/agent/conversations/${conversationId}/messages`,
+      { since: state.lastSeen }
+    );
+    const msgs = data.messages ?? [];
+    if (msgs.length > 0) {
+      state.queue.push(...msgs);
+      const latest = msgs[msgs.length - 1];
+      if (latest?.created_at) {
+        const raw = latest.created_at;
+        if (typeof raw === "string") {
+          state.lastSeen = raw;
+        } else if (raw?._seconds !== void 0) {
+          state.lastSeen = new Date(raw._seconds * 1e3 + Math.floor((raw._nanoseconds ?? 0) / 1e6)).toISOString();
+        } else if (raw?.seconds !== void 0) {
+          state.lastSeen = new Date(raw.seconds * 1e3).toISOString();
+        }
+      }
+      if (msgs.some((m) => m.sender_type === "human")) {
+        state.fibStep = 0;
+      }
+    } else {
+      state.fibStep = Math.min(state.fibStep + 1, FIBONACCI_MS.length - 1);
+    }
+  } catch {
+  }
+  if (watches.has(conversationId)) {
+    scheduleNext(conversationId, state);
+  }
+}
+function startPolling(conversationId) {
+  if (watches.has(conversationId)) return;
+  const state = {
+    timeoutId: null,
+    fibStep: 0,
+    lastSeen: (/* @__PURE__ */ new Date()).toISOString(),
+    queue: []
+  };
+  watches.set(conversationId, state);
+  scheduleNext(conversationId, state);
+}
+function drainQueue(conversationId) {
+  const state = watches.get(conversationId);
+  if (!state) return [];
+  const msgs = [...state.queue];
+  state.queue = [];
+  return msgs;
+}
+function stopPolling(conversationId) {
+  const state = watches.get(conversationId);
+  if (!state) return false;
+  if (state.timeoutId !== null) clearTimeout(state.timeoutId);
+  watches.delete(conversationId);
+  return true;
+}
+function listWatched() {
+  return [...watches.keys()];
+}
+function getPollIntervalMs(conversationId) {
+  const state = watches.get(conversationId);
+  if (!state) return null;
+  return getFibMs(state.fibStep);
+}
+
+// src/tools/conversations.ts
+var conversationTools = [
+  {
+    name: "start_conversation",
+    description: "Start a new conversation with a human. Idempotent \u2014 if a conversation already exists with this human (and mission), returns the existing one. If the existing conversation was archived, it will be reopened.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        human_uid: { type: "string", description: "The human's Firebase uid \u2014 use the 'uid' field from browse_humans results, NOT 'user_id'. user_id is a mutable display name; uid is the stable internal identifier." },
+        initial_message: { type: "string", description: "First message to send" },
+        mission_id: { type: "string", description: "Optional: link conversation to a mission" }
+      },
+      required: ["human_uid", "initial_message"]
+    }
+  },
+  {
+    name: "list_conversations",
+    description: "List conversations. Use status filter to focus on active conversations. Pagination supported for agents with many conversations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["active", "archived", "closed"], description: "Filter by status (default: all)" },
+        limit: { type: "number", description: "Max results (default 20, max 100)" },
+        page: { type: "number", description: "Page number (default 1)" }
+      }
+    }
+  },
+  {
+    name: "get_conversation_upload_url",
+    description: "Get a signed upload URL to attach an image to a message. For agent uploads prefer upload_conversation_image instead. Otherwise: upload the file with PUT to the returned upload_url, then pass the returned storage_path in send_message attachment_paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        content_type: { type: "string", description: "MIME type of the file, e.g. image/jpeg, image/png, image/webp (default image/jpeg)" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "upload_conversation_image",
+    description: "Upload an image into a conversation and get its storage_path for use in send_message. Pass the image as base64-encoded data (e.g. from a user attachment or generated image). Returns storage_path to include in send_message attachment_paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        image_base64: { type: "string", description: "Base64-encoded image data (no data URL prefix)" },
+        content_type: { type: "string", description: "MIME type: image/jpeg, image/png, or image/webp (default image/jpeg)" }
+      },
+      required: ["conversation_id", "image_base64"]
+    }
+  },
+  {
+    name: "send_message",
+    description: "Send a message in an existing conversation. Optionally include attachment_paths (from get_conversation_upload_url + upload) to attach images. At least one of content or attachment_paths is required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        content: { type: "string", description: "Message text (can be empty if attachment_paths provided)" },
+        attachment_paths: { type: "array", items: { type: "string" }, description: "Storage paths from get_conversation_upload_url flow; max 4 per message" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "get_messages",
+    description: "Retrieve messages from a conversation. Use the `since` parameter to poll for new messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        since: { type: "string", description: "ISO 8601 timestamp \u2014 only return messages after this time" },
+        limit: { type: "number", description: "Max messages to return (default 50)" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "close_conversation",
+    description: 'Manage conversation lifecycle. Use "archive" to shelve inactive conversations (reopenable). Use "close" to permanently end a conversation. Use "reopen" to resume an archived conversation. Best practice: archive conversations when waiting for a long response, close when the objective is met.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        action: { type: "string", enum: ["archive", "close", "reopen"], description: "Action to perform" }
+      },
+      required: ["conversation_id", "action"]
+    }
+  }
+];
+async function handleConversationTool(name, args) {
+  switch (name) {
+    case "start_conversation":
+      return apiPost("/agent/conversations", {
+        human_uid: args.human_uid,
+        initial_message: args.initial_message,
+        ...args.mission_id ? { mission_id: args.mission_id } : {}
+      });
+    case "list_conversations": {
+      const params = {};
+      if (args.status) params.status = args.status;
+      if (args.limit) params.limit = args.limit;
+      if (args.page) params.page = args.page;
+      return apiGet("/agent/conversations", params);
+    }
+    case "get_conversation_upload_url": {
+      const ct = args.content_type || "image/jpeg";
+      const path = `/agent/conversations/${args.conversation_id}/upload-url?content_type=${encodeURIComponent(ct)}`;
+      return apiPost(path);
+    }
+    case "upload_conversation_image": {
+      const ct = args.content_type || "image/jpeg";
+      const path = `/agent/conversations/${args.conversation_id}/upload-url?content_type=${encodeURIComponent(ct)}`;
+      const { upload_url, storage_path } = await apiPost(path);
+      const body = Buffer.from(args.image_base64, "base64");
+      const res = await fetch(upload_url, {
+        method: "PUT",
+        body,
+        headers: { "Content-Type": ct }
+      });
+      if (!res.ok) throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+      return { storage_path };
+    }
+    case "send_message": {
+      const body = { content: args.content ?? "" };
+      if (args.attachment_paths?.length) body.attachment_paths = args.attachment_paths;
+      return apiPost(`/agent/conversations/${args.conversation_id}/messages`, body);
+    }
+    case "get_messages": {
+      const params = {};
+      if (args.since) params.since = args.since;
+      if (args.limit) params.limit = args.limit;
+      return apiGet(`/agent/conversations/${args.conversation_id}/messages`, params);
+    }
+    case "close_conversation": {
+      const result = await apiPost(`/agent/conversations/${args.conversation_id}/${args.action}`);
+      if (args.action === "close") {
+        stopPolling(args.conversation_id);
+      }
+      return result;
+    }
+    default:
+      throw new Error(`Unknown conversation tool: ${name}`);
+  }
+}
+
+// src/realtime/missionPoller.ts
+var missionWatches = /* @__PURE__ */ new Map();
+async function startMissionPolling(missionId, intervalMinutes = 10) {
+  if (missionWatches.has(missionId)) return;
+  let knownParticipantUids = /* @__PURE__ */ new Set();
+  try {
+    const data = await apiGet(`/agent/missions/${missionId}`);
+    for (const p of data.participants ?? []) {
+      knownParticipantUids.add(p.uid);
+    }
+  } catch {
+  }
+  const intervalMs = intervalMinutes * 60 * 1e3;
+  const state = {
+    knownParticipantUids,
+    queue: [],
+    intervalId: setInterval(async () => {
+      try {
+        const data = await apiGet(`/agent/missions/${missionId}`);
+        for (const p of data.participants ?? []) {
+          if (!state.knownParticipantUids.has(p.uid)) {
+            state.knownParticipantUids.add(p.uid);
+            state.queue.push({
+              mission_id: missionId,
+              type: "new_participant",
+              participant: {
+                uid: p.uid,
+                user_id: p.user_id,
+                joined_at: p.joined_at,
+                ...p.conversation_id ? { conversation_id: p.conversation_id } : {}
+              }
+            });
+          }
+        }
+      } catch {
+      }
+    }, intervalMs)
+  };
+  missionWatches.set(missionId, state);
+}
+function drainMissionQueue(missionId) {
+  const state = missionWatches.get(missionId);
+  if (!state) return [];
+  const updates = [...state.queue];
+  state.queue = [];
+  return updates;
+}
+function stopMissionPolling(missionId) {
+  const state = missionWatches.get(missionId);
+  if (!state) return false;
+  clearInterval(state.intervalId);
+  missionWatches.delete(missionId);
+  return true;
+}
+function listWatchedMissions() {
+  return [...missionWatches.keys()];
+}
+
+// src/tools/realtime.ts
+var realtimeTools = [
+  {
+    name: "watch_conversation",
+    description: "Start watching a conversation for new messages. Uses a Fibonacci delay schedule: starts at 1s, advances on each miss (up to 600s cap), resets to 1s when the human replies. Drain buffered messages with get_pending_messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID to watch" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "get_pending_messages",
+    description: "Return and clear all buffered new messages for a watched conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "unwatch_conversation",
+    description: "Stop watching a conversation and discard its message buffer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID to stop watching" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "watch_mission",
+    description: 'Start polling a mission for new participants. When a human joins and taps "Say Hi", their participant entry gains a conversation_id \u2014 drain updates with get_pending_mission_updates, then call watch_conversation on each conversation_id to start chatting.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID to watch" },
+        interval_minutes: {
+          type: "number",
+          description: "How often to check for new participants in minutes (default: 10)",
+          minimum: 1
+        }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_pending_mission_updates",
+    description: "Return and clear buffered mission updates (new participants). Each update includes the participant's conversation_id if they have started a conversation. Call watch_conversation(conversation_id) for each new participant to begin chatting.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "unwatch_mission",
+    description: "Stop polling a mission for new participants.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID to stop watching" }
+      },
+      required: ["mission_id"]
+    }
+  }
+];
+async function handleRealtimeTool(name, args) {
+  switch (name) {
+    case "watch_conversation": {
+      const id = args.conversation_id;
+      const alreadyWatching = listWatched().includes(id);
+      startPolling(id);
+      const intervalMs = getPollIntervalMs(id) ?? 5e3;
+      return {
+        success: true,
+        conversation_id: id,
+        watching: true,
+        already_was_watching: alreadyWatching,
+        poll_interval_seconds: intervalMs / 1e3,
+        message: alreadyWatching ? `Already watching conversation ${id}` : `Started watching conversation ${id} \u2014 polling every ${intervalMs / 1e3}s (Fibonacci schedule)`
+      };
+    }
+    case "get_pending_messages": {
+      const id = args.conversation_id;
+      const msgs = drainQueue(id);
+      return {
+        conversation_id: id,
+        pending_count: msgs.length,
+        messages: msgs
+      };
+    }
+    case "unwatch_conversation": {
+      const id = args.conversation_id;
+      const stopped = stopPolling(id);
+      return {
+        success: true,
+        conversation_id: id,
+        was_watching: stopped,
+        message: stopped ? `Stopped watching conversation ${id}` : `Conversation ${id} was not being watched`
+      };
+    }
+    case "watch_mission": {
+      const missionId = args.mission_id;
+      const intervalMinutes = args.interval_minutes ?? 10;
+      const alreadyWatching = listWatchedMissions().includes(missionId);
+      await startMissionPolling(missionId, intervalMinutes);
+      return {
+        success: true,
+        mission_id: missionId,
+        already_was_watching: alreadyWatching,
+        interval_minutes: intervalMinutes,
+        message: alreadyWatching ? `Already watching mission ${missionId}` : `Started watching mission ${missionId} \u2014 checking for new participants every ${intervalMinutes} min`
+      };
+    }
+    case "get_pending_mission_updates": {
+      const missionId = args.mission_id;
+      const updates = drainMissionQueue(missionId);
+      return {
+        mission_id: missionId,
+        pending_count: updates.length,
+        updates
+      };
+    }
+    case "unwatch_mission": {
+      const missionId = args.mission_id;
+      const stopped = stopMissionPolling(missionId);
+      return {
+        success: true,
+        mission_id: missionId,
+        was_watching: stopped,
+        message: stopped ? `Stopped watching mission ${missionId}` : `Mission ${missionId} was not being watched`
+      };
+    }
+    default:
+      throw new Error(`Unknown realtime tool: ${name}`);
+  }
+}
+
+// src/tools/agent.ts
+var agentTools = [
+  {
+    name: "register_agent",
+    description: "Self-register a new agent on the Solo platform. No existing agent key required. Returns agent_id and api_key \u2014 the key is shown only once, save it immediately. Use this to bootstrap a fresh agent identity.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Agent name (3\u201350 characters)",
+          minLength: 3,
+          maxLength: 50
+        }
+      },
+      required: ["name"]
+    }
+  }
+];
+async function handleAgentTool(name, args) {
+  switch (name) {
+    case "register_agent":
+      return publicApiPost("/agent/register", { name: args.name });
+    default:
+      throw new Error(`Unknown agent tool: ${name}`);
+  }
+}
+
+// src/tools/tracks.ts
+var trackTools = [
+  {
+    name: "add_mission_track",
+    description: "Upload a media item (audio, image, or video) to a media_review mission. Provide the file as a base64-encoded string. For on-chain missions, call this BEFORE confirm_funding \u2014 uploads are blocked once the mission is active. For off-chain missions, call while the mission is active and before any participant is hired. The item becomes visible to hired participants once confirmed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the media_review mission" },
+        title: { type: "string", description: "Item title (required)" },
+        artist: { type: "string", description: "Artist / creator name (optional; typically used for audio)" },
+        file_base64: { type: "string", description: "Base64-encoded file contents" },
+        content_type: {
+          type: "string",
+          enum: ["audio/mpeg", "audio/mp4", "image/jpeg", "image/png", "image/webp", "video/mp4"],
+          description: "MIME type of the file. Mobile-compatible formats only (iOS + Android). audio/mpeg (MP3) and audio/mp4 (AAC/M4A): max 25 MB. image/jpeg, image/png, image/webp: max 10 MB. video/mp4: max 200 MB \u2014 must be faststart-encoded (moov atom first) for partial play."
+        },
+        duration_seconds: { type: "number", description: "Duration in seconds (optional; applicable to audio and video only)" }
+      },
+      required: ["mission_id", "title", "file_base64", "content_type"]
+    }
+  },
+  {
+    name: "list_mission_tracks",
+    description: "List all media items on a media_review mission. Returns raw stats for each item: media_type (audio/image/video), vote_counts ({1,2,3,4,5,total} star-rating distribution) and total_listen_seconds (cumulative engagement time across all participants). Use these to compute your own scoring.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the mission" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_track_ratings",
+    description: "Get per-participant star ratings for one track on a media_review mission. Only participants who submitted a rating are returned \u2014 play-only rows are excluded. Each entry includes uid, rating (1\u20135), optional comment, total_listen_seconds, and rated_at.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the mission" },
+        track_id: { type: "string", description: "ID of the track" }
+      },
+      required: ["mission_id", "track_id"]
+    }
+  },
+  {
+    name: "delete_mission_track",
+    description: "Delete a track from a mission. Only allowed if the track has received no ratings yet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the mission" },
+        track_id: { type: "string", description: "ID of the track to delete" }
+      },
+      required: ["mission_id", "track_id"]
+    }
+  }
+];
+async function handleTrackTool(name, args) {
+  switch (name) {
+    case "add_mission_track": {
+      const { mission_id, title, artist, file_base64, content_type, duration_seconds } = args;
+      const urlRes = await apiPost(
+        `/agent/missions/${mission_id}/tracks/upload-url`,
+        { title, artist, content_type }
+      );
+      const fileBytes = Buffer.from(file_base64, "base64");
+      const uploadRes = await fetch(urlRes.upload_url, {
+        method: "PUT",
+        headers: { "Content-Type": content_type },
+        body: fileBytes
+      });
+      if (!uploadRes.ok) {
+        const errText = await uploadRes.text().catch(() => "");
+        await apiDelete(`/agent/missions/${mission_id}/tracks/${urlRes.track_id}`).catch(() => {
+        });
+        throw new Error(`Media upload failed: ${uploadRes.status} ${errText}`);
+      }
+      const confirmed = await apiPost(
+        `/agent/missions/${mission_id}/tracks/${urlRes.track_id}/confirm`,
+        { title, artist, duration_seconds }
+      );
+      return confirmed.track;
+    }
+    case "list_mission_tracks": {
+      const { mission_id } = args;
+      return apiGet(`/agent/missions/${mission_id}/tracks`);
+    }
+    case "get_track_ratings": {
+      const { mission_id, track_id } = args;
+      return apiGet(`/agent/missions/${mission_id}/tracks/${track_id}/ratings`);
+    }
+    case "delete_mission_track": {
+      const { mission_id, track_id } = args;
+      return apiDelete(`/agent/missions/${mission_id}/tracks/${track_id}`);
+    }
+    default:
+      throw new Error(`Unknown track tool: ${name}`);
+  }
+}
+
+// src/index.ts
+var ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools];
+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));
+var CONVERSATION_TOOL_NAMES = new Set(conversationTools.map((t) => t.name));
+var REALTIME_TOOL_NAMES = new Set(realtimeTools.map((t) => t.name));
+var TRACK_TOOL_NAMES = new Set(trackTools.map((t) => t.name));
+var server = new Server(
+  { name: "solo-mission-mcp", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: ALL_TOOLS
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  try {
+    let result;
+    if (AGENT_TOOL_NAMES.has(name)) {
+      result = await handleAgentTool(name, args);
+    } else if (MISSION_TOOL_NAMES.has(name)) {
+      result = await handleMissionTool(name, args);
+    } else if (HUMAN_TOOL_NAMES.has(name)) {
+      result = await handleHumanTool(name, args);
+    } else if (CONVERSATION_TOOL_NAMES.has(name)) {
+      result = await handleConversationTool(name, args);
+    } else if (REALTIME_TOOL_NAMES.has(name)) {
+      result = await handleRealtimeTool(name, args);
+    } else if (TRACK_TOOL_NAMES.has(name)) {
+      result = await handleTrackTool(name, args);
+    } else {
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  } catch (error) {
+    const message = error?.response?.data ? JSON.stringify(error.response.data) : error?.message ?? String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Failed to start solo-mission-mcp:", err);
+  process.exit(1);
+});