@motionsmith/apple-messages-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+## 0.1.0 — 2026-07-23
+
+- First public release of the Apple Messages MCP protocol library and reusable local macOS helper source.
+- Defines protocol v1: `messages_status`, `setup_messages_watch`, and `read_messages_context`.
+- Adds opaque conversation-reference validation, five-candidate ambiguity cap, sanitised MCP errors, and redacted message normalization.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Motionsmith
+
+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,115 @@
+# Apple Messages MCP
+
+`@motionsmith/apple-messages-mcp` is a library-first MCP protocol and reusable local macOS helper
+toolkit for Apple Messages. It is for any consumer that can host a stdio MCP server and provide its
+own status, watch setup, and optional bounded context callbacks. It is not a configuration store,
+approval system, transcript database, or Sugar integration.
+
+Apple Messages data stays on the local Mac. The helper reads the local `chat.db`; the app that
+compiles and runs it needs macOS Full Disk Access. This package never bypasses macOS privacy.
+
+## Install
+
+```sh
+corepack pnpm add @motionsmith/apple-messages-mcp@0.1.0
+```
+
+The package supports Node 20 or newer and is useful for live helper work only on macOS. The
+library's fixture and protocol APIs are cross-platform.
+
+## Host the stdio MCP server
+
+The consumer owns callbacks and their policies. In particular, it decides whether setup writes
+configuration, whether a user approves that write, what a status response contains, and whether
+bounded context is persisted or displayed.
+
+```js
+import { runAppleMessagesMcpStdioServer } from '@motionsmith/apple-messages-mcp';
+
+await runAppleMessagesMcpStdioServer({
+  callbacks: {
+    status: async () => ({ status: 'not_configured' }),
+    setup: async ({ watch, candidate, alias, approve }) => {
+      // Resolve and store a watch in this application's own configuration.
+      return { status: 'dry_run', watch, candidate, alias, approve: approve === true };
+    },
+    readContext: async ({ conversationRef, limit = 5 }) => {
+      // Read only this application's configured opaque ref, bounded by `limit`.
+      return { status: 'ready', conversationRef, limit, messages: [] };
+    },
+  },
+});
+```
+
+This server reads newline-delimited JSON-RPC on stdin and writes newline-delimited JSON-RPC on
+stdout. The package intentionally has no default executable: a consumer cannot use it safely
+without owning those callbacks.
+
+## Protocol v1
+
+The MCP server handles `initialize`, `notifications/initialized`, `tools/list`, and `tools/call`.
+Tool calls are:
+
+- `messages_status` — calls the consumer's `status` callback.
+- `setup_messages_watch` — calls `setup` with `watch`, optional opaque `candidate`, optional
+  `alias`, and explicit `approve: true` only when supplied.
+- `read_messages_context` — calls optional `readContext` with a required opaque
+  `apple_messages_conversation_*` ref and a limit from 1 through 20.
+
+Candidate payloads are validated and capped at five. Invalid requests and callback failures produce
+sanitised MCP errors. The library normalizes fixture or helper rows to opaque refs and hashes; it
+does not emit raw message bodies, handles, chat GUIDs, lookup queries, or attachment contents.
+See [the compatibility policy](docs/compatibility.md).
+
+## Helper template
+
+The reusable helper source is `helper/apple-messages-helper.swift`; its protocol commands are
+`messages-candidates`, `messages-validate`, and `messages-read`. Build the default standalone host
+app on macOS:
+
+```sh
+corepack pnpm helper:build
+```
+
+This creates `bin/Apple Messages MCP Host.app`, bundle id
+`com.motionsmith.apple-messages-mcp.host`. Grant that app Full Disk Access in System Settings >
+Privacy & Security before a live `chat.db` read. A consumer may compile the included source into
+its own host app identity; it then owns installation and recovery language for that identity.
+
+## Safe fixture verification
+
+Use the supplied consumer example after installing from a packed artifact. It hosts callbacks only
+and does not read live Apple Messages data:
+
+```sh
+corepack pnpm exec node examples/consumer-smoke.mjs --stdio <<'EOF'
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"messages_status","arguments":{}}}
+EOF
+```
+
+Expected results include the `apple-messages` server info, the three protocol-v1 tools, and a
+`not_configured` callback response. Configure a non-sensitive test thread only for a manual live
+smoke. Do not add raw messages or contact identifiers to fixtures, screenshots, CI logs, issue
+reports, or package documentation.
+
+## Development and releases
+
+```sh
+corepack pnpm install
+corepack pnpm lint
+corepack pnpm test
+corepack pnpm build
+corepack pnpm pack
+```
+
+CI runs the frozen install, lint, tests, TypeScript build, package-content check, and the macOS
+helper compile/dispatch smoke. Tag releases use npm provenance after the repository's `publish`
+environment has been configured as the npm trusted publisher. See
+[release policy](docs/release-policy.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## Notices
+
+This package is not affiliated with Apple or OpenAI. Apple Messages and macOS are Apple platforms.
+Codex and OpenAI are separate products and services.

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+export declare const APPLE_MESSAGES_PROVIDER_VERSION = "0.1.0";
+export declare const MAX_APPLE_MESSAGES_CANDIDATES = 5;
+export type AppleMessagesReadStatus = 'ready' | 'unsupported' | 'missing_config' | 'missing_permission' | 'failed';
+export type AppleMessagesDirection = 'inbound' | 'outbound';
+export type AppleMessagesContentMode = 'hash_only' | 'metadata_only';
+export interface AppleMessagesSourceReadInput {
+    scope: string;
+    sourceId: string;
+    conversationLabel: string;
+    conversationRef?: string;
+    maxMessages: number;
+}
+export type AppleMessagesSourceRead = (input: AppleMessagesSourceReadInput) => Promise<AppleMessagesReadResult>;
+export interface AppleMessagesReadResult {
+    schemaVersion: 1;
+    status: AppleMessagesReadStatus;
+    messages: NormalizedAppleMessage[];
+    providerCursor?: string;
+    findings: string[];
+}
+export interface NormalizedAppleMessage {
+    source: 'apple_messages';
+    id: string;
+    conversation: {
+        ref: string;
+        label: string;
+    };
+    direction: AppleMessagesDirection;
+    service: 'iMessage' | 'SMS' | 'unknown' | string;
+    sentAt: string;
+    senderRef?: string;
+    attachmentCount: number;
+    content: {
+        mode: AppleMessagesContentMode;
+        hash?: string;
+    };
+    editedAt?: string;
+    deletedAt?: string;
+    unsupported: {
+        reactions: boolean;
+    };
+}
+export interface AppleMessagesFixtureReadInput {
+    conversation: {
+        label: string;
+        refSeed?: string;
+    };
+    rows: AppleMessagesFixtureRow[];
+}
+export interface AppleMessagesFixtureRow {
+    messageId: string;
+    chatGuid: string;
+    isFromMe: boolean;
+    service?: string;
+    sentAt: string;
+    handleValue?: string;
+    text?: string;
+    attachmentCount?: number;
+    editedAt?: string;
+    deletedAt?: string;
+    hasReactions?: boolean;
+}
+export interface AppleMessagesSqliteRow {
+    messageId: number | string;
+    chatGuid: string;
+    isFromMe: number | string | boolean;
+    service?: string | null;
+    appleDate: number | string | null;
+    handleValue?: string | null;
+    text?: string | null;
+    attachmentCount?: number | string | null;
+    dateEdited?: number | string | null;
+    dateDeleted?: number | string | null;
+}
+export interface AppleMessagesCandidate {
+    candidateRef: string;
+    label: string;
+    matchKind: 'exact_label' | 'query_match' | 'contact_match';
+}
+export interface AppleMessagesHelperPayload {
+    schemaVersion?: number;
+    kind?: string;
+    status?: AppleMessagesReadStatus;
+    rows?: AppleMessagesSqliteRow[];
+    candidates?: unknown[];
+    findings?: string[];
+}
+export interface AppleMessagesHelperReadOptions {
+    invoke: (input: Record<string, unknown>) => Promise<unknown>;
+}
+export interface AppleMessagesChatDbReadOptions {
+    databasePath?: string;
+    runner: (command: string, args: string[], options: {
+        timeoutMs?: number;
+    }) => Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    timeoutMs?: number;
+}
+export declare function isAppleMessagesConversationRef(value: string): boolean;
+export declare function normalizeAppleMessagesFixtureReadResult(input: AppleMessagesFixtureReadInput): AppleMessagesReadResult;
+export declare function normalizeAppleMessagesHelperReadResult(payload: unknown, conversationLabel: string, readerLabel?: string): AppleMessagesReadResult;
+export declare function readAppleMessagesHelper(input: AppleMessagesSourceReadInput, options: AppleMessagesHelperReadOptions): Promise<AppleMessagesReadResult>;
+export declare function createAppleMessagesChatDbRead(options: AppleMessagesChatDbReadOptions): AppleMessagesSourceRead;
+export declare function parseAppleMessagesCandidates(payload: unknown): AppleMessagesCandidate[];
+export declare function appleMessagesHelperStatus(payload: unknown): AppleMessagesReadStatus | undefined;
+export declare function appleMessagesHelperFindings(payload: unknown): string[];
+export interface AppleMessagesMcpRequest {
+    id?: unknown;
+    method?: unknown;
+    params?: unknown;
+}
+export interface AppleMessagesMcpCallbacks {
+    status: () => Promise<unknown>;
+    setup: (input: {
+        watch: string;
+        candidate?: string;
+        alias?: string;
+        approve?: boolean;
+    }) => Promise<unknown>;
+    readContext?: (input: {
+        conversationRef: string;
+        limit?: number;
+    }) => Promise<unknown>;
+}
+export interface AppleMessagesMcpStdioServerOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    callbacks: AppleMessagesMcpCallbacks;
+}
+export declare function appleMessagesMcpTools(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {};
+    };
+}[];
+export declare function handleAppleMessagesMcpRequest(request: AppleMessagesMcpRequest, callbacks: AppleMessagesMcpCallbacks): Promise<unknown>;
+export declare function runAppleMessagesMcpStdioServer(options: AppleMessagesMcpStdioServerOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,432 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_APPLE_MESSAGES_CANDIDATES = exports.APPLE_MESSAGES_PROVIDER_VERSION = void 0;
+exports.isAppleMessagesConversationRef = isAppleMessagesConversationRef;
+exports.normalizeAppleMessagesFixtureReadResult = normalizeAppleMessagesFixtureReadResult;
+exports.normalizeAppleMessagesHelperReadResult = normalizeAppleMessagesHelperReadResult;
+exports.readAppleMessagesHelper = readAppleMessagesHelper;
+exports.createAppleMessagesChatDbRead = createAppleMessagesChatDbRead;
+exports.parseAppleMessagesCandidates = parseAppleMessagesCandidates;
+exports.appleMessagesHelperStatus = appleMessagesHelperStatus;
+exports.appleMessagesHelperFindings = appleMessagesHelperFindings;
+exports.appleMessagesMcpTools = appleMessagesMcpTools;
+exports.handleAppleMessagesMcpRequest = handleAppleMessagesMcpRequest;
+exports.runAppleMessagesMcpStdioServer = runAppleMessagesMcpStdioServer;
+const crypto_1 = require("crypto");
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = require("readline");
+const process_1 = require("process");
+exports.APPLE_MESSAGES_PROVIDER_VERSION = '0.1.0';
+exports.MAX_APPLE_MESSAGES_CANDIDATES = 5;
+function isAppleMessagesConversationRef(value) {
+    return /^apple_messages_conversation_[a-f0-9]{32,64}$/.test(value);
+}
+function normalizeAppleMessagesFixtureReadResult(input) {
+    const conversationSeed = input.conversation.refSeed ?? input.rows[0]?.chatGuid ?? `fixture:${input.conversation.label}`;
+    const conversationRef = `apple_messages_conversation_${hashText(conversationSeed).slice(0, 32)}`;
+    const messages = input.rows
+        .map((row) => normalizeFixtureRow(row, input.conversation.label, conversationRef))
+        .sort((left, right) => left.sentAt.localeCompare(right.sentAt) || left.id.localeCompare(right.id));
+    return {
+        schemaVersion: 1,
+        status: 'ready',
+        messages,
+        providerCursor: providerCursorForMessages(messages),
+        findings: [],
+    };
+}
+function normalizeAppleMessagesHelperReadResult(payload, conversationLabel, readerLabel = 'Apple Messages host helper') {
+    const helper = parseHelperPayload(payload);
+    if (helper === undefined)
+        return failedRead('Apple Messages host helper returned malformed JSON.');
+    if (helper.status !== 'ready') {
+        return {
+            schemaVersion: 1,
+            status: helper.status ?? 'failed',
+            messages: [],
+            findings: nonEmptyFindings(helper.findings, `Apple Messages host helper failed before producing normalized records: ${helper.status ?? 'failed'}`),
+        };
+    }
+    return appleMessagesReadResultFromSqliteRows(helper.rows ?? [], conversationLabel, readerLabel);
+}
+async function readAppleMessagesHelper(input, options) {
+    return normalizeAppleMessagesHelperReadResult(await options.invoke({
+        ...(input.conversationRef === undefined
+            ? { conversationLabel: input.conversationLabel }
+            : { conversationRef: input.conversationRef }),
+        maxMessages: input.maxMessages,
+    }), input.conversationLabel);
+}
+function createAppleMessagesChatDbRead(options) {
+    const databasePath = options.databasePath ?? path_1.default.join(os_1.default.homedir(), 'Library', 'Messages', 'chat.db');
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    return async (input) => {
+        try {
+            await promises_1.default.access(databasePath);
+        }
+        catch (error) {
+            const status = isPermissionError(error) ? 'missing_permission' : 'failed';
+            return failedWithStatus(status, status === 'missing_permission'
+                ? 'Apple Messages chat.db is not readable; grant Full Disk Access to the configured Apple Messages host app.'
+                : 'Apple Messages chat.db was not found at the expected local path.');
+        }
+        const response = await options.runner('sqlite3', ['-readonly', '-json', databasePath, messagesSql(input.conversationLabel, input.maxMessages)], { timeoutMs });
+        if (response.exitCode !== 0) {
+            const status = sqliteFailureStatus(response.stderr);
+            return failedWithStatus(status, sqliteFailureFinding(status));
+        }
+        try {
+            const rows = response.stdout.trim().length === 0
+                ? []
+                : JSON.parse(response.stdout);
+            return normalizeAppleMessagesHelperReadResult({ status: 'ready', rows }, input.conversationLabel, 'chat.db reader');
+        }
+        catch {
+            return failedRead('Apple Messages chat.db reader returned malformed JSON.');
+        }
+    };
+}
+function parseAppleMessagesCandidates(payload) {
+    const candidates = parseHelperPayload(payload)?.candidates ?? [];
+    return candidates
+        .filter((candidate) => isRecord(candidate) &&
+        typeof candidate.candidateRef === 'string' &&
+        isAppleMessagesConversationRef(candidate.candidateRef) &&
+        typeof candidate.label === 'string' &&
+        (candidate.matchKind === 'exact_label' ||
+            candidate.matchKind === 'query_match' ||
+            candidate.matchKind === 'contact_match'))
+        .slice(0, exports.MAX_APPLE_MESSAGES_CANDIDATES);
+}
+function appleMessagesHelperStatus(payload) {
+    return parseHelperPayload(payload)?.status;
+}
+function appleMessagesHelperFindings(payload) {
+    return nonEmptyFindings(parseHelperPayload(payload)?.findings);
+}
+function appleMessagesMcpTools() {
+    return [
+        {
+            name: 'messages_status',
+            description: 'Report every configured Apple Messages watch and its checkpoint health.',
+            inputSchema: emptySchema(),
+        },
+        {
+            name: 'setup_messages_watch',
+            description: 'Resolve a bounded Messages candidate and, only with approve=true, add the selected watch.',
+            inputSchema: setupSchema(),
+        },
+        {
+            name: 'read_messages_context',
+            description: 'Read a bounded recent transcript for one already configured opaque conversation reference.',
+            inputSchema: contextSchema(),
+        },
+    ];
+}
+async function handleAppleMessagesMcpRequest(request, callbacks) {
+    if (request.method === 'initialize')
+        return {
+            protocolVersion: '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'apple-messages', version: exports.APPLE_MESSAGES_PROVIDER_VERSION },
+        };
+    if (request.method === 'notifications/initialized')
+        return undefined;
+    if (request.method === 'tools/list')
+        return {
+            tools: appleMessagesMcpTools().map((tool) => ({
+                ...tool,
+                annotations: {
+                    readOnlyHint: tool.name !== 'setup_messages_watch',
+                    destructiveHint: false,
+                    idempotentHint: tool.name !== 'setup_messages_watch',
+                    openWorldHint: true,
+                },
+            })),
+        };
+    if (request.method !== 'tools/call' ||
+        !isRecord(request.params) ||
+        typeof request.params.name !== 'string')
+        return { error: { code: -32601, message: 'Method not found' } };
+    if (request.params.name === 'messages_status')
+        return success(await callbacks.status());
+    if (request.params.name === 'read_messages_context') {
+        if (callbacks.readContext === undefined)
+            return failure('invalid_input', 'read_messages_context is unavailable.');
+        if (!isRecord(request.params.arguments) ||
+            typeof request.params.arguments.conversationRef !== 'string')
+            return failure('invalid_input', 'read_messages_context requires conversationRef.');
+        const limit = request.params.arguments.limit;
+        if (limit !== undefined &&
+            (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 20))
+            return failure('invalid_input', 'read_messages_context limit must be between 1 and 20.');
+        return success(await callbacks.readContext({
+            conversationRef: request.params.arguments.conversationRef,
+            ...(typeof limit === 'number' ? { limit } : {}),
+        }));
+    }
+    if (request.params.name !== 'setup_messages_watch' ||
+        !isRecord(request.params.arguments) ||
+        typeof request.params.arguments.watch !== 'string')
+        return failure('invalid_input', 'setup_messages_watch requires watch.');
+    const input = request.params.arguments;
+    const watch = input.watch;
+    if (typeof watch !== 'string')
+        return failure('invalid_input', 'setup_messages_watch requires watch.');
+    return success(await callbacks.setup({
+        watch,
+        ...(typeof input.candidate === 'string' ? { candidate: input.candidate } : {}),
+        ...(typeof input.alias === 'string' ? { alias: input.alias } : {}),
+        ...(input.approve === true ? { approve: true } : {}),
+    }));
+}
+async function runAppleMessagesMcpStdioServer(options) {
+    const reader = (0, readline_1.createInterface)({ input: options.stdin ?? process_1.stdin, crlfDelay: Infinity });
+    const stdout = options.stdout ?? process_1.stdout;
+    for await (const line of reader) {
+        if (line.trim().length === 0)
+            continue;
+        const request = parseRequest(line);
+        if (request === undefined) {
+            write(stdout, null, { error: { code: -32700, message: 'Parse error' } });
+            continue;
+        }
+        try {
+            const response = await handleAppleMessagesMcpRequest(request, options.callbacks);
+            if (response !== undefined)
+                write(stdout, request.id ?? null, response);
+        }
+        catch {
+            write(stdout, request.id ?? null, failure('tool_execution_failed', 'Apple Messages tool request could not be completed.'));
+        }
+    }
+}
+function appleMessagesReadResultFromSqliteRows(rows, conversationLabel, readerLabel) {
+    if (rows.length === 0)
+        return {
+            schemaVersion: 1,
+            status: 'missing_config',
+            messages: [],
+            findings: [
+                'No Apple Messages conversation matched the configured watched conversation label.',
+            ],
+        };
+    try {
+        const messages = rows
+            .map((row) => normalizeSqliteRow(row, conversationLabel))
+            .sort((left, right) => left.sentAt.localeCompare(right.sentAt) || left.id.localeCompare(right.id));
+        return {
+            schemaVersion: 1,
+            status: 'ready',
+            messages,
+            providerCursor: providerCursorForMessages(messages),
+            findings: [],
+        };
+    }
+    catch {
+        return failedRead(`Apple Messages ${readerLabel} returned invalid message records.`);
+    }
+}
+function normalizeSqliteRow(row, conversationLabel) {
+    const chatGuid = requireNonEmptyValue(row.chatGuid, 'Apple Messages chat guid');
+    return normalizeFixtureRow({
+        messageId: requireNonEmptyValue(String(row.messageId), 'Apple Messages message id'),
+        chatGuid,
+        isFromMe: row.isFromMe === true || row.isFromMe === 1 || row.isFromMe === '1',
+        service: row.service ?? undefined,
+        sentAt: appleMessageDateToIso(row.appleDate, 'Apple Messages message date'),
+        handleValue: row.handleValue ?? undefined,
+        text: row.text ?? undefined,
+        attachmentCount: integerFromSqlite(row.attachmentCount),
+        editedAt: row.dateEdited === undefined || row.dateEdited === null || Number(row.dateEdited) === 0
+            ? undefined
+            : appleMessageDateToIso(row.dateEdited, 'Apple Messages edit date'),
+        deletedAt: row.dateDeleted === undefined || row.dateDeleted === null || Number(row.dateDeleted) === 0
+            ? undefined
+            : appleMessageDateToIso(row.dateDeleted, 'Apple Messages delete date'),
+        hasReactions: false,
+    }, conversationLabel, `apple_messages_conversation_${hashText(chatGuid).slice(0, 32)}`);
+}
+function normalizeFixtureRow(row, conversationLabel, conversationRef) {
+    assertNonEmptyString(row.messageId, 'Apple Messages fixture messageId');
+    assertNonEmptyString(row.chatGuid, 'Apple Messages fixture chatGuid');
+    const sentAt = isoTimestamp(row.sentAt, 'Apple Messages fixture sentAt');
+    const text = row.text ?? '';
+    return {
+        source: 'apple_messages',
+        id: `apple_message_${hashText(`${row.chatGuid}:${row.messageId}`).slice(0, 32)}`,
+        conversation: { ref: conversationRef, label: conversationLabel },
+        direction: row.isFromMe ? 'outbound' : 'inbound',
+        service: normalizeService(row.service),
+        sentAt,
+        ...(row.handleValue === undefined
+            ? {}
+            : { senderRef: `apple_messages_sender_${hashText(row.handleValue).slice(0, 32)}` }),
+        attachmentCount: row.attachmentCount ?? 0,
+        content: text.length === 0 ? { mode: 'metadata_only' } : { mode: 'hash_only', hash: hashText(text) },
+        ...(row.editedAt === undefined
+            ? {}
+            : { editedAt: isoTimestamp(row.editedAt, 'Apple Messages fixture editedAt') }),
+        ...(row.deletedAt === undefined
+            ? {}
+            : { deletedAt: isoTimestamp(row.deletedAt, 'Apple Messages fixture deletedAt') }),
+        unsupported: { reactions: row.hasReactions === true },
+    };
+}
+function parseHelperPayload(payload) {
+    if (!isRecord(payload))
+        return undefined;
+    return {
+        status: validStatus(payload.status) ? payload.status : undefined,
+        rows: Array.isArray(payload.rows) ? payload.rows : undefined,
+        candidates: Array.isArray(payload.candidates) ? payload.candidates : undefined,
+        findings: Array.isArray(payload.findings)
+            ? payload.findings.filter((value) => typeof value === 'string')
+            : undefined,
+    };
+}
+function validStatus(value) {
+    return (value === 'ready' ||
+        value === 'unsupported' ||
+        value === 'missing_config' ||
+        value === 'missing_permission' ||
+        value === 'failed');
+}
+function nonEmptyFindings(findings, fallback) {
+    const value = findings?.filter((finding) => finding.trim().length > 0) ?? [];
+    return value.length > 0 ? value : fallback === undefined ? [] : [fallback];
+}
+function failedRead(finding) {
+    return { schemaVersion: 1, status: 'failed', messages: [], findings: [finding] };
+}
+function failedWithStatus(status, finding) {
+    return { schemaVersion: 1, status, messages: [], findings: [finding] };
+}
+function isPermissionError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        (error.code === 'EACCES' ||
+            error.code === 'EPERM'));
+}
+function messagesSql(conversationLabel, maxMessages) {
+    const value = `'${conversationLabel.replace(/'/g, "''")}'`;
+    return [
+        `SELECT m.ROWID AS messageId, c.guid AS chatGuid, m.is_from_me AS isFromMe, m.service AS service, m.date AS appleDate, h.id AS handleValue, m.text AS text, COALESCE(m.cache_has_attachments, 0) AS attachmentCount, COALESCE(m.date_edited, 0) AS dateEdited, COALESCE(m.date_retracted, 0) AS dateDeleted`,
+        'FROM chat c JOIN chat_message_join cmj ON cmj.chat_id = c.ROWID JOIN message m ON m.ROWID = cmj.message_id LEFT JOIN handle h ON h.ROWID = m.handle_id',
+        `WHERE c.display_name = ${value} OR c.chat_identifier = ${value} OR c.guid = ${value}`,
+        'ORDER BY m.date DESC, m.ROWID DESC',
+        `LIMIT ${Math.max(1, Math.min(maxMessages, 500))};`,
+    ].join('\n');
+}
+function sqliteFailureStatus(stderr) {
+    const lower = stderr.toLowerCase();
+    if (lower.includes('authorization denied') ||
+        lower.includes('not authorized') ||
+        lower.includes('permission denied') ||
+        lower.includes('unable to open database'))
+        return 'missing_permission';
+    if (lower.includes('command not found') || lower.includes('no such file'))
+        return 'unsupported';
+    return 'failed';
+}
+function sqliteFailureFinding(status) {
+    if (status === 'missing_permission')
+        return 'Apple Messages chat.db is not readable; grant Full Disk Access to the configured Apple Messages host app.';
+    if (status === 'unsupported')
+        return 'Apple Messages live reads require the sqlite3 command on this Mac.';
+    return 'Apple Messages chat.db reader failed before producing normalized records.';
+}
+function providerCursorForMessages(messages) {
+    return messages
+        .map((message) => message.sentAt)
+        .sort()
+        .at(-1);
+}
+function appleMessageDateToIso(value, label) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        throw new Error(`Invalid ${label}: ${String(value)}`);
+    const unixMs = numeric > 10_000_000_000_000_000
+        ? numeric / 1_000_000 + 978_307_200_000
+        : numeric > 10_000_000_000
+            ? numeric + 978_307_200_000
+            : numeric * 1_000 + 978_307_200_000;
+    return new Date(unixMs).toISOString();
+}
+function integerFromSqlite(value) {
+    const numeric = Number(value ?? 0);
+    return Number.isInteger(numeric) && numeric >= 0 ? numeric : 0;
+}
+function normalizeService(service) {
+    return service === undefined || service.trim().length === 0 ? 'unknown' : service.trim();
+}
+function isoTimestamp(value, label) {
+    if (Number.isNaN(Date.parse(value)) || !value.includes('T'))
+        throw new Error(`Invalid ${label} timestamp: ${value}`);
+    return value;
+}
+function requireNonEmptyValue(value, label) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} must be non-empty`);
+    return value;
+}
+function assertNonEmptyString(value, label) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} must be non-empty`);
+}
+function hashText(value) {
+    return (0, crypto_1.createHash)('sha256').update(value).digest('hex');
+}
+function emptySchema() {
+    return { type: 'object', additionalProperties: false, properties: {} };
+}
+function setupSchema() {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['watch'],
+        properties: {
+            watch: { type: 'string', minLength: 2 },
+            candidate: { type: 'string' },
+            alias: { type: 'string' },
+            approve: { type: 'boolean' },
+        },
+    };
+}
+function contextSchema() {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['conversationRef'],
+        properties: {
+            conversationRef: { type: 'string', minLength: 60 },
+            limit: { type: 'integer', minimum: 1, maximum: 20 },
+        },
+    };
+}
+function success(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value) }] };
+}
+function failure(code, message) {
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify({ code, message }) }] };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function parseRequest(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function write(stdout, id, result) {
+    stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
+}

package/helper/apple-messages-helper.swift

@@ -0,0 +1,145 @@
+import Contacts
+import CryptoKit
+import Foundation
+
+let outputFilePath: String? = {
+  let arguments = CommandLine.arguments
+  guard let index = arguments.firstIndex(of: "--output-file"), index + 1 < arguments.count else {
+    return nil
+  }
+  return arguments[index + 1]
+}()
+
+func printJson(_ value: Any) {
+  let data = try! JSONSerialization.data(withJSONObject: value, options: [.sortedKeys])
+  if let outputFilePath {
+    FileManager.default.createFile(atPath: outputFilePath, contents: data)
+  } else {
+    print(String(data: data, encoding: .utf8)!)
+  }
+}
+
+func readRequest() -> [String: Any] {
+  let arguments = CommandLine.arguments
+  if let inputIndex = arguments.firstIndex(of: "--input-file"), inputIndex + 1 < arguments.count,
+     let data = FileManager.default.contents(atPath: arguments[inputIndex + 1]),
+     let object = try? JSONSerialization.jsonObject(with: data), let request = object as? [String: Any] {
+    return request
+  }
+  let data = FileHandle.standardInput.readDataToEndOfFile()
+  return ((try? JSONSerialization.jsonObject(with: data)) as? [String: Any]) ?? [:]
+}
+
+func opaqueConversationRef(_ guid: String) -> String {
+  let digest = SHA256.hash(data: Data(guid.utf8))
+  return "apple_messages_conversation_" + digest.map { String(format: "%02x", $0) }.joined()
+}
+
+func databasePath(_ request: [String: Any]) -> String {
+  return ((request["databasePath"] as? String) ?? (NSHomeDirectory() as NSString).appendingPathComponent("Library/Messages/chat.db"))
+    .trimmingCharacters(in: .whitespacesAndNewlines)
+}
+
+func sqlQuote(_ value: String) -> String { return "'\(value.replacingOccurrences(of: "'", with: "''"))'" }
+
+func sqlite(_ path: String, _ sql: String) throws -> (stdout: String, stderr: String, status: Int32) {
+  let process = Process()
+  process.executableURL = URL(fileURLWithPath: "/usr/bin/sqlite3")
+  process.arguments = ["-readonly", "-json", path, sql]
+  let stdout = Pipe(); let stderr = Pipe()
+  process.standardOutput = stdout; process.standardError = stderr
+  try process.run(); process.waitUntilExit()
+  return (String(data: stdout.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? "", String(data: stderr.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? "", process.terminationStatus)
+}
+
+func failureStatus(_ stderr: String) -> String {
+  let lower = stderr.lowercased()
+  if lower.contains("authorization denied") || lower.contains("not authorized") || lower.contains("permission denied") || lower.contains("operation not permitted") || lower.contains("unable to open database") { return "missing_permission" }
+  if lower.contains("command not found") || lower.contains("no such file") { return "unsupported" }
+  return "failed"
+}
+
+func failureFinding(_ status: String) -> String {
+  if status == "missing_permission" { return "Apple Messages chat.db is not readable; grant Full Disk Access to the configured Apple Messages host app." }
+  if status == "unsupported" { return "Apple Messages live reads require the sqlite3 command on this Mac." }
+  return "Apple Messages host helper failed before producing normalized records."
+}
+
+func result(_ kind: String, status: String, rows: [[String: Any]] = [], candidates: [[String: Any]] = [], findings: [String] = []) {
+  var body: [String: Any] = ["schemaVersion": 1, "kind": kind, "status": status, "findings": findings]
+  if kind.contains("candidates") { body["candidates"] = candidates } else { body["rows"] = rows }
+  printJson(body)
+}
+
+func contactIdentifiers(_ query: String) -> [String] {
+  guard CNContactStore.authorizationStatus(for: .contacts) == .authorized else { return [] }
+  let keys: [CNKeyDescriptor] = [CNContactGivenNameKey as CNKeyDescriptor, CNContactFamilyNameKey as CNKeyDescriptor, CNContactNicknameKey as CNKeyDescriptor, CNContactPhoneNumbersKey as CNKeyDescriptor, CNContactEmailAddressesKey as CNKeyDescriptor]
+  let request = CNContactFetchRequest(keysToFetch: keys)
+  var identifiers = Set<String>(); let needle = query.lowercased()
+  try? CNContactStore().enumerateContacts(with: request) { contact, _ in
+    let names = [contact.givenName, contact.familyName, contact.nickname, "\(contact.givenName) \(contact.familyName)"]
+    guard names.contains(where: { $0.lowercased().contains(needle) }) else { return }
+    contact.phoneNumbers.forEach { identifiers.insert($0.value.stringValue) }
+    contact.emailAddresses.forEach { identifiers.insert(String($0.value)) }
+  }
+  return Array(identifiers).sorted().prefix(10).map { $0 }
+}
+
+func candidatesSql(_ query: String, identifiers: [String], limit: Int) -> String {
+  let value = sqlQuote(query); let contact = identifiers.map { "c.chat_identifier = \(sqlQuote($0))" }.joined(separator: " OR ")
+  let contactCase = contact.isEmpty ? "" : " WHEN \(contact) THEN 'contact_match'"
+  let contactWhere = contact.isEmpty ? "" : " OR \(contact)"
+  return "SELECT DISTINCT c.guid AS chatGuid, CASE WHEN c.display_name = \(value) OR c.chat_identifier = \(value) THEN 'exact_label'\(contactCase) ELSE 'query_match' END AS matchKind FROM chat c WHERE instr(c.display_name, \(value)) > 0 OR instr(c.chat_identifier, \(value)) > 0\(contactWhere) ORDER BY c.ROWID DESC LIMIT \(min(max(limit, 1), 5));"
+}
+
+func readSql(_ conversation: String, _ maxMessages: Int) -> String {
+  let value = sqlQuote(conversation)
+  return "SELECT m.ROWID AS messageId, c.guid AS chatGuid, m.is_from_me AS isFromMe, m.service AS service, m.date AS appleDate, h.id AS handleValue, m.text AS text, COALESCE(m.cache_has_attachments, 0) AS attachmentCount, COALESCE(m.date_edited, 0) AS dateEdited, COALESCE(m.date_retracted, 0) AS dateDeleted FROM chat c JOIN chat_message_join cmj ON cmj.chat_id = c.ROWID JOIN message m ON m.ROWID = cmj.message_id LEFT JOIN handle h ON h.ROWID = m.handle_id WHERE c.display_name = \(value) OR c.chat_identifier = \(value) OR c.guid = \(value) ORDER BY m.date DESC, m.ROWID DESC LIMIT \(min(max(maxMessages, 1), 500));"
+}
+
+let command = CommandLine.arguments.dropFirst().first(where: { !$0.hasPrefix("--") }) ?? "messages-read"
+let request = readRequest(); let path = databasePath(request)
+let candidateKind = "apple-messages-helper-candidates-result"; let readKind = "apple-messages-helper-read-result"
+guard !path.isEmpty && FileManager.default.fileExists(atPath: path) else { result(command == "messages-read" ? readKind : candidateKind, status: "failed", findings: ["Apple Messages chat.db was not found at the expected local path."]); exit(2) }
+guard FileManager.default.isReadableFile(atPath: path) else { result(command == "messages-read" ? readKind : candidateKind, status: "missing_permission", findings: ["Apple Messages chat.db is not readable; grant Full Disk Access to the configured Apple Messages host app."]); exit(3) }
+
+do {
+  if command == "messages-candidates" {
+    let query = ((request["query"] as? String) ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+    guard query.count >= 2 else { result(candidateKind, status: "failed", findings: ["Apple Messages candidate lookup requires a query of at least two characters."]); exit(64) }
+    let response = try sqlite(path, candidatesSql(query, identifiers: contactIdentifiers(query), limit: (request["limit"] as? Int) ?? 5))
+    guard response.status == 0 else { let status = failureStatus(response.stderr); result(candidateKind, status: status, findings: [failureFinding(status)]); exit(status == "missing_permission" ? 3 : 2) }
+    let rows = ((try? JSONSerialization.jsonObject(with: Data(response.stdout.utf8))) as? [[String: Any]]) ?? []
+    let candidates = rows.enumerated().compactMap { index, row -> [String: Any]? in guard let guid = row["chatGuid"] as? String, let kind = row["matchKind"] as? String else { return nil }; return ["candidateRef": opaqueConversationRef(guid), "label": "Conversation \(index + 1)", "matchKind": kind == "exact_label" ? "exact_label" : kind == "contact_match" ? "contact_match" : "query_match"] }
+    result(candidateKind, status: "ready", candidates: candidates)
+  } else if command == "messages-validate" {
+    let ref = (request["conversationRef"] as? String) ?? ""
+    let response = try sqlite(path, "SELECT c.guid AS chatGuid FROM chat c ORDER BY c.ROWID DESC;")
+    guard response.status == 0 else { let status = failureStatus(response.stderr); result(candidateKind, status: status, findings: [failureFinding(status)]); exit(status == "missing_permission" ? 3 : 2) }
+    let rows = ((try? JSONSerialization.jsonObject(with: Data(response.stdout.utf8))) as? [[String: Any]]) ?? []
+    let found = rows.contains { ($0["chatGuid"] as? String).map(opaqueConversationRef) == ref }
+    result(candidateKind, status: found ? "ready" : "missing_config", findings: found ? [] : ["The configured Apple Messages conversation is no longer available."])
+  } else {
+    var conversation = ((request["conversationLabel"] as? String) ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+    let ref = ((request["conversationRef"] as? String) ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+    if !ref.isEmpty {
+      let response = try sqlite(path, "SELECT c.guid AS chatGuid FROM chat c ORDER BY c.ROWID DESC;")
+      guard response.status == 0 else {
+        let status = failureStatus(response.stderr)
+        result(readKind, status: status, findings: [failureFinding(status)])
+        exit(status == "missing_permission" ? 3 : 2)
+      }
+      let rows = ((try? JSONSerialization.jsonObject(with: Data(response.stdout.utf8))) as? [[String: Any]]) ?? []
+      guard let guid = rows.first(where: { ($0["chatGuid"] as? String).map(opaqueConversationRef) == ref })?["chatGuid"] as? String else {
+        result(readKind, status: "missing_config", findings: ["The configured Apple Messages conversation is no longer available."])
+        exit(2)
+      }
+      conversation = guid
+    }
+    guard !conversation.isEmpty else { result(readKind, status: "missing_config", findings: ["Apple Messages host helper requires a watched conversation label."]); exit(64) }
+    let response = try sqlite(path, readSql(conversation, (request["maxMessages"] as? Int) ?? 50))
+    guard response.status == 0 else { let status = failureStatus(response.stderr); result(readKind, status: status, findings: [failureFinding(status)]); exit(status == "missing_permission" ? 3 : 2) }
+    let rows = response.stdout.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? [] : (((try? JSONSerialization.jsonObject(with: Data(response.stdout.utf8))) as? [[String: Any]]) ?? [])
+    result(readKind, status: "ready", rows: rows)
+  }
+} catch { result(command == "messages-read" ? readKind : candidateKind, status: "unsupported", findings: ["Apple Messages live reads require the sqlite3 command on this Mac."]); exit(2) }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@motionsmith/apple-messages-mcp",
+  "version": "0.1.0",
+  "description": "Library-first MCP protocol and local macOS helper toolkit for Apple Messages.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "helper/apple-messages-helper.swift",
+    "scripts/build-apple-messages-helper.sh",
+    "scripts/apple-messages-helper.Info.plist",
+    "README.md",
+    "LICENSE.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motionsmith/apple-messages-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/motionsmith/apple-messages-mcp/issues"
+  },
+  "homepage": "https://github.com/motionsmith/apple-messages-mcp#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^22.15.0",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.59.4",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "lint": "eslint . --ext .ts",
+    "helper:build": "scripts/build-apple-messages-helper.sh",
+    "pack:check": "pnpm pack --pack-destination /tmp/apple-messages-mcp-pack"
+  }
+}

package/scripts/apple-messages-helper.Info.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>apple-messages-helper</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.motionsmith.apple-messages-mcp.host</string>
+  <key>CFBundleName</key>
+  <string>Apple Messages MCP Host</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>0.1.0</string>
+  <key>LSUIElement</key>
+  <true/>
+</dict>
+</plist>

package/scripts/build-apple-messages-helper.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SOURCE="$ROOT/helper/apple-messages-helper.swift"
+APP_NAME="${APPLE_MESSAGES_MCP_HOST_APP_NAME:-Apple Messages MCP Host}"
+BUNDLE_ID="${APPLE_MESSAGES_MCP_HOST_BUNDLE_ID:-com.motionsmith.apple-messages-mcp.host}"
+APP_DIR="${APPLE_MESSAGES_MCP_HOST_APP_DIR:-$ROOT/bin/$APP_NAME.app}"
+EXECUTABLE="$APP_DIR/Contents/MacOS/apple-messages-helper"
+PLIST="$APP_DIR/Contents/Info.plist"
+TEMPLATE="$ROOT/scripts/apple-messages-helper.Info.plist"
+
+if [ "$(uname -s)" != "Darwin" ]; then
+  echo 'Apple Messages helper compilation requires macOS.' >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$EXECUTABLE")"
+swiftc -framework Contacts "$SOURCE" -o "$EXECUTABLE"
+chmod +x "$EXECUTABLE"
+sed \
+  -e "s/com.motionsmith.apple-messages-mcp.host/$BUNDLE_ID/g" \
+  -e "s/Apple Messages MCP Host/$APP_NAME/g" \
+  "$TEMPLATE" > "$PLIST"
+codesign --force --sign "${APPLE_MESSAGES_MCP_CODESIGN_IDENTITY:--}" "$EXECUTABLE"
+codesign --force --sign "${APPLE_MESSAGES_MCP_CODESIGN_IDENTITY:--}" "$APP_DIR"
+printf 'Built %s\n' "$APP_DIR"