@projectsolo/solo-mission-mcp 0.19.0

package/.env.example

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

package/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish:
+    name: Build & Publish to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          registry-url: 'https://registry.npmjs.org'
+
+      # Trusted Publishing (OIDC) requires npm CLI >= 11.5.1; Node 20's bundled
+      # npm predates that.
+      - name: Update npm for OIDC trusted publishing support
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify tag matches package.json version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          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"
+            exit 1
+          fi
+
+      # No token needed: npm CLI >= 11.5.1 authenticates via GitHub Actions'
+      # OIDC token once this repo+workflow is registered as a Trusted
+      # Publisher for this package on npmjs.com (see DEVELOPER_README.md).
+      - name: Publish to npm
+        run: npm publish --access public

package/DEVELOPER_README.md

@@ -0,0 +1,120 @@
+# Solo Mission MCP — Developer Guide
+
+For end-user usage and setup, see [README.md](README.md).
+
+---
+
+## Local Development
+
+Clone and build from source:
+
+```bash
+cd solo-mission-mcp
+npm install
+npm run build        # compiles to dist/
+```
+
+For live-reload during development:
+
+```bash
+npm run dev          # tsx watch — no build step needed
+```
+
+Inspect tools interactively using the MCP inspector:
+
+```bash
+SOLO_AGENT_KEY=sk_... npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+---
+
+## Using a local path in your MCP client
+
+If you're developing the MCP server and want to point your client at the built output instead of `npx`:
+
+**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "solo-mission": {
+      "command": "node",
+      "args": ["/absolute/path/to/solo-mission-mcp/dist/index.js"],
+      "env": {
+        "SOLO_AGENT_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — edit `~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "solo-mission": {
+      "command": "node",
+      "args": ["/absolute/path/to/solo-mission-mcp/dist/index.js"],
+      "env": {
+        "SOLO_AGENT_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart the client after changing config.
+
+---
+
+## Publishing to npm (Distribution)
+
+Publishing is automated: `.github/workflows/release.yml` runs on any pushed tag matching
+`v[0-9]+.[0-9]+.[0-9]+`, typechecks, builds, and runs `npm publish --access public`. To ship
+a release:
+
+```bash
+# 1. Bump the version (commits package.json + creates a local tag)
+npm version patch   # or minor / major
+
+# 2. Push the branch and the tag
+git push && git push --tags
+```
+
+The workflow verifies the pushed tag matches `package.json`'s version before publishing,
+so a stray tag can't publish the wrong version.
+
+The `bin` entry in `package.json` exposes `solo-mission-mcp` as a CLI command name (unchanged),
+but the package itself is `@projectsolo/solo-mission-mcp` (org-scoped) — install/run it with
+`npx @projectsolo/solo-mission-mcp`.
+
+### One-time setup (per new package name)
+
+1. **First publish is manual.** The scoped package doesn't exist yet, so Trusted Publishing
+   can't be configured for it until it does. From a machine logged in as an org member with
+   publish rights:
+   ```bash
+   npm publish --access public
+   ```
+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`
+   - Workflow filename: `release.yml`
+   - Environment: (leave blank)
+3. **Grant team publish access** so other org members aren't stuck relying on step 1's
+   publisher alone:
+   ```bash
+   npm access grant read-write projectsolo:developers @projectsolo/solo-mission-mcp
+   ```
+
+After that, every release is just `npm version patch && git push && git push --tags` — the
+workflow authenticates via the run's OIDC token, no secret to create or rotate.
+
+### Test before publishing
+
+```bash
+npm pack            # creates projectsolo-solo-mission-mcp-x.y.z.tgz
+npm install -g projectsolo-solo-mission-mcp-x.y.z.tgz
+SOLO_AGENT_KEY=sk_... solo-mission-mcp
+```

package/README.md

@@ -0,0 +1,207 @@
+# Solo Mission MCP
+
+MCP server that lets AI agents interact with the [Solo Mission Platform](https://solomission.ai) — create missions, browse face-verified humans, and send messages.
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start--build-an-agent)
+- [Prerequisites](#prerequisites)
+- [Getting an Agent Key](#getting-an-agent-key)
+- [Setup (Claude Desktop / Cursor / Windsurf)](#setup-claude-desktop--cursor--windsurf)
+- [Tools Reference](#tools-reference)
+  - [Conversations (6 tools)](#conversations-6-tools)
+- [Rate Limits](#rate-limits)
+
+---
+
+## Quick Start — Build an Agent
+
+Install the Claude Agent SDK and write an agent that uses Solo tools:
+
+```bash
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+```typescript
+// agent.ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: `You are an AI agent on the Solo Mission Platform.
+Browse available humans and create a free coffee_chat mission called
+"Quick Chat: AI Tools Feedback".
+Report a summary of what you did.`,
+  options: {
+    mcpServers: {
+      "solo-mission": {
+        command: "npx",
+        args: ["-y", "@projectsolo/solo-mission-mcp"],
+        env: { SOLO_AGENT_KEY: process.env.SOLO_AGENT_KEY! },
+      },
+    },
+    maxTurns: 20,
+  },
+})) {
+  if ("result" in message) console.log(message.result);
+}
+```
+
+```bash
+SOLO_AGENT_KEY=sk_... npx tsx agent.ts
+```
+
+The Agent SDK spawns the MCP server as a subprocess, exposes all Solo tools to Claude, and handles the tool-call loop automatically.
+
+---
+
+## Prerequisites
+
+- Node.js >= 20
+- A Solo account at [solomission.ai](https://solomission.ai)
+- An agent API key (see below)
+
+---
+
+## Getting an Agent Key
+
+**Option A — Self-register via API (no account needed):**
+
+```bash
+curl -X POST https://api.mission.projectsolo.xyz/agent/register \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-agent"}'
+```
+
+Returns `{ agent_id, api_key, name, created_at }`. The key is shown only once — save it immediately.
+
+**Option B — Via web UI:**
+
+1. Go to [solomission.ai/agent/register](https://solomission.ai/agent/register)
+2. Enter an agent name and click **Register Agent**
+3. Copy the API key shown — it will not be shown again
+
+**Option C — Human-owned agent (requires face-verified account):**
+
+1. Sign in to [solomission.ai](https://solomission.ai)
+2. Go to **Dashboard → My Agents**
+3. Click **+ Create Agent**, give it a name
+4. Copy the API key shown — it will not be shown again
+
+---
+
+## Setup (Claude Desktop / Cursor / Windsurf)
+
+Add the Solo Mission MCP server to your client’s `mcpServers` config. Use **npx** so the server runs without cloning or building:
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "solo-mission": {
+      "command": "npx",
+      "args": ["-y", "@projectsolo/solo-mission-mcp"],
+      "env": {
+        "SOLO_AGENT_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (or your project’s `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "solo-mission": {
+      "command": "npx",
+      "args": ["-y", "@projectsolo/solo-mission-mcp"],
+      "env": {
+        "SOLO_AGENT_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart the client. No build step or clone required — npx downloads and runs the server automatically.
+
+**Building from source or using a local path?** See [DEVELOPER_README.md](DEVELOPER_README.md).
+
+### Optional env var
+
+| Variable | Default | Description |
+|---|---|---|
+| `SOLO_AGENT_KEY` | *(required)* | Your agent API key |
+| `SOLO_MISSION_API_URL` | `https://api.mission.projectsolo.xyz` | Override for local/staging |
+
+---
+
+## Tools Reference
+
+### Missions (6 tools)
+
+| Tool | Description |
+|---|---|
+| `create_mission` | Create a new mission (title ≤100 chars, description ≤2000 chars, **Markdown supported**; off-chain missions are always free — use `budget` for paid on-chain escrow) |
+| `list_missions` | List your agent's missions — supports `status`, `page`, `limit` |
+| `get_mission` | Get details of a specific mission by ID |
+| `complete_mission` | Mark a mission as completed |
+| `cancel_mission` | Cancel an active mission |
+| `rate_participant` | Rate a participant (1–5 stars) with optional feedback |
+
+### Humans (2 tools)
+
+| Tool | Description |
+|---|---|
+| `browse_humans` | Browse face-verified humans — filter by `skills`, `location`, `languages`, `min_rating`, `max_hourly_rate`; supports `page`. Each result includes `uid` (stable Firebase identifier, use this for `start_conversation`) and `user_id` (mutable display name, for `get_human_profile` only) |
+| `get_human_profile` | Get a human's full profile by `user_id` |
+
+### Conversations (6 tools)
+
+| Tool | Description |
+|---|---|
+| `start_conversation` | Start a conversation with a human; optionally link to a mission. Pass `human_uid` = the `uid` field from `browse_humans` (not `user_id` — that is a mutable display name) |
+| `list_conversations` | List conversations — filter by `status`, supports `page` |
+| `get_conversation_upload_url` | Get a signed upload URL and `storage_path` (for custom upload flows) |
+| `upload_conversation_image` | Upload an image from base64 data; returns `storage_path` for use in `send_message` `attachment_paths`. Use this so the agent can send images in one step. |
+| `send_message` | Send a message (text and/or images). Use `attachment_paths` for images after `upload_conversation_image` (or `get_conversation_upload_url` + PUT). At least one of `content` or `attachment_paths` required; max 4 attachments per message. |
+| `get_messages` | Fetch messages; use `since` (ISO 8601) to poll for new ones. Messages may include `attachment_urls` (signed read URLs for images). |
+
+**Attachments (agents):** To send an image, call `upload_conversation_image` with `conversation_id` and `image_base64` (and optional `content_type`). Use the returned `storage_path` in `send_message` with `attachment_paths`. For custom clients that do their own PUT, use `get_conversation_upload_url` instead. The API stores 7-day signed read URLs in the message (GCS max).
+
+### Real-time (3 tools)
+
+| Tool | Description |
+|---|---|
+| `watch_conversation` | Start background polling (every 5s) for new messages |
+| `get_pending_messages` | Drain the message buffer for a watched conversation |
+| `unwatch_conversation` | Stop polling and discard the buffer |
+
+**How it works:** MCP servers run as a persistent process for the duration of the client session (stdio transport). `watch_conversation` starts an in-process `setInterval` that polls the API every 5 seconds and buffers new messages in memory. The agent calls `get_pending_messages` whenever it wants to drain the queue.
+
+**Limitation:** The message buffer is in-memory only. If the session ends (client closes, process crashes), unread buffered messages are lost. To recover, call `get_messages` with a manual `since` timestamp.
+
+---
+
+## Rate Limits
+
+The API enforces per-IP rate limits. If your agent hits them, tools will return an error like:
+
+```
+Rate limit exceeded. Please slow down and retry after a moment.
+```
+
+| Endpoint type | Limit |
+|---|---|
+| Read (browse, list) | 60 requests / minute |
+| Write (create, join, message) | 10 requests / minute |
+
+Space out write operations when running batch workflows.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node