@toknbase/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# @toknbase/mcp-server
+
+Zero-knowledge secrets management for AI agents via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Toknbase is the only secrets manager where the host never sees your plaintext secrets. This MCP server connects your AI coding assistant to your Toknbase vault -- read, create, update, and delete secrets directly from Cursor, Windsurf, Claude Code, VS Code, Zed, and Cline.
+
+## Quick Start
+
+### 1. Create an Agent Token
+
+Log in to your Toknbase dashboard and navigate to **API Tokens → Agent Tokens**. Create a new token with the scope you need:
+
+- `read_only` -- list and reveal secrets
+- `read_write` -- list, reveal, create, and update secrets
+- `full_access` -- all of the above plus delete and folder management
+
+Copy the `agt_` token value -- it is shown only once.
+
+### 2. Add to Your Editor
+
+Replace `agt_your_token_here` with your token and `YOUR_CANISTER_ID` with your Toknbase canister ID (visible in the dashboard).
+
+**Cursor** (`~/.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "toknbase": {
+      "command": "npx",
+      "args": ["-y", "@toknbase/mcp-server"],
+      "env": {
+        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
+        "TOKNBASE_CANISTER_ID": "YOUR_CANISTER_ID"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude.json`, mcpServers section)
+```json
+{
+  "mcpServers": {
+    "toknbase": {
+      "command": "npx",
+      "args": ["-y", "@toknbase/mcp-server"],
+      "env": {
+        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
+        "TOKNBASE_CANISTER_ID": "YOUR_CANISTER_ID"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description | Required Scope |
+|---|---|---|
+| `toknbase_list_secrets` | List all secrets (names, descriptions, environments -- no values) | read_only |
+| `toknbase_reveal_secret` | Retrieve the value of a specific secret by name | read_only |
+| `toknbase_create_secret` | Add a new secret to the vault | read_write |
+| `toknbase_update_secret` | Update a secret's value | read_write |
+| `toknbase_delete_secret` | Permanently delete a secret | full_access |
+| `toknbase_list_folders` | List all folders | read_only |
+| `toknbase_assign_folder` | Assign a secret to a folder | full_access |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `TOKNBASE_AGENT_TOKEN` | Yes | Your `agt_` agent token from the dashboard |
+| `TOKNBASE_CANISTER_ID` | Yes | Your Toknbase canister ID |
+| `TOKNBASE_IC_HOST` | No | IC host URL (default: `https://ic0.app`) |
+
+## Security
+
+Toknbase is zero-knowledge -- your plaintext secrets never leave your device. The MCP server calls the Toknbase canister which returns encrypted values. For `reveal_secret`, the value returned is the stored encrypted blob; decryption happens in your local environment using your client-side key.
+
+Every action taken by an agent token is recorded in your Toknbase cryptographic audit log under the token's name.
+
+## Requirements
+
+- Node.js 18+
+- A Toknbase account with an active agent token

package/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * @toknbase/mcp-server
+ * Zero-knowledge secrets management for AI agents via Model Context Protocol.
+ *
+ * Required env vars:
+ *   TOKNBASE_AGENT_TOKEN  -- your agt_ scoped agent token from the Toknbase dashboard
+ *   TOKNBASE_CANISTER_ID  -- your Toknbase canister ID (e.g. xxxxx-xxxxx-cai)
+ *
+ * Optional:
+ *   TOKNBASE_IC_HOST      -- IC host (default: https://ic0.app)
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { Actor, HttpAgent } from "@dfinity/agent";
+import { IDL } from "@dfinity/candid";
+
+// ── Config ──────────────────────────────────────────────────────────────────
+const TOKEN = process.env.TOKNBASE_AGENT_TOKEN;
+const CANISTER_ID = process.env.TOKNBASE_CANISTER_ID;
+const IC_HOST = process.env.TOKNBASE_IC_HOST ?? "https://ic0.app";
+
+if (!TOKEN) {
+  console.error("[toknbase-mcp] Missing TOKNBASE_AGENT_TOKEN environment variable.");
+  process.exit(1);
+}
+if (!CANISTER_ID) {
+  console.error("[toknbase-mcp] Missing TOKNBASE_CANISTER_ID environment variable.");
+  process.exit(1);
+}
+
+// ── Candid IDL (agent-token surface only) ───────────────────────────────────
+const idlFactory = ({ IDL: I }) => {
+  const SecretMeta = I.Record({
+    name: I.Text,
+    description: I.Text,
+    environment: I.Text,
+  });
+  const FolderMeta = I.Record({
+    id: I.Nat,
+    name: I.Text,
+  });
+  return I.Service({
+    listSecretsByAgentToken: I.Func([I.Text], [I.Vec(SecretMeta)], ["query"]),
+    createSecretByAgentToken: I.Func(
+      [I.Text, I.Text, I.Text, I.Text, I.Text],
+      [I.Bool],
+      []
+    ),
+    updateSecretByAgentToken: I.Func([I.Text, I.Text, I.Text], [I.Bool], []),
+    deleteSecretByAgentToken: I.Func([I.Text, I.Text], [I.Bool], []),
+    listFoldersByAgentToken: I.Func([I.Text], [I.Vec(FolderMeta)], ["query"]),
+    assignFolderByAgentToken: I.Func([I.Text, I.Nat, I.Text], [I.Bool], []),
+    getSecretByAgentToken: I.Func([I.Text, I.Text], [I.Opt(I.Text)], ["query"]),
+  });
+};
+
+// ── IC Actor ─────────────────────────────────────────────────────────────────
+const agent = new HttpAgent({ host: IC_HOST });
+// Fetch root key only on local replica
+if (IC_HOST !== "https://ic0.app") {
+  await agent.fetchRootKey();
+}
+
+const backend = Actor.createActor(idlFactory, { agent, canisterId: CANISTER_ID });
+
+// ── MCP Server ───────────────────────────────────────────────────────────────
+const server = new Server(
+  { name: "toknbase", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+// Tool definitions
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "toknbase_list_secrets",
+      description: "List all secrets you have access to. Returns names, descriptions, and environments -- never plaintext values.",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+      name: "toknbase_reveal_secret",
+      description: "Reveal the encrypted value of a specific secret by name. Use this only when you need the actual value.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The exact secret name" },
+        },
+        required: ["name"],
+      },
+    },
+    {
+      name: "toknbase_create_secret",
+      description: "Add a new secret to the vault. Requires read_write or full_access scope.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Secret name (e.g. STRIPE_SECRET_KEY)" },
+          value: { type: "string", description: "The secret value to store" },
+          description: { type: "string", description: "Optional description" },
+          environment: {
+            type: "string",
+            enum: ["production", "staging", "development"],
+            description: "Environment tag",
+          },
+        },
+        required: ["name", "value"],
+      },
+    },
+    {
+      name: "toknbase_update_secret",
+      description: "Update the value of an existing secret. Requires read_write or full_access scope.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The exact secret name to update" },
+          value: { type: "string", description: "The new secret value" },
+        },
+        required: ["name", "value"],
+      },
+    },
+    {
+      name: "toknbase_delete_secret",
+      description: "Permanently delete a secret from the vault. Requires full_access scope. This cannot be undone.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The exact secret name to delete" },
+        },
+        required: ["name"],
+      },
+    },
+    {
+      name: "toknbase_list_folders",
+      description: "List all folders in the vault.",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+      name: "toknbase_assign_folder",
+      description: "Assign a secret to a folder. Requires full_access scope.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          secret_name: { type: "string", description: "The secret name to assign" },
+          folder_id: { type: "number", description: "The numeric folder ID" },
+        },
+        required: ["secret_name", "folder_id"],
+      },
+    },
+  ],
+}));
+
+// Tool handlers
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "toknbase_list_secrets": {
+        const secrets = await backend.listSecretsByAgentToken(TOKEN);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(secrets, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "toknbase_reveal_secret": {
+        const result = await backend.getSecretByAgentToken(args.name, TOKEN);
+        if (result.length === 0 || result[0] === undefined) {
+          return {
+            content: [{ type: "text", text: `Secret '${args.name}' not found or access denied.` }],
+            isError: true,
+          };
+        }
+        return {
+          content: [{ type: "text", text: result[0] }],
+        };
+      }
+
+      case "toknbase_create_secret": {
+        const ok = await backend.createSecretByAgentToken(
+          args.name,
+          args.value,
+          args.description ?? "",
+          args.environment ?? "development",
+          TOKEN
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: ok
+                ? `Secret '${args.name}' created successfully.`
+                : `Failed to create secret '${args.name}'. Check your token scope (requires read_write or full_access).`,
+            },
+          ],
+          isError: !ok,
+        };
+      }
+
+      case "toknbase_update_secret": {
+        const ok = await backend.updateSecretByAgentToken(args.name, args.value, TOKEN);
+        return {
+          content: [
+            {
+              type: "text",
+              text: ok
+                ? `Secret '${args.name}' updated successfully.`
+                : `Failed to update secret '${args.name}'. Check that it exists and your token scope (requires read_write or full_access).`,
+            },
+          ],
+          isError: !ok,
+        };
+      }
+
+      case "toknbase_delete_secret": {
+        const ok = await backend.deleteSecretByAgentToken(args.name, TOKEN);
+        return {
+          content: [
+            {
+              type: "text",
+              text: ok
+                ? `Secret '${args.name}' deleted.`
+                : `Failed to delete secret '${args.name}'. Check that it exists and your token scope (requires full_access).`,
+            },
+          ],
+          isError: !ok,
+        };
+      }
+
+      case "toknbase_list_folders": {
+        const folders = await backend.listFoldersByAgentToken(TOKEN);
+        return {
+          content: [{ type: "text", text: JSON.stringify(folders, null, 2) }],
+        };
+      }
+
+      case "toknbase_assign_folder": {
+        const ok = await backend.assignFolderByAgentToken(
+          args.secret_name,
+          BigInt(args.folder_id),
+          TOKEN
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: ok
+                ? `Secret '${args.secret_name}' assigned to folder ${args.folder_id}.`
+                : `Failed to assign folder. Check token scope (requires full_access).`,
+            },
+          ],
+          isError: !ok,
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[toknbase-mcp] Server running. Canister:", CANISTER_ID);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@toknbase/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Toknbase -- zero-knowledge secrets management for AI agents",
+  "type": "module",
+  "bin": {
+    "toknbase-mcp-server": "./index.js"
+  },
+  "main": "./index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@dfinity/agent": "^2.1.3",
+    "@dfinity/candid": "^2.1.3",
+    "@dfinity/principal": "^2.1.3"
+  },
+  "keywords": ["mcp", "secrets", "toknbase", "icp", "zero-knowledge", "ai-agent"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}