kmemo-mcp 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerNoteTools } from './tools/notes.js';
+import { registerArrangeTools } from './tools/arrange.js';
+import { registerFileTools } from './tools/files.js';
+import { registerPageTools } from './tools/pages.js';
+const server = new McpServer({
+    name: 'sticky-notes',
+    version: '1.0.0',
+});
+registerNoteTools(server);
+registerArrangeTools(server);
+registerFileTools(server);
+registerPageTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Server failed to start:', err);
+    process.exit(1);
+});

package/dist/lib/api-client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HTTP API client for MCP server.
+ * Calls the deployed website API with MEMO_TOKEN authentication.
+ * No Supabase SDK, no .env file, no service keys.
+ */
+export declare function apiGet(path: string, params?: Record<string, string>): Promise<unknown>;
+export declare function apiPost(path: string, body?: unknown): Promise<unknown>;
+export declare function apiPut(path: string, body?: unknown): Promise<unknown>;
+export declare function apiDelete(path: string, body?: unknown): Promise<unknown>;

package/dist/lib/api-client.js

@@ -0,0 +1,64 @@
+/**
+ * HTTP API client for MCP server.
+ * Calls the deployed website API with MEMO_TOKEN authentication.
+ * No Supabase SDK, no .env file, no service keys.
+ */
+const API_URL = process.env.API_URL || 'https://kmemo.vercel.app';
+const MEMO_TOKEN = process.env.MEMO_TOKEN;
+if (!MEMO_TOKEN) {
+    console.error('Missing MEMO_TOKEN. Generate one from your memo app settings.');
+    process.exit(1);
+}
+const headers = {
+    'Authorization': `Bearer ${MEMO_TOKEN}`,
+    'Content-Type': 'application/json',
+};
+let tokenWarningShown = false;
+function checkTokenExpiryWarning(res) {
+    if (res.headers.get('X-Token-Expires-Soon') === 'true' && !tokenWarningShown) {
+        const daysRemaining = res.headers.get('X-Token-Days-Remaining') || '?';
+        console.error(`\n[WARNING] Your access token expires in ${daysRemaining} day(s).` +
+            `\nGenerate a new token from your memo app settings before it expires.\n`);
+        tokenWarningShown = true;
+    }
+}
+async function handleResponse(res) {
+    checkTokenExpiryWarning(res);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`API ${res.status}: ${body}`);
+    }
+    return res.json();
+}
+export async function apiGet(path, params) {
+    const url = new URL(path, API_URL);
+    if (params) {
+        Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    const res = await fetch(url.toString(), { headers });
+    return handleResponse(res);
+}
+export async function apiPost(path, body) {
+    const res = await fetch(new URL(path, API_URL).toString(), {
+        method: 'POST',
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return handleResponse(res);
+}
+export async function apiPut(path, body) {
+    const res = await fetch(new URL(path, API_URL).toString(), {
+        method: 'PUT',
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return handleResponse(res);
+}
+export async function apiDelete(path, body) {
+    const res = await fetch(new URL(path, API_URL).toString(), {
+        method: 'DELETE',
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return handleResponse(res);
+}

package/dist/tools/arrange.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerArrangeTools(server: McpServer): void;

package/dist/tools/arrange.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { apiGet, apiPost, apiPut } from '../lib/api-client.js';
+export function registerArrangeTools(server) {
+    server.tool('arrange_notes', 'Arrange notes on a page into a layout pattern.', {
+        page: z.number().describe('Page number to arrange'),
+        layout: z.enum(['grid', 'row', 'column', 'cascade', 'stack']).describe('Layout type'),
+        columns: z.number().optional().describe('Number of columns for grid layout (default: 3)'),
+        gap: z.number().optional().describe('Gap between notes in pixels (default: 30)'),
+        startX: z.number().optional().describe('Starting X position (default: 50)'),
+        startY: z.number().optional().describe('Starting Y position (default: 50)'),
+    }, async ({ page, layout, columns, gap, startX, startY }) => {
+        try {
+            const result = await apiPost('/api/mcp/notes/arrange', {
+                page,
+                layout,
+                columns: columns ?? 3,
+                gap: gap ?? 30,
+                startX: startX ?? 50,
+                startY: startY ?? 50,
+            });
+            const layoutDesc = layout === 'grid' ? `${columns ?? 3}-column grid` : layout;
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Arranged ${result.arranged} notes on page ${page} in ${layoutDesc} layout.`,
+                    }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('move_note', 'Move a note to a specific position and/or resize it.', {
+        id: z.string().describe('Note UUID'),
+        x: z.number().optional().describe('New X position'),
+        y: z.number().optional().describe('New Y position'),
+        w: z.number().optional().describe('New width'),
+        h: z.number().optional().describe('New height'),
+    }, async ({ id, x, y, w, h }) => {
+        try {
+            // First get current note to merge position/size
+            const current = await apiGet(`/api/mcp/notes/${id}`);
+            const body = {};
+            if (x !== undefined || y !== undefined) {
+                body.position = {
+                    x: x ?? current.note.position.x,
+                    y: y ?? current.note.position.y,
+                };
+            }
+            if (w !== undefined || h !== undefined) {
+                body.size = {
+                    w: w ?? current.note.size.w,
+                    h: h ?? current.note.size.h,
+                };
+            }
+            await apiPut(`/api/mcp/notes/${id}`, body);
+            return { content: [{ type: 'text', text: `Note ${id} moved/resized successfully.` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('move_notes_to_page', 'Move one or more notes to a different page.', {
+        ids: z.array(z.string()).describe('Array of note UUIDs to move'),
+        targetPage: z.number().describe('Target page number'),
+    }, async ({ ids, targetPage }) => {
+        try {
+            await apiPost('/api/mcp/notes/arrange', {
+                action: 'move_page',
+                ids,
+                target_page: targetPage,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Moved ${ids.length} note(s) to page ${targetPage}.`,
+                    }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+}

package/dist/tools/files.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFileTools(server: McpServer): void;

package/dist/tools/files.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { apiPost, apiGet, apiPut } from '../lib/api-client.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export function registerFileTools(server) {
+    server.tool('upload_file', 'Upload a local file to storage. Returns the public URL.', {
+        filePath: z.string().describe('Absolute path to the local file'),
+    }, async ({ filePath }) => {
+        try {
+            const buffer = await fs.readFile(filePath);
+            const base64 = buffer.toString('base64');
+            const fileName = path.basename(filePath);
+            const result = await apiPost('/api/mcp/upload', {
+                file_base64: base64,
+                file_name: fileName,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `File uploaded successfully.\nOriginal: ${fileName}\nURL: ${result.url}`,
+                    }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Failed to upload file: ${msg}` }] };
+        }
+    });
+    server.tool('attach_file_to_note', 'Attach an uploaded file to a note.', {
+        noteId: z.string().describe('Note UUID to attach file to'),
+        fileUrl: z.string().optional().describe('Public URL of already uploaded file'),
+        filePath: z.string().optional().describe('Local file path to upload and attach'),
+        fileName: z.string().optional().describe('Display name for the attachment'),
+    }, async ({ noteId, fileUrl, filePath, fileName }) => {
+        try {
+            if (filePath) {
+                // Upload and attach in one call
+                const buffer = await fs.readFile(filePath);
+                const base64 = buffer.toString('base64');
+                const name = fileName || path.basename(filePath);
+                const result = await apiPost('/api/mcp/upload', {
+                    file_base64: base64,
+                    file_name: path.basename(filePath),
+                    note_id: noteId,
+                    display_name: name,
+                });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `File attached to note ${noteId}.\nName: ${result.attachment.name}\nType: ${result.attachment.type}\nURL: ${result.attachment.url}`,
+                        }],
+                };
+            }
+            if (!fileUrl) {
+                return { content: [{ type: 'text', text: 'Provide either fileUrl or filePath.' }] };
+            }
+            // Attach existing URL - update note attachments via PUT
+            const noteResult = await apiGet(`/api/mcp/notes/${noteId}`);
+            const currentAttachments = noteResult.note.attachments || [];
+            const ext = path.extname(fileUrl).toLowerCase();
+            const isImage = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp'].includes(ext);
+            const newAttachment = {
+                id: crypto.randomUUID(),
+                name: fileName || path.basename(fileUrl),
+                url: fileUrl,
+                type: isImage ? 'image' : 'document',
+            };
+            await apiPut(`/api/mcp/notes/${noteId}`, {
+                attachments: [...currentAttachments, newAttachment],
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `File attached to note ${noteId}.\nName: ${newAttachment.name}\nType: ${newAttachment.type}\nURL: ${newAttachment.url}`,
+                    }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Failed to attach file: ${msg}` }] };
+        }
+    });
+    server.tool('list_attachments', 'List all attachments of a specific note.', {
+        noteId: z.string().describe('Note UUID'),
+    }, async ({ noteId }) => {
+        try {
+            const result = await apiGet(`/api/mcp/notes/${noteId}`);
+            const { title, attachments } = result.note;
+            if (!attachments?.length) {
+                return { content: [{ type: 'text', text: `Note "${title}" has no attachments.` }] };
+            }
+            const lines = attachments.map((a, i) => `${i + 1}. ${a.name} (${a.type}) - ${a.url}`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Attachments for "${title}" (${attachments.length}):\n\n${lines.join('\n')}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+}

package/dist/tools/notes.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerNoteTools(server: McpServer): void;

package/dist/tools/notes.js

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+import { apiGet, apiPost, apiPut, apiDelete } from '../lib/api-client.js';
+function formatNote(note) {
+    const parts = [
+        `[${note.id}] ${note.title || '(Untitled)'}`,
+        `Page: ${note.page_id} | Color: ${note.color}`,
+        `Position: (${note.position.x}, ${note.position.y}) | Size: ${note.size.w}x${note.size.h}`,
+        `Created: ${note.created_at} | Updated: ${note.updated_at}`,
+    ];
+    if (note.content) {
+        parts.push(`\n--- Content ---\n${note.content}`);
+    }
+    if (note.attachments?.length) {
+        parts.push(`\n--- Attachments (${note.attachments.length}) ---`);
+        for (const a of note.attachments) {
+            parts.push(`  - ${a.name} (${a.type}): ${a.url}`);
+        }
+    }
+    return parts.join('\n');
+}
+function formatSummary(note) {
+    const preview = note.content
+        ? note.content.substring(0, 80).replace(/\n/g, ' ')
+        : '';
+    const attachCount = note.attachments?.length || 0;
+    const attachInfo = attachCount > 0 ? ` [${attachCount} files]` : '';
+    return `[${note.id}] ${note.title || '(Untitled)'}${attachInfo} - ${preview}`;
+}
+export function registerNoteTools(server) {
+    server.tool('list_notes', 'List all notes on a specific page (or all pages). Returns id, title, and preview.', {
+        page: z.number().optional().describe('Page number to filter. Omit for all pages.'),
+    }, async ({ page }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = String(page);
+            const result = await apiGet('/api/mcp/notes', params);
+            const notes = result.notes;
+            if (notes.length === 0) {
+                const scope = page !== undefined ? `page ${page}` : 'any page';
+                return { content: [{ type: 'text', text: `No notes found on ${scope}.` }] };
+            }
+            const header = page !== undefined
+                ? `Notes on page ${page} (${notes.length}):`
+                : `All notes (${notes.length}):`;
+            const lines = notes.map(formatSummary);
+            return { content: [{ type: 'text', text: `${header}\n\n${lines.join('\n')}` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('read_note', 'Read the full content of a specific note by its ID.', {
+        id: z.string().describe('Note UUID'),
+    }, async ({ id }) => {
+        try {
+            const result = await apiGet(`/api/mcp/notes/${id}`);
+            return { content: [{ type: 'text', text: formatNote(result.note) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('search_notes', 'Search notes by keyword in title or content.', {
+        keyword: z.string().describe('Search keyword'),
+        page: z.number().optional().describe('Limit search to specific page'),
+    }, async ({ keyword, page }) => {
+        try {
+            const params = { search: keyword };
+            if (page !== undefined)
+                params.page = String(page);
+            const result = await apiGet('/api/mcp/notes', params);
+            const notes = result.notes;
+            if (notes.length === 0) {
+                return { content: [{ type: 'text', text: `No notes matching "${keyword}".` }] };
+            }
+            const lines = notes.map(formatSummary);
+            return { content: [{ type: 'text', text: `Found ${notes.length} note(s) matching "${keyword}":\n\n${lines.join('\n')}` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('create_note', 'Create a new sticky note.', {
+        title: z.string().optional().describe('Note title'),
+        content: z.string().optional().describe('Note content (plain text or markdown)'),
+        color: z.string().optional().describe('Background color hex (default: #FFD700)'),
+        page: z.number().optional().describe('Page number (default: 1)'),
+        x: z.number().optional().describe('X position'),
+        y: z.number().optional().describe('Y position'),
+    }, async ({ title, content, color, page, x, y }) => {
+        try {
+            const body = {};
+            if (title)
+                body.title = title;
+            if (content)
+                body.content = content;
+            if (color)
+                body.color = color;
+            if (page)
+                body.page_id = page;
+            if (x !== undefined || y !== undefined) {
+                body.position = { x: x ?? 100, y: y ?? 100 };
+            }
+            const result = await apiPost('/api/mcp/notes', body);
+            return { content: [{ type: 'text', text: `Note created: [${result.note.id}] ${result.note.title}` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('update_note', 'Update an existing note (title, content, color, etc.).', {
+        id: z.string().describe('Note UUID'),
+        title: z.string().optional().describe('New title'),
+        content: z.string().optional().describe('New content'),
+        color: z.string().optional().describe('New background color hex'),
+    }, async ({ id, title, content, color }) => {
+        try {
+            const body = {};
+            if (title !== undefined)
+                body.title = title;
+            if (content !== undefined)
+                body.content = content;
+            if (color !== undefined)
+                body.color = color;
+            const result = await apiPut(`/api/mcp/notes/${id}`, body);
+            return { content: [{ type: 'text', text: `Note updated: [${result.note.id}] ${result.note.title}` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+    server.tool('delete_note', 'Delete a note by its ID.', {
+        id: z.string().describe('Note UUID'),
+    }, async ({ id }) => {
+        try {
+            await apiDelete(`/api/mcp/notes/${id}`);
+            return { content: [{ type: 'text', text: `Note ${id} deleted.` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+}

package/dist/tools/pages.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPageTools(server: McpServer): void;

package/dist/tools/pages.js

@@ -0,0 +1,21 @@
+import { apiGet } from '../lib/api-client.js';
+export function registerPageTools(server) {
+    server.tool('list_pages', 'List all pages that have notes, with the count of notes on each page.', {}, async () => {
+        try {
+            const result = await apiGet('/api/mcp/pages');
+            if (result.pages.length === 0) {
+                return { content: [{ type: 'text', text: 'No notes found in any page.' }] };
+            }
+            const lines = result.pages.map(p => `Page ${p.page_id}: ${p.count} note(s)`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Pages with notes (${result.pages.length} pages, ${result.total_notes} total notes):\n\n${lines.join('\n')}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "kmemo-mcp",
+    "version": "1.0.0",
+    "description": "MCP server for Kmemo sticky notes - read, create, and manage your memos from AI assistants",
+    "type": "module",
+    "bin": {
+        "kmemo-mcp": "./dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build",
+        "start": "node dist/index.js",
+        "dev": "tsx watch src/index.ts"
+    },
+    "keywords": [
+        "mcp",
+        "sticky-notes",
+        "memo",
+        "ai",
+        "claude",
+        "gemini"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.26.0",
+        "zod": "^3.25.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20",
+        "tsx": "^4.19.0",
+        "typescript": "^5"
+    }
+}