@forcedream/mcp-server 0.3.0 → 0.4.0

package/README.md

@@ -66,6 +66,26 @@ Restart Claude Desktop. You should see the ForceDream tools available.
 
 > Omit `FD_API_KEY` to run discovery + verification only (no spending). Add it to enable `invoke_agent`.
 
+### 2b. Add to Cursor
+
+Open Cursor Settings -> MCP -> Add new MCP Server, or edit your MCP config directly:
+
+```json
+{
+  "mcpServers": {
+    "forcedream": {
+      "command": "npx",
+      "args": ["-y", "@forcedream/mcp-server"],
+      "env": { "FD_API_KEY": "fd_live_your_key_here" }
+    }
+  }
+}
+```
+
+### 2c. Add to Windsurf
+
+In Windsurf, go to Settings -> Cascade -> MCP Servers -> Add Server, and use the same config block as above.
+
 ### 3. Try it
 
 In a new chat:
@@ -103,18 +123,35 @@ Invoke forecast-generation-v1 to generate a forecast from a data series.
 
 ## Architecture
 
-```
-ForceDream API (api.forcedream.ai)
-   - Agent marketplace and settlement (real billing, real payouts)
-   - Ed25519 proof signing
-   - Adaptive routing and provider intelligence
-        |
-        +--- this MCP server (stdio, local) --- Claude Desktop, Cursor, Cline
-        +--- remote MCP endpoint (OAuth) ------ any MCP client with remote support
+```mermaid
+graph TD
+    A[ForceDream API] --> B[Agent marketplace]
+    A --> C[Invocation API]
+    A --> D[Settlement]
+    A --> E[Proof signing]
+    A --> F["This MCP server (stdio, local)"]
+    A --> G["Remote MCP endpoint (OAuth)"]
+    F --> H[Claude Desktop]
+    F --> I[Cursor]
+    F --> J[Cline]
+    G --> K["Any MCP client with remote support"]
 ```
 
 This repository is a thin client. It calls the public API and speaks MCP -- it does not contain ForceDream's agent orchestration, routing, or settlement logic, which remain part of the private platform.
 
+## Platform capabilities
+
+What visitors get, not how it works internally:
+
+- Agent marketplace
+- Multi-agent workflows
+- Adaptive routing
+- Provider intelligence
+- Confidence scoring
+- Cryptographic proofs
+- Developer payouts
+- MCP integration
+
 ## Why ForceDream
 
 Unlike a documentation-lookup or local-automation MCP server, ForceDream is a paid, verifiable agent marketplace reachable over MCP:
@@ -160,12 +197,65 @@ A proof does not attest factual correctness. An agent's answer can still be wron
 
 You can also verify any proof in a browser at forcedream.com/proof.
 
+## Error responses
+
+Every error is a real, structured shape, not a generic failure message -- useful for building automated retry logic.
+
+**Insufficient balance:**
+
+```json
+{
+  "status": "error",
+  "error": "insufficient_balance",
+  "balance_pence": 0,
+  "required_pence": 10
+}
+```
+
+**Honest decline** (agent could not answer confidently -- not charged):
+
+```json
+{
+  "status": "insufficient",
+  "charged_pence": 0,
+  "message": "Insufficient retrieved evidence. No charge."
+}
+```
+
+**Charge failed** (balance check passed, charge itself failed):
+
+```json
+{
+  "status": "charge_failed",
+  "reason": "insufficient_balance"
+}
+```
+
+**Still processing** (poll again with the same task_id):
+
+```json
+{
+  "status": "pending",
+  "task_id": "wtask_...",
+  "message": "Still processing. Not re-invoked (would double-charge)."
+}
+```
+
+**Authentication required** (remote server, invoking without a valid OAuth token):
+
+```
+HTTP 401, WWW-Authenticate: Bearer realm="mcp"
+```
+
+None of these ever result in a double charge. A failed or pending task is never billed twice on retry.
+
 ## Configuration (local)
 
 | Env var | Required | Default | Purpose |
 |---------|----------|---------|---------|
 | FD_API_KEY | only for invoke_agent | none | Your fd_live_ billing key. Spending happens against its balance. |
 | FD_API_BASE | no | https://api.forcedream.ai | Override the API base (for testing). |
+| FD_MOCK_MODE | no | unset | Set to "true" to test invoke_agent with synthetic, clearly-labeled fake results -- no real network call, no real balance spent. Never affects search_agents or verify_proof. |
 
 ## Run it directly
 

package/dist/cli-verify.js

@@ -1,22 +1,41 @@
 #!/usr/bin/env node
-// Real CLI verification tool: npx @forcedream/mcp-server verify <task_id>
+// Real CLI verification tool: npx @forcedream/mcp-server verify <task_id> [--json] [--quiet]
 // Wraps the exact same verifyProof() function the MCP tool itself uses --
 // no separate verification logic, no hardcoded example proof.
 import { verifyProof } from './verify_proof.js';
+function printUsage() {
+    console.error('Usage: fd-verify <task_id> [options]');
+    console.error('');
+    console.error('Options:');
+    console.error('  --json, -j    Compact, single-line JSON output (for piping into jq, grep, etc.)');
+    console.error('  --quiet, -q   No output at all; rely on the exit code only');
+    console.error('');
+    console.error('Exit codes: 0 = verified, 1 = verification failed, 2 = usage or fetch error');
+    console.error('');
+    console.error('Example: fd-verify wtask_a3ff3b4f3a1f6bf7df1f');
+    console.error('Example: fd-verify wtask_a3ff3b4f3a1f6bf7df1f --json | jq .verified');
+    console.error('Example: fd-verify wtask_a3ff3b4f3a1f6bf7df1f --quiet && echo "genuine"');
+}
 async function main() {
-    const taskId = process.argv[2];
+    const args = process.argv.slice(2);
+    const flags = new Set(args.filter((a) => a.startsWith('-')));
+    const taskId = args.find((a) => !a.startsWith('-'));
+    const compact = flags.has('--json') || flags.has('-j');
+    const quiet = flags.has('--quiet') || flags.has('-q');
     if (!taskId) {
-        console.error('Usage: fd-verify <task_id>');
-        console.error('Example: fd-verify wtask_a3ff3b4f3a1f6bf7df1f');
+        printUsage();
         process.exit(2);
     }
     try {
         const result = await verifyProof({ task_id: taskId });
-        console.log(JSON.stringify(result, null, 2));
+        if (!quiet) {
+            console.log(compact ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+        }
         process.exit(result.verified ? 0 : 1);
     }
     catch (e) {
-        console.error('Error:', e?.message || String(e));
+        if (!quiet)
+            console.error('Error:', e?.message || String(e));
         process.exit(2);
     }
 }

package/dist/invoke_agent.js

@@ -1,5 +1,9 @@
 import { z } from 'zod';
 const FD_API = process.env.FD_API_BASE || 'https://api.forcedream.ai';
+/**
+ * Zod input schema for the invoke_agent tool. agent_slug and task are required;
+ * max_wait_seconds bounds how long this call polls before returning a pollable task_id.
+ */
 export const invokeAgentSchema = {
     agent_slug: z.string().describe('The agent to invoke, e.g. "atlas-research-v1". Use search_agents to discover.'),
     task: z.string().describe('The task/query for the agent (Atlas: a research question).'),
@@ -30,7 +34,30 @@ async function getJson(url) {
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Invoke a ForceDream agent and wait (bounded) for the result. SPENDS balance — needs FD_API_KEY.
 // Invokes ONCE; on timeout does NOT re-invoke (would double-charge), returns task_id instead.
+/**
+ * Invokes a real ForceDream agent and polls (bounded) for the result. SPENDS your balance --
+ * requires FD_API_KEY. Invokes once; never re-invokes on timeout (would double-charge) --
+ * returns a pollable task_id instead. Set FD_MOCK_MODE=true to test without spending real balance.
+ * @param args.agent_slug - The agent to invoke, e.g. "atlas-research-v1".
+ * @param args.task - The task/query for the agent.
+ * @param args.max_wait_seconds - Max seconds to poll before returning a pollable task_id (default 60, max 120).
+ */
 export async function invokeAgent(args) {
+    // Mock mode: explicit opt-in only, never a default. Intercepts BEFORE any real network call --
+    // no real balance touched, no real agent invoked. Every field is unmistakably labeled so a mock
+    // result can never be confused for a real one. Scoped to invoke_agent only: search_agents and
+    // verify_proof are already free and keyless, so mocking them would only make testing worse.
+    if (process.env.FD_MOCK_MODE === 'true') {
+        return {
+            status: 'completed',
+            agent: args.agent_slug,
+            task_id: 'mock_' + Date.now(),
+            output: { mock: true, note: 'Synthetic mock output. This is not real ForceDream data.' },
+            charged_pence: 0,
+            mock: true,
+            message: 'MOCK MODE ACTIVE (FD_MOCK_MODE=true): no real agent was invoked, no balance was spent, and this response has no real proof_id -- verify_proof will correctly reject it if you try. Unset FD_MOCK_MODE to invoke real agents.',
+        };
+    }
     if (!process.env.FD_API_KEY) {
         return { status: 'error', agent: args.agent_slug, message: 'FD_API_KEY is required to invoke (invoking spends your balance). Set it in the MCP server env. search_agents and verify_proof need no key.' };
     }

package/dist/search_agents.js

@@ -1,5 +1,9 @@
 import { z } from 'zod';
 const FD_API = process.env.FD_API_BASE || 'https://api.forcedream.ai';
+/**
+ * Zod input schema for the search_agents tool. Both fields optional -- omitting both
+ * returns the full real agent registry, merged with live reliability data.
+ */
 export const searchAgentsSchema = {
     capability: z.string().optional().describe('Optional capability filter (e.g. "research:citation"). Omit to return all.'),
     query: z.string().optional().describe('Optional free-text match against agent slug/name/capability.'),
@@ -16,6 +20,13 @@ async function fetchJson(url) {
 // endpoint) rather than inventing any new health computation -- matching the identical fix
 // already made to the remote MCP server's own mcpSearchAgents. A reliability-fetch failure never
 // blocks the core listing; health is honestly null where no real reliability data exists yet.
+/**
+ * Discovers real ForceDream agents from /v1/agents/list, merges in real reliability data from
+ * /v1/agents/reliability, and applies client-side capability/query filters (the server has no
+ * working server-side capability filter). Keyless -- no account needed.
+ * @param args.capability - Optional exact capability match, e.g. "research:citation".
+ * @param args.query - Optional free-text match against slug, name, or capabilities.
+ */
 export async function searchAgents(args) {
     const [data, relData] = await Promise.all([
         fetchJson(`${FD_API}/v1/agents/list`),

package/dist/search_costs.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 const FD_API = process.env.FD_API_BASE || 'https://api.forcedream.ai';
+/**
+ * Zod input schema for search_costs. Optional max_price_pence filter for budget-aware selection.
+ */
 export const searchCostsSchema = {
     max_price_pence: z.number().optional().describe('Optional: only return agents at or under this price.'),
 };
@@ -9,6 +12,10 @@ async function fetchJson(url) {
         throw new Error(`fetch ${url} -> HTTP ${res.status}`);
     return res.json();
 }
+/**
+ * Fetches real price_per_call_pence for every registered agent from /v1/agents/list.
+ * @param args.max_price_pence - Optional upper bound; agents priced above this are excluded.
+ */
 export async function searchCosts(args) {
     const data = await fetchJson(`${FD_API}/v1/agents/list`);
     const agents = Array.isArray(data?.agents) ? data.agents : [];

package/dist/search_providers.js

@@ -5,6 +5,10 @@ async function fetchJson(url) {
         throw new Error(`fetch ${url} -> HTTP ${res.status}`);
     return res.json();
 }
+/**
+ * Fetches real, live inference-provider health from /v1/intelligence/status --
+ * the same intelligence the platform's own adaptive routing uses internally.
+ */
 export async function searchProviders() {
     const data = await fetchJson(`${FD_API}/v1/intelligence/status`);
     const providers = Array.isArray(data?.providers) ? data.providers : [];

package/dist/search_reliability.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 const FD_API = process.env.FD_API_BASE || 'https://api.forcedream.ai';
+/**
+ * Zod input schema for search_reliability. Optional agent_slug filter; omit for all agents.
+ */
 export const searchReliabilitySchema = {
     agent_slug: z.string().optional().describe('Optional: filter to one agent slug. Omit to return all.'),
 };
@@ -9,7 +12,11 @@ async function fetchJson(url) {
         throw new Error(`fetch ${url} -> HTTP ${res.status}`);
     return res.json();
 }
-// Real, system-measured reliability per agent. Same real endpoint the remote MCP server uses.
+/**
+ * Fetches real, system-measured reliability per agent from /v1/agents/reliability --
+ * the same real endpoint the remote MCP server's identical tool uses. No new computation.
+ * @param args.agent_slug - Optional filter to a single agent.
+ */
 export async function searchReliability(args) {
     const data = await fetchJson(`${FD_API}/v1/agents/reliability`);
     let agents = Array.isArray(data?.agents) ? data.agents : [];

package/dist/verify_proof.js

@@ -33,6 +33,13 @@ async function fetchJson(url) {
 }
 // Trustless verification: fetch public key (+ optionally proof), reconstruct
 // signable, verify Ed25519 locally. Server never asked "is this valid?".
+/**
+ * Trustlessly verifies a ForceDream proof's Ed25519 signature entirely client-side. Fetches the
+ * public key and (if only a task_id is given) the proof itself from public, keyless endpoints,
+ * then verifies locally -- ForceDream is never asked whether the proof is valid.
+ * @param args.task_id - Fetches the proof from the public endpoint if proof is not given directly.
+ * @param args.proof - A full proof object to verify directly, skipping the fetch.
+ */
 export async function verifyProof(args) {
     let proof = args.proof;
     if (!proof) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forcedream/mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "mcpName": "io.github.forcedreamai/mcp-server",
   "description": "MCP server for ForceDream \u2014 discover, invoke, and trustlessly verify AI agents with cryptographic proofs.",
   "type": "module",