@forcedream/mcp-server 0.5.1 → 0.6.0

package/README.docker.md

@@ -0,0 +1,68 @@
+# Running the ForceDream MCP Server via Docker
+
+**This is a stdio-based MCP server, not an HTTP service.** Confirmed directly against the
+real source (`src/index.ts` uses `StdioServerTransport`, has no `process.env` reads, and
+never calls `.listen()` on any port). It communicates over the container's stdin/stdout --
+the same way a locally-run `npx @forcedream/mcp-server` process would. There is nothing to
+`curl` and no port to publish; running it detached (`docker run -d`) will not work, because
+nothing would ever be connected to its stdin.
+
+## Pull
+
+```bash
+docker pull forcedream/forcedream-mcp
+```
+
+## Use with Claude Desktop (or any stdio-based MCP host)
+
+Add this to your MCP client's config (for Claude Desktop,
+`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "forcedream": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "forcedream/forcedream-mcp"]
+    }
+  }
+}
+```
+
+- `-i` keeps stdin open -- required, since that's the entire transport.
+- `--rm` cleans up the container on exit, since the client spawns a fresh one each session.
+
+## Run it directly, for manual testing
+
+```bash
+docker run -i --rm forcedream/forcedream-mcp
+```
+
+Then type a real MCP JSON-RPC request on stdin, e.g.:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual-test","version":"0.1"}}}
+```
+
+and press Enter -- you should get a real `initialize` response back on stdout.
+
+## Passing environment variables (if/when needed)
+
+The current server doesn't read any environment variables directly (confirmed against the
+real source) -- individual tool calls (like `invoke_agent`) take a real API key as an MCP
+tool argument, not a container-level secret. If that changes in a future version, pass
+variables the standard way:
+
+```bash
+docker run -i --rm -e SOME_VAR=value forcedream/forcedream-mcp
+```
+
+## Building locally
+
+```bash
+docker build -t forcedream/forcedream-mcp .
+```
+
+Multi-stage: the build stage installs `devDependencies` (needed for `tsc`), the runtime
+stage installs only production dependencies and copies in the compiled `dist/` -- keeps the
+final image smaller and free of build-only tooling.

package/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@forcedream/mcp-server.svg)](https://www.npmjs.com/package/@forcedream/mcp-server)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![smithery badge](https://smithery.ai/badge/forcedreamai/mcp-server)](https://smithery.ai/servers/forcedreamai/mcp-server)
 
 An [MCP](https://modelcontextprotocol.io) server for **ForceDream** — discover AI agents, invoke them to do real work, and **verify the result cryptographically in your own process**. No trust in ForceDream required: every agent task produces an Ed25519-signed proof that this server checks locally.
 
@@ -15,23 +16,23 @@ Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io)
 | **Transport** | stdio, runs on your machine | Streamable HTTP, hosted by ForceDream |
 | **Setup** | `npx -y @forcedream/mcp-server` | Point your client at `https://api.forcedream.ai/v1/mcp` |
 | **Auth for invoking** | `FD_API_KEY` env var | OAuth 2.1 + PKCE (standard MCP auth flow) |
-| **Tools available** | `search_agents`, `verify_proof`, `invoke_agent` | All of the above, plus `check_fraud`, `generate_embedding`, `market_quote` |
+| **Tools available** | `forcedream_search_agents`, `forcedream_verify_proof`, `forcedream_invoke_agent` | All of the above, plus `forcedream_check_fraud`, `forcedream_generate_embedding`, `forcedream_market_quote` |
 | **Best for** | Claude Desktop, local dev | Any client with native remote-MCP + OAuth support |
 
 Both talk to the same real ForceDream API and the same real settlement system. Pick whichever fits your client.
 
 ## What it does
 
-`search_agents` and `verify_proof` need no account. Tools that spend your balance need authentication.
+`forcedream_search_agents` and `forcedream_verify_proof` need no account. Tools that spend your balance need authentication.
 
 | Tool | Auth | What it does |
 |------|------|--------------|
-| `search_agents` | none | Discover ForceDream agents, their real capabilities, and honest, system-derived metrics. |
-| `verify_proof` | none | Independently verify a ForceDream proof by task ID. Checked locally against the published public key. |
-| `invoke_agent` | key/OAuth | Invoke an agent to do real work. Spends your balance. Honest declines and failed charges cost nothing. |
-| `check_fraud`\* | OAuth | Real-time fraud risk scoring using IP reputation and behavioural signals. |
-| `generate_embedding`\* | OAuth | Real 1024-dim text embeddings via Voyage voyage-3.5. |
-| `market_quote`\* | OAuth | Live stock quotes via Alpha Vantage, cached, WORM-sealed. |
+| `forcedream_search_agents` | none | Discover ForceDream agents, their real capabilities, and honest, system-derived metrics. |
+| `forcedream_verify_proof` | none | Independently verify a ForceDream proof by task ID. Checked locally against the published public key. |
+| `forcedream_invoke_agent` | key/OAuth | Invoke an agent to do real work. Spends your balance. Honest declines and failed charges cost nothing. |
+| `forcedream_check_fraud`\* | OAuth | Real-time fraud risk scoring using IP reputation and behavioural signals. |
+| `forcedream_generate_embedding`\* | OAuth | Real 1024-dim text embeddings via Voyage voyage-3.5. |
+| `forcedream_market_quote`\* | OAuth | Live stock quotes via Alpha Vantage, cached, WORM-sealed. |
 
 \* remote server only.
 
@@ -64,7 +65,7 @@ Edit your `claude_desktop_config.json`:
 
 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`.
+> Omit `FD_API_KEY` to run discovery + verification only (no spending). Add it to enable `forcedream_invoke_agent`.
 
 ### 2b. Add to Cursor
 
@@ -112,7 +113,7 @@ Your client will handle the OAuth 2.1 + PKCE flow automatically the first time y
 
 ## Examples
 
-Real agents you can try, see search_agents for the full current list.
+Real agents you can try, see forcedream_search_agents for the full current list.
 
 ```
 Invoke data-extract-v1 to pull structured fields from raw text.
@@ -178,7 +179,7 @@ Real prompts you can adapt, covering different real ways to use the tools togeth
 > Feed this sales history to forecast-generation-v1 and ask for a 3-month forecast.
 
 **Fraud check before a sensitive action** (remote only)
-> Before processing this withdrawal, run check_fraud on this user ID and IP address.
+> Before processing this withdrawal, run forcedream_check_fraud on this user ID and IP address.
 
 **Market-aware research** (remote only)
 > Get a live quote for AAPL, then summarize what today's price move might mean for a tech-sector report.
@@ -253,9 +254,9 @@ None of these ever result in a double charge. A failed or pending task is never
 
 | 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_KEY | only for forcedream_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. |
+| FD_MOCK_MODE | no | unset | Set to "true" to test forcedream_invoke_agent with synthetic, clearly-labeled fake results -- no real network call, no real balance spent. Never affects forcedream_search_agents or forcedream_verify_proof. |
 
 ## Run it directly
 

package/dist/index.js

@@ -5,10 +5,19 @@ import { z } from 'zod';
 import { verifyProof } from './verify_proof.js';
 import { searchAgents, searchAgentsSchema } from './search_agents.js';
 import { invokeAgent, invokeAgentSchema } from './invoke_agent.js';
+import { securityScan, securityScanSchema } from './security_scan.js';
 import { searchReliability, searchReliabilitySchema } from './search_reliability.js';
 import { searchCosts, searchCostsSchema } from './search_costs.js';
 import { searchProviders } from './search_providers.js';
-const server = new McpServer({ name: 'forcedream', version: '0.3.0' });
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// Real fix for the version mismatch (this file previously hardcoded '0.3.0' as a separate,
+// independently-drifting string, while package.json said '0.5.1'): read the one, real,
+// canonical version at startup, so there is only ever one place this number lives.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+const server = new McpServer({ name: 'forcedream', version: pkg.version });
 // forcedream_verify_proof — trustless, keyless. Verify a ForceDream proof's Ed25519 signature client-side.
 server.registerTool('forcedream_verify_proof', {
     title: 'Verify a ForceDream proof',
@@ -60,6 +69,25 @@ server.registerTool('forcedream_invoke_agent', {
         return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: e.message }, null, 2) }], isError: true };
     }
 });
+// forcedream_security_scan — dedicated, named tool for security-scan-v1 specifically.
+// Spends balance (needs FD_API_KEY). Same real invoke/poll pattern as forcedream_invoke_agent,
+// fixed to this one agent so a caller doesn't need to know the generic agent_slug pattern.
+server.registerTool('forcedream_security_scan', {
+    title: 'Scan code for security vulnerabilities',
+    description: 'Real security review for code: OWASP Top 10, injection, secrets, and dependency risks. ' +
+        'Cross-references imported dependencies against OSV.dev for real CVEs, and scans for hardcoded ' +
+        'secrets via GitGuardian\'s real-time detection (400+ types). SPENDS your balance — requires FD_API_KEY. ' +
+        'Returns severity-graded findings, a risk score, what you were charged, and a proof_id.',
+    inputSchema: securityScanSchema,
+}, async ({ code, max_wait_seconds }) => {
+    try {
+        const result = await securityScan({ code, max_wait_seconds });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: e.message }, null, 2) }], isError: true };
+    }
+});
 // forcedream_search_reliability — keyless. Real, system-measured reliability per agent.
 server.registerTool('forcedream_search_reliability', {
     title: 'Search agent reliability data',

package/dist/security_scan.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+const FD_API = process.env.FD_API_BASE || 'https://api.forcedream.ai';
+const SLUG = 'security-scan-v1';
+/**
+ * Zod input schema for the forcedream_security_scan tool. code is required;
+ * max_wait_seconds bounds how long this call polls before returning a pollable task_id.
+ * A dedicated, named tool for ForceDream's security-scan-v1 agent, rather than requiring
+ * a caller to know the generic forcedream_invoke_agent + agent_slug pattern.
+ */
+export const securityScanSchema = {
+    code: z.string().describe('The code to scan for security vulnerabilities (OWASP Top 10, injection, secrets, dependency risks).'),
+    max_wait_seconds: z.number().optional().describe('Max seconds to poll (default 60, agent typically takes ~45s). On timeout, returns task_id to poll later.'),
+};
+function authHeader() {
+    const key = process.env.FD_API_KEY || '';
+    return key ? { Authorization: `Bearer ${key}` } : {};
+}
+async function postJson(url, body) {
+    const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...authHeader() }, body: JSON.stringify(body) });
+    let json = null;
+    try {
+        json = await res.json();
+    }
+    catch { }
+    return { status: res.status, json };
+}
+async function getJson(url) {
+    const res = await fetch(url, { headers: authHeader() });
+    let json = null;
+    try {
+        json = await res.json();
+    }
+    catch { }
+    return { status: res.status, json };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Invoke security-scan-v1 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.
+// Same real invoke/poll pattern as forcedream_invoke_agent, fixed to this one, specific agent.
+/**
+ * Invokes ForceDream's real security-scan-v1 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.code - The code to scan.
+ * @param args.max_wait_seconds - Max seconds to poll before returning a pollable task_id (default 60, max 120).
+ */
+export async function securityScan(args) {
+    // Mock mode: explicit opt-in only, never a default. Intercepts BEFORE any real network
+    // call -- no real balance touched, no real agent invoked. Same discipline as invoke_agent.ts.
+    if (process.env.FD_MOCK_MODE === 'true') {
+        return {
+            status: 'completed',
+            agent: SLUG,
+            task_id: 'mock_' + Date.now(),
+            output: { mock: true, findings: [], risk_score: 0, note: 'Synthetic mock output. This is not a real scan result.' },
+            charged_pence: 0,
+            mock: true,
+            message: 'MOCK MODE ACTIVE (FD_MOCK_MODE=true): no real scan was run, no balance was spent, and this response has no real proof_id -- forcedream_verify_proof will correctly reject it if you try. Unset FD_MOCK_MODE to run real scans.',
+        };
+    }
+    if (!process.env.FD_API_KEY) {
+        return { status: 'error', agent: SLUG, message: 'FD_API_KEY is required to scan (scanning spends your balance). Set it in the MCP server env. forcedream_search_agents and forcedream_verify_proof need no key.' };
+    }
+    const maxWaitMs = Math.max(5, Math.min(120, args.max_wait_seconds ?? 60)) * 1000;
+    const inv = await postJson(`${FD_API}/v1/agents/${SLUG}/invoke`, { task: args.code });
+    if (inv.status === 401)
+        return { status: 'error', agent: SLUG, message: 'Invalid FD_API_KEY (401). Check the key in the MCP server env.' };
+    if (!inv.json?.task_id)
+        return { status: 'error', agent: SLUG, message: `Invoke failed (HTTP ${inv.status}): ${inv.json?.error || inv.json?.note || 'no task_id'}` };
+    const taskId = inv.json.task_id;
+    const start = Date.now();
+    let intervalMs = 2500;
+    while (Date.now() - start < maxWaitMs) {
+        await sleep(intervalMs);
+        const poll = await getJson(`${FD_API}/v1/agents/${SLUG}/result/${encodeURIComponent(taskId)}`);
+        const d = poll.json || {};
+        const status = d.status || d.outcome;
+        if (status === 'completed' || status === 'succeeded' || d.ok === true) {
+            return {
+                status: 'completed', agent: SLUG, task_id: taskId, output: d.output, charged_pence: d.charged_pence,
+                proof_id: d.proof_id || taskId,
+                verify_proof_hint: `Verify trustlessly: call forcedream_verify_proof with task_id "${d.proof_id || taskId}". The signature proves authenticity without trusting ForceDream.`,
+                message: `Completed. Charged ${d.charged_pence}p. Cryptographically proven (proof_id ${d.proof_id || taskId}).`,
+            };
+        }
+        if (status === 'charge_failed')
+            return { status: 'charge_failed', agent: SLUG, task_id: taskId, charged_pence: 0, message: `Charge failed: ${d.reason || 'insufficient_balance'}. Nothing charged or delivered. Top up and retry.` };
+        if (status === 'failed' || status === 'dead_letter')
+            return { status: 'error', agent: SLUG, task_id: taskId, message: `Task ${status}: ${d.reason || d.last_error || 'unknown'}` };
+        intervalMs = Math.min(intervalMs + 1000, 6000);
+    }
+    return { status: 'pending', agent: SLUG, task_id: taskId, message: `Still processing after ${maxWaitMs / 1000}s. Not re-invoked (would double-charge). Poll the result later with this task_id.` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forcedream/mcp-server",
-  "version": "0.5.1",
+  "version": "0.6.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",