@nodatachat/mcp 0.4.0

package/README.md

@@ -0,0 +1,106 @@
+# @nodatachat/mcp
+
+MCP (Model Context Protocol) server for **governing data given to AI agents** — plus NoData's Blind Relay (encrypt / decrypt / deliver / evidence).
+
+## Two modes — the credential decides what the server can do
+
+**Agent mode (`--grant-token ndca-...`)** — *permission management for language models.*
+You hand an AI agent a grant token; this server exposes tools hard-scoped to that grant: `nodata_decide` (may I reach this? — decision + proof, no data), `nodata_retrieve` (authorized context, filtered to what you may see), `nodata_read` (read governed rows), and `nodata_use` (secret-blind invoke). The agent may only request columns its grant allows — **denied columns never decrypt server-side**, and every action emits a cryptographic receipt. Point any MCP client (Claude, an agent runtime) at it and it physically cannot exceed its claims.
+
+The plan-then-act loop: **`nodata_decide`** to check reachability (allow / degrade / deny + access-distance cost), then **`nodata_retrieve`** to pull only the authorized context into your prompt.
+
+```bash
+claude mcp add nodata -- npx @nodatachat/mcp --grant-token ndca-YOUR_GRANT
+```
+
+**Admin mode (`--api-key sk_live_...`)** — manage governance from inside any MCP client: register your tables, issue grants, revoke them, and use blind relay.
+
+```bash
+claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY
+```
+
+## Installation
+
+```bash
+npm install @nodatachat/mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx @nodatachat/mcp --api-key sk_live_your_key_here
+```
+
+## Claude Code Setup
+
+Add the server to Claude Code in one command:
+
+```bash
+claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY
+```
+
+Or with a custom base URL (for self-hosted or staging):
+
+```bash
+claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY --base-url https://staging.nodatacapsule.com
+```
+
+## Configuration
+
+| Option | Flag | Env Var | Default |
+|--------|------|---------|---------|
+| API Key (admin) | `--api-key` | `NODATA_API_KEY` | — |
+| 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`).
+
+## Available Tools
+
+**Agent mode** (`--grant-token`):
+
+| Tool | Description |
+|------|-------------|
+| `nodata_decide` | Ask whether the agent MAY reach a resource, without reading it. Returns allow / degrade (reachable subset) / deny + an access-distance cost + a signed proof. No data. Plan before you read. |
+| `nodata_retrieve` | Prompt-ready authorized context, filtered to exactly the allowed columns (denied columns never decrypt), with an accounting of what was withheld + a signed proof. |
+| `nodata_read` | Read governed data within this agent's grant. Denied columns never decrypt; every read emits a receipt. Hard-scoped to the grant token. |
+| `nodata_use` | Invoke a pre-registered secret-blind capability; the Capsule injects the sealed credential server-side and returns only the result. The secret never reaches the agent. |
+
+**Admin mode** (`--api-key`):
+
+| Tool | Description |
+|------|-------------|
+| `nodata_register_table` | Register one of your tables as AI-agent-readable ("connect your data"). |
+| `nodata_grant` | Issue an agent a claim-scoped grant; returns a grant_token (shown once). |
+| `nodata_revoke` | Revoke a grant by handle or jti. |
+| `nodata_encrypt` | Encrypt a field (AES-256-GCM). Returns ciphertext for you to store. NoData stores nothing. |
+| `nodata_decrypt` | Decrypt ciphertext back to plaintext. |
+| `nodata_deliver` | Create a burn-after-read secure link with OTP. |
+| `nodata_evidence` | Retrieve audit trail (metadata only). |
+
+## Example Usage in Claude Code
+
+Once the MCP server is added, you can use natural language:
+
+- "Encrypt my database password using NoData"
+- "Create a secure link to send this API key to the DevOps team"
+- "Show me the audit trail for the last 7 days"
+- "Decrypt this ciphertext: aes256gcm:v1:..."
+
+## Development
+
+```bash
+cd packages/mcp-server
+npm install
+npm run dev -- --api-key sk_live_test_key
+```
+
+Build for production:
+
+```bash
+npm run build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * NoData MCP Server
+ *
+ * Two modes — the credential you give it decides what it can do:
+ *
+ *   ADMIN MODE  (--api-key sk_live_...)
+ *     Manage governance + blind-relay from inside any MCP client:
+ *       nodata_register_table · nodata_grant · nodata_revoke
+ *       nodata_encrypt · nodata_decrypt · nodata_deliver · nodata_evidence
+ *
+ *   AGENT MODE  (--grant-token ndca-...)
+ *     This is the "permission management for language models" artifact.
+ *     You hand an AI agent a grant token; this server then exposes tools
+ *     scoped to exactly that grant:
+ *       nodata_decide   — ask "may I reach this?" and get a decision + proof,
+ *                         never any data (plan before you read).
+ *       nodata_retrieve — get prompt-ready context filtered to what you may
+ *                         see, with an accounting of what was withheld.
+ *       nodata_read     — read governed data (denied columns never decrypt).
+ *       nodata_use      — invoke a secret-blind capability: the Capsule injects
+ *                         the sealed credential server-side and returns only the
+ *                         result; the agent never receives the secret.
+ *     Every decide/retrieve/read/invoke emits a receipt. Point any MCP client
+ *     (Claude, an agent runtime) at it: it physically cannot exceed its grant.
+ *
+ * Usage:
+ *   nodata-mcp --api-key sk_live_xxx
+ *   nodata-mcp --grant-token ndca-xxx [--base-url https://www.nodatacapsule.com]
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * NoData MCP Server
+ *
+ * Two modes — the credential you give it decides what it can do:
+ *
+ *   ADMIN MODE  (--api-key sk_live_...)
+ *     Manage governance + blind-relay from inside any MCP client:
+ *       nodata_register_table · nodata_grant · nodata_revoke
+ *       nodata_encrypt · nodata_decrypt · nodata_deliver · nodata_evidence
+ *
+ *   AGENT MODE  (--grant-token ndca-...)
+ *     This is the "permission management for language models" artifact.
+ *     You hand an AI agent a grant token; this server then exposes tools
+ *     scoped to exactly that grant:
+ *       nodata_decide   — ask "may I reach this?" and get a decision + proof,
+ *                         never any data (plan before you read).
+ *       nodata_retrieve — get prompt-ready context filtered to what you may
+ *                         see, with an accounting of what was withheld.
+ *       nodata_read     — read governed data (denied columns never decrypt).
+ *       nodata_use      — invoke a secret-blind capability: the Capsule injects
+ *                         the sealed credential server-side and returns only the
+ *                         result; the agent never receives the secret.
+ *     Every decide/retrieve/read/invoke emits a receipt. Point any MCP client
+ *     (Claude, an agent runtime) at it: it physically cannot exceed its grant.
+ *
+ * Usage:
+ *   nodata-mcp --api-key sk_live_xxx
+ *   nodata-mcp --grant-token ndca-xxx [--base-url https://www.nodatacapsule.com]
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function parseArgs(argv) {
+    let apiKey = "";
+    let grantToken = "";
+    let baseUrl = "https://www.nodatacapsule.com";
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--api-key" && argv[i + 1]) {
+            apiKey = argv[++i];
+        }
+        else if (argv[i] === "--grant-token" && argv[i + 1]) {
+            grantToken = argv[++i];
+        }
+        else if (argv[i] === "--base-url" && argv[i + 1]) {
+            baseUrl = argv[++i];
+        }
+    }
+    if (!apiKey)
+        apiKey = process.env.NODATA_API_KEY ?? "";
+    if (!grantToken)
+        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),
+    });
+    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 };
+}
+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(), {
+        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);
+    if (!resp.ok) {
+        return {
+            content: [{ type: "text", text: `Error (HTTP ${resp.status}):\n${text}` }],
+            isError: true,
+        };
+    }
+    return { content: [{ type: "text", text }] };
+}
+/** Decode the handle out of an agent grant token (ndca-<jwt>). */
+function handleFromGrant(token) {
+    try {
+        const jwt = token.startsWith("ndca-") ? token.slice(5) : token;
+        const payload = jwt.split(".")[1];
+        if (!payload)
+            return null;
+        const json = JSON.parse(Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+        return json.handle ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+function registerAdminTools(server, baseUrl, apiKey) {
+    // ── Governance ──────────────────────────────────────────────────────
+    server.registerTool("nodata_register_table", {
+        description: "Register one of your own tables as AI-agent-readable ('connect your data'). Declares which columns are encrypted (per-column key release) and which are plaintext metadata. After this, grants can target the table.",
+        inputSchema: {
+            table_name: z.string().describe("Your SQL table name"),
+            encrypted_columns: z.array(z.string()).describe("Columns stored as <col>_ct/_iv/_tag triplets"),
+            plaintext_columns: z.array(z.string()).optional().describe("Plaintext metadata/filter columns"),
+            classification_column: z.string().optional().describe("Plaintext column carrying the classification value"),
+        },
+    }, async ({ table_name, encrypted_columns, plaintext_columns, classification_column }) => {
+        const resp = await apiPost(baseUrl, apiKey, "/api/v1/governance/tables", {
+            table_name,
+            encrypted_columns,
+            plaintext_columns: plaintext_columns ?? [],
+            classification_column,
+        });
+        return formatResult(resp);
+    });
+    server.registerTool("nodata_grant", {
+        description: "Issue an AI agent a claim-scoped grant over your data — claims, not blanket access. Returns a grant_token (shown once) the agent presents to read. Denied columns never decrypt.",
+        inputSchema: {
+            agent: z.string().describe("Agent label (becomes its handle)"),
+            table: z.string().optional().describe("Target table (default agent_demo_records)"),
+            columns: z.array(z.string()).describe("Columns the agent may read"),
+            where: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe("Equality filter (plaintext cols only)"),
+            classifications: z.array(z.string()).optional().describe("Allowed classification values; empty = no gating"),
+            ttl_seconds: z.number().optional().describe("Token lifetime (default 30d, max 1y)"),
+        },
+    }, async ({ agent, table, columns, where, classifications, ttl_seconds }) => {
+        const resp = await apiPost(baseUrl, apiKey, "/api/v1/governance/grant", {
+            agent,
+            table,
+            columns,
+            where,
+            classifications,
+            ttl_seconds,
+        });
+        return formatResult(resp);
+    });
+    server.registerTool("nodata_revoke", {
+        description: "Revoke an agent's grant by handle (kills all its active credentials) or by a specific jti. Revocation is mathematics — the next read 401s and any cached data is governance-dead.",
+        inputSchema: {
+            handle: z.string().optional().describe("Agent handle to revoke"),
+            jti: z.string().optional().describe("Specific credential jti to revoke"),
+            reason: z.string().optional(),
+        },
+    }, async ({ handle, jti, reason }) => {
+        const resp = await apiPost(baseUrl, apiKey, "/api/v1/governance/revoke", { handle, jti, reason });
+        return formatResult(resp);
+    });
+    // ── Blind relay (kept from v0.1) ────────────────────────────────────
+    server.registerTool("nodata_encrypt", {
+        description: "Encrypt a sensitive field value using Capsule Blind Relay. Returns ciphertext. NoData stores nothing — the key is embedded in the ciphertext for YOU to store.",
+        inputSchema: {
+            field: z.string(),
+            value: z.string(),
+            context: z.string().optional(),
+        },
+    }, async ({ field, value, context }) => {
+        const body = { field, value };
+        if (context)
+            body.context = context;
+        return formatResult(await apiPost(baseUrl, apiKey, "/api/v1/encrypt", body));
+    });
+    server.registerTool("nodata_decrypt", {
+        description: "Decrypt a Capsule ciphertext back to plaintext (aes256gcm:v1:iv:cipher:key format).",
+        inputSchema: {
+            ciphertext: z.string(),
+            field: z.string().optional(),
+            requester: z.string().optional(),
+        },
+    }, async ({ ciphertext, field, requester }) => {
+        const body = { ciphertext };
+        if (field)
+            body.field = field;
+        if (requester)
+            body.requester = requester;
+        return formatResult(await apiPost(baseUrl, apiKey, "/api/v1/decrypt", body));
+    });
+    server.registerTool("nodata_deliver", {
+        description: "Create a burn-after-read secure link for delivering sensitive content. Returns a view URL and OTP.",
+        inputSchema: {
+            content: z.string(),
+            to: z.string().optional(),
+            maxViews: z.number().optional(),
+            ttl: z.string().optional(),
+            burn: z.boolean().optional(),
+        },
+    }, async ({ content, to, maxViews, ttl, burn }) => {
+        const body = { content };
+        if (to)
+            body.to = to;
+        if (maxViews !== undefined)
+            body.maxViews = maxViews;
+        if (ttl)
+            body.ttl = ttl;
+        if (burn !== undefined)
+            body.burn = burn;
+        return formatResult(await apiPost(baseUrl, apiKey, "/api/v1/deliver", body));
+    });
+    server.registerTool("nodata_evidence", {
+        description: "Retrieve the audit trail of governance/encryption events. Metadata only — never content, keys, or plaintext.",
+        inputSchema: {
+            from: z.string().optional(),
+            to: z.string().optional(),
+            action: z.string().optional(),
+            limit: z.number().optional(),
+        },
+    }, async ({ from, to, action, limit }) => {
+        const params = {
+            from,
+            to,
+            action,
+            limit: limit !== undefined ? String(limit) : undefined,
+        };
+        return formatResult(await apiGet(baseUrl, apiKey, "/api/v1/evidence", params));
+    });
+}
+function registerAgentTool(server, baseUrl, grantToken) {
+    const handle = handleFromGrant(grantToken);
+    // ── 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
+    // (the reachable subset), or deny — with an access-distance cost. Bearer-only
+    // endpoint (no handle in the path).
+    server.registerTool("nodata_decide", {
+        description: "Ask whether this agent MAY reach a resource, WITHOUT reading it. Returns a decision (allow / degrade / deny), the reachable column subset, an access-distance cost, and a signed proof — never any data. Use it to plan: check reachability before you retrieve. Hard-scoped to this server's grant token.",
+        inputSchema: {
+            table: z.string().describe("Table to check (must be in your grant)"),
+            columns: z.array(z.string()).describe("Columns you want to reach"),
+            where: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe("Equality filter (readable columns only)"),
+        },
+    }, async ({ table, columns, where }) => {
+        const resp = await apiPost(baseUrl, grantToken, "/api/access/decide", {
+            resource: { table, columns, where },
+            intent: "read",
+        });
+        return formatResult(resp);
+    });
+    // ── Authorized Context · access-aware RAG (P1) ──────────────────────
+    // Runs the same decision, then returns prompt-ready context filtered to
+    // exactly the allowed columns (denied columns are never decrypted), plus an
+    // accounting of what was withheld and a signed proof.
+    server.registerTool("nodata_retrieve", {
+        description: "Retrieve prompt-ready context for a resource, filtered to exactly what this agent may see. Denied columns are never decrypted; the response includes an accounting of what was withheld (columns + estimated tokens saved) and a signed proof. Prefer this over a raw read when assembling an LLM prompt. Hard-scoped to this server's grant token.",
+        inputSchema: {
+            table: z.string().describe("Table to retrieve from (must be in your grant)"),
+            columns: z.array(z.string()).describe("Columns to include in context"),
+            where: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            top_k: z.number().optional().describe("Max rows (default 50, max 200)"),
+        },
+    }, async ({ table, columns, where, top_k }) => {
+        const resp = await apiPost(baseUrl, grantToken, "/api/access/retrieve", {
+            resource: { table, columns, where },
+            top_k,
+        });
+        return formatResult(resp);
+    });
+    server.registerTool("nodata_read", {
+        description: "Read governed data within this agent's grant. You may only request columns your grant allows — denied columns never decrypt server-side, and every read emits a cryptographic receipt. This tool is hard-scoped to the grant token this server was started with.",
+        inputSchema: {
+            table: z.string().describe("Table to read (must be in your grant)"),
+            columns: z.array(z.string()).describe("Columns to read (must be in your grant)"),
+            where: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            limit: z.number().optional().describe("Max rows (default 50, max 200)"),
+        },
+    }, async ({ table, columns, where, limit }) => {
+        if (!handle) {
+            return {
+                content: [{ type: "text", text: "Error: could not derive agent handle from grant token." }],
+                isError: true,
+            };
+        }
+        const resp = await apiPost(baseUrl, grantToken, `/api/agents/${encodeURIComponent(handle)}/read`, {
+            table,
+            columns,
+            where,
+            limit,
+        });
+        return formatResult(resp);
+    });
+    // ── Secret-blind action (AI Access Plane) ───────────────────────────
+    // The headline of the plane: INVOKE a pre-registered capability. The
+    // Capsule injects the sealed secret server-side and returns ONLY the
+    // result — you (the agent / model) never receive the key. Deny-by-default:
+    // you can invoke only capabilities your grant lists. Every invoke emits a
+    // signed receipt proving you acted and never held the secret.
+    server.registerTool("nodata_use", {
+        description: "Invoke a pre-registered capability (deploy, send, charge, query, …) WITHOUT receiving the secret. The Capsule injects the sealed credential server-side and returns only the result. You may invoke only capabilities your grant allows; the secret never reaches you. Hard-scoped to the grant token this server was started with.",
+        inputSchema: {
+            capability: z.string().describe("Capability name to invoke (must be in your grant, e.g. 'deploy-prod')"),
+            params: z.record(z.string(), z.unknown()).optional().describe("Allowlisted params; unknown keys are dropped server-side"),
+            resource_key: z.string().optional().describe("Optional folder/resource the action targets (enforced against corpus scope)"),
+        },
+    }, async ({ capability, params, resource_key }) => {
+        if (!handle) {
+            return {
+                content: [{ type: "text", text: "Error: could not derive agent handle from grant token." }],
+                isError: true,
+            };
+        }
+        const resp = await apiPost(baseUrl, grantToken, `/api/agents/${encodeURIComponent(handle)}/use`, {
+            capability,
+            params,
+            resource_key,
+        });
+        return formatResult(resp);
+    });
+}
+// ---------------------------------------------------------------------------
+// Server setup
+// ---------------------------------------------------------------------------
+async function main() {
+    const { apiKey, grantToken, baseUrl } = parseArgs(process.argv.slice(2));
+    const mode = grantToken ? "agent" : "admin";
+    const server = new McpServer({
+        name: mode === "agent" ? "NoData (agent-scoped)" : "NoData",
+        version: "0.4.0",
+    });
+    if (apiKey)
+        registerAdminTools(server, baseUrl, apiKey);
+    if (grantToken)
+        registerAgentTool(server, baseUrl, grantToken);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nodatachat/mcp",
+  "version": "0.4.0",
+  "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"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://www.nodatacapsule.com/developers",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "data-governance",
+    "nodata",
+    "access-control"
+  ],
+  "license": "MIT"
+}