@uuaid/mcp 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @uuaid/mcp
+
+**Give your agent a life that outlives the session.**
+
+One MCP entry gives any AI agent (Claude Code, Cursor, Codex, or anything that
+speaks [MCP](https://modelcontextprotocol.io)) a **permanent, verifiable
+identity** and **encrypted, quantum-ready memory**:
+
+```json
+{
+  "mcpServers": {
+    "uuaid": {
+      "command": "npx",
+      "args": ["-y", "@uuaid/mcp"],
+      "env": {
+        "UUAID_API_KEY": "uuaid_live_…",
+        "UUAID_VAULT_KEY": "uvk_…",
+        "UUAID_AGENT": "uuaid:foundation:agent:…"
+      }
+    }
+  }
+}
+```
+
+No key yet? Add the server with no env and ask your agent to run the
+`uuaid_signup` tool — a free-tier key (10 MB encrypted memory per agent) is
+minted in one call.
+
+## What your agent can do
+
+| Tool | What it does |
+|---|---|
+| `uuaid_signup` | One-call free-tier signup (key shown once) |
+| `mint_identity` | Mint the agent's **permanent UUAID** — public, resolvable, on-chain-anchored |
+| `save_memory` / `recall_memory` | Persist + retrieve memories across sessions |
+| `list_memories` / `delete_memory` | Manage the vault |
+| `verify_agent` | Publicly verify any other agent's identity + certifications |
+| `get_badge_url` | Live SVG trust badge for READMEs |
+| `whoami` | Show configured identity + vault status |
+
+## How the memory works
+
+- Encryption happens **inside this process** with [`@uuaid/vault`](https://www.npmjs.com/package/@uuaid/vault):
+  AES-256-GCM, per-item keys derived via HKDF-SHA256 from your `UUAID_VAULT_KEY`.
+  A hybrid **X25519 + ML-KEM-768** (post-quantum) recipient mode is available in the SDK.
+- The UUAID service stores **ciphertext only**. It cannot read your agent's memory.
+- Every write's content hash lands in a hash-chained ledger that is
+  Merkle-anchored on **Polygon mainnet** — your agent can prove a memory
+  existed, untampered, at a point in time, without revealing it.
+- Free tier: 10 MB / 500 items per agent. [Pricing](https://uuaid.org/#pricing) for more.
+
+## The identity
+
+A UUAID (`uuaid:foundation:agent:<uuidv7>`) is durable and portable — it is not
+tied to a platform, a framework, or a session. Anyone can resolve it at
+[registry.uuaid.org](https://registry.uuaid.org), verify its certifications
+(examined at Open Agent University), and check the on-chain anchor.
+
+```md
+[![UUAID verified](https://api.uuaid.org/badge/agent/<uuaid>.svg)](https://registry.uuaid.org)
+```
+
+Docs: [api.uuaid.org/docs](https://api.uuaid.org/docs) · Spec: `docs/UAP-SPEC.md` · Apache-2.0

package/dist/server.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { UuaidClient, generateVaultKey } from "@uuaid/sdk";
+var BASE_URL = process.env.UUAID_BASE_URL ?? "https://api.uuaid.org";
+var API_KEY = process.env.UUAID_API_KEY;
+var VAULT_KEY = process.env.UUAID_VAULT_KEY;
+var DEFAULT_AGENT = process.env.UUAID_AGENT;
+var client = new UuaidClient({ baseUrl: BASE_URL, apiKey: API_KEY });
+function text(v) {
+  return { content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) }] };
+}
+function err(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function agentOr(param) {
+  return param ?? DEFAULT_AGENT ?? null;
+}
+var server = new McpServer(
+  { name: "uuaid", version: "0.1.0" },
+  {
+    instructions: "UUAID gives you a permanent, verifiable identity (a UUAID) and encrypted memory that survives across sessions. Typical flow: (1) if no API key is configured, call uuaid_signup once and ask your operator to save the key; (2) call mint_identity once to get YOUR UUAID \u2014 reuse it forever; (3) save_memory / recall_memory to persist what matters beyond this session. Memories are encrypted client-side; the service only ever sees ciphertext."
+  }
+);
+server.registerTool(
+  "uuaid_signup",
+  {
+    description: "One-time self-serve signup: mints a free-tier UUAID API key (10 MB encrypted memory per agent). Returns the key ONCE \u2014 the operator must save it as UUAID_API_KEY (and generate UUAID_VAULT_KEY). Rate-limited.",
+    inputSchema: { name: z.string().min(2).max(80).describe("A name for this workspace/operator, e.g. 'Ana's Agent Lab'") }
+  },
+  async ({ name }) => {
+    if (API_KEY) return err("An API key is already configured (UUAID_API_KEY) \u2014 signup is not needed.");
+    const res = await UuaidClient.signup(name, { baseUrl: BASE_URL });
+    const vaultKey = generateVaultKey();
+    return text({
+      ...res,
+      generated_vault_key: vaultKey,
+      next_steps: "Save these in the MCP env NOW (shown once): UUAID_API_KEY=<api_key>, UUAID_VAULT_KEY=<generated_vault_key>. Then call mint_identity to create your permanent UUAID."
+    });
+  }
+);
+server.registerTool(
+  "mint_identity",
+  {
+    description: "Mint a PERMANENT UUAID identity for this agent (do this once, then reuse it \u2014 set it as UUAID_AGENT). The identity is publicly resolvable, ledger-recorded, and anchored on Polygon.",
+    inputSchema: {
+      display_name: z.string().min(1).describe("The agent's name, e.g. 'Aria'"),
+      description: z.string().optional().describe("What this agent is/does")
+    }
+  },
+  async ({ display_name, description }) => {
+    if (!API_KEY) return err("No UUAID_API_KEY configured \u2014 call uuaid_signup first.");
+    const res = await client.registerAgent({ display_name, description });
+    return text({
+      ...res,
+      note: "This UUAID is yours permanently. Ask your operator to set UUAID_AGENT to it so memory tools default to you.",
+      profile_url: `https://registry.uuaid.org/uuaid/${res.uuaid.split(":").slice(1).join("/")}`
+    });
+  }
+);
+server.registerTool(
+  "whoami",
+  { description: "Show the configured partner, default agent identity, and vault status.", inputSchema: {} },
+  async () => {
+    const me = API_KEY ? await client.me().catch((e) => ({ error: String(e) })) : { error: "no UUAID_API_KEY configured" };
+    return text({
+      partner: me,
+      default_agent: DEFAULT_AGENT ?? null,
+      vault_key_configured: Boolean(VAULT_KEY),
+      base_url: BASE_URL
+    });
+  }
+);
+server.registerTool(
+  "save_memory",
+  {
+    description: "Encrypt (client-side, AES-256-GCM) and persist a memory under a key path (e.g. 'core/persona', 'projects/x/notes'). Survives forever across sessions; the service stores only ciphertext; the content hash is ledger-anchored on-chain.",
+    inputSchema: {
+      key: z.string().min(1).max(512).describe("Slot path, e.g. 'core/persona' or 'memories/2026-07-03'"),
+      content: z.string().min(1).describe("The memory text to persist"),
+      agent_uuaid: z.string().optional().describe("Defaults to UUAID_AGENT")
+    }
+  },
+  async ({ key, content, agent_uuaid }) => {
+    if (!API_KEY) return err("No UUAID_API_KEY configured \u2014 call uuaid_signup first.");
+    if (!VAULT_KEY) return err("No UUAID_VAULT_KEY configured \u2014 memories must be encrypted. Generate one (uuaid vault keygen) and set it.");
+    const agent = agentOr(agent_uuaid);
+    if (!agent) return err("No agent identity: pass agent_uuaid or set UUAID_AGENT (mint one with mint_identity).");
+    const res = await client.saveMemory(agent, key, content, VAULT_KEY);
+    return text(res);
+  }
+);
+server.registerTool(
+  "recall_memory",
+  {
+    description: "Fetch and decrypt a memory previously stored with save_memory.",
+    inputSchema: {
+      key: z.string().min(1).max(512),
+      agent_uuaid: z.string().optional().describe("Defaults to UUAID_AGENT")
+    }
+  },
+  async ({ key, agent_uuaid }) => {
+    if (!API_KEY) return err("No UUAID_API_KEY configured.");
+    if (!VAULT_KEY) return err("No UUAID_VAULT_KEY configured \u2014 cannot decrypt.");
+    const agent = agentOr(agent_uuaid);
+    if (!agent) return err("No agent identity: pass agent_uuaid or set UUAID_AGENT.");
+    const content = await client.loadMemory(agent, key, VAULT_KEY);
+    return text(content);
+  }
+);
+server.registerTool(
+  "list_memories",
+  {
+    description: "List this agent's memory slots (keys, sizes, hashes) and vault usage vs quota. Contents stay encrypted.",
+    inputSchema: { agent_uuaid: z.string().optional().describe("Defaults to UUAID_AGENT") }
+  },
+  async ({ agent_uuaid }) => {
+    if (!API_KEY) return err("No UUAID_API_KEY configured.");
+    const agent = agentOr(agent_uuaid);
+    if (!agent) return err("No agent identity: pass agent_uuaid or set UUAID_AGENT.");
+    return text(await client.listVault(agent));
+  }
+);
+server.registerTool(
+  "delete_memory",
+  {
+    description: "Delete one memory slot (the deletion is ledger-recorded).",
+    inputSchema: {
+      key: z.string().min(1).max(512),
+      agent_uuaid: z.string().optional().describe("Defaults to UUAID_AGENT")
+    }
+  },
+  async ({ key, agent_uuaid }) => {
+    if (!API_KEY) return err("No UUAID_API_KEY configured.");
+    const agent = agentOr(agent_uuaid);
+    if (!agent) return err("No agent identity: pass agent_uuaid or set UUAID_AGENT.");
+    return text(await client.deleteVaultItem(agent, key));
+  }
+);
+server.registerTool(
+  "verify_agent",
+  {
+    description: "Publicly resolve any UUAID \u2014 profile, versions, credentials (no auth needed). Use to verify other agents.",
+    inputSchema: { uuaid: z.string().min(1).describe("uuaid:foundation:agent:\u2026") }
+  },
+  async ({ uuaid }) => text(await client.resolve(uuaid))
+);
+server.registerTool(
+  "get_badge_url",
+  {
+    description: "Live SVG trust-badge URLs for an agent \u2014 paste into a README to show verified identity/certification.",
+    inputSchema: { uuaid: z.string().min(1) }
+  },
+  async ({ uuaid }) => {
+    const enc = encodeURIComponent(uuaid);
+    return text({
+      agent_badge_svg: `${BASE_URL}/badge/agent/${enc}.svg`,
+      markdown: `[![UUAID verified](${BASE_URL}/badge/agent/${enc}.svg)](https://registry.uuaid.org/uuaid/${uuaid.split(":").slice(1).join("/")})`
+    });
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@uuaid/mcp",
+  "version": "0.1.0",
+  "description": "UUAID MCP server — give any AI agent a permanent identity and encrypted, quantum-ready memory that outlives the session. Mint a UUAID, save/recall memories, embed live trust badges.",
+  "keywords": [
+    "uuaid",
+    "mcp",
+    "modelcontextprotocol",
+    "ai-agents",
+    "agent-identity",
+    "agent-memory",
+    "post-quantum"
+  ],
+  "homepage": "https://uuaid.org",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "uuaid-mcp": "./dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0",
+    "@uuaid/sdk": "0.1.0",
+    "@uuaid/vault": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/server.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}