@scales-baby/nest-bridge 1.0.0

package/dist/mcp.js

@@ -0,0 +1,324 @@
+"use strict";
+// Bridge — the MCP server (stdio transport).
+//
+// Exposes list/get/search/create/update tools for people, companies, tasks,
+// events (+ get_digest). Reads decrypt locally; writes encrypt locally. The
+// Nest server only ever sees ciphertext + the API key.
+//
+// Scopes: the bridge respects the key's scopes by simply forwarding requests —
+// the Nest REST API enforces scope per-route (a read-only key gets 403 on a
+// write, surfaced back to Claude as an error). We also pre-gate write tools
+// when the key is known to be read-only, for a cleaner message.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServer = buildServer;
+exports.runStdio = runStdio;
+const zod_1 = require("zod");
+const nestClient_1 = require("./nestClient");
+async function loadSdk() {
+    const mcp = await Promise.resolve().then(() => __importStar(require("@modelcontextprotocol/sdk/server/mcp.js")));
+    const stdio = await Promise.resolve().then(() => __importStar(require("@modelcontextprotocol/sdk/server/stdio.js")));
+    return {
+        McpServer: mcp.McpServer,
+        StdioServerTransport: stdio.StdioServerTransport,
+    };
+}
+function jsonResult(value) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(value, null, 2) },
+        ],
+    };
+}
+function errResult(e) {
+    const msg = e instanceof nestClient_1.NestApiError
+        ? `Nest API error (${e.status}): ${e.message}`
+        : e instanceof Error
+            ? e.message
+            : String(e);
+    return {
+        isError: true,
+        content: [{ type: "text", text: msg }],
+    };
+}
+// Simple client-side fuzzy filter for search tools (the REST API has no text
+// search on encrypted content — we decrypt locally then match).
+function matches(row, q, keys) {
+    const needle = q.toLowerCase();
+    return keys.some((k) => {
+        const v = row[k];
+        return typeof v === "string" && v.toLowerCase().includes(needle);
+    });
+}
+async function buildServer(ctx) {
+    const { McpServer } = await loadSdk();
+    const server = new McpServer({
+        name: "nest-bridge",
+        version: "1.0.0",
+    });
+    const encNote = ctx.encrypted
+        ? ctx.unlocked
+            ? " This account is end-to-end encrypted; the bridge decrypts/encrypts locally so you see and write real content."
+            : " WARNING: this encrypted account is LOCKED (no key) — content fields will be blank."
+        : "";
+    // ---- generic registrars -------------------------------------------------
+    const listFilter = {
+        status: zod_1.z.string().optional().describe("Filter by status"),
+        dueWithin: zod_1.z
+            .enum(["today", "week", "overdue"])
+            .optional()
+            .describe("Filter by next-action / due date window"),
+        limit: zod_1.z.number().int().min(1).max(1000).optional(),
+    };
+    function registerList(name, model, desc, extra = {}) {
+        server.registerTool(name, {
+            description: desc + encNote,
+            inputSchema: { ...listFilter, ...extra },
+        }, async (args) => {
+            try {
+                const rows = await ctx.data.list(model, args);
+                return jsonResult({ count: rows.length, items: rows });
+            }
+            catch (e) {
+                return errResult(e);
+            }
+        });
+    }
+    function registerGet(name, model, desc) {
+        server.registerTool(name, {
+            description: desc + encNote,
+            inputSchema: { id: zod_1.z.string().describe("The record's _id") },
+        }, async (args) => {
+            try {
+                const row = await ctx.data.get(model, args.id);
+                if (!row)
+                    return errResult(new Error("not_found"));
+                return jsonResult(row);
+            }
+            catch (e) {
+                return errResult(e);
+            }
+        });
+    }
+    function registerSearch(name, model, keys, desc) {
+        server.registerTool(name, {
+            description: desc + encNote,
+            inputSchema: {
+                query: zod_1.z.string().describe("Text to fuzzy-match against content"),
+                limit: zod_1.z.number().int().min(1).max(1000).optional(),
+            },
+        }, async (args) => {
+            try {
+                const rows = await ctx.data.list(model, { limit: 1000 });
+                const hits = rows
+                    .filter((r) => matches(r, args.query, keys))
+                    .slice(0, args.limit ?? 50);
+                return jsonResult({ count: hits.length, items: hits });
+            }
+            catch (e) {
+                return errResult(e);
+            }
+        });
+    }
+    function registerCreate(name, model, shape, desc) {
+        server.registerTool(name, { description: desc + encNote, inputSchema: shape }, async (args) => {
+            if (!ctx.canWrite) {
+                return errResult(new Error("This API key is read-only (no write scope)."));
+            }
+            try {
+                const clean = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
+                const created = await ctx.data.create(model, clean);
+                return jsonResult(created);
+            }
+            catch (e) {
+                return errResult(e);
+            }
+        });
+    }
+    function registerUpdate(name, model, shape, desc) {
+        server.registerTool(name, {
+            description: desc + encNote,
+            inputSchema: { id: zod_1.z.string().describe("The record's _id"), ...shape },
+        }, async (args) => {
+            if (!ctx.canWrite) {
+                return errResult(new Error("This API key is read-only (no write scope)."));
+            }
+            try {
+                const { id, ...rest } = args;
+                const changes = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+                const updated = await ctx.data.update(model, id, changes);
+                return jsonResult(updated);
+            }
+            catch (e) {
+                return errResult(e);
+            }
+        });
+    }
+    // ---- PEOPLE -------------------------------------------------------------
+    registerList("list_people", "person", "List people in your CRM. Filter by status or dueWithin.");
+    registerGet("get_person", "person", "Get one person by id, with notes.");
+    registerSearch("search_people", "person", ["name", "companyName", "role", "notes", "channelMet"], "Search people by name/company/role/notes.");
+    registerCreate("create_person", "person", {
+        name: zod_1.z.string().describe("Full name"),
+        companyName: zod_1.z.string().optional(),
+        role: zod_1.z.string().optional(),
+        channelMet: zod_1.z.string().optional(),
+        status: zod_1.z.string().optional().describe("cold|contacted|replied|met|in_conversation|close|customer|dead|parked"),
+        nextAction: zod_1.z.string().optional(),
+        nextActionDate: zod_1.z.string().optional().describe("ISO date"),
+        linkedin: zod_1.z.string().optional(),
+        twitter: zod_1.z.string().optional(),
+        telegram: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+        tags: zod_1.z.array(zod_1.z.string()).optional(),
+    }, "Create a person.");
+    registerUpdate("update_person", "person", {
+        name: zod_1.z.string().optional(),
+        companyName: zod_1.z.string().optional(),
+        role: zod_1.z.string().optional(),
+        channelMet: zod_1.z.string().optional(),
+        status: zod_1.z.string().optional(),
+        nextAction: zod_1.z.string().optional(),
+        nextActionDate: zod_1.z.string().optional(),
+        linkedin: zod_1.z.string().optional(),
+        twitter: zod_1.z.string().optional(),
+        telegram: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+        tags: zod_1.z.array(zod_1.z.string()).optional(),
+    }, "Update a person (only the fields you pass change).");
+    // ---- COMPANIES ----------------------------------------------------------
+    registerList("list_companies", "company", "List companies.");
+    registerGet("get_company", "company", "Get one company by id, with notes.");
+    registerSearch("search_companies", "company", ["name", "notes"], "Search companies by name/notes.");
+    registerCreate("create_company", "company", {
+        name: zod_1.z.string().describe("Company name"),
+        city: zod_1.z.string().optional(),
+        category: zod_1.z.string().optional(),
+        website: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+        tags: zod_1.z.array(zod_1.z.string()).optional(),
+    }, "Create a company.");
+    registerUpdate("update_company", "company", {
+        name: zod_1.z.string().optional(),
+        city: zod_1.z.string().optional(),
+        category: zod_1.z.string().optional(),
+        website: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+        tags: zod_1.z.array(zod_1.z.string()).optional(),
+    }, "Update a company.");
+    // ---- TASKS --------------------------------------------------------------
+    registerList("list_tasks", "task", "List tasks. Filter by status or dueWithin.");
+    registerGet("get_task", "task", "Get one task by id, with notes.");
+    registerSearch("search_tasks", "task", ["title", "notes"], "Search tasks by title/notes.");
+    registerCreate("create_task", "task", {
+        title: zod_1.z.string().describe("Task title"),
+        dueDate: zod_1.z.string().optional().describe("ISO date"),
+        status: zod_1.z.string().optional().describe("open|done"),
+        priority: zod_1.z.string().optional().describe("high|medium|low"),
+        relatedPerson: zod_1.z.string().optional().describe("Person _id"),
+        relatedEvent: zod_1.z.string().optional().describe("Event _id"),
+        notes: zod_1.z.string().optional(),
+    }, "Create a task.");
+    registerUpdate("update_task", "task", {
+        title: zod_1.z.string().optional(),
+        dueDate: zod_1.z.string().optional(),
+        status: zod_1.z.string().optional(),
+        priority: zod_1.z.string().optional(),
+        relatedPerson: zod_1.z.string().optional(),
+        relatedEvent: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+    }, "Update a task.");
+    server.registerTool("complete_task", {
+        description: "Mark a task done (metadata-only).",
+        inputSchema: { id: zod_1.z.string().describe("The task _id") },
+    }, async (args) => {
+        if (!ctx.canWrite) {
+            return errResult(new Error("This API key is read-only (no write scope)."));
+        }
+        try {
+            return jsonResult(await ctx.data.completeTask(args.id));
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    // ---- EVENTS -------------------------------------------------------------
+    registerList("list_events", "event", "List events. Filter by status.");
+    registerGet("get_event", "event", "Get one event by id, with notes.");
+    registerSearch("search_events", "event", ["title", "notes", "researchNotes"], "Search events by title/notes.");
+    registerCreate("create_event", "event", {
+        title: zod_1.z.string().describe("Event title (kept as cleartext metadata)"),
+        date: zod_1.z.string().describe("ISO date"),
+        city: zod_1.z.string().optional(),
+        venue: zod_1.z.string().optional(),
+        type: zod_1.z.string().optional(),
+        status: zod_1.z.string().optional(),
+        url: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+        researchNotes: zod_1.z.string().optional(),
+        tags: zod_1.z.array(zod_1.z.string()).optional(),
+    }, "Create an event.");
+    registerUpdate("update_event", "event", {
+        title: zod_1.z.string().optional(),
+        date: zod_1.z.string().optional(),
+        city: zod_1.z.string().optional(),
+        venue: zod_1.z.string().optional(),
+        type: zod_1.z.string().optional(),
+        status: zod_1.z.string().optional(),
+        url: zod_1.z.string().optional(),
+        notes: zod_1.z.string().optional(),
+        researchNotes: zod_1.z.string().optional(),
+        tags: zod_1.z.array(zod_1.z.string()).optional(),
+    }, "Update an event.");
+    // ---- DIGEST -------------------------------------------------------------
+    server.registerTool("get_digest", {
+        description: "Get the actionable digest (overdue/today/this-week follow-ups + open tasks)." +
+            encNote,
+        inputSchema: {},
+    }, async () => {
+        try {
+            return jsonResult(await ctx.data.digest());
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    return server;
+}
+async function runStdio(server) {
+    const { StdioServerTransport } = await loadSdk();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/nestClient.js

@@ -0,0 +1,83 @@
+"use strict";
+// Bridge — typed HTTP client for the Nest REST API.
+//
+// Talks to nest.scales.baby (or a configured URL) using the user's SCOPED API
+// KEY as a Bearer token. The server returns CIPHERTEXT for encrypted accounts
+// (the `enc` blob + blanked plaintext columns) — decryption happens locally in
+// the bridge with the DEK. On writes the bridge sends ciphertext we built
+// locally. The server never sees the DEK, the password, or plaintext.
+//
+// trailingSlash:true on Nest → every API path MUST end in "/" (a no-slash path
+// 308-redirects and can drop a POST body).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestClient = exports.NestApiError = void 0;
+class NestApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "NestApiError";
+        this.status = status;
+    }
+}
+exports.NestApiError = NestApiError;
+class NestClient {
+    base;
+    key;
+    constructor(cfg) {
+        // Normalise: strip a trailing slash from the base; we add per-path slashes.
+        this.base = cfg.apiUrl.replace(/\/+$/, "");
+        this.key = cfg.apiKey;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.key}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+    }
+    // Ensure exactly one trailing slash (before any query string).
+    url(path) {
+        const [p, q] = path.split("?");
+        const withSlash = p.endsWith("/") ? p : `${p}/`;
+        return `${this.base}${withSlash}${q ? `?${q}` : ""}`;
+    }
+    async request(method, path, body) {
+        const res = await fetch(this.url(path), {
+            method,
+            headers: this.headers(),
+            body: body === undefined ? undefined : JSON.stringify(body),
+            redirect: "follow",
+        });
+        let json = null;
+        const text = await res.text();
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = null;
+        }
+        if (!res.ok) {
+            const msg = json?.error || text || res.statusText;
+            throw new NestApiError(msg || `request_failed_${res.status}`, res.status);
+        }
+        if (json && json.error) {
+            throw new NestApiError(json.error, res.status);
+        }
+        // Some endpoints return the data directly under `data`.
+        return (json ? json.data : null);
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    // --- bridge unlock: fetch the password-wrapped DEK blob ------------------
+    async getBridgeWrap() {
+        return this.get("/api/keys/bridge-wrap");
+    }
+}
+exports.NestClient = NestClient;

package/dist/prompt.js

@@ -0,0 +1,58 @@
+"use strict";
+// Bridge — secure hidden password prompt (stdin, no echo).
+//
+// Prompts on the CONTROLLING TTY so it works even when stdio is wired to an MCP
+// client over the pipe. We write the prompt to stderr and read the password
+// from the TTY with echo OFF, then restore terminal state. The password is held
+// only in memory by the caller and never persisted.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptHidden = promptHidden;
+const node_readline_1 = require("node:readline");
+const node_fs_1 = require("node:fs");
+// Read a line from the TTY with input hidden. Falls back to stdin if no TTY.
+async function promptHidden(question) {
+    // Prefer the real terminal so we don't consume the MCP stdio pipe.
+    let input;
+    let isTty = false;
+    try {
+        const fd = (0, node_fs_1.openSync)("/dev/tty", "r");
+        input = (0, node_fs_1.createReadStream)("", { fd });
+        isTty = true;
+    }
+    catch {
+        input = process.stdin;
+        isTty = process.stdin.isTTY === true;
+    }
+    const output = process.stderr;
+    return new Promise((resolve, reject) => {
+        const rl = (0, node_readline_1.createInterface)({ input, output, terminal: true });
+        // Mute echo: override the readline output writer so typed chars don't show.
+        let muted = false;
+        const realWrite = output.write.bind(output);
+        // @ts-expect-error patching the stream write for masking
+        rl._writeToOutput = (s) => {
+            if (muted) {
+                // Allow the prompt line + newline through; mask everything else.
+                if (s.includes(question))
+                    realWrite(s);
+                else if (s === "\n" || s === "\r\n")
+                    realWrite(s);
+                return;
+            }
+            realWrite(s);
+        };
+        rl.question(question, (answer) => {
+            muted = false;
+            rl.close();
+            // Newline after the (hidden) input so the next output starts cleanly.
+            output.write("\n");
+            resolve(answer);
+        });
+        muted = true;
+        rl.on("SIGINT", () => {
+            rl.close();
+            reject(new Error("cancelled"));
+        });
+        void isTty;
+    });
+}

package/manifest.json

@@ -0,0 +1,84 @@
+{
+  "manifest_version": "0.3",
+  "name": "scales-nest",
+  "display_name": "Nest by SCALES",
+  "version": "1.0.0",
+  "description": "Read and write your end-to-end-encrypted Nest through your own AI. Your encryption key is derived locally and never leaves your machine; Nest's servers only ever see ciphertext.",
+  "long_description": "Nest is your encrypted second brain (people, companies, tasks, events). This connector runs a small MCP server on your own machine. It fetches your password-wrapped key from Nest, unwraps it locally, then decrypts on read and encrypts on write right here. The Nest server only ever stores ciphertext and never receives your password, your key, or your plaintext. Mint a scoped API key in Nest (Settings then Connect your AI), paste it plus your encryption password below, and your AI can read and (with a full-control key) write your Nest data.",
+  "author": {
+    "name": "SCALES",
+    "url": "https://nest.scales.baby"
+  },
+  "homepage": "https://nest.scales.baby",
+  "icon": "icon.png",
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/dist/index.js"],
+      "env": {
+        "NEST_API_KEY": "${user_config.nest_api_key}",
+        "NEST_PASSWORD": "${user_config.nest_password}",
+        "NEST_API_URL": "${user_config.nest_api_url}",
+        "NEST_NON_INTERACTIVE": "1"
+      }
+    }
+  },
+  "tools": [
+    { "name": "list_people", "description": "List people in your Nest, decrypted locally." },
+    { "name": "get_person", "description": "Get one person by id, decrypted locally." },
+    { "name": "search_people", "description": "Search people by decrypted name or notes." },
+    { "name": "create_person", "description": "Create a person; encrypted locally before it is stored." },
+    { "name": "update_person", "description": "Update a person; re-encrypted locally before it is stored." },
+    { "name": "list_companies", "description": "List companies in your Nest." },
+    { "name": "get_company", "description": "Get one company by id." },
+    { "name": "search_companies", "description": "Search companies." },
+    { "name": "create_company", "description": "Create a company." },
+    { "name": "update_company", "description": "Update a company." },
+    { "name": "list_tasks", "description": "List tasks in your Nest." },
+    { "name": "get_task", "description": "Get one task by id." },
+    { "name": "search_tasks", "description": "Search tasks." },
+    { "name": "create_task", "description": "Create a task." },
+    { "name": "update_task", "description": "Update a task." },
+    { "name": "complete_task", "description": "Mark a task complete." },
+    { "name": "list_events", "description": "List events in your Nest." },
+    { "name": "get_event", "description": "Get one event by id." },
+    { "name": "search_events", "description": "Search events." },
+    { "name": "create_event", "description": "Create an event." },
+    { "name": "update_event", "description": "Update an event." },
+    { "name": "get_digest", "description": "Get your follow-up digest (overdue and upcoming)." }
+  ],
+  "keywords": ["crm", "encrypted", "mcp", "nest", "scales", "second-brain"],
+  "license": "MIT",
+  "compatibility": {
+    "claude_desktop": ">=0.10.0",
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "node": ">=20.0.0"
+    }
+  },
+  "user_config": {
+    "nest_api_key": {
+      "type": "string",
+      "title": "Nest API key",
+      "description": "Your scoped key from Nest (Settings then Connect your AI). Read-only is enough to read; choose Full control to let your AI create and update records. Looks like nest_xxxx_...",
+      "required": true,
+      "sensitive": true
+    },
+    "nest_password": {
+      "type": "string",
+      "title": "Nest encryption password",
+      "description": "The password you set when you turned on encryption in Nest. Used locally to unlock your key. It is stored in your operating system keychain and is never sent to Nest. Leave blank only if your account is not encrypted.",
+      "required": true,
+      "sensitive": true
+    },
+    "nest_api_url": {
+      "type": "string",
+      "title": "Nest URL (advanced)",
+      "description": "Leave as the default unless you are testing against another Nest instance.",
+      "required": false,
+      "default": "https://nest.scales.baby"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@scales-baby/nest-bridge",
+  "version": "1.0.0",
+  "description": "Local MCP bridge for Nest. Read and write your end-to-end-encrypted Nest data through your own AI; the encryption key is derived locally from your password and never leaves your machine.",
+  "license": "MIT",
+  "author": "SCALES (https://nest.scales.baby)",
+  "homepage": "https://nest.scales.baby",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scales-baby/nest-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/scales-baby/nest-bridge/issues"
+  },
+  "keywords": [
+    "crm",
+    "encrypted",
+    "e2e-encryption",
+    "mcp",
+    "model-context-protocol",
+    "nest",
+    "scales",
+    "second-brain",
+    "claude",
+    "ai"
+  ],
+  "type": "commonjs",
+  "bin": {
+    "nest-bridge": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist/",
+    "manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node ./dist/index.js",
+    "test": "node test/crypto-roundtrip.mjs",
+    "pack:mcpb": "bash scripts/pack-mcpb.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "hash-wasm": "^4.12.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.3"
+  }
+}