@nodatachat/mcp 0.4.0 → 0.4.2

package/README.md

@@ -39,6 +39,14 @@ Add the server to Claude Code in one command:
 claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY
 ```
 
+On **Windows**, native (non-WSL) `npx` needs the `cmd /c` wrapper:
+
+```cmd
+claude mcp add nodata -- cmd /c npx @nodatachat/mcp --api-key YOUR_API_KEY
+```
+
+After changing the server's config (e.g. adding a credential), **restart Claude Code** — the running server process keeps its old arguments until the session restarts.
+
 Or with a custom base URL (for self-hosted or staging):
 
 ```bash
@@ -53,7 +61,9 @@ claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY --base-url h
 | Grant token (agent) | `--grant-token` | `NODATA_GRANT_TOKEN` | — |
 | Base URL | `--base-url` | `NODATA_BASE_URL` | `https://www.nodatacapsule.com` |
 
-At least one of `--api-key` or `--grant-token` is required. API keys use the format `sk_live_…`; grant tokens are `ndca-…` (mint via `POST /api/v1/governance/grant`).
+API keys use the format `sk_live_…` (get one free at [/developers/get-started](https://www.nodatacapsule.com/developers/get-started)); grant tokens are `ndca-…` (mint via `POST /api/v1/governance/grant` or the `nodata_grant` tool).
+
+**No credential? Setup mode.** Started without a credential, the server still connects and exposes a single `nodata_get_started` tool that walks you (or your AI) through getting a key and reconnecting — it never fails the MCP handshake. Data tools stay disabled until a credential is provided. `--help` and `--version` are also available.
 
 ## Available Tools
 

package/dist/index.js

@@ -31,6 +31,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+const VERSION = "0.4.2";
+const USAGE = `nodata-mcp v${VERSION} — NoData MCP server\n\n` +
+    "  ADMIN mode:  nodata-mcp --api-key sk_live_...\n" +
+    "  AGENT mode:  nodata-mcp --grant-token ndca-...\n" +
+    "  Options:     --base-url <url>   (default https://www.nodatacapsule.com)\n" +
+    "               --help · --version\n\n" +
+    "Env vars: NODATA_API_KEY · NODATA_GRANT_TOKEN · NODATA_BASE_URL\n" +
+    "Get a free API key: https://www.nodatacapsule.com/developers/get-started\n" +
+    "Mint a grant token: POST /api/v1/governance/grant (or the nodata_grant tool).";
 function parseArgs(argv) {
     let apiKey = "";
     let grantToken = "";
@@ -45,6 +54,18 @@ function parseArgs(argv) {
         else if (argv[i] === "--base-url" && argv[i + 1]) {
             baseUrl = argv[++i];
         }
+        else if (argv[i] === "--help" || argv[i] === "-h") {
+            console.log(USAGE);
+            process.exit(0);
+        }
+        else if (argv[i] === "--version" || argv[i] === "-v") {
+            console.log(VERSION);
+            process.exit(0);
+        }
+        else if (argv[i].startsWith("--")) {
+            // A typo like --apikey silently degrading to setup mode is worse than noise.
+            console.error(`nodata-mcp: unknown option '${argv[i]}' (see --help)`);
+        }
     }
     if (!apiKey)
         apiKey = process.env.NODATA_API_KEY ?? "";
@@ -52,26 +73,29 @@ function parseArgs(argv) {
         grantToken = process.env.NODATA_GRANT_TOKEN ?? "";
     if (process.env.NODATA_BASE_URL)
         baseUrl = process.env.NODATA_BASE_URL;
-    if (!apiKey && !grantToken) {
-        console.error("Error: a credential is required.\n\n" +
-            "  ADMIN mode:  nodata-mcp --api-key sk_live_...\n" +
-            "  AGENT mode:  nodata-mcp --grant-token ndca-...\n\n" +
-            "Get an API key at https://www.nodatacapsule.com/developers/get-started\n" +
-            "Mint a grant token via POST /api/v1/governance/grant.");
-        process.exit(1);
-    }
     baseUrl = baseUrl.replace(/\/+$/, "");
     return { apiKey, grantToken, baseUrl };
 }
-async function apiPost(baseUrl, bearer, path, body) {
-    const res = await fetch(`${baseUrl}${path}`, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${bearer}`,
-        },
-        body: JSON.stringify(body),
-    });
+// Without a deadline a dead network turns a tool call into an indefinite hang
+// inside the MCP client; 30s comfortably covers a slow decide/retrieve.
+const REQUEST_TIMEOUT_MS = 30_000;
+async function doFetch(url, init) {
+    let res;
+    try {
+        res = await fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    }
+    catch (err) {
+        const timedOut = err instanceof Error && err.name === "TimeoutError";
+        return {
+            ok: false,
+            status: 0,
+            body: {
+                error: timedOut
+                    ? `Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${url}`
+                    : `Network error reaching ${url}: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
     let parsed;
     try {
         parsed = await res.json();
@@ -81,24 +105,26 @@ async function apiPost(baseUrl, bearer, path, body) {
     }
     return { ok: res.ok, status: res.status, body: parsed };
 }
+async function apiPost(baseUrl, bearer, path, body) {
+    return doFetch(`${baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${bearer}`,
+        },
+        body: JSON.stringify(body),
+    });
+}
 async function apiGet(baseUrl, bearer, path, params) {
     const url = new URL(`${baseUrl}${path}`);
     for (const [key, val] of Object.entries(params)) {
         if (val !== undefined && val !== "")
             url.searchParams.set(key, val);
     }
-    const res = await fetch(url.toString(), {
+    return doFetch(url.toString(), {
         method: "GET",
         headers: { Authorization: `Bearer ${bearer}` },
     });
-    let parsed;
-    try {
-        parsed = await res.json();
-    }
-    catch {
-        parsed = { error: `Non-JSON response (HTTP ${res.status})` };
-    }
-    return { ok: res.ok, status: res.status, body: parsed };
 }
 function formatResult(resp) {
     const text = JSON.stringify(resp.body, null, 2);
@@ -248,6 +274,13 @@ function registerAdminTools(server, baseUrl, apiKey) {
 }
 function registerAgentTool(server, baseUrl, grantToken) {
     const handle = handleFromGrant(grantToken);
+    if (!handle) {
+        // decide/retrieve are bearer-only and still work; read/use need the handle.
+        // Say so at startup instead of surprising the agent mid-conversation.
+        console.error("nodata-mcp: warning — could not derive an agent handle from the grant token " +
+            "(expected ndca-<jwt> with a 'handle' claim). nodata_decide/nodata_retrieve will work; " +
+            "nodata_read/nodata_use will fail until a valid grant token is provided.");
+    }
     // ── Access Compute · the "may I?" oracle (P0) ───────────────────────
     // Returns ONLY a decision + a signed proof, never any content. A planner
     // calls this to learn what it can reach BEFORE moving data: allow, degrade
@@ -341,19 +374,55 @@ function registerAgentTool(server, baseUrl, grantToken) {
     });
 }
 // ---------------------------------------------------------------------------
+// Setup mode — no credential yet
+// ---------------------------------------------------------------------------
+// The public one-liner (`claude mcp add nodata -- npx @nodatachat/mcp`) arrives
+// here with no credential. Exiting 1 makes the MCP client report an opaque
+// "connection failed" and the stderr explanation is never seen. Instead we
+// connect successfully and expose a single tool whose answer walks the user
+// (via their own AI) to a working credential.
+const SETUP_TEXT = "This NoData server is connected but has NO credential yet, so no data tools are available.\n\n" +
+    "To finish setup:\n\n" +
+    "1. Get a free API key (takes seconds, no card):\n" +
+    "   https://www.nodatacapsule.com/developers/get-started\n\n" +
+    "2. Reconnect with the key —\n" +
+    "   Claude Code:  claude mcp remove nodata\n" +
+    "                 claude mcp add nodata -- npx @nodatachat/mcp --api-key sk_live_YOUR_KEY\n" +
+    "   Or keep the command credential-free and set the env var instead:\n" +
+    "                 claude mcp add nodata --env NODATA_API_KEY=sk_live_YOUR_KEY -- npx @nodatachat/mcp\n\n" +
+    "   IMPORTANT: after changing the config, RESTART the MCP client (e.g. exit and reopen\n" +
+    "   Claude Code) — this server process was spawned with the old config and a config edit\n" +
+    "   does not affect it. Until the restart it will keep answering in setup mode.\n\n" +
+    "3. (Agent mode) If you were handed a grant token (ndca-...), use --grant-token ndca-YOUR_GRANT\n" +
+    "   (or NODATA_GRANT_TOKEN) instead of an API key — the server then exposes only the\n" +
+    "   decide/retrieve/read/use tools scoped to that grant.\n\n" +
+    "Admin mode (--api-key) manages governance: register tables, issue/revoke grants, encrypt,\n" +
+    "decrypt, deliver, evidence. Agent mode (--grant-token) is what you hand an AI agent.";
+function registerSetupTool(server) {
+    server.registerTool("nodata_get_started", {
+        description: "NoData is connected WITHOUT a credential — data tools are disabled. Call this (no arguments) to get the exact steps to finish setup: where to get a free API key and how to reconnect in admin or agent mode. If the user asks why NoData tools are missing or how to set up NoData, call this and relay the steps.",
+        inputSchema: {},
+    }, async () => ({ content: [{ type: "text", text: SETUP_TEXT }] }));
+}
+// ---------------------------------------------------------------------------
 // Server setup
 // ---------------------------------------------------------------------------
 async function main() {
     const { apiKey, grantToken, baseUrl } = parseArgs(process.argv.slice(2));
-    const mode = grantToken ? "agent" : "admin";
+    const mode = grantToken ? "agent" : apiKey ? "admin" : "setup";
     const server = new McpServer({
-        name: mode === "agent" ? "NoData (agent-scoped)" : "NoData",
-        version: "0.4.0",
+        name: mode === "agent" ? "NoData (agent-scoped)" : mode === "setup" ? "NoData (setup)" : "NoData",
+        version: VERSION,
     });
     if (apiKey)
         registerAdminTools(server, baseUrl, apiKey);
     if (grantToken)
         registerAgentTool(server, baseUrl, grantToken);
+    if (mode === "setup") {
+        registerSetupTool(server);
+        console.error("nodata-mcp: no credential given — running in setup mode (only nodata_get_started is available).\n" +
+            "Pass --api-key sk_live_... or --grant-token ndca-... to enable data tools. See --help.");
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@nodatachat/mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "NoData MCP Server — govern data for AI agents: decide (may I?) + retrieve (authorized context) + read + secret-blind invoke, plus admin governance/encrypt/decrypt/deliver",
   "bin": {
-    "nodata-mcp": "./dist/index.js"
+    "nodata-mcp": "dist/index.js"
   },
   "type": "module",
   "scripts": {