@amenopohis1er/mynotes-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog — @amenopohis1er/mynotes-mcp
+
+The companion versions independently of the My Notes extension; the bridge
+protocol has its own version (`v: 1` in every frame). Compatibility notes
+appear here whenever either side moves.
+
+## 0.1.0 — 2026-07-03
+
+First release. Requires My Notes ≥ 0.5.0 (bridge protocol v1).
+
+- MCP stdio server with five tools: `search_notes`, `list_notes`, `read_note`
+  (paged via `offset`), `create_note`, `append_to_note` — no delete, by design.
+- Native-messaging host role (Chrome-spawned) relaying to a 0600 local socket;
+  multiple agents multiplexed over one bridge.
+- `install`: registers the host with every detected Chromium browser
+  (Chrome/Beta/Chromium/Brave/Edge/Arc on macOS; XDG paths on Linux).
+- `doctor`: end-to-end chain diagnosis with actionable hints.
+- Cause-aware errors written for LLM consumption (Chrome closed vs Agent
+  access off vs bridge stalled), with explicit retry guidance.
+- macOS + Linux. Windows: not yet (registry-based registration).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amen (amenophis1er)
+
+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,43 @@
+# @amenopohis1er/mynotes-mcp
+
+MCP companion for the [My Notes](https://mynotes.amenophis.dev) Chrome
+extension — lets local AI agents (Claude Code, or any MCP client) search,
+read, and add to your notes. **Local-only**: no servers, no network; every
+byte stays on your machine, flowing Chrome ↔ this process ↔ your agent.
+
+## Setup
+
+```bash
+npx @amenopohis1er/mynotes-mcp install     # register the native-messaging host, then restart Chrome
+```
+
+1. In My Notes → **Settings → Labs**, turn ON **Agent access (MCP)**.
+2. Add to your agent's MCP config:
+
+```json
+{ "mcpServers": { "mynotes": { "command": "npx", "args": ["@amenopohis1er/mynotes-mcp"] } } }
+```
+
+3. Anything wrong? `npx @amenopohis1er/mynotes-mcp doctor` diagnoses the whole chain.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_notes` | Full-text search (optionally within a `#tag`), returns snippets |
+| `list_notes` | Most-recently-updated notes (id, title, pinned) |
+| `read_note` | One note as Markdown (pages via `offset` for large notes) |
+| `create_note` | New note from Markdown |
+| `append_to_note` | Append Markdown to a note (snapshotted first — restorable from History) |
+
+Chrome must be running with the extension enabled — notes live in the
+browser's storage and never leave it except through this local bridge.
+Agent edits are snapshotted to the note's History before they land.
+
+**Multiple Chrome profiles?** Notes are per-profile, and the bridge serves
+ONE profile at a time: enable "Agent access" in exactly the profile whose
+notes your agent should see. If it's on in several, the first to connect
+wins and the others wait — flip the toggle off in the profiles you don't
+want exposed.
+
+Design & protocol: [`companion/DESIGN.md`](./DESIGN.md) in the repo.

package/dist/protocol.js

@@ -0,0 +1,14 @@
+/**
+ * Bridge protocol between the extension's service worker and the companion
+ * (native-messaging host ↔ MCP server). Imported by BOTH sides — this file is
+ * the single source of truth (see companion/DESIGN.md).
+ *
+ * Native messaging caps a message at ~1 MB each way; results that could grow
+ * (search snippets, note bodies) are truncated/paginated by the handler.
+ */
+/** The native-messaging host name registered by `mynotes-mcp install`. */
+export const NATIVE_HOST_NAME = 'com.mynotes.companion';
+/** The published Chrome Web Store extension ID (pinned by the manifest `key`,
+ *  so dev/unpacked builds share it) — the ONLY origin the host trusts. */
+export const EXTENSION_ID = 'fcfkddblflheplmakgjaippneanoibge';
+export const PROTOCOL_VERSION = 1;

package/dist/src/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * mynotes-mcp — one binary, two roles + utilities (companion/DESIGN.md):
+ *   (spawned by Chrome w/ a chrome-extension:// arg)  → native-messaging host
+ *   mynotes-mcp                                       → MCP stdio server
+ *   mynotes-mcp install                               → register the host
+ *   mynotes-mcp doctor                                → diagnose the chain
+ */
+import { createRequire } from 'node:module';
+import { isChromeSpawned, runHost } from './host.js';
+import { runServer } from './server.js';
+import { runInstall } from './install.js';
+import { runDoctor } from './doctor.js';
+const version = createRequire(import.meta.url)('../../package.json').version;
+const arg = process.argv[2];
+if (isChromeSpawned(process.argv)) {
+    void runHost();
+}
+else if (arg === 'install') {
+    runInstall();
+}
+else if (arg === 'doctor') {
+    void runDoctor();
+}
+else if (arg === 'host') {
+    void runHost(); // manual/debug entry
+}
+else if (arg === undefined || arg === 'serve') {
+    void runServer(version);
+}
+else {
+    console.error(`Unknown command: ${arg}\nUsage: mynotes-mcp [install|doctor]  (no args = MCP stdio server)`);
+    process.exit(1);
+}

package/dist/src/client.js

@@ -0,0 +1,108 @@
+/**
+ * Socket client used by the server role and `doctor`: newline-delimited JSON
+ * to the host, with per-request timeouts and self-diagnosing errors.
+ */
+import { execFile } from 'node:child_process';
+import net from 'node:net';
+import readline from 'node:readline';
+import { PROTOCOL_VERSION } from '../protocol.js';
+import { socketPath } from './paths.js';
+/** Best-effort "is a Chromium browser running?" — splits the two failure modes
+ *  so the error tells the user the RIGHT action. Never throws. */
+function chromeRunning() {
+    const pattern = process.platform === 'darwin' ? 'Google Chrome|Chromium|Brave|Microsoft Edge|Arc' : 'chrome|chromium|brave|msedge';
+    return new Promise((resolve) => {
+        execFile('pgrep', ['-if', pattern], (error) => resolve(!error));
+    });
+}
+/** These strings are read by an LLM — each states the cause, the exact user
+ *  action, and whether retrying helps. */
+async function notReachable() {
+    if (await chromeRunning()) {
+        return ("My Notes isn't reachable. Chrome appears to be running, so the likely cause is that " +
+            '"Agent access (MCP)" is OFF: ask the user to open My Notes → Settings → Labs and turn it on ' +
+            '(or run `npx @amenopohis1er/mynotes-mcp doctor` if it already is). Do not retry until the user confirms — ' +
+            'then the same call will work.');
+    }
+    return ("My Notes isn't reachable because Chrome is not running — the notes live inside the browser. " +
+        'Ask the user to open Chrome (the bridge reconnects automatically within a few seconds), ' +
+        'then retry the same call. Do not retry before that.');
+}
+export class BridgeClient {
+    path;
+    socket = null;
+    pending = new Map();
+    seq = 0;
+    constructor(path = socketPath()) {
+        this.path = path;
+    }
+    async ensureConnected() {
+        if (this.socket && !this.socket.destroyed)
+            return this.socket;
+        const socket = await new Promise((resolve, reject) => {
+            const s = net.connect(this.path, () => resolve(s));
+            s.on('error', () => {
+                void notReachable().then((message) => reject(new Error(message)));
+            });
+        });
+        const lines = readline.createInterface({ input: socket });
+        lines.on('line', (line) => {
+            let response;
+            try {
+                response = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            const resolve = this.pending.get(response.id);
+            if (resolve) {
+                this.pending.delete(response.id);
+                resolve(response);
+            }
+        });
+        const dropAll = () => {
+            this.socket = null;
+            for (const [id, resolve] of this.pending) {
+                this.pending.delete(id);
+                resolve({
+                    v: PROTOCOL_VERSION,
+                    id,
+                    ok: false,
+                    error: 'The connection to My Notes dropped mid-call (Chrome closed, or Agent access was ' +
+                        'turned off). Ask the user to check Chrome and the Labs toggle, then retry.',
+                });
+            }
+        };
+        socket.on('close', dropAll);
+        socket.on('error', dropAll);
+        this.socket = socket;
+        return socket;
+    }
+    async call(method, params, timeoutMs = 15_000) {
+        const socket = await this.ensureConnected();
+        const id = `r${++this.seq}`;
+        const response = await new Promise((resolve) => {
+            this.pending.set(id, resolve);
+            socket.write(JSON.stringify({ v: PROTOCOL_VERSION, id, method, params }) + '\n');
+            setTimeout(() => {
+                if (this.pending.delete(id)) {
+                    resolve({
+                        v: PROTOCOL_VERSION,
+                        id,
+                        ok: false,
+                        error: `${method} timed out: the bridge socket exists but the extension didn't answer. ` +
+                            'Ask the user to toggle "Agent access" off and on in My Notes → Settings → Labs, ' +
+                            'or run `npx @amenopohis1er/mynotes-mcp doctor`. Retrying without that will likely time out again.',
+                    });
+                }
+            }, timeoutMs).unref();
+        });
+        if (!response.ok)
+            throw new Error(response.error);
+        return response.result;
+    }
+    close() {
+        this.socket?.destroy();
+        this.socket = null;
+    }
+}

package/dist/src/doctor.js

@@ -0,0 +1,51 @@
+/** `mynotes-mcp doctor` — diagnose the whole chain with actionable hints. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { NATIVE_HOST_NAME } from '../protocol.js';
+import { BridgeClient } from './client.js';
+import { nativeMessagingDirs, socketPath } from './paths.js';
+export async function runDoctor() {
+    let failed = false;
+    const bad = (msg, hint) => {
+        console.log(`✗ ${msg}\n    ↳ ${hint}`);
+        failed = true;
+    };
+    const good = (msg) => console.log(`✓ ${msg}`);
+    const manifests = nativeMessagingDirs()
+        .map(({ browser, dir }) => ({ browser, file: path.join(dir, `${NATIVE_HOST_NAME}.json`) }))
+        .filter(({ file }) => fs.existsSync(file));
+    if (manifests.length) {
+        good(`Host manifest registered (${manifests.map((m) => m.browser).join(', ')})`);
+        for (const { file } of manifests) {
+            try {
+                const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (!manifest.path || !fs.existsSync(manifest.path)) {
+                    bad(`Launcher missing: ${manifest.path}`, 'Re-run `npx @amenopohis1er/mynotes-mcp install`.');
+                }
+            }
+            catch {
+                bad(`Unreadable manifest: ${file}`, 'Re-run `npx @amenopohis1er/mynotes-mcp install`.');
+            }
+        }
+    }
+    else {
+        bad('No native-messaging manifest found', 'Run `npx @amenopohis1er/mynotes-mcp install`, then restart Chrome.');
+    }
+    if (fs.existsSync(socketPath()) || process.platform === 'win32') {
+        const client = new BridgeClient();
+        try {
+            const pong = (await client.call('ping', undefined, 5_000));
+            good(`Bridge alive — My Notes ${pong.extension} (protocol v${pong.version})`);
+        }
+        catch (error) {
+            bad(`Socket exists but ping failed: ${error instanceof Error ? error.message : error}`, 'Toggle "Agent access" off/on in My Notes → Settings → Labs, or restart Chrome.');
+        }
+        finally {
+            client.close();
+        }
+    }
+    else {
+        bad(`Bridge socket not found (${socketPath()})`, 'Is Chrome running? Is "Agent access (MCP)" ON in My Notes → Settings → Labs? (And restart Chrome after install.)');
+    }
+    process.exit(failed ? 1 : 0);
+}

package/dist/src/framing.js

@@ -0,0 +1,36 @@
+/**
+ * Chrome native-messaging framing: each message is a 4-byte little-endian
+ * uint32 length followed by that many bytes of UTF-8 JSON.
+ */
+export function encodeFrame(message) {
+    const body = Buffer.from(JSON.stringify(message), 'utf8');
+    const frame = Buffer.allocUnsafe(4 + body.length);
+    frame.writeUInt32LE(body.length, 0);
+    body.copy(frame, 4);
+    return frame;
+}
+/**
+ * Incremental frame decoder — feed arbitrary chunks, get whole messages.
+ * Chrome never sends >1 MB; reject bigger lengths so a corrupt stream can't
+ * make us buffer unbounded garbage.
+ */
+export class FrameDecoder {
+    buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        const messages = [];
+        for (;;) {
+            if (this.buffer.length < 4)
+                break;
+            const length = this.buffer.readUInt32LE(0);
+            if (length > 8 * 1024 * 1024)
+                throw new Error(`Frame too large: ${length} bytes`);
+            if (this.buffer.length < 4 + length)
+                break;
+            const body = this.buffer.subarray(4, 4 + length).toString('utf8');
+            this.buffer = this.buffer.subarray(4 + length);
+            messages.push(JSON.parse(body));
+        }
+        return messages;
+    }
+}

package/dist/src/host.js

@@ -0,0 +1,100 @@
+/**
+ * Host role — spawned BY Chrome (native messaging) when the extension's Labs
+ * toggle connects. Relays frames between the extension (stdin/stdout) and any
+ * number of MCP server processes (unix socket clients), multiplexing by
+ * request id: client ids are prefixed `c<N>:` on the way in and stripped on
+ * the way out, so concurrent agents can't collide.
+ */
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import readline from 'node:readline';
+import { FrameDecoder, encodeFrame } from './framing.js';
+import { dataDir, socketPath } from './paths.js';
+export async function runHost(io = { input: process.stdin, output: process.stdout }) {
+    const { input, output } = io;
+    const exit = io.exit ?? ((code) => process.exit(code));
+    const sock = io.sock ?? socketPath();
+    fs.mkdirSync(dataDir(), { recursive: true });
+    // A stale socket file from a crashed host blocks bind — remove it. If another
+    // LIVE host holds it (second Chrome profile), fail: one host per user.
+    if (process.platform !== 'win32' && fs.existsSync(sock)) {
+        const alive = await new Promise((resolve) => {
+            const probe = net.connect(sock, () => {
+                probe.destroy();
+                resolve(true);
+            });
+            probe.on('error', () => resolve(false));
+        });
+        if (alive) {
+            process.stderr.write('mynotes-mcp: another host already owns the socket; exiting\n');
+            process.exit(1);
+        }
+        fs.unlinkSync(sock);
+    }
+    let clientSeq = 0;
+    const clients = new Map();
+    const server = net.createServer((client) => {
+        const clientId = ++clientSeq;
+        clients.set(clientId, client);
+        const lines = readline.createInterface({ input: client });
+        lines.on('line', (line) => {
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof request?.id !== 'string')
+                return;
+            // Tag the id with the client, forward to the extension.
+            output.write(encodeFrame({ ...request, id: `c${clientId}:${request.id}` }));
+        });
+        client.on('close', () => clients.delete(clientId));
+        client.on('error', () => clients.delete(clientId));
+    });
+    server.listen(sock, () => {
+        if (process.platform !== 'win32')
+            fs.chmodSync(sock, 0o600);
+    });
+    // Extension → host frames are responses; route back by the id prefix.
+    const decoder = new FrameDecoder();
+    input.on('data', (chunk) => {
+        let messages;
+        try {
+            messages = decoder.push(chunk);
+        }
+        catch {
+            exit(1); // corrupt stream — Chrome will respawn us on reconnect
+            return;
+        }
+        for (const message of messages) {
+            const response = message;
+            const match = /^c(\d+):(.*)$/.exec(response?.id ?? '');
+            if (!match)
+                continue;
+            const client = clients.get(Number(match[1]));
+            client?.write(JSON.stringify({ ...response, id: match[2] }) + '\n');
+        }
+    });
+    // Chrome closed the port (toggle off / browser quit): clean up and exit.
+    input.on('end', () => {
+        server.close();
+        for (const client of clients.values())
+            client.destroy();
+        try {
+            if (process.platform !== 'win32')
+                fs.unlinkSync(sock);
+        }
+        catch {
+            /* already gone */
+        }
+        exit(0);
+    });
+}
+/** Chrome passes the extension origin as an argument — that's the role signal. */
+export function isChromeSpawned(argv) {
+    return argv.some((a) => a.startsWith('chrome-extension://'));
+}
+export const HOST_LOG_HINT = path.join(dataDir(), 'host.log');

package/dist/src/install.js

@@ -0,0 +1,50 @@
+/**
+ * `mynotes-mcp install` — register the native-messaging host so Chrome can
+ * spawn us. Writes a launcher script (node + absolute path to this package)
+ * and a host manifest into each detected browser's NativeMessagingHosts dir.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXTENSION_ID, NATIVE_HOST_NAME } from '../protocol.js';
+import { dataDir, nativeMessagingDirs } from './paths.js';
+export function runInstall() {
+    if (process.platform === 'win32') {
+        console.error('Windows is not supported yet (native-messaging registration uses the registry).');
+        process.exit(1);
+    }
+    const cliPath = fileURLToPath(new URL('./cli.js', import.meta.url));
+    const launcher = path.join(dataDir(), 'mynotes-mcp-host.sh');
+    fs.mkdirSync(dataDir(), { recursive: true });
+    // Chrome spawns the manifest's `path` directly with no shell/PATH — pin the
+    // exact node binary running this install.
+    fs.writeFileSync(launcher, `#!/bin/sh\nexec "${process.execPath}" "${cliPath}" "$@"\n`, { mode: 0o755 });
+    const manifest = {
+        name: NATIVE_HOST_NAME,
+        description: 'My Notes MCP companion — local agent access to your notes',
+        path: launcher,
+        type: 'stdio',
+        allowed_origins: [`chrome-extension://${EXTENSION_ID}/`],
+    };
+    let wrote = 0;
+    for (const { browser, dir } of nativeMessagingDirs()) {
+        // Only register where the browser is actually present (its parent profile
+        // dir exists) — don't create skeleton dirs for browsers the user never ran.
+        if (!fs.existsSync(path.dirname(dir)))
+            continue;
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `${NATIVE_HOST_NAME}.json`);
+        fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
+        console.log(`✓ ${browser}: ${file}`);
+        wrote++;
+    }
+    if (!wrote) {
+        console.error('✗ No Chromium-based browser profile found — is Chrome installed?');
+        process.exit(1);
+    }
+    console.log(`\nDone. Next:
+  1. Restart Chrome (native-messaging manifests are read at browser start).
+  2. In My Notes → Settings → Labs, turn ON "Agent access (MCP)".
+  3. Add to your agent's MCP config: {"command": "npx", "args": ["@amenopohis1er/mynotes-mcp"]}
+  4. Check the chain anytime: npx @amenopohis1er/mynotes-mcp doctor`);
+}

package/dist/src/paths.js

@@ -0,0 +1,44 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Per-user data dir for the launcher script + socket (created by install/host). */
+export function dataDir() {
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'MyNotes');
+    }
+    if (process.platform === 'win32') {
+        return path.join(process.env.APPDATA ?? os.homedir(), 'MyNotes');
+    }
+    return path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share'), 'mynotes');
+}
+/** The host↔server rendezvous: a 0600 unix socket (named pipe on Windows). */
+export function socketPath() {
+    if (process.platform === 'win32')
+        return '\\\\.\\pipe\\mynotes-mcp';
+    if (process.platform === 'linux' && process.env.XDG_RUNTIME_DIR) {
+        return path.join(process.env.XDG_RUNTIME_DIR, 'mynotes-mcp.sock');
+    }
+    return path.join(dataDir(), 'mcp.sock');
+}
+/** Native-messaging manifest directories per browser (user-level). */
+export function nativeMessagingDirs() {
+    const home = os.homedir();
+    if (process.platform === 'darwin') {
+        const base = path.join(home, 'Library', 'Application Support');
+        return [
+            { browser: 'Chrome', dir: path.join(base, 'Google', 'Chrome', 'NativeMessagingHosts') },
+            { browser: 'Chrome Beta', dir: path.join(base, 'Google', 'Chrome Beta', 'NativeMessagingHosts') },
+            { browser: 'Chromium', dir: path.join(base, 'Chromium', 'NativeMessagingHosts') },
+            { browser: 'Brave', dir: path.join(base, 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts') },
+            { browser: 'Edge', dir: path.join(base, 'Microsoft Edge', 'NativeMessagingHosts') },
+            { browser: 'Arc', dir: path.join(base, 'Arc', 'User Data', 'NativeMessagingHosts') },
+        ];
+    }
+    // Linux. (Windows uses the registry — not supported in v1; DESIGN.md non-goal.)
+    const cfg = process.env.XDG_CONFIG_HOME ?? path.join(home, '.config');
+    return [
+        { browser: 'Chrome', dir: path.join(cfg, 'google-chrome', 'NativeMessagingHosts') },
+        { browser: 'Chromium', dir: path.join(cfg, 'chromium', 'NativeMessagingHosts') },
+        { browser: 'Brave', dir: path.join(cfg, 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts') },
+        { browser: 'Edge', dir: path.join(cfg, 'microsoft-edge', 'NativeMessagingHosts') },
+    ];
+}

package/dist/src/server.js

@@ -0,0 +1,89 @@
+/**
+ * Server role — spawned by the agent (`npx @amenopohis1er/mynotes-mcp` in an MCP config).
+ * Exposes the note tools over MCP stdio and forwards each call to the
+ * Chrome-spawned host via the local socket.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { BridgeClient } from './client.js';
+export async function runServer(version) {
+    const bridge = new BridgeClient();
+    const server = new McpServer({ name: 'mynotes', version });
+    const asText = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+    const asError = (error) => ({
+        isError: true,
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+    });
+    server.registerTool('search_notes', {
+        description: 'Full-text search across the user\'s My Notes (local Chrome extension). Returns note ids, titles and matching snippets.',
+        inputSchema: {
+            query: z.string().describe('Text to search for'),
+            tag: z.string().optional().describe('Restrict to notes carrying this #tag (with or without the #)'),
+            limit: z.number().int().min(0).max(50).optional().describe('Max results (default 20)'),
+        },
+    }, async (args) => {
+        try {
+            return asText(await bridge.call('search_notes', args));
+        }
+        catch (error) {
+            return asError(error);
+        }
+    });
+    server.registerTool('list_notes', {
+        description: 'List the user\'s notes, most recently updated first (id, title, updatedAt, pinned).',
+        inputSchema: {
+            limit: z.number().int().min(0).max(200).optional().describe('Max results (default 50)'),
+        },
+    }, async (args) => {
+        try {
+            return asText(await bridge.call('list_notes', args));
+        }
+        catch (error) {
+            return asError(error);
+        }
+    });
+    server.registerTool('read_note', {
+        description: 'Read one note as Markdown. Large notes page: when `truncated` is true, call again with offset += markdown.length.',
+        inputSchema: {
+            id: z.string().describe('Note id (from search_notes / list_notes)'),
+            offset: z.number().int().min(0).optional().describe('Character offset to continue from (default 0)'),
+        },
+    }, async (args) => {
+        try {
+            return asText(await bridge.call('read_note', args));
+        }
+        catch (error) {
+            return asError(error);
+        }
+    });
+    server.registerTool('create_note', {
+        description: 'Create a new note from Markdown (headings #–###, - bullets, - [ ] checklists, numbered lists; inline markup stays literal).',
+        inputSchema: {
+            title: z.string().optional().describe('Note title (optional)'),
+            markdown: z.string().describe('The note body as Markdown'),
+        },
+    }, async (args) => {
+        try {
+            return asText(await bridge.call('create_note', args));
+        }
+        catch (error) {
+            return asError(error);
+        }
+    });
+    server.registerTool('append_to_note', {
+        description: 'Append Markdown to an existing note (separated by a divider). The note is snapshotted first, so the user can restore from History. On "note changed" errors, re-read and retry.',
+        inputSchema: {
+            id: z.string().describe('Note id to append to'),
+            markdown: z.string().describe('Markdown to append'),
+        },
+    }, async (args) => {
+        try {
+            return asText(await bridge.call('append_to_note', args));
+        }
+        catch (error) {
+            return asError(error);
+        }
+    });
+    await server.connect(new StdioServerTransport());
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@amenopohis1er/mynotes-mcp",
+  "version": "0.1.0",
+  "description": "MCP companion for the My Notes Chrome extension \u2014 lets local AI agents search, read, and add to your notes. Local-only: no servers, no network.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "notes",
+    "chrome-extension",
+    "claude",
+    "ai-agent",
+    "local-first",
+    "native-messaging"
+  ],
+  "license": "MIT",
+  "author": "Amen (https://github.com/amenophis1er)",
+  "homepage": "https://mynotes.amenophis.dev/ai-agent-notes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amenophis1er/chrome-extension-my-notes.git",
+    "directory": "companion"
+  },
+  "bugs": {
+    "url": "https://github.com/amenophis1er/chrome-extension-my-notes/issues"
+  },
+  "type": "module",
+  "bin": {
+    "mynotes-mcp": "dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}