@letterapp/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 letter.app
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @letterapp/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that gives your AI coding agent tools to set up and verify a [Letter](https://letter.app) integration.
+
+It reads the credential written by `npx @letterapp/cli` (`~/.letter/credentials.json`), so **your MCP config never contains a secret**.
+
+## Setup
+
+First authenticate once from your project:
+
+```bash
+npx @letterapp/cli
+```
+
+This opens a browser to confirm and writes `LETTER_API_KEY` to `.env.local` plus `~/.letter/credentials.json` (used by this server). The key is never printed to your terminal or chat.
+
+Then add the server to your MCP client (e.g. `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "letter": {
+      "command": "npx",
+      "args": ["-y", "@letterapp/mcp"]
+    }
+  }
+}
+```
+
+No API key in the config. The server resolves it from `~/.letter/credentials.json`, or from `LETTER_API_KEY` in the environment (handy for CI).
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `setup_guide` | Returns Letter's step-by-step integration guide (markdown). |
+| `check_connection` | Reports whether the connected project has received any contacts or events. |
+| `send_test_event` | Sends a test `identify` + `track` to prove the pipe works. |
+| `identify` | Report a user (`userId`, optional `email`, `traits`). |
+| `track` | Report an event (`userId`, `event`, optional `properties`). |
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `LETTER_API_KEY` | (from credential file) | Overrides the stored credential. |
+| `LETTER_BASE_URL` | `https://api.letter.app` | API origin (self-host/dev). |
+| `LETTER_DOCS_URL` | `https://letter.app` | Docs origin used by `setup_guide`. |
+
+## License
+
+MIT

package/dist/credentials.js

@@ -0,0 +1,41 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+export const DEFAULT_API_BASE = "https://api.letter.app";
+export const DEFAULT_DOCS_BASE = "https://letter.app";
+/**
+ * Resolves the Letter credential for the MCP server, in priority order:
+ *   1. LETTER_API_KEY (+ LETTER_BASE_URL) from the environment.
+ *   2. ~/.letter/credentials.json written by `npx @letterapp/cli`.
+ *
+ * Returns null when neither is present, so tools can return a friendly
+ * "run `npx @letterapp/cli` first" message instead of crashing. The secret is
+ * never logged or echoed back through tool results.
+ */
+export async function resolveCredential() {
+    const envKey = process.env.LETTER_API_KEY;
+    if (envKey) {
+        return {
+            apiKey: envKey,
+            baseUrl: (process.env.LETTER_BASE_URL || DEFAULT_API_BASE).replace(/\/$/, ""),
+        };
+    }
+    try {
+        const file = path.join(homedir(), ".letter", "credentials.json");
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (!parsed.apiKey)
+            return null;
+        return {
+            apiKey: parsed.apiKey,
+            baseUrl: (parsed.baseUrl || DEFAULT_API_BASE).replace(/\/$/, ""),
+            project: parsed.project,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Docs origin for fetching the agent-setup guide. */
+export function docsBase() {
+    return (process.env.LETTER_DOCS_URL || DEFAULT_DOCS_BASE).replace(/\/$/, "");
+}

package/dist/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { docsBase, resolveCredential, } from "./credentials.js";
+const VERSION = "0.1.0";
+const USER_AGENT = "@letterapp/mcp";
+function text(t, isError = false) {
+    return { content: [{ type: "text", text: t }], isError };
+}
+const NOT_CONNECTED = text("No Letter credential found. Run `npx @letterapp/cli` in your project to log in (it writes ~/.letter/credentials.json), or set LETTER_API_KEY in the environment. The key is provisioned via a browser confirmation - never paste it into chat.", true);
+async function api(cred, method, pathname, body) {
+    const res = await fetch(`${cred.baseUrl}${pathname}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${cred.apiKey}`,
+            "content-type": "application/json",
+            "user-agent": USER_AGENT,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    let json = null;
+    try {
+        json = await res.json();
+    }
+    catch {
+        json = null;
+    }
+    return { ok: res.ok, status: res.status, json };
+}
+async function main() {
+    const server = new McpServer({ name: "letter", version: VERSION });
+    // setup_guide: hand the agent the full, current integration steps.
+    server.tool("setup_guide", "Get Letter's step-by-step integration guide (install, authenticate, instrument identify/track). Returns markdown an agent can follow.", {}, async () => {
+        try {
+            const res = await fetch(`${docsBase()}/docs/agent-setup/raw`, {
+                headers: { "user-agent": USER_AGENT },
+            });
+            if (res.ok)
+                return text(await res.text());
+        }
+        catch {
+            // fall through to the built-in summary
+        }
+        return text([
+            "# Letter setup",
+            "1. Run `npx @letterapp/cli` in the project root to authenticate (browser confirm) and install @letterapp/node. It writes LETTER_API_KEY to .env.local.",
+            "2. Create a server-side client: `new Letter({ apiKey: process.env.LETTER_API_KEY! })`.",
+            "3. Call `letter.identify({ userId, email, traits })` where users sign up/log in.",
+            "4. Call `letter.track({ userId, event })` on 2-3 key actions.",
+            "5. Verify with the `check_connection` tool.",
+            "Full docs: https://letter.app/docs/agent-setup",
+        ].join("\n"));
+    });
+    // check_connection: confirm the project has received data.
+    server.tool("check_connection", "Check whether the connected Letter project has received any contacts or events yet. Use to verify the integration is live.", {}, async () => {
+        const cred = await resolveCredential();
+        if (!cred)
+            return NOT_CONNECTED;
+        const { ok, status, json } = await api(cred, "GET", "/v1/status");
+        if (!ok) {
+            return text(`Could not reach Letter (HTTP ${status}).`, true);
+        }
+        const data = json;
+        const name = data.project?.name ?? cred.project?.name ?? "your project";
+        return text(data.connected
+            ? `Connected. ${name} has ${data.contacts ?? 0} contact(s) and ${data.events ?? 0} event(s).`
+            : `${name} is set up but hasn't received any data yet. Trigger an identify/track call (or use send_test_event).`);
+    });
+    // send_test_event: prove the pipe end to end.
+    server.tool("send_test_event", "Send a test identify + track to Letter to prove the connection works. Optionally pass a userId/email.", {
+        userId: z.string().optional(),
+        email: z.string().optional(),
+    }, async ({ userId, email }) => {
+        const cred = await resolveCredential();
+        if (!cred)
+            return NOT_CONNECTED;
+        const uid = userId || `mcp_test_${Date.now()}`;
+        const mail = email || `${uid}@example.com`;
+        const idRes = await api(cred, "POST", "/v1/identify", {
+            userId: uid,
+            email: mail,
+            traits: { name: "MCP Test", source: "mcp" },
+        });
+        if (!idRes.ok) {
+            return text(`identify failed (HTTP ${idRes.status}).`, true);
+        }
+        const trackRes = await api(cred, "POST", "/v1/track", {
+            userId: uid,
+            event: "MCP Test Event",
+            properties: { via: "@letterapp/mcp" },
+        });
+        if (!trackRes.ok) {
+            return text(`track failed (HTTP ${trackRes.status}).`, true);
+        }
+        return text(`Sent a test contact (${uid}) and a "MCP Test Event". Check your Letter dashboard, or run check_connection.`);
+    });
+    // identify passthrough.
+    server.tool("identify", "Report a user to Letter (Segment-style identify). Use a stable userId.", {
+        userId: z.string(),
+        email: z.string().optional(),
+        traits: z.record(z.any()).optional(),
+    }, async ({ userId, email, traits }) => {
+        const cred = await resolveCredential();
+        if (!cred)
+            return NOT_CONNECTED;
+        const res = await api(cred, "POST", "/v1/identify", {
+            userId,
+            email,
+            traits,
+        });
+        return res.ok
+            ? text(`Identified ${userId}.`)
+            : text(`identify failed (HTTP ${res.status}).`, true);
+    });
+    // track passthrough.
+    server.tool("track", "Report an event a user performed to Letter (Segment-style track).", {
+        userId: z.string(),
+        event: z.string(),
+        properties: z.record(z.any()).optional(),
+    }, async ({ userId, event, properties }) => {
+        const cred = await resolveCredential();
+        if (!cred)
+            return NOT_CONNECTED;
+        const res = await api(cred, "POST", "/v1/track", {
+            userId,
+            event,
+            properties,
+        });
+        return res.ok
+            ? text(`Tracked "${event}" for ${userId}.`)
+            : text(`track failed (HTTP ${res.status}).`, true);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`letter-mcp failed to start: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@letterapp/mcp",
+  "version": "0.1.0",
+  "description": "Letter MCP server - give your AI agent tools to set up and verify a Letter integration. Reads the credential written by `letter login`; no secret in your MCP config.",
+  "license": "MIT",
+  "homepage": "https://letter.app",
+  "author": "letter.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vincenzor/letter-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vincenzor/letter-mcp/issues"
+  },
+  "type": "module",
+  "bin": {
+    "letter-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "letter",
+    "letterapp",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}