@projectsolo/solo-mission-mcp 0.21.11 → 0.21.14

package/DEVELOPER_README.md

@@ -99,7 +99,7 @@ but the package itself is `@projectsolo/solo-mission-mcp` (org-scoped) — insta
    ```
 2. **Register Trusted Publishing.** On https://www.npmjs.com, open
    `@projectsolo/solo-mission-mcp` → **Settings → Trusted Publisher → GitHub Actions**:
-   - Organization/repo: `ProjectSoloXYZ/solo_mission_mcp`
+   - Organization/repo: `ProjectSoloAI/solo_mission_mcp`
    - Workflow filename: `release.yml`
    - Environment: (leave blank)
 3. **Grant team publish access** so other org members aren't stuck relying on step 1's

package/dist/index.js

@@ -19,7 +19,7 @@ import {
 var RESPONSE_SCHEMA_PROPERTY = {
   type: "array",
   maxItems: 20,
-  description: 'Structured completion questions a human answers to complete the mission. Question ids must be unique within one schema \u2014 a duplicate id is rejected at creation/update, not merged or silently overwritten. When set, finalize_qualification auto-derives qualified UIDs from completion instead of requiring an explicit qualified_human_uids list \u2014 same mechanism media_review has always used for track ratings, generalized to any mission type. media_review defaults to a canonical two-question schema when this is omitted at creation \u2014 literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", required: false } \u2014 so read/append against those exact ids if you rely on the default rather than supplying your own schema. Every other type has no default (stays fully manual/chat-based unless you set this).',
+  description: 'Structured completion questions a human answers to complete the mission. Question ids must be unique within one schema \u2014 a duplicate id is rejected at creation/update, not merged or silently overwritten. When set, finalize_qualification auto-derives qualified UIDs from completion instead of requiring an explicit qualified_human_uids list \u2014 same mechanism media_review has always used for track ratings, generalized to any mission type. media_review defaults to a canonical two-question schema when this is omitted at creation \u2014 literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", required: true } \u2014 so read/append against those exact ids if you rely on the default rather than supplying your own schema. Every other type has no default (stays fully manual/chat-based unless you set this).',
   items: {
     type: "object",
     properties: {
@@ -43,7 +43,10 @@ var RESPONSE_SCHEMA_PROPERTY = {
       },
       label: { type: "string", description: "Question text shown to the human (max 200 chars). For the checkbox kind this is the checkbox's own clickable text, not a separate heading." },
       help: { type: "string", description: "Optional helper text shown under the label (max 500 chars)." },
-      required: { type: "boolean", description: "Whether this question must be answered to complete the mission." },
+      required: {
+        type: "boolean",
+        description: "Whether this question must be answered to complete the mission. A required: false question does NOT block mission completion or finalize_qualification's auto-qualification \u2014 both derive purely from the required questions, so an optional question left blank (or still being typed into) will not stop either from firing the instant the required ones are answered. If every question in the schema should actually be answered, mark them all required: true; reserve required: false for a genuinely optional/skippable field."
+      },
       options: {
         type: "array",
         items: { type: "string" },
@@ -95,7 +98,7 @@ var missionTools = [
         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: 0.0166, 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. Backend floor is 60s (0.0166h), same for every chain \u2014 see work_duration_hours for the reasoning." },
         work_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) hired participants have to complete the work. Agent must call settle_mission before this period ends. Backend floor is 60s (0.0166h) for every chain \u2014 this is a flat sanity check against a near-zero window, not a guarantee of a legal settlement window on every chain: Base's own EscrowVault contract separately enforces its own fixed 1-hour minimum regardless of what this floor allows through, so a too-short Base mission still fails downstream (at finalize_qualification, or on-chain) instead of being caught at creation." },
-        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." },
+        auto_accept_applicants: { type: "boolean", description: "Defaults to true \u2014 applicants are automatically hired when they apply, no manual hire_participant call needed, first-come first-served up to max_humans, face verification still required. Pass false to opt into manual review instead (see hire_participant for how unreviewed applicants are still handled once the hiring window closes)." },
         response_schema: RESPONSE_SCHEMA_PROPERTY
       },
       required: ["type", "title", "description"]
@@ -875,17 +878,25 @@ async function handleAgentTool(name, args) {
 }
 
 // src/tools/tracks.ts
+import { readFile } from "fs/promises";
 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.",
+    description: "Upload a media item (audio, image, or video) to a media_review mission. Provide the file EITHER via file_path (the MCP server reads it from local disk and uploads it directly \u2014 use this for audio/video, since inlining a multi-MB file as base64 in the tool call can exceed the calling agent's own tool-call or context limits, causing a silent client-side failure before any request reaches the API) OR inline as file_base64 (fine for small images). Exactly one of the two is required. 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" },
+        file_path: {
+          type: "string",
+          description: "Path to a local file to upload, as an alternative to file_base64. The MCP server reads this file itself and PUTs it to the signed upload URL, so the calling agent only needs to pass the path \u2014 not the file contents. Prefer this for audio/video files. Use an absolute path: a relative path resolves against the MCP server process's working directory, not the caller's. Exactly one of file_base64 or file_path is required."
+        },
+        file_base64: {
+          type: "string",
+          description: "Base64-encoded file contents, as an alternative to file_path. Fine for small images; for audio/video prefer file_path \u2014 encoding a multi-MB file inline can exceed the calling agent's own tool-call or context limits. Exactly one of file_base64 or file_path is required."
+        },
         content_type: {
           type: "string",
           enum: ["audio/mpeg", "audio/mp4", "image/jpeg", "image/png", "image/webp", "video/mp4"],
@@ -893,7 +904,7 @@ var trackTools = [
         },
         duration_seconds: { type: "number", description: "Duration in seconds (optional; applicable to audio and video only)" }
       },
-      required: ["mission_id", "title", "file_base64", "content_type"]
+      required: ["mission_id", "title", "content_type"]
     }
   },
   {
@@ -935,12 +946,27 @@ var trackTools = [
 async function handleTrackTool(name, args) {
   switch (name) {
     case "add_mission_track": {
-      const { mission_id, title, artist, file_base64, content_type, duration_seconds } = args;
+      const { mission_id, title, artist, file_base64, file_path, content_type, duration_seconds } = args;
+      if (!file_base64 && !file_path) {
+        throw new Error("add_mission_track requires either file_base64 or file_path");
+      }
+      if (file_base64 && file_path) {
+        throw new Error("add_mission_track accepts only one of file_base64 or file_path, not both");
+      }
+      let fileBytes;
+      if (file_path) {
+        try {
+          fileBytes = await readFile(file_path);
+        } catch (err) {
+          throw new Error(`Could not read file_path "${file_path}": ${err.message}`);
+        }
+      } else {
+        fileBytes = Buffer.from(file_base64, "base64");
+      }
       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 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectsolo/solo-mission-mcp",
-  "version": "0.21.11",
+  "version": "0.21.14",
   "description": "MCP server for Solo Mission Platform — lets AI agents create missions, browse humans, and chat.",
   "type": "module",
   "main": "dist/index.js",

package/src/tools/missions.ts

@@ -26,7 +26,7 @@ const RESPONSE_SCHEMA_PROPERTY = {
     'media_review has always used for track ratings, generalized to any mission type. ' +
     'media_review defaults to a canonical two-question schema when this is omitted at creation — ' +
     'literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", ' +
-    'required: false } — so read/append against those exact ids if you rely on the default rather ' +
+    'required: true } — so read/append against those exact ids if you rely on the default rather ' +
     'than supplying your own schema. Every other type has no default (stays fully manual/chat-based ' +
     'unless you set this).',
   items: {
@@ -63,7 +63,16 @@ const RESPONSE_SCHEMA_PROPERTY = {
       },
       label: { type: 'string', description: 'Question text shown to the human (max 200 chars). For the checkbox kind this is the checkbox\'s own clickable text, not a separate heading.' },
       help: { type: 'string', description: 'Optional helper text shown under the label (max 500 chars).' },
-      required: { type: 'boolean', description: 'Whether this question must be answered to complete the mission.' },
+      required: {
+        type: 'boolean',
+        description:
+          'Whether this question must be answered to complete the mission. A required: false question ' +
+          'does NOT block mission completion or finalize_qualification\'s auto-qualification — both ' +
+          'derive purely from the required questions, so an optional question left blank (or still ' +
+          'being typed into) will not stop either from firing the instant the required ones are ' +
+          'answered. If every question in the schema should actually be answered, mark them all ' +
+          'required: true; reserve required: false for a genuinely optional/skippable field.',
+      },
       options: {
         type: 'array',
         items: { type: 'string' },
@@ -116,7 +125,7 @@ export const missionTools: Tool[] = [
         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: 0.0166, 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. Backend floor is 60s (0.0166h), same for every chain — see work_duration_hours for the reasoning.' },
         work_duration_hours: { type: 'number', minimum: 0.0166, description: 'How long (hours) hired participants have to complete the work. Agent must call settle_mission before this period ends. Backend floor is 60s (0.0166h) for every chain — this is a flat sanity check against a near-zero window, not a guarantee of a legal settlement window on every chain: Base\'s own EscrowVault contract separately enforces its own fixed 1-hour minimum regardless of what this floor allows through, so a too-short Base mission still fails downstream (at finalize_qualification, or on-chain) instead of being caught at creation.' },
-        auto_accept_applicants: { type: 'boolean', description: 'When true, applicants are automatically hired when they apply — 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.' },
+        auto_accept_applicants: { type: 'boolean', description: 'Defaults to true — applicants are automatically hired when they apply, no manual hire_participant call needed, first-come first-served up to max_humans, face verification still required. Pass false to opt into manual review instead (see hire_participant for how unreviewed applicants are still handled once the hiring window closes).' },
         response_schema: RESPONSE_SCHEMA_PROPERTY,
       },
       required: ['type', 'title', 'description'],

package/src/tools/tracks.test.ts

@@ -0,0 +1,151 @@
+/**
+ * `add_mission_track` accepts a file two ways: base64 inline in the tool-call args, or a local
+ * file_path the MCP server reads itself. The file_path option exists because inlining a multi-MB
+ * audio/video file as base64 can blow past the CALLING AGENT's own tool-call or context limits —
+ * a client-side failure that never reaches solo-firebase at all (root-caused against mission
+ * nJskovWGfrbfVu6gU3b5, where zero upload requests hit the backend). These tests cover the
+ * validation/ordering around that new path, plus a regression check that file_base64 still works
+ * unchanged.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const apiPost = vi.fn();
+const apiGet = vi.fn();
+const apiDelete = vi.fn();
+
+vi.mock('../api/client.js', () => ({
+  apiPost: (...args: unknown[]) => apiPost(...args),
+  apiGet: (...args: unknown[]) => apiGet(...args),
+  apiDelete: (...args: unknown[]) => apiDelete(...args),
+}));
+
+import { handleTrackTool } from './tracks.js';
+
+describe('add_mission_track', () => {
+  let tmpDir: string;
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'solo-mcp-track-'));
+    apiPost.mockReset();
+    apiGet.mockReset();
+    apiDelete.mockReset();
+    fetchMock = vi.fn().mockResolvedValue({ ok: true, text: async () => '' });
+    vi.stubGlobal('fetch', fetchMock);
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    vi.unstubAllGlobals();
+  });
+
+  function mockHappyPathApi() {
+    apiPost.mockImplementation(async (path: string) => {
+      if (path.endsWith('/tracks/upload-url')) {
+        return { upload_url: 'https://storage.example/signed-put', storage_path: 'x/y.mp3', track_id: 'trk_1' };
+      }
+      if (path.endsWith('/confirm')) {
+        return { track: { id: 'trk_1', title: 'My Track' } };
+      }
+      throw new Error(`Unexpected apiPost call: ${path}`);
+    });
+  }
+
+  it('reads the file from file_path and PUTs its exact bytes to the signed URL', async () => {
+    mockHappyPathApi();
+    const filePath = join(tmpDir, 'song.mp3');
+    const contents = Buffer.from('fake mp3 bytes');
+    writeFileSync(filePath, contents);
+
+    const result = await handleTrackTool('add_mission_track', {
+      mission_id: 'm1',
+      title: 'My Track',
+      content_type: 'audio/mpeg',
+      file_path: filePath,
+    });
+
+    expect(result).toEqual({ id: 'trk_1', title: 'My Track' });
+    expect(apiPost).toHaveBeenCalledWith('/agent/missions/m1/tracks/upload-url', {
+      title: 'My Track',
+      artist: undefined,
+      content_type: 'audio/mpeg',
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://storage.example/signed-put');
+    expect(init.method).toBe('PUT');
+    expect(Buffer.isBuffer(init.body) ? init.body : Buffer.from(init.body)).toEqual(contents);
+  });
+
+  it('still accepts inline file_base64 unchanged (regression)', async () => {
+    mockHappyPathApi();
+    const contents = Buffer.from('fake image bytes');
+
+    await handleTrackTool('add_mission_track', {
+      mission_id: 'm1',
+      title: 'My Image',
+      content_type: 'image/png',
+      file_base64: contents.toString('base64'),
+    });
+
+    const [, init] = fetchMock.mock.calls[0];
+    expect(Buffer.isBuffer(init.body) ? init.body : Buffer.from(init.body)).toEqual(contents);
+  });
+
+  it('rejects when neither file_base64 nor file_path is provided, without calling the API', async () => {
+    await expect(
+      handleTrackTool('add_mission_track', { mission_id: 'm1', title: 'X', content_type: 'audio/mpeg' }),
+    ).rejects.toThrow(/requires either file_base64 or file_path/);
+    expect(apiPost).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('rejects when both file_base64 and file_path are provided, without calling the API', async () => {
+    await expect(
+      handleTrackTool('add_mission_track', {
+        mission_id: 'm1',
+        title: 'X',
+        content_type: 'audio/mpeg',
+        file_base64: 'YWJj',
+        file_path: join(tmpDir, 'irrelevant.mp3'),
+      }),
+    ).rejects.toThrow(/only one of file_base64 or file_path/);
+    expect(apiPost).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('fails fast on an unreadable file_path, before creating a pending track doc', async () => {
+    await expect(
+      handleTrackTool('add_mission_track', {
+        mission_id: 'm1',
+        title: 'X',
+        content_type: 'audio/mpeg',
+        file_path: join(tmpDir, 'does-not-exist.mp3'),
+      }),
+    ).rejects.toThrow(/Could not read file_path/);
+    // The whole point of reading the file before Step 1: no upload-url/track doc created for a bad path.
+    expect(apiPost).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('deletes the pending track doc when the signed-URL PUT fails', async () => {
+    mockHappyPathApi();
+    apiDelete.mockResolvedValue(undefined);
+    fetchMock.mockResolvedValue({ ok: false, status: 500, text: async () => 'boom' });
+    const filePath = join(tmpDir, 'song.mp3');
+    writeFileSync(filePath, 'bytes');
+
+    await expect(
+      handleTrackTool('add_mission_track', {
+        mission_id: 'm1',
+        title: 'My Track',
+        content_type: 'audio/mpeg',
+        file_path: filePath,
+      }),
+    ).rejects.toThrow(/Media upload failed/);
+    expect(apiDelete).toHaveBeenCalledWith('/agent/missions/m1/tracks/trk_1');
+  });
+});

package/src/tools/tracks.ts

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { apiGet, apiPost, apiDelete } from '../api/client.js';
 
@@ -5,7 +6,11 @@ export const trackTools: Tool[] = [
   {
     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. ' +
+      'Upload a media item (audio, image, or video) to a media_review mission. Provide the file EITHER via file_path ' +
+      '(the MCP server reads it from local disk and uploads it directly — use this for audio/video, since inlining a ' +
+      'multi-MB file as base64 in the tool call can exceed the calling agent\'s own tool-call or context limits, ' +
+      'causing a silent client-side failure before any request reaches the API) OR inline as file_base64 (fine for ' +
+      'small images). Exactly one of the two is required. ' +
       'For on-chain missions, call this BEFORE confirm_funding — 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.',
@@ -15,7 +20,21 @@ export const trackTools: Tool[] = [
         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' },
+        file_path: {
+          type: 'string',
+          description:
+            'Path to a local file to upload, as an alternative to file_base64. The MCP server reads this file itself ' +
+            'and PUTs it to the signed upload URL, so the calling agent only needs to pass the path — not the file ' +
+            'contents. Prefer this for audio/video files. Use an absolute path: a relative path resolves against the ' +
+            "MCP server process's working directory, not the caller's. Exactly one of file_base64 or file_path is required.",
+        },
+        file_base64: {
+          type: 'string',
+          description:
+            'Base64-encoded file contents, as an alternative to file_path. Fine for small images; for audio/video ' +
+            'prefer file_path — encoding a multi-MB file inline can exceed the calling agent\'s own tool-call or ' +
+            'context limits. Exactly one of file_base64 or file_path is required.',
+        },
         content_type: {
           type: 'string',
           enum: ['audio/mpeg', 'audio/mp4', 'image/jpeg', 'image/png', 'image/webp', 'video/mp4'],
@@ -27,7 +46,7 @@ export const trackTools: Tool[] = [
         },
         duration_seconds: { type: 'number', description: 'Duration in seconds (optional; applicable to audio and video only)' },
       },
-      required: ['mission_id', 'title', 'file_base64', 'content_type'],
+      required: ['mission_id', 'title', 'content_type'],
     },
   },
   {
@@ -76,7 +95,28 @@ export const trackTools: Tool[] = [
 export async function handleTrackTool(name: string, args: Record<string, any>): Promise<unknown> {
   switch (name) {
     case 'add_mission_track': {
-      const { mission_id, title, artist, file_base64, content_type, duration_seconds } = args;
+      const { mission_id, title, artist, file_base64, file_path, content_type, duration_seconds } = args;
+
+      if (!file_base64 && !file_path) {
+        throw new Error('add_mission_track requires either file_base64 or file_path');
+      }
+      if (file_base64 && file_path) {
+        throw new Error('add_mission_track accepts only one of file_base64 or file_path, not both');
+      }
+
+      // Read/decode the file up front, before creating any server-side state, so a
+      // missing or unreadable local file fails fast without leaving a pending track
+      // doc that would then need cleanup.
+      let fileBytes: Buffer;
+      if (file_path) {
+        try {
+          fileBytes = await readFile(file_path);
+        } catch (err) {
+          throw new Error(`Could not read file_path "${file_path}": ${(err as Error).message}`);
+        }
+      } else {
+        fileBytes = Buffer.from(file_base64, 'base64');
+      }
 
       // Step 1: Get signed upload URL and create pending track doc
       const urlRes = await apiPost<{ upload_url: string; storage_path: string; track_id: string }>(
@@ -87,7 +127,6 @@ export async function handleTrackTool(name: string, args: Record<string, any>):
       // Step 2: Upload binary to the signed URL.
       // On failure, delete the pending track doc so it doesn't consume the 20-track
       // slot or appear as a ghost in list results.
-      const fileBytes = Buffer.from(file_base64, 'base64');
       const uploadRes = await fetch(urlRes.upload_url, {
         method: 'PUT',
         headers: { 'Content-Type': content_type },