decoy-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,54 @@
+# decoy-mcp-server
+
+A local [MCP](https://modelcontextprotocol.io) bridge for [Decoy](https://decoys.me).
+It lets an AI agent (Claude Desktop, Claude Code, or any MCP client) manage your
+Decoy identities — create decoy email aliases, list and create accounts, and fill
+credentials — on your behalf.
+
+**End-to-end encrypted.** The bridge unwraps your vault-key grant and decrypts
+account data **on your machine**. Decoy's servers only ever see sealed blobs — they
+stay blind to your service↔identity graph.
+
+## Quick start
+
+```bash
+npx decoy-mcp-server
+```
+
+On first run it prints a pairing code and a link to **https://decoys.me/connect** —
+approve it in the Decoy iOS app. The approved agent token is saved to
+`~/.decoy/mcp-token` and reused on subsequent runs.
+
+The bridge serves MCP over HTTP at `http://localhost:3001/mcp`.
+
+### Connect your MCP client
+
+Point your client at the local bridge. For example, Claude Desktop
+(`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "decoy": { "url": "http://localhost:3001/mcp" }
+  }
+}
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `DECOY_AGENT_TOKEN` | — | Explicit agent token (skips interactive pairing) |
+| `PORT` | `3001` | Local HTTP port for the MCP endpoint |
+| `DECOY_AGENT_API_URL` | `https://api.decoys.me/api/agent` | Decoy agent API base |
+| `DECOY_AGENT_NAME` | `MCP Server` | Name shown in the Decoy approval prompt |
+
+Token and agent key live under `~/.decoy/`.
+
+## Docs
+
+Full tool catalog and guides: **https://decoys.me/documentation**
+
+## License
+
+MIT

package/dist/cxf-structured.d.ts

@@ -0,0 +1,12 @@
+export declare const STRUCTURED_CXF_TYPES: Set<string>;
+export interface StructuredFieldBlob {
+    id: string;
+    kind: string;
+    label: string | null;
+    values: Record<string, string>;
+}
+/**
+ * Reconstruct StructuredFieldBlob[] from a CXF Item's address/credit-card
+ * credentials. Returns [] when there are none. `genId` is injectable for tests.
+ */
+export declare function cxfItemToStructured(item: any, genId?: () => string): StructuredFieldBlob[];

package/dist/cxf-structured.js

@@ -0,0 +1,33 @@
+import { randomUUID } from 'node:crypto';
+// Multi-part typed fields (address, credit-card) ⇄ StructuredFieldBlob[].
+//
+// This is the MCP-server inverse of the iOS AccountMetadataBlob.toCXFItem mapping
+// (CryptoService.swift). Each such CXF credential carries its members as
+// EditableFields whose `designation` IS the CXF member name (= the
+// StructuredFieldBlob `values` key), e.g. address → streetAddress/city/postalCode/…,
+// credit-card → number/fullName/expiryDate/verificationNumber.
+//
+// CRITICAL: every emitted entry MUST have a string `id`. iOS StructuredFieldBlob.id
+// is a required Codable key with no custom decoder, so a missing id makes the entire
+// `structured` array silently decode to nil on the device → the user's address/card
+// vanishes. The id is ephemeral (iOS regenerates it on its own CXF reads), so a fresh
+// uuid per reconstruction is correct.
+export const STRUCTURED_CXF_TYPES = new Set(['address', 'credit-card']);
+/**
+ * Reconstruct StructuredFieldBlob[] from a CXF Item's address/credit-card
+ * credentials. Returns [] when there are none. `genId` is injectable for tests.
+ */
+export function cxfItemToStructured(item, genId = randomUUID) {
+    const creds = (item && item.credentials) || [];
+    return creds
+        .filter((c) => STRUCTURED_CXF_TYPES.has(c?.type))
+        .map((c) => {
+        const values = {};
+        for (const f of (c.fields || [])) {
+            if (f?.designation)
+                values[f.designation] = f.value;
+        }
+        return { id: genId(), kind: c.type, label: c.label ?? null, values };
+    })
+        .filter((s) => Object.keys(s.values).length > 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Decoy MCP Server v2.2 — Streamable HTTP transport
+ *
+ * Setup: first run opens decoys.me/connect?code=... in the user's browser → scan QR
+ * with the Decoy iOS app → approved token saved to ~/.decoy/mcp-token and reused
+ * on subsequent runs. No localhost setup page — the public website is the kiosk.
+ *
+ * Auth priority:
+ *   1. DECOY_AGENT_TOKEN env var (explicit override)
+ *   2. ~/.decoy/mcp-token config file (saved after first pairing)
+ *   3. Interactive pairing via decoys.me/connect (first-time setup)
+ *
+ * ENV:
+ *   DECOY_AGENT_TOKEN    Explicit agent token (skips pairing)
+ *   DECOY_AGENT_API_URL  Base URL for agent API (default: https://api.decoys.me/api/agent)
+ *   DECOY_CONNECT_URL    Frontend pairing page (default: https://decoys.me/connect)
+ *   DECOY_AGENT_FOR      Slug for ?for= param so the website shows the right agent
+ *                        name (e.g. claude-code, cursor, gemini, codex). Default: mcp
+ *   PORT                 HTTP port (default: 3001)
+ *   DEV_MODE             "true" → use dev-api.decoys.me
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function openVault(blobBase64: string, vaultKey: Buffer): Record<string, unknown>;
+export declare function sealVault(value: unknown, vaultKey: Buffer): string;
+/** Injectable dependencies — production uses the real HTTP client + grant-based
+ *  vault key; tests inject an in-memory API and a fixed test key to exercise the
+ *  real tool handlers (schema validation → crypto → re-seal) without a network. */
+export interface ServerDeps {
+    call?: <T = unknown>(path: string, method?: string, body?: Record<string, unknown>) => Promise<T>;
+    getVaultKey?: () => Promise<Buffer | null>;
+}
+export declare function buildMcpServer(agentToken: string, privateKeyPem?: string, deps?: ServerDeps): McpServer;