blujay-mcp 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0 (2026-11-10)
+
+First release.
+
+- Read tools: account and numbers, conversations, transcripts, who needs a reply, message status, iMessage checks, contacts, webhooks, docs search
+- Write tools: send texts (to phone numbers, or email addresses over iMessage) with a photo, video, document (PDF, .docx, .xlsx, .pptx; iMessage or RCS) or contact card (from a link, or a file on your computer in one step), iMessage effects on follow-ups, audio files as voice memos, reactions (tapbacks and emoji), edit and unsend, read receipts, typing, group changes, contacts, opt-outs, webhooks
+- Safety: `--read-only`, `--allow-send-to`, read/act labels on every tool, an idempotency key on every send
+- Prompts: Who needs a reply?, Summarize a conversation, Send me a test message
+- `--enable-invoke-api` adds `invoke_api` for any endpoint

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blujay
+
+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

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# Blujay MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/blujay-mcp)](https://www.npmjs.com/package/blujay-mcp)
+[![CI](https://github.com/blujayhq/blujay-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/blujayhq/blujay-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Let Claude, Cursor, VS Code and other AI assistants work with your [Blujay](https://blujay.io) account: read conversations, see who needs a reply, and send iMessage, RCS and SMS from your Blujay phone numbers.
+
+> **Every text is real.** Blujay has no test mode. Most assistants ask before each send unless you've set them to approve tools automatically, so try it with `--allow-send-to` limited to your own number first (see [Safety](#safety)).
+
+## What you can ask
+
+- "Who texted me today that I haven't answered?"
+- "Summarize my conversation with Ava and draft a reply."
+- "Text +1 555 555 0123: running 10 minutes late."
+- "Send Ava the photo on my Desktop called beach.jpg."
+- "Text Sam the lease PDF in my Downloads folder."
+- "Send Ava happy birthday with balloons."
+- "Did my last message to Sam get delivered?"
+- "Does this number have iMessage?"
+- "Set up a webhook to https://example.com/blujay for new messages."
+- "How do I verify webhook signatures?"
+
+## Setup
+
+You need Node.js 20 or later and a Blujay API key from the **API** tab in Blujay.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=blujay&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJsdWpheS1tY3AiXSwiZW52Ijp7IkJMVUpBWV9BUElfS0VZIjoiYmx1X3lvdXJfYXBpX2tleSJ9fQ==)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Blujay-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=blujay&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22blujay-mcp%22%5D%2C%22env%22%3A%7B%22BLUJAY_API_KEY%22%3A%22blu_your_api_key%22%7D%7D)
+
+The buttons add the server with a placeholder key; replace `blu_your_api_key` with yours.
+
+### Claude Desktop
+
+Open **Settings → Developer → Edit Config** and add:
+
+```json
+{
+  "mcpServers": {
+    "blujay": {
+      "command": "npx",
+      "args": ["-y", "blujay-mcp"],
+      "env": { "BLUJAY_API_KEY": "blu_your_api_key" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+### Claude Code
+
+```sh
+claude mcp add blujay --env BLUJAY_API_KEY=blu_your_api_key -- npx -y blujay-mcp
+```
+
+### Cursor
+
+In **Cursor Settings → Tools & MCP → New MCP Server**, add to `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "blujay": {
+      "command": "npx",
+      "args": ["-y", "blujay-mcp"],
+      "env": { "BLUJAY_API_KEY": "blu_your_api_key" }
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "blujay": {
+      "command": "npx",
+      "args": ["-y", "blujay-mcp"],
+      "env": { "BLUJAY_API_KEY": "${input:blujay-api-key}" }
+    }
+  },
+  "inputs": [
+    { "id": "blujay-api-key", "type": "promptString", "description": "Blujay API key", "password": true }
+  ]
+}
+```
+
+### Other MCP clients
+
+Run `npx -y blujay-mcp` with `BLUJAY_API_KEY` set. It speaks MCP over stdio.
+
+## Safety
+
+- **Assistants ask before sends.** Every tool is labeled read or act, so your client can approve reads and ask before anything reaches a person.
+- **`--allow-send-to +15555550123`** limits every send and change to the numbers you list; try it on your own number first.
+- **`--read-only`** leaves out every tool that sends, changes or deletes.
+- **Files only by full path:** photos, videos, documents, contact cards and audio up to 100 MiB, checked by their contents.
+
+Details, including what these checks can't stop, are in [SECURITY.md](SECURITY.md).
+
+## Tools
+
+| Tool | What it does | Reaches a person |
+| --- | --- | --- |
+| `get_account` | Your workspace and phone numbers, and what each can do | |
+| `list_conversations` | Recent conversations, optionally with one person or on one number | |
+| `get_conversation` | A conversation as a transcript, found by phone number, email or chat ID | |
+| `find_unanswered` | Conversations where the other person is waiting on you | |
+| `get_message` | A message's delivery status and why it failed | |
+| `check_imessage` | Whether a number uses iMessage | |
+| `find_contacts` | Search contacts by name, phone or email, or list saved (or unsaved) contacts | |
+| `list_webhooks` | Webhook subscriptions and recent delivery attempts | |
+| `search_docs` | Search docs.blujay.io | |
+| `send_message` | Text a person or group, or reply in a conversation, with an optional photo, video, document, contact card or audio file (sent as a voice memo) from your computer, a photo, video or contact card from a link, or an iMessage effect such as balloons or slam on a follow-up | Yes |
+| `react_to_message` | Add or remove a tapback or an emoji reaction | Yes |
+| `edit_message` | Edit a sent iMessage | Yes |
+| `unsend_message` | Unsend an iMessage | Yes |
+| `mark_conversation_read` | Mark a conversation as read | Yes (read receipt) |
+| `set_typing` | Show or hide the typing bubble | Yes |
+| `update_group` | Rename an iMessage group, or add or remove a person | Yes |
+| `save_contact` | Create or update a contact, and tag it | Can: a tag can start a workflow that texts them |
+| `opt_out_contact` | Stop all texts to a contact (off with `--allow-send-to`) | |
+| `create_webhook` | Create a webhook subscription (off with `--allow-send-to`) | |
+| `invoke_api` | Call any Blujay endpoint (only with `--enable-invoke-api`) | Depends |
+
+## Prompts
+
+Your MCP client shows these as ready-made actions:
+
+- **Who needs a reply?** Finds the conversations waiting on you and drafts a reply for each, without sending.
+- **Summarize a conversation** with one person.
+- **Send me a test message** to your own phone and confirm it arrived.
+
+## Options
+
+| Option | Effect |
+| --- | --- |
+| `--read-only` | Only the tools that read |
+| `--allow-send-to <numbers>` | Only reach these comma-separated numbers |
+| `--enable-invoke-api` | Add `invoke_api` for any endpoint. Only `GET` with `--read-only` or `--allow-send-to` |
+| `--help`, `--version` | |
+
+## Troubleshooting
+
+- **"set BLUJAY_API_KEY"**: add the key to the `env` block of your MCP client's config, then restart the client.
+- **401, `API_KEY_REVOKED` or `API_KEY_EXPIRED`**: email support@blujay.io for a new key, then update `BLUJAY_API_KEY`.
+- **The tools don't appear**: check that `npx -y blujay-mcp --version` works in a terminal, and restart your MCP client.
+
+## More
+
+- [Blujay API docs](https://docs.blujay.io)
+- Libraries for your own code: [blujay on npm](https://www.npmjs.com/package/blujay) and [blujay on PyPI](https://pypi.org/project/blujay/)
+- Questions and bugs: [support@blujay.io](mailto:support@blujay.io) or [open an issue](https://github.com/blujayhq/blujay-mcp/issues). Security issues: [SECURITY.md](SECURITY.md)
+
+## License
+
+[MIT](LICENSE)

package/dist/docs.d.ts

@@ -0,0 +1,8 @@
+interface Page {
+    title: string;
+    url: string;
+    body: string;
+}
+export declare function loadDocs(fetchFn?: typeof fetch): Promise<Page[]>;
+export declare function searchDocs(query: string, fetchFn?: typeof fetch, maxResults?: number): Promise<string>;
+export {};

package/dist/docs.js

@@ -0,0 +1,61 @@
+// Searches the Blujay docs (docs.blujay.io/llms-full.txt, loaded once per session).
+const DOCS_URL = "https://docs.blujay.io/llms-full.txt";
+let pages = null;
+function parse(text) {
+    return text
+        .split(/\n(?=# )/)
+        .map((chunk) => {
+        const [heading = "", source = "", ...rest] = chunk.split("\n");
+        return {
+            title: heading.replace(/^# /, "").trim(),
+            url: source.replace(/^Source: /, "").trim(),
+            body: rest.join("\n").trim(),
+        };
+    })
+        .filter((page) => page.title && page.url.startsWith("http"));
+}
+export function loadDocs(fetchFn = fetch) {
+    pages ??= fetchFn(DOCS_URL)
+        .then((response) => {
+        if (!response.ok)
+            throw new Error(`docs.blujay.io returned ${response.status}`);
+        return response.text();
+    })
+        .then(parse)
+        .catch((error) => {
+        pages = null; // try again next time
+        throw error;
+    });
+    return pages;
+}
+export async function searchDocs(query, fetchFn = fetch, maxResults = 3) {
+    const terms = query.toLowerCase().split(/\W+/).filter((term) => term.length > 2);
+    if (!terms.length)
+        return "Add a few words to search for.";
+    const scored = (await loadDocs(fetchFn))
+        .map((page) => {
+        const title = page.title.toLowerCase();
+        const body = page.body.toLowerCase();
+        let score = 0;
+        for (const term of terms) {
+            if (title.includes(term))
+                score += 10;
+            score += Math.min(body.split(term).length - 1, 10);
+        }
+        // Guides explain; reference pages list fields. Prefer guides when they tie.
+        if (!page.url.includes("/api-reference/"))
+            score += 0.5;
+        return { page, score };
+    })
+        .filter((result) => result.score > 1)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+    if (!scored.length)
+        return `Nothing in the docs matched "${query}". Browse https://docs.blujay.io.`;
+    return scored
+        .map(({ page }) => {
+        const excerpt = page.body.length > 2500 ? `${page.body.slice(0, 2500)}\n…` : page.body;
+        return `# ${page.title}\n${page.url}\n\n${excerpt}`;
+    })
+        .join("\n\n---\n\n");
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param wrote true for a tool that sends or changes something: after a timeout or lost connection
+ * it may have gone through, so the assistant must check before trying again.
+ */
+export declare function describeError(error: unknown, wrote?: boolean): string;

package/dist/errors.js

@@ -0,0 +1,53 @@
+// API errors as plain sentences with the next step, so the assistant can recover
+// or explain the problem instead of showing a bare error code.
+import { BlujayError, BlujayTimeoutError } from "blujay";
+const NEXT_STEP = {
+    UNAUTHORIZED: "Check that BLUJAY_API_KEY is set to the key shown under API in the Blujay sidebar.",
+    API_KEY_EXPIRED: "This API key has expired. Email support@blujay.io for a new one, then update BLUJAY_API_KEY.",
+    API_KEY_REVOKED: "This API key was revoked. Email support@blujay.io for a new one, then update BLUJAY_API_KEY.",
+    NOT_FOUND: "Check the ID, or look it up again with list_conversations or find_contacts.",
+    PRE_REPLY_LIMIT_REACHED: "This person hasn't replied yet, and the number of texts allowed before a reply is used up. Wait for them to reply.",
+    PRE_REPLY_CONTENT_BLOCKED: "Links and attachments can't be sent until the person replies. Send text only for now.",
+    FIRST_MESSAGE_LINK_NOT_ALLOWED: "A first message can't contain a link. Send text only, and share the link after they reply.",
+    PRE_REPLY_LENGTH_EXCEEDED: "Until the person replies, texts must be 300 characters or less. Shorten the text.",
+    CONTACT_MUST_TEXT_FIRST: "This number can only message people who texted it first. Send from a different number, or ask them to text you.",
+    CONTACT_NOT_VERIFIED: "This number can only message people who texted it first. Send from a different number, or ask them to text you.",
+    RECIPIENT_SUPPRESSED: "This person opted out, so Blujay won't text them.",
+    FROM_NUMBER_REQUIRED: "Pick which of your numbers to send from (see get_account) and pass it as `from`.",
+    QUEUE_FULL: "Too many messages are waiting to send from this number. Try again in a few minutes.",
+    IDEMPOTENCY_IN_PROGRESS: "Blujay is still working on the earlier attempt. Check get_conversation in a minute before sending again.",
+    RATE_LIMIT_EXCEEDED: "Too many requests right now. Wait a minute and try again.",
+    EDIT_LIMIT_REACHED: "This message can't be edited again (iMessage allows 5 edits within 15 minutes).",
+    EDIT_WINDOW_EXPIRED: "It's been more than 15 minutes, so it can't be edited. Send a new message instead.",
+    UNSEND_WINDOW_EXPIRED: "It's been more than 2 minutes, so it can't be unsent.",
+    UNSUPPORTED_ATTACHMENT_TYPE: "This file can't go out in this conversation. Documents (PDF, Word, Excel, PowerPoint) and voice memos need iMessage or RCS, and a voice memo needs a conversation that already has messages. Over SMS, send a photo, video or contact card. A link must point straight at a photo, video or contact card (or audio, sent as a voice memo).",
+};
+/**
+ * @param wrote true for a tool that sends or changes something: after a timeout or lost connection
+ * it may have gone through, so the assistant must check before trying again.
+ */
+export function describeError(error, wrote = false) {
+    const mayHaveHappened = wrote
+        ? " It may still have gone through: check with get_conversation or get_message before trying again."
+        : "";
+    if (error instanceof BlujayTimeoutError) {
+        return `Blujay didn't answer in time.${mayHaveHappened || " Try again in a moment."}`;
+    }
+    if (error instanceof BlujayError && error.statusCode === undefined) {
+        // No response at all: the connection failed or dropped.
+        return `Couldn't reach Blujay: ${error.message}.${mayHaveHappened}`;
+    }
+    if (error instanceof BlujayError) {
+        const body = error.body;
+        const code = error.code;
+        const message = body?.error?.message ?? error.message;
+        const nextStep = code ? NEXT_STEP[code] : undefined;
+        return [
+            `Blujay returned an error${error.statusCode ? ` (${error.statusCode}${code ? ` ${code}` : ""})` : ""}: ${message}`,
+            nextStep,
+            body?.error?.doc_url ? `Details: ${body.error.doc_url}` : undefined,
+        ].filter(Boolean).join("\n");
+    }
+    const text = error instanceof Error ? error.message : String(error);
+    return `Couldn't reach Blujay: ${text}.${mayHaveHappened}`;
+}

package/dist/files.d.ts

@@ -0,0 +1,36 @@
+import { type FileHandle } from "node:fs/promises";
+/** Blujay's limit for one attachment (`POST /v1/attachments`). */
+export declare const MAX_FILE_BYTES: number;
+/** The file can't be sent; the message says why in plain words. */
+export declare class FileRefusedError extends Error {
+}
+export type FileKind = "photo" | "video" | "document" | "contact card" | "audio";
+export interface SendableFile {
+    bytes: Buffer;
+    kind: FileKind;
+    /** What Blujay is told the file is: image/jpeg, video/quicktime, text/vcard, ... */
+    contentType: string;
+    /** The name the recipient sees, with the extension that matches the contents. */
+    filename: string;
+    /** Hex SHA-256 of the bytes, so a repeat of the same file is recognised. */
+    sha256: string;
+}
+interface DetectedType {
+    contentType: string;
+    extension: string;
+    kind: FileKind;
+}
+/** The CRC-32 a zip records for each entry. */
+export declare function crc32(bytes: Uint8Array): number;
+/** What a file is from its bytes, or null when it isn't a photo, a video, a document, a contact card or audio. */
+export declare function detectFileType(bytes: Buffer): DetectedType | null;
+/** `~/Desktop/a.jpg` or `/Users/ava/Desktop/a.jpg`. A relative path depends on where the server started, so it's refused. */
+export declare function resolveUserPath(path: string): string;
+/**
+ * Reads exactly `size` bytes from an open file. If it holds fewer or more than when it was
+ * checked, it changed while being read, and it's refused rather than sent half-written.
+ */
+export declare function readExactly(handle: FileHandle, size: number, resolved: string): Promise<Buffer>;
+/** Reads a file to send, refusing anything that isn't a readable photo, video, document, contact card or audio file within the limit. */
+export declare function readSendableFile(path: string): Promise<SendableFile>;
+export {};