@projectsolo/solo-mission-mcp 0.19.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@projectsolo/solo-mission-mcp",
+  "version": "0.19.0",
+  "description": "MCP server for Solo Mission Platform — lets AI agents create missions, browse humans, and chat.",
+  "type": "module",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "solo-mission-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,71 @@
+import { config } from '../config.js';
+
+const DEFAULT_HEADERS: Record<string, string> = {
+  'Content-Type': 'application/json',
+  'X-Agent-Key': config.agentKey,
+};
+
+class ApiResponseError extends Error {
+  status: number;
+  data: unknown;
+  constructor(status: number, data: unknown) {
+    const msg = (data as any)?.message || (data as any)?.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: Response): Promise<never> {
+  const data = await response.json().catch(() => ({}));
+  throw new ApiResponseError(response.status, data);
+}
+
+/** Unwrap fetch response and propagate API errors cleanly */
+export async function apiGet<T>(path: string, params?: Record<string, any>): Promise<T> {
+  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(30_000),
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json() as Promise<T>;
+}
+
+export async function apiPost<T>(path: string, body?: unknown): Promise<T> {
+  const response = await fetch(`${config.apiUrl}${path}`, {
+    method: 'POST',
+    headers: DEFAULT_HEADERS,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json() as Promise<T>;
+}
+
+export async function apiDelete<T>(path: string): Promise<T> {
+  const response = await fetch(`${config.apiUrl}${path}`, {
+    method: 'DELETE',
+    headers: DEFAULT_HEADERS,
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json() as Promise<T>;
+}
+
+/** POST without X-Agent-Key — for public endpoints like /agent/register */
+export async function publicApiPost<T>(path: string, body?: unknown): Promise<T> {
+  const response = await fetch(`${config.apiUrl}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) return parseErrorResponse(response);
+  return response.json() as Promise<T>;
+}

package/src/config.ts

@@ -0,0 +1,10 @@
+import 'dotenv/config';
+
+export const 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.');
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Solo Mission MCP Server
+ * Exposes 15 tools for AI agents to interact with the Solo Mission Platform.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// Tool definitions
+import { missionTools, handleMissionTool } from './tools/missions.js';
+import { humanTools, handleHumanTool } from './tools/humans.js';
+import { conversationTools, handleConversationTool } from './tools/conversations.js';
+import { realtimeTools, handleRealtimeTool } from './tools/realtime.js';
+import { agentTools, handleAgentTool } from './tools/agent.js';
+import { trackTools, handleTrackTool } from './tools/tracks.js';
+
+const ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools];
+
+const AGENT_TOOL_NAMES = new Set(agentTools.map((t) => t.name));
+const MISSION_TOOL_NAMES = new Set(missionTools.map((t) => t.name));
+const HUMAN_TOOL_NAMES = new Set(humanTools.map((t) => t.name));
+const CONVERSATION_TOOL_NAMES = new Set(conversationTools.map((t) => t.name));
+const REALTIME_TOOL_NAMES = new Set(realtimeTools.map((t) => t.name));
+const TRACK_TOOL_NAMES = new Set(trackTools.map((t) => t.name));
+
+const 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: unknown;
+
+    if (AGENT_TOOL_NAMES.has(name)) {
+      result = await handleAgentTool(name, args as Record<string, any>);
+    } else if (MISSION_TOOL_NAMES.has(name)) {
+      result = await handleMissionTool(name, args as Record<string, any>);
+    } else if (HUMAN_TOOL_NAMES.has(name)) {
+      result = await handleHumanTool(name, args as Record<string, any>);
+    } else if (CONVERSATION_TOOL_NAMES.has(name)) {
+      result = await handleConversationTool(name, args as Record<string, any>);
+    } else if (REALTIME_TOOL_NAMES.has(name)) {
+      result = await handleRealtimeTool(name, args as Record<string, any>);
+    } else if (TRACK_TOOL_NAMES.has(name)) {
+      result = await handleTrackTool(name, args as Record<string, any>);
+    } else {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (error: any) {
+    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);
+  // Server runs until process exits
+}
+
+main().catch((err) => {
+  console.error('Failed to start solo-mission-mcp:', err);
+  process.exit(1);
+});

package/src/realtime/missionPoller.ts

@@ -0,0 +1,104 @@
+import { apiGet } from '../api/client.js';
+
+export interface MissionUpdate {
+  mission_id: string;
+  type: 'new_participant';
+  participant: {
+    uid: string;
+    user_id: string;
+    joined_at: string;
+    conversation_id?: string;
+  };
+}
+
+interface MissionWatchState {
+  intervalId: ReturnType<typeof setInterval>;
+  knownParticipantUids: Set<string>;
+  queue: MissionUpdate[];
+}
+
+interface MissionResponse {
+  mission: { mission_id: string };
+  participants: Array<{
+    uid: string;
+    user_id: string;
+    joined_at: string;
+    conversation_id?: string;
+  }>;
+}
+
+/** In-process store: missionId → watch state */
+const missionWatches = new Map<string, MissionWatchState>();
+
+/**
+ * Start polling a mission for new participants.
+ * Already-known participants at watch time are seeded into knownParticipantUids.
+ */
+export async function startMissionPolling(missionId: string, intervalMinutes = 10): Promise<void> {
+  if (missionWatches.has(missionId)) return;
+
+  // Seed known participants so we only surface new ones going forward
+  let knownParticipantUids = new Set<string>();
+  try {
+    const data = await apiGet<MissionResponse>(`/agent/missions/${missionId}`);
+    for (const p of data.participants ?? []) {
+      knownParticipantUids.add(p.uid);
+    }
+  } catch {
+    // If initial fetch fails, start with empty set so all participants are surfaced on first tick
+  }
+
+  const intervalMs = intervalMinutes * 60 * 1000;
+
+  const state: MissionWatchState = {
+    knownParticipantUids,
+    queue: [],
+    intervalId: setInterval(async () => {
+      try {
+        const data = await apiGet<MissionResponse>(`/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 {
+        // Silently ignore transient errors; polling continues
+      }
+    }, intervalMs),
+  };
+
+  missionWatches.set(missionId, state);
+}
+
+/** Return and clear all buffered mission updates. */
+export function drainMissionQueue(missionId: string): MissionUpdate[] {
+  const state = missionWatches.get(missionId);
+  if (!state) return [];
+  const updates = [...state.queue];
+  state.queue = [];
+  return updates;
+}
+
+/** Stop polling a mission. */
+export function stopMissionPolling(missionId: string): boolean {
+  const state = missionWatches.get(missionId);
+  if (!state) return false;
+  clearInterval(state.intervalId);
+  missionWatches.delete(missionId);
+  return true;
+}
+
+/** Return list of currently watched mission IDs. */
+export function listWatchedMissions(): string[] {
+  return [...missionWatches.keys()];
+}

package/src/realtime/poller.ts

@@ -0,0 +1,128 @@
+import { apiGet } from '../api/client.js';
+
+interface QueuedMessage {
+  conversation_id: string;
+  message_id: string;
+  sender_type: 'agent' | 'human';
+  sender_id: string;
+  content: string;
+  created_at: string;
+}
+
+interface MessagesResponse {
+  messages: QueuedMessage[];
+}
+
+interface WatchState {
+  timeoutId: ReturnType<typeof setTimeout> | null;
+  fibStep: number;
+  lastSeen: string;
+  queue: QueuedMessage[];
+}
+
+/** In-process store: conversationId → watch state */
+const watches = new Map<string, WatchState>();
+
+const FIBONACCI_MS = [
+  1_000, 1_000, 2_000, 3_000, 5_000, 8_000, 13_000,
+  21_000, 34_000, 55_000, 89_000, 144_000, 233_000, 377_000, 600_000,
+];
+
+function getFibMs(step: number): number {
+  return FIBONACCI_MS[Math.min(step, FIBONACCI_MS.length - 1)];
+}
+
+function scheduleNext(conversationId: string, state: WatchState): void {
+  state.timeoutId = setTimeout(() => pollOnce(conversationId, state), getFibMs(state.fibStep));
+}
+
+async function pollOnce(conversationId: string, state: WatchState): Promise<void> {
+  if (!watches.has(conversationId)) return;
+  try {
+    const data = await apiGet<MessagesResponse>(
+      `/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) {
+        // The API returns created_at as a Firestore Timestamp object { _seconds, _nanoseconds }
+        // or sometimes as a string. Normalise to ISO string so it's safe to use as a query param.
+        const raw = latest.created_at as any;
+        if (typeof raw === 'string') {
+          state.lastSeen = raw;
+        } else if (raw?._seconds !== undefined) {
+          state.lastSeen = new Date(raw._seconds * 1000 + Math.floor((raw._nanoseconds ?? 0) / 1_000_000)).toISOString();
+        } else if (raw?.seconds !== undefined) {
+          state.lastSeen = new Date(raw.seconds * 1000).toISOString();
+        }
+      }
+      // Human replied — reset to step 0 (1s)
+      if (msgs.some(m => m.sender_type === 'human')) {
+        state.fibStep = 0;
+      }
+    } else {
+      // No new messages — advance to next Fibonacci step
+      state.fibStep = Math.min(state.fibStep + 1, FIBONACCI_MS.length - 1);
+    }
+  } catch {
+    // Silently ignore transient errors; polling continues
+  }
+  if (watches.has(conversationId)) {
+    scheduleNext(conversationId, state);
+  }
+}
+
+/**
+ * Start polling a conversation for new messages.
+ * Uses Fibonacci delay schedule: starts at 1s, advances on each miss, resets to 1s on human reply, caps at 600s.
+ */
+export function startPolling(conversationId: string): void {
+  if (watches.has(conversationId)) return;
+
+  const state: WatchState = {
+    timeoutId: null,
+    fibStep: 0,
+    lastSeen: new Date().toISOString(),
+    queue: [],
+  };
+
+  watches.set(conversationId, state);
+  scheduleNext(conversationId, state);
+}
+
+/**
+ * Return and clear all buffered messages for a conversation.
+ */
+export function drainQueue(conversationId: string): QueuedMessage[] {
+  const state = watches.get(conversationId);
+  if (!state) return [];
+  const msgs = [...state.queue];
+  state.queue = [];
+  return msgs;
+}
+
+/**
+ * Stop polling a conversation.
+ */
+export function stopPolling(conversationId: string): boolean {
+  const state = watches.get(conversationId);
+  if (!state) return false;
+  if (state.timeoutId !== null) clearTimeout(state.timeoutId);
+  watches.delete(conversationId);
+  return true;
+}
+
+/** Return list of currently watched conversation IDs */
+export function listWatched(): string[] {
+  return [...watches.keys()];
+}
+
+/** Return current poll interval for a conversation (ms), or null if not watched */
+export function getPollIntervalMs(conversationId: string): number | null {
+  const state = watches.get(conversationId);
+  if (!state) return null;
+  return getFibMs(state.fibStep);
+}

package/src/tools/agent.ts

@@ -0,0 +1,34 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { publicApiPost } from '../api/client.js';
+
+export const agentTools: Tool[] = [
+  {
+    name: 'register_agent',
+    description:
+      'Self-register a new agent on the Solo platform. No existing agent key required. ' +
+      'Returns agent_id and api_key — 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–50 characters)',
+          minLength: 3,
+          maxLength: 50,
+        },
+      },
+      required: ['name'],
+    },
+  },
+];
+
+export async function handleAgentTool(name: string, args: Record<string, any>): Promise<unknown> {
+  switch (name) {
+    case 'register_agent':
+      return publicApiPost('/agent/register', { name: args.name });
+
+    default:
+      throw new Error(`Unknown agent tool: ${name}`);
+  }
+}

package/src/tools/conversations.ts

@@ -0,0 +1,158 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { apiGet, apiPost } from '../api/client.js';
+import { stopPolling } from '../realtime/poller.js';
+
+export const conversationTools: Tool[] = [
+  {
+    name: 'start_conversation',
+    description: 'Start a new conversation with a human. Idempotent — 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 — 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 — 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'],
+    },
+  },
+];
+
+export async function handleConversationTool(name: string, args: Record<string, any>): Promise<unknown> {
+  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: Record<string, any> = {};
+      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)) as { upload_url: string; storage_path: string };
+      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: Record<string, unknown> = { 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: Record<string, any> = {};
+      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}`);
+      // Auto-unwatch if closing (no point polling a closed conversation)
+      if (args.action === 'close') {
+        stopPolling(args.conversation_id as string);
+      }
+      return result;
+    }
+
+    default:
+      throw new Error(`Unknown conversation tool: ${name}`);
+  }
+}

package/src/tools/humans.ts

@@ -0,0 +1,58 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { apiGet } from '../api/client.js';
+
+export const humanTools: Tool[] = [
+  {
+    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–5)' },
+        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'],
+    },
+  },
+];
+
+export async function handleHumanTool(name: string, args: Record<string, any>): Promise<unknown> {
+  switch (name) {
+    case 'browse_humans': {
+      const params: Record<string, any> = {};
+      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 !== undefined) params.min_rating = args.min_rating;
+      if (args.max_hourly_rate !== undefined) params.max_hourly_rate = args.max_hourly_rate;
+      if (args.min_tier !== undefined) 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}`);
+  }
+}