@pinmark/mcp 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @pinmark/mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **PinMark** — let AI agents create, search,
+update, and organize sticky notes on your Mac. **Fully local**: notes never leave your machine,
+there's no network backend, and no third-party analytics. The agent reads and writes the notes
+you choose to expose to it.
+
+It's a thin adapter over the `pinmark` command-line tool: the PinMark app remains the single
+source of truth for storage, validation, and the free/Pro boundary.
+
+## Requirements
+
+- macOS with **PinMark** installed.
+- The `pinmark` CLI installed (PinMark → Settings → Command Line Tool). The server looks for
+  `~/.local/bin/pinmark`, then falls back to your `PATH`.
+
+## Use with an MCP client
+
+Add to your client config (e.g. Claude Desktop `claude_desktop_config.json`, or Cursor):
+
+```json
+{
+  "mcpServers": {
+    "pinmark": {
+      "command": "npx",
+      "args": ["-y", "@pinmark/mcp"]
+    }
+  }
+}
+```
+
+The server runs over stdio and is launched on demand by the client.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `create_note` | Create a text note (Markdown). |
+| `append_to_note` | Append text to an existing note. |
+| `update_note` | Update content / title / color / caption. |
+| `get_note` | Fetch one note with full content. |
+| `list_notes` | List notes (excludes trash unless asked). |
+| `search_notes` | Search by title, content, caption, or image filename. |
+| `delete_note` | Move a note to the trash (recoverable). |
+| `restore_note` | Restore a note from the trash. |
+| `pin_note` / `unpin_note` | Pin / unpin a note. |
+| `open_note` | Bring a note to the foreground (this one activates PinMark). |
+
+Note ids come from `list_notes` / `search_notes` / `create_note`. Content is Markdown.
+
+## Behavior notes
+
+- **Non-disruptive**: every operation reaches PinMark without stealing focus, except `open_note`
+  (and `*_open`), which intentionally brings the note to the foreground.
+- **Pro features**: custom note colors (non-preset) and a few limits are enforced by the app;
+  if a call hits one, the tool returns a clear error (e.g. `custom_color_requires_pro`).
+- **Trash safety**: `delete_note` is a recoverable trash move; there is no permanent delete.
+  Other mutations don't act on trashed notes.
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm test        # vitest (invocation-layer unit tests)
+```
+
+## Publishing
+
+This is a **public** scoped package. `publishConfig.access` is set to `public` in
+`package.json`, so `npm publish` does not need an explicit `--access public` flag.
+
+First-time setup:
+
+- An npm account, and membership in the `pinmark` org (the `@pinmark` scope). Create the org at
+  npmjs.com if it doesn't exist yet — a free org can publish unlimited public packages.
+
+Each release:
+
+```bash
+npm login                       # or use an automation token in CI
+npm publish                     # prepack runs the build; add --otp=<code> if 2FA is on
+npm view @pinmark/mcp version   # verify the published version
+npx -y @pinmark/mcp             # smoke test: should start the stdio server
+```
+
+`npx -y @pinmark/mcp` always pulls the latest published version, so keep the published version's
+CLI protocol compatible with the PinMark app that's shipping. Bump the package version whenever
+the `pinmark` CLI contract changes.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// pinmark-mcp entry: resolve the CLI, warm up the app, and serve MCP over stdio.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveCliPath, runPinmark, PinmarkError } from "./pinmark.js";
+import { createServer } from "./server.js";
+async function main() {
+    // Layer 1 — CLI health check: is the `pinmark` binary installed?
+    let cliPath;
+    try {
+        cliPath = await resolveCliPath();
+    }
+    catch (error) {
+        const message = error instanceof PinmarkError ? error.message : String(error);
+        process.stderr.write(`pinmark-mcp: ${message}\n`);
+        process.exit(1);
+    }
+    // Layer 2 — App warm-up (best-effort): a non-activating ping so the first real tool call hits
+    // a warm app. Never blocks startup; if the app isn't running it will cold-launch on first use.
+    void runPinmark(cliPath, { kind: "ping" }, 6000).catch(() => {
+        process.stderr.write("pinmark-mcp: PinMark not responding to warm-up ping; it will launch on first use.\n");
+    });
+    const server = createServer(cliPath);
+    await server.connect(new StdioServerTransport());
+    process.stderr.write("pinmark-mcp: ready (stdio)\n");
+}
+main().catch((error) => {
+    process.stderr.write(`pinmark-mcp: fatal: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/pinmark.js

@@ -0,0 +1,194 @@
+// Invocation layer: translate an MCP tool call into a `pinmark` CLI invocation and run it.
+// Thin adapter — the CLI + PinMark app remain the single source of truth for validation,
+// Pro gating, and note storage. See doc/requirement/pinmark-mcp-*.md.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Query commands accept `--format json`; mutation commands reject it and always return JSON. */
+const QUERY_COMMANDS = new Set(["list", "search", "show", "open"]);
+/**
+ * Builds the CLI invocation for a command. Hard rules (kept in sync with the CLI contract):
+ * - No shell: caller uses spawn/execFile with this argv array.
+ * - Note body (create/append/update) goes via `--from-file -` + stdin, never argv (length /
+ *   escaping / process-list exposure).
+ * - `--format json` only for query commands; mutation commands must not receive it.
+ * - `--no-activate` is appended to every call (wake layer); only `open` / `--open` activate the
+ *   app at the execution layer, which `--no-activate` does not suppress.
+ */
+export function buildInvocation(cmd) {
+    const argv = [];
+    let stdin;
+    const pushBody = (content) => {
+        if (content !== undefined) {
+            argv.push("--from-file", "-");
+            stdin = content;
+        }
+    };
+    switch (cmd.kind) {
+        case "create":
+            argv.push("create", "--type", "text");
+            if (cmd.title !== undefined)
+                argv.push("--title", cmd.title);
+            if (cmd.color !== undefined)
+                argv.push("--color", cmd.color);
+            if (cmd.open)
+                argv.push("--open");
+            pushBody(cmd.content);
+            break;
+        case "append":
+            argv.push("append", cmd.noteId);
+            if (cmd.separator !== undefined)
+                argv.push("--separator", cmd.separator);
+            if (cmd.open)
+                argv.push("--open");
+            pushBody(cmd.content);
+            break;
+        case "update":
+            argv.push("update", cmd.noteId);
+            if (cmd.title !== undefined)
+                argv.push("--title", cmd.title);
+            if (cmd.color !== undefined)
+                argv.push("--color", cmd.color);
+            if (cmd.caption !== undefined)
+                argv.push("--caption", cmd.caption);
+            pushBody(cmd.content);
+            break;
+        case "list":
+            argv.push("list");
+            if (cmd.type !== undefined)
+                argv.push("--type", cmd.type);
+            if (cmd.limit !== undefined)
+                argv.push("--limit", String(cmd.limit));
+            if (cmd.includeTrash)
+                argv.push("--include-trash");
+            break;
+        case "search":
+            argv.push("search", cmd.query);
+            if (cmd.type !== undefined)
+                argv.push("--type", cmd.type);
+            if (cmd.limit !== undefined)
+                argv.push("--limit", String(cmd.limit));
+            if (cmd.includeTrash)
+                argv.push("--include-trash");
+            break;
+        case "get":
+            argv.push("show", cmd.noteId);
+            break;
+        case "open":
+            argv.push("open", cmd.noteId);
+            break;
+        case "delete":
+        case "restore":
+        case "pin":
+        case "unpin":
+            argv.push(cmd.kind, cmd.noteId);
+            break;
+        case "ping":
+            argv.push("ping");
+            break;
+    }
+    if (QUERY_COMMANDS.has(argv[0])) {
+        argv.push("--format", "json");
+    }
+    argv.push("--no-activate");
+    return { argv, stdin };
+}
+/** Error carrying the CLI/app response code so the MCP layer can surface a stable code. */
+export class PinmarkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PinmarkError";
+    }
+}
+/** Resolves the installed `pinmark` binary: prefer ~/.local/bin, else PATH. */
+export async function resolveCliPath() {
+    const preferred = join(homedir(), ".local", "bin", "pinmark");
+    if (existsSync(preferred))
+        return preferred;
+    const fromPath = await which("pinmark");
+    if (fromPath)
+        return fromPath;
+    throw new PinmarkError("cli_not_installed", "The `pinmark` CLI was not found. Install it from PinMark → Settings → Command Line Tool.");
+}
+function which(bin) {
+    return new Promise((resolve) => {
+        const child = spawn("/usr/bin/which", [bin], { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        child.stdout.on("data", (d) => (out += d));
+        child.on("error", () => resolve(undefined));
+        child.on("close", (code) => resolve(code === 0 && out.trim() ? out.trim() : undefined));
+    });
+}
+export function execFilePinmark(cliPath, argv, stdin, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(cliPath, argv, { stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        child.stdin.on("error", () => { });
+        child.stdout.on("error", () => { });
+        child.stderr.on("error", () => { });
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr: stderr || String(e), code: 127 });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code: code ?? (timedOut ? 124 : 1), timedOut });
+        });
+        try {
+            if (stdin !== undefined)
+                child.stdin.write(stdin);
+            child.stdin.end();
+        }
+        catch {
+            // The child may have exited before consuming stdin; stream error handlers above keep the
+            // server alive and the close/error events still produce the command result.
+        }
+    });
+}
+function codeFromExit(code, stderr = "") {
+    switch (code) {
+        case 2: return "invalid_request";
+        case 3: return /timed out|timeout/i.test(stderr) ? "timeout" : "app_not_available";
+        case 4: return "note_not_found";
+        case 5: return "permission_denied";
+        case 124: return "timeout";
+        default: return "operation_failed";
+    }
+}
+/**
+ * Runs a command and returns the response payload. Throws `PinmarkError` on failure.
+ * The CLI prints the full JSON response to stdout for JSON commands even on app errors (then
+ * exits non-zero), so we parse stdout first and fall back to stderr + exit code for usage errors.
+ */
+export async function runPinmark(cliPath, cmd, timeoutMs = 20000) {
+    const { argv, stdin } = buildInvocation(cmd);
+    const { stdout, stderr, code, timedOut } = await execFilePinmark(cliPath, argv, stdin, timeoutMs);
+    let parsed;
+    try {
+        parsed = stdout.trim() ? JSON.parse(stdout) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed && typeof parsed === "object" && "ok" in parsed) {
+        const response = parsed;
+        if (response.ok)
+            return response.payload ?? {};
+        throw new PinmarkError(response.error?.code ?? "operation_failed", response.error?.message ?? "PinMark command failed.");
+    }
+    if (code === 0)
+        return {};
+    const message = (stderr || stdout || "PinMark command failed.").trim();
+    throw new PinmarkError(timedOut ? "timeout" : codeFromExit(code, message), message);
+}

package/dist/server.js

@@ -0,0 +1,107 @@
+// MCP server: registers PinMark note tools and maps each to a `pinmark` CLI invocation.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runPinmark, PinmarkError } from "./pinmark.js";
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function fail(error) {
+    if (error instanceof PinmarkError) {
+        return { content: [{ type: "text", text: `Error [${error.code}]: ${error.message}` }], isError: true };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+const noteIdSchema = z.string().describe("The note's UUID, as returned by list_notes / search_notes / create_note.");
+export function createServer(cliPath) {
+    const server = new McpServer({ name: "pinmark-mcp", version: "0.1.0" });
+    const run = async (cmd) => {
+        try {
+            return ok(await runPinmark(cliPath, cmd));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    };
+    server.registerTool("create_note", {
+        title: "Create note",
+        description: "Create a new text note on the desktop. Content is Markdown. Returns the new note's id.",
+        inputSchema: {
+            content: z.string().optional().describe("Markdown body of the note."),
+            title: z.string().optional().describe("Optional title; if omitted PinMark derives one from the content."),
+            color: z.string().optional().describe("Preset color name (yellow, blue, green, pink, purple, gray, white) or hex; custom colors require Pro."),
+            open: z.boolean().optional().describe("Bring the new note to the foreground after creating it."),
+        },
+    }, async (args) => run({ kind: "create", ...args }));
+    server.registerTool("append_to_note", {
+        title: "Append to note",
+        description: "Append Markdown text to an existing text note (e.g. to maintain a running log).",
+        inputSchema: {
+            noteId: noteIdSchema,
+            content: z.string().describe("Markdown text to append."),
+            separator: z.string().optional().describe("Separator inserted before the new text when the note is non-empty. Defaults to a blank line."),
+            open: z.boolean().optional().describe("Bring the note to the foreground after appending."),
+        },
+    }, async (args) => run({ kind: "append", ...args }));
+    server.registerTool("update_note", {
+        title: "Update note",
+        description: "Update an existing note. Provide at least one of content (text notes), title, color (text notes), or caption (image notes).",
+        inputSchema: {
+            noteId: noteIdSchema,
+            content: z.string().optional().describe("Replace the body (text notes only)."),
+            title: z.string().optional().describe("Set the title (text or image notes)."),
+            color: z.string().optional().describe("Background color (text notes only); custom colors require Pro."),
+            caption: z.string().optional().describe("Set the caption (image notes only)."),
+        },
+    }, async (args) => run({ kind: "update", ...args }));
+    server.registerTool("get_note", {
+        title: "Get note",
+        description: "Fetch one note by id, including its full content / caption.",
+        inputSchema: { noteId: noteIdSchema },
+    }, async (args) => run({ kind: "get", ...args }));
+    server.registerTool("list_notes", {
+        title: "List notes",
+        description: "List notes. Excludes trash unless includeTrash is set.",
+        inputSchema: {
+            type: z.enum(["text", "image"]).optional().describe("Filter by note type."),
+            limit: z.number().int().min(1).max(200).optional().describe("Max results (1-200, default 20)."),
+            includeTrash: z.boolean().optional().describe("Include notes in the trash."),
+        },
+    }, async (args) => run({ kind: "list", ...args }));
+    server.registerTool("search_notes", {
+        title: "Search notes",
+        description: "Search notes by title, content, caption, or image filename.",
+        inputSchema: {
+            query: z.string().describe("Search query."),
+            type: z.enum(["text", "image"]).optional().describe("Filter by note type."),
+            limit: z.number().int().min(1).max(200).optional().describe("Max results (1-200, default 20)."),
+            includeTrash: z.boolean().optional().describe("Include notes in the trash."),
+        },
+    }, async (args) => run({ kind: "search", ...args }));
+    server.registerTool("delete_note", {
+        title: "Delete note",
+        description: "Move a note to the trash. Recoverable with restore_note; not a permanent delete.",
+        inputSchema: { noteId: noteIdSchema },
+    }, async (args) => run({ kind: "delete", ...args }));
+    server.registerTool("restore_note", {
+        title: "Restore note",
+        description: "Restore a note from the trash.",
+        inputSchema: { noteId: noteIdSchema },
+    }, async (args) => run({ kind: "restore", ...args }));
+    server.registerTool("pin_note", {
+        title: "Pin note",
+        description: "Pin a note so it stays above others.",
+        inputSchema: { noteId: noteIdSchema },
+    }, async (args) => run({ kind: "pin", ...args }));
+    server.registerTool("unpin_note", {
+        title: "Unpin note",
+        description: "Unpin a note.",
+        inputSchema: { noteId: noteIdSchema },
+    }, async (args) => run({ kind: "unpin", ...args }));
+    server.registerTool("open_note", {
+        title: "Open note",
+        description: "Bring a note to the foreground on the desktop (this one intentionally activates PinMark).",
+        inputSchema: { noteId: noteIdSchema },
+    }, async (args) => run({ kind: "open", ...args }));
+    return server;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pinmark/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PinMark — let AI agents create, search, and organize notes on your Mac, fully local.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pinmark-mcp": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  }
+}