@projectsolo/solo-mission-mcp 0.19.2 → 0.19.3

package/.env.example

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

package/.github/workflows/release.yml

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

package/package.json

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

package/src/scripts/check-tools-against-spec.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env tsx
+/**
+ * Release gate: fails if solo-firebase's live OpenAPI spec documents a route that no
+ * MCP tool in this package actually calls.
+ *
+ * Companion to solo_firebase#196 (mission-api now serves GET /agent/openapi.json,
+ * generated live from its own route annotations) and solo_mission_web#156 (the same
+ * gate for the /developers page). Without something on this side checking against it,
+ * a live spec existing doesn't stop these tools from drifting the same way the docs
+ * page did in solo_mission_web#154.
+ *
+ * Direction of the check, and why: this package's tool set is intentionally BIGGER
+ * than what the spec currently covers (36 tools vs. 19 annotated operations — most of
+ * solo-firebase's mission-api routes aren't annotated yet, see solo_firebase#196's
+ * "next steps"). Checking "every REST call in this package must appear in the spec"
+ * would fail on every one of those un-annotated routes for no real reason. Checking
+ * the other direction — "every route the spec DOES document must be called by
+ * something here" — only walks the spec's small, well-defined set, so it stays
+ * meaningful without needing a maintained allowlist of which tools are in scope.
+ *
+ * Extraction is static regex over src/tools/*.ts (same approach as solo-firebase's own
+ * openapiSpecConformance.test.ts and solo-mission-web's check-dev-docs-against-spec.mjs
+ * — no runtime app boot, no live network call except the one spec fetch), matching
+ * apiGet/apiPost/apiPut/apiDelete/publicApiPost call sites, tolerating the generic type
+ * argument (apiPost<T>(...)) and multi-line calls actually used in this codebase.
+ * Template-literal interpolations (${args.mission_id}) and OpenAPI {id}-style path
+ * params are both normalized to a generic :param token and compared positionally —
+ * exact param names don't need to match, only path shape.
+ *
+ * Usage: npx tsx src/scripts/check-tools-against-spec.ts
+ * Override the spec URL (e.g. against a local/staging backend) with SPEC_URL=...
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOLS_DIR = join(__dirname, '../tools');
+const SPEC_URL = process.env.SPEC_URL ?? 'https://api.mission.projectsolo.ai/agent/openapi.json';
+
+const METHOD_BY_FN: Record<string, string> = {
+  apiGet: 'GET',
+  apiPost: 'POST',
+  apiPut: 'PUT',
+  apiDelete: 'DELETE',
+  publicApiPost: 'POST',
+};
+
+function normalizeParams(path: string): string {
+  return path
+    .split('?')[0] // strip query strings (e.g. the upload-url ?content_type=... calls)
+    .replace(/\$\{[^}]*\}/g, ':param') // template-literal interpolations
+    .replace(/\{[^}]*\}/g, ':param'); // OpenAPI {param} style, for symmetry if ever mixed in
+}
+
+/** Every "METHOD normalizedPath" this package's tools actually call, from any tools/*.ts file. */
+function extractCalledRoutes(): Set<string> {
+  const routes = new Set<string>();
+  const files = readdirSync(TOOLS_DIR).filter((f) => f.endsWith('.ts'));
+  const fnNames = Object.keys(METHOD_BY_FN).join('|');
+  // Matches both the common case — a string/template literal passed straight into the
+  // call — and an identifier (e.g. apiPost(path)) built from a `const path = \`...\``
+  // a line or two earlier, which conversations.ts's upload-url tools both do (the path
+  // there needs a query string appended, so it's assembled before the call).
+  const directCallPattern = new RegExp(`\\b(${fnNames})\\s*(?:<[^>]*>)?\\s*\\(\\s*(\`|'|")((?:(?!\\2).)*)\\2`, 'gs');
+  const indirectCallPattern = new RegExp(`\\b(${fnNames})\\s*(?:<[^>]*>)?\\s*\\(\\s*([A-Za-z_$][A-Za-z0-9_$]*)\\s*[,)]`, 'g');
+  const constAssignPattern = /const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(`|'|")((?:(?!\2).)*)\2/gs;
+
+  for (const file of files) {
+    const source = readFileSync(join(TOOLS_DIR, file), 'utf8');
+
+    let match: RegExpExecArray | null;
+    while ((match = directCallPattern.exec(source)) !== null) {
+      const [, fnName, , rawPath] = match;
+      routes.add(`${METHOD_BY_FN[fnName]} ${normalizeParams(rawPath)}`);
+    }
+
+    const localPaths = new Map<string, string>();
+    while ((match = constAssignPattern.exec(source)) !== null) {
+      const [, varName, , rawValue] = match;
+      if (rawValue.startsWith('/')) localPaths.set(varName, rawValue);
+    }
+    while ((match = indirectCallPattern.exec(source)) !== null) {
+      const [, fnName, varName] = match;
+      const rawPath = localPaths.get(varName);
+      if (rawPath) routes.add(`${METHOD_BY_FN[fnName]} ${normalizeParams(rawPath)}`);
+    }
+  }
+  return routes;
+}
+
+/** Every "METHOD normalizedPath" the live spec documents. */
+async function fetchSpecRoutes(): Promise<string[]> {
+  const res = await fetch(SPEC_URL);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${SPEC_URL}: HTTP ${res.status}`);
+  }
+  const spec = (await res.json()) as { paths?: Record<string, Record<string, unknown>> };
+  const routes: string[] = [];
+  for (const [openApiPath, operations] of Object.entries(spec.paths ?? {})) {
+    const normalizedPath = normalizeParams(openApiPath);
+    for (const method of Object.keys(operations)) {
+      routes.push(`${method.toUpperCase()} ${normalizedPath}`);
+    }
+  }
+  return routes;
+}
+
+const called = extractCalledRoutes();
+if (called.size < 10) {
+  // Sanity check on the extraction itself — if the call-site shape changes and the
+  // regex stops matching, fail loudly instead of silently passing on a near-empty set.
+  console.error(`Only extracted ${called.size} called routes from src/tools/*.ts — expected 15+. Regex may be out of sync with the call-site shape.`);
+  process.exit(1);
+}
+
+let specRoutes: string[];
+try {
+  specRoutes = await fetchSpecRoutes();
+} catch (err) {
+  console.error(`Could not verify tool coverage against the live API spec: ${(err as Error).message}`);
+  process.exit(1);
+}
+
+const uncalled = specRoutes.filter((route) => !called.has(route) && !route.endsWith('/agent/openapi.json'));
+
+if (uncalled.length > 0) {
+  console.error("The live API spec documents routes that no tool in src/tools/*.ts calls:");
+  for (const route of uncalled) console.error(`  - ${route}`);
+  console.error(`\nSpec source: ${SPEC_URL}`);
+  console.error("Either a tool's REST call was changed/removed without updating this check's");
+  console.error('expectations, or the backend added something here that this package should');
+  console.error('expose a tool for.');
+  process.exit(1);
+}
+
+console.log(`OK: all ${specRoutes.length} spec-documented routes are called by at least one tool.`);