@hu14/memos-mcp 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# Memos MCP Server
+
+A Model Context Protocol (MCP) server for interacting with [Memos](https://usememos.com/) - a lightweight, open-source memo hub.
+
+## Features
+
+- **Complete Memo Management**: Create, read, update, and delete memos
+- **Tag Support**: List, create, and manage tags
+- **Flexible Filtering**: Filter memos by creator, tags, visibility, and more
+- **Pagination**: Efficiently handle large memo collections
+
+## Installation
+
+```bash
+npm install -g memos-mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx memos-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MEMOS_API_URL` | No | Your Memos instance URL (default: `http://localhost:5230`) |
+| `MEMOS_API_TOKEN` | Yes | Your Memos API access token |
+
+### Getting an API Token
+
+1. Log in to your Memos instance
+2. Go to **Settings** → **Access Tokens**
+3. Create a new token with appropriate permissions
+
+### Claude Code Configuration
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "memos": {
+      "command": "npx",
+      "args": ["-y", "memos-mcp"],
+      "env": {
+        "MEMOS_API_URL": "https://your-memos-instance.com",
+        "MEMOS_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Or for local development:
+
+```json
+{
+  "mcpServers": {
+    "memos": {
+      "command": "node",
+      "args": ["/path/to/memos-mcp/dist/index.js"],
+      "env": {
+        "MEMOS_API_URL": "http://localhost:5230",
+        "MEMOS_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Memos
+
+- **`list_memos`** - List all memos with optional filtering and pagination
+  - `filter`: Filter expression (e.g., `creator == "users/1"`, `tag == "ideas"`)
+  - `limit`: Maximum number of memos to return (default: 10)
+  - `offset`: Number of memos to skip for pagination
+  - `sort`: Sort order (e.g., `create_time desc`, `update_time`)
+
+- **`get_memo`** - Get a single memo by ID
+  - `name`: Memo name/ID (e.g., `memos/123`)
+
+- **`create_memo`** - Create a new memo
+  - `content`: Memo content (supports Markdown)
+  - `visibility`: Visibility level (`PRIVATE`, `PROTECTED`, `PUBLIC`)
+  - `tags`: Array of tags to attach
+
+- **`update_memo`** - Update an existing memo
+  - `name`: Memo name/ID
+  - `content`: New content
+  - `visibility`: New visibility
+  - `tags`: New tags (replaces existing)
+
+- **`delete_memo`** - Delete a memo permanently
+  - `name`: Memo name/ID to delete
+
+### Tags
+
+- **`list_tags`** - List all tags
+  - `creator`: Filter by creator
+  - `limit`: Maximum number of tags
+
+- **`create_tag`** - Create a new tag
+  - `name`: Tag name (without # prefix)
+
+- **`delete_tag`** - Delete a tag
+  - `name`: Tag name (e.g., `tags/ideas`)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+MEMOS_API_URL=http://localhost:5230 MEMOS_API_TOKEN=xxx npm run dev
+```
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+// Environment configuration
+const MEMOS_API_URL = process.env.MEMOS_API_URL || "http://localhost:5230";
+const MEMOS_API_TOKEN = process.env.MEMOS_API_TOKEN;
+if (!MEMOS_API_TOKEN) {
+    console.error("Error: MEMOS_API_TOKEN environment variable is required");
+    process.exit(1);
+}
+// API client
+async function memosApi(path, options = {}) {
+    const url = `${MEMOS_API_URL}${path}`;
+    const headers = {
+        "Authorization": `Bearer ${MEMOS_API_TOKEN}`,
+        "Content-Type": "application/json",
+        ...options.headers,
+    };
+    const response = await fetch(url, { ...options, headers });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`API Error ${response.status}: ${errorText}`);
+    }
+    if (response.status === 204) {
+        return null;
+    }
+    return response.json();
+}
+// Tool definitions
+const TOOLS = [
+    {
+        name: "list_memos",
+        description: "List all memos with optional filtering and pagination",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filter: {
+                    type: "string",
+                    description: "Filter expression (e.g., 'creator == \"users/1\"', 'tag == \"ideas\"')",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of memos to return (default: 10)",
+                    default: 10,
+                },
+                offset: {
+                    type: "number",
+                    description: "Number of memos to skip for pagination",
+                    default: 0,
+                },
+                sort: {
+                    type: "string",
+                    description: "Sort order (e.g., 'create_time desc', 'update_time')",
+                    default: "create_time desc",
+                },
+            },
+        },
+    },
+    {
+        name: "get_memo",
+        description: "Get a single memo by ID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Memo name/ID (e.g., 'memos/123')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "create_memo",
+        description: "Create a new memo",
+        inputSchema: {
+            type: "object",
+            properties: {
+                content: {
+                    type: "string",
+                    description: "Memo content (supports Markdown)",
+                },
+                visibility: {
+                    type: "string",
+                    description: "Memo visibility: PRIVATE, PROTECTED, or PUBLIC",
+                    enum: ["PRIVATE", "PROTECTED", "PUBLIC"],
+                    default: "PRIVATE",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Tags to attach to the memo",
+                },
+            },
+            required: ["content"],
+        },
+    },
+    {
+        name: "update_memo",
+        description: "Update an existing memo",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Memo name/ID (e.g., 'memos/123')",
+                },
+                content: {
+                    type: "string",
+                    description: "New memo content",
+                },
+                visibility: {
+                    type: "string",
+                    description: "New visibility: PRIVATE, PROTECTED, or PUBLIC",
+                    enum: ["PRIVATE", "PROTECTED", "PUBLIC"],
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "New tags to replace existing ones",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "delete_memo",
+        description: "Delete a memo permanently",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Memo name/ID to delete (e.g., 'memos/123')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "list_tags",
+        description: "List all tags with optional filtering",
+        inputSchema: {
+            type: "object",
+            properties: {
+                creator: {
+                    type: "string",
+                    description: "Filter by creator (e.g., 'users/1')",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of tags to return",
+                    default: 100,
+                },
+            },
+        },
+    },
+    {
+        name: "create_tag",
+        description: "Create a new tag",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Tag name (without # prefix)",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "delete_tag",
+        description: "Delete a tag",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Tag name to delete (e.g., 'tags/ideas')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+];
+// Tool handlers
+async function handleListMemos(args) {
+    const params = new URLSearchParams();
+    if (args.filter)
+        params.append("filter", args.filter);
+    if (args.limit)
+        params.append("pageSize", args.limit.toString());
+    if (args.offset)
+        params.append("offset", args.offset.toString());
+    if (args.sort)
+        params.append("orderBy", args.sort);
+    const result = await memosApi(`/api/v1/memos?${params.toString()}`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+async function handleGetMemo(args) {
+    const result = await memosApi(`/api/v1/${args.name}`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+async function handleCreateMemo(args) {
+    const body = {
+        content: args.content,
+        visibility: args.visibility || "PRIVATE",
+        tags: args.tags || [],
+    };
+    const result = await memosApi("/api/v1/memos", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Memo created successfully:\n${JSON.stringify(result, null, 2)}`,
+            },
+        ],
+    };
+}
+async function handleUpdateMemo(args) {
+    const body = {};
+    if (args.content !== undefined)
+        body.content = args.content;
+    if (args.visibility !== undefined)
+        body.visibility = args.visibility;
+    if (args.tags !== undefined)
+        body.tags = args.tags;
+    const result = await memosApi(`/api/v1/${args.name}`, {
+        method: "PATCH",
+        body: JSON.stringify(body),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Memo updated successfully:\n${JSON.stringify(result, null, 2)}`,
+            },
+        ],
+    };
+}
+async function handleDeleteMemo(args) {
+    await memosApi(`/api/v1/${args.name}`, {
+        method: "DELETE",
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Memo ${args.name} deleted successfully.`,
+            },
+        ],
+    };
+}
+async function handleListTags(args) {
+    const params = new URLSearchParams();
+    if (args.creator)
+        params.append("filter", `creator == "${args.creator}"`);
+    if (args.limit)
+        params.append("pageSize", args.limit.toString());
+    const result = await memosApi(`/api/v1/tags?${params.toString()}`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+async function handleCreateTag(args) {
+    const body = {
+        name: args.name,
+    };
+    const result = await memosApi("/api/v1/tags", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Tag created successfully:\n${JSON.stringify(result, null, 2)}`,
+            },
+        ],
+    };
+}
+async function handleDeleteTag(args) {
+    await memosApi(`/api/v1/${args.name}`, {
+        method: "DELETE",
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Tag ${args.name} deleted successfully.`,
+            },
+        ],
+    };
+}
+// Main server
+const server = new index_js_1.Server({
+    name: "memos-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "list_memos":
+                return await handleListMemos(args);
+            case "get_memo":
+                return await handleGetMemo(args);
+            case "create_memo":
+                return await handleCreateMemo(args);
+            case "update_memo":
+                return await handleUpdateMemo(args);
+            case "delete_memo":
+                return await handleDeleteMemo(args);
+            case "list_tags":
+                return await handleListTags(args);
+            case "create_tag":
+                return await handleCreateTag(args);
+            case "delete_tag":
+                return await handleDeleteTag(args);
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Memos MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@hu14/memos-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Memos - A lightweight, open-source memo hub",
+  "main": "dist/index.js",
+  "bin": {
+    "memos-mcp": "dist/index.js"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "npm run build && npm run start"
+  },
+  "keywords": [
+    "mcp",
+    "memos",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^6.0.2"
+  }
+}