@nodatachat/mcp 0.4.0 → 0.4.1

package/README.md

@@ -53,7 +53,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.1";
+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,14 +73,6 @@ 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 };
 }
@@ -341,19 +354,52 @@ 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" +
+    "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,6 +1,6 @@
 {
   "name": "@nodatachat/mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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"