memos-mcp 1.0.0

package/src/index.ts

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+/**
+ * Memos MCP Server
+ * A Model Context Protocol server for interacting with Memos instances
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { MemosClient } from "./memos-client.ts";
+
+// Configuration from environment variables
+const MEMOS_URL = process.env.MEMOS_URL;
+const MEMOS_ACCESS_TOKEN = process.env.MEMOS_ACCESS_TOKEN;
+
+// Validate configuration
+function validateConfig(): void {
+  if (!MEMOS_URL) {
+    console.error("Error: MEMOS_URL environment variable is required");
+    console.error("Set it to your Memos instance URL, e.g., https://memos.example.com");
+    process.exit(1);
+  }
+  if (!MEMOS_ACCESS_TOKEN) {
+    console.error("Error: MEMOS_ACCESS_TOKEN environment variable is required");
+    console.error("Generate a Personal Access Token in your Memos settings");
+    process.exit(1);
+  }
+}
+
+// Tool definitions
+const tools: Tool[] = [
+  {
+    name: "create_memo",
+    description:
+      "Create a new memo in Memos. Supports markdown content, visibility settings, and optional location data.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        content: {
+          type: "string",
+          description: "The memo content in markdown format. Can include tags using #tag syntax.",
+        },
+        visibility: {
+          type: "string",
+          enum: ["PRIVATE", "PROTECTED", "PUBLIC"],
+          description:
+            "Visibility of the memo. PRIVATE (default): only you can see it. PROTECTED: visible to authenticated users. PUBLIC: visible to everyone.",
+        },
+        location: {
+          type: "object",
+          description: "Optional location data for the memo",
+          properties: {
+            placeholder: {
+              type: "string",
+              description: "Location name/description",
+            },
+            latitude: {
+              type: "number",
+              description: "Latitude coordinate",
+            },
+            longitude: {
+              type: "number",
+              description: "Longitude coordinate",
+            },
+          },
+        },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "search_memos",
+    description:
+      "Search and list memos from Memos. Supports various filters including content search, tags, visibility, and date ranges.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query to find in memo content. Leave empty to list all memos.",
+        },
+        tag: {
+          type: "string",
+          description: "Filter memos by a specific tag (without the # prefix)",
+        },
+        visibility: {
+          type: "string",
+          enum: ["PRIVATE", "PROTECTED", "PUBLIC"],
+          description: "Filter by visibility level",
+        },
+        state: {
+          type: "string",
+          enum: ["NORMAL", "ARCHIVED"],
+          description: "Filter by memo state. Default is NORMAL.",
+        },
+        pageSize: {
+          type: "number",
+          description: "Number of memos to return (default: 20, max: 100)",
+        },
+        orderBy: {
+          type: "string",
+          description: 'Sort order, e.g., "display_time desc" or "create_time asc"',
+        },
+      },
+    },
+  },
+  {
+    name: "get_memo",
+    description: "Get a single memo by its ID",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        memoId: {
+          type: "string",
+          description: "The memo ID (the part after 'memos/' in the resource name)",
+        },
+      },
+      required: ["memoId"],
+    },
+  },
+];
+
+// Create the MCP server
+const server = new Server(
+  {
+    name: "memos-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+// Initialize Memos client (will be set after config validation)
+let memosClient: MemosClient;
+
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "create_memo": {
+        const input = args as {
+          content: string;
+          visibility?: "PRIVATE" | "PROTECTED" | "PUBLIC";
+          location?: {
+            placeholder?: string;
+            latitude?: number;
+            longitude?: number;
+          };
+        };
+
+        const memo = await memosClient.createMemo({
+          content: input.content,
+          visibility: input.visibility,
+          location: input.location,
+        });
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  success: true,
+                  memo: {
+                    name: memo.name,
+                    content: memo.content,
+                    visibility: memo.visibility,
+                    tags: memo.tags,
+                    createTime: memo.createTime,
+                    snippet: memo.snippet,
+                  },
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      case "search_memos": {
+        const input = args as {
+          query?: string;
+          tag?: string;
+          visibility?: "PRIVATE" | "PROTECTED" | "PUBLIC";
+          state?: "NORMAL" | "ARCHIVED";
+          pageSize?: number;
+          orderBy?: string;
+        };
+
+        // Build filter from inputs
+        const filters: string[] = [];
+
+        if (input.query) {
+          filters.push(`content.contains("${input.query.replace(/"/g, '\\"')}")`);
+        }
+
+        if (input.tag) {
+          filters.push(`tag == "${input.tag.replace(/"/g, '\\"')}"`);
+        }
+
+        if (input.visibility) {
+          filters.push(`visibility == "${input.visibility}"`);
+        }
+
+        const filter = filters.length > 0 ? filters.join(" && ") : undefined;
+
+        const response = await memosClient.listMemos({
+          filter,
+          state: input.state,
+          pageSize: input.pageSize || 20,
+          orderBy: input.orderBy || "display_time desc",
+        });
+
+        const formattedMemos = response.memos.map((memo) => ({
+          name: memo.name,
+          content: memo.content.length > 200 ? memo.content.substring(0, 200) + "..." : memo.content,
+          visibility: memo.visibility,
+          tags: memo.tags,
+          pinned: memo.pinned,
+          createTime: memo.createTime,
+          displayTime: memo.displayTime,
+        }));
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  success: true,
+                  count: formattedMemos.length,
+                  memos: formattedMemos,
+                  nextPageToken: response.nextPageToken,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      case "get_memo": {
+        const input = args as { memoId: string };
+
+        const memo = await memosClient.getMemo(input.memoId);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  success: true,
+                  memo: {
+                    name: memo.name,
+                    content: memo.content,
+                    visibility: memo.visibility,
+                    tags: memo.tags,
+                    pinned: memo.pinned,
+                    state: memo.state,
+                    createTime: memo.createTime,
+                    updateTime: memo.updateTime,
+                    displayTime: memo.displayTime,
+                    location: memo.location,
+                  },
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Unknown tool: ${name}`,
+            },
+          ],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(
+            {
+              success: false,
+              error: errorMessage,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Main entry point
+async function main(): Promise<void> {
+  validateConfig();
+
+  // Initialize the Memos client
+  memosClient = new MemosClient({
+    baseUrl: MEMOS_URL!,
+    accessToken: MEMOS_ACCESS_TOKEN!,
+  });
+
+  // Test connection
+  const connected = await memosClient.testConnection();
+  if (!connected) {
+    console.error("Warning: Could not connect to Memos instance. Check your configuration.");
+  }
+
+  // Start the server
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Memos MCP server started");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/memos-client.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Tests for Memos API Client
+ */
+
+import { describe, it, mock, beforeEach } from "node:test";
+import assert from "node:assert";
+import { MemosClient } from "./memos-client.ts";
+
+// Mock fetch function - cast to any since undici's fetch has slightly different types
+const mockFetch = mock.fn<typeof globalThis.fetch>();
+
+describe("MemosClient", () => {
+  let client: MemosClient;
+
+  beforeEach(() => {
+    mockFetch.mock.resetCalls();
+    client = new MemosClient({
+      baseUrl: "https://memos.example.com",
+      accessToken: "test-token",
+      // Inject mock fetch via config instead of globalThis
+      fetch: mockFetch as unknown as typeof import("undici").fetch,
+    });
+  });
+
+  describe("constructor", () => {
+    it("should remove trailing slash from baseUrl", () => {
+      const clientWithSlash = new MemosClient({
+        baseUrl: "https://memos.example.com/",
+        accessToken: "test-token",
+        fetch: mockFetch as unknown as typeof import("undici").fetch,
+      });
+      // We can verify this by checking a request URL
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify({ name: "users/1" }), { status: 200 })),
+      );
+
+      clientWithSlash.getCurrentUser();
+
+      const callArgs = mockFetch.mock.calls[0];
+      assert.ok(callArgs);
+      assert.strictEqual(callArgs.arguments[0], "https://memos.example.com/api/v1/auth/me");
+    });
+  });
+
+  describe("createMemo", () => {
+    it("should create a memo with content only", async () => {
+      const mockMemo = {
+        name: "memos/abc123",
+        content: "Test memo",
+        visibility: "PRIVATE",
+        tags: [],
+        createTime: "2024-01-01T00:00:00Z",
+      };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockMemo), { status: 200 })),
+      );
+
+      const result = await client.createMemo({ content: "Test memo" });
+
+      assert.strictEqual(result.name, "memos/abc123");
+      assert.strictEqual(result.content, "Test memo");
+
+      const callArgs = mockFetch.mock.calls[0];
+      assert.ok(callArgs);
+      assert.strictEqual(callArgs.arguments[0], "https://memos.example.com/api/v1/memos");
+      assert.strictEqual(callArgs.arguments[1]?.method, "POST");
+      assert.strictEqual(
+        (callArgs.arguments[1]?.headers as Record<string, string>)?.Authorization,
+        "Bearer test-token",
+      );
+    });
+
+    it("should create a memo with visibility and location", async () => {
+      const mockMemo = {
+        name: "memos/xyz789",
+        content: "Geo memo",
+        visibility: "PUBLIC",
+        location: { placeholder: "NYC", latitude: 40.7, longitude: -74.0 },
+      };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockMemo), { status: 200 })),
+      );
+
+      const result = await client.createMemo({
+        content: "Geo memo",
+        visibility: "PUBLIC",
+        location: { placeholder: "NYC", latitude: 40.7, longitude: -74.0 },
+      });
+
+      assert.strictEqual(result.visibility, "PUBLIC");
+      assert.deepStrictEqual(result.location, { placeholder: "NYC", latitude: 40.7, longitude: -74.0 });
+
+      const callArgs = mockFetch.mock.calls[0];
+      const body = JSON.parse(callArgs?.arguments[1]?.body as string);
+      assert.strictEqual(body.content, "Geo memo");
+      assert.strictEqual(body.visibility, "PUBLIC");
+      assert.deepStrictEqual(body.location, { placeholder: "NYC", latitude: 40.7, longitude: -74.0 });
+    });
+
+    it("should throw error on API failure", async () => {
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response("Unauthorized", { status: 401, statusText: "Unauthorized" })),
+      );
+
+      await assert.rejects(async () => await client.createMemo({ content: "Test" }), {
+        message: /Memos API error: 401/,
+      });
+    });
+  });
+
+  describe("listMemos", () => {
+    it("should list memos without filters", async () => {
+      const mockResponse = {
+        memos: [{ name: "memos/1", content: "Memo 1" }],
+        nextPageToken: "token123",
+      };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      );
+
+      const result = await client.listMemos();
+
+      assert.strictEqual(result.memos.length, 1);
+      assert.strictEqual(result.nextPageToken, "token123");
+
+      const callArgs = mockFetch.mock.calls[0];
+      assert.strictEqual(callArgs?.arguments[0], "https://memos.example.com/api/v1/memos");
+    });
+
+    it("should list memos with all filters", async () => {
+      const mockResponse = { memos: [], nextPageToken: undefined };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      );
+
+      await client.listMemos({
+        filter: 'visibility == "PUBLIC"',
+        pageSize: 50,
+        pageToken: "abc",
+        state: "ARCHIVED",
+        orderBy: "create_time desc",
+      });
+
+      const callArgs = mockFetch.mock.calls[0];
+      const url = callArgs?.arguments[0] as string;
+
+      assert.ok(url.includes("filter=visibility"));
+      assert.ok(url.includes("pageSize=50"));
+      assert.ok(url.includes("pageToken=abc"));
+      assert.ok(url.includes("state=ARCHIVED"));
+      assert.ok(url.includes("orderBy=create_time"));
+    });
+  });
+
+  describe("getMemo", () => {
+    it("should get a memo by ID", async () => {
+      const mockMemo = {
+        name: "memos/abc123",
+        content: "My memo",
+        visibility: "PRIVATE",
+      };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockMemo), { status: 200 })),
+      );
+
+      const result = await client.getMemo("abc123");
+
+      assert.strictEqual(result.name, "memos/abc123");
+      assert.strictEqual(result.content, "My memo");
+
+      const callArgs = mockFetch.mock.calls[0];
+      assert.strictEqual(callArgs?.arguments[0], "https://memos.example.com/api/v1/memos/abc123");
+    });
+
+    it("should throw error when memo not found", async () => {
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response("Not Found", { status: 404, statusText: "Not Found" })),
+      );
+
+      await assert.rejects(async () => await client.getMemo("nonexistent"), {
+        message: /Memos API error: 404/,
+      });
+    });
+  });
+
+  describe("searchMemos", () => {
+    it("should search memos by query", async () => {
+      const mockResponse = {
+        memos: [{ name: "memos/1", content: "Hello world" }],
+      };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      );
+
+      await client.searchMemos("Hello");
+
+      const callArgs = mockFetch.mock.calls[0];
+      const url = callArgs?.arguments[0] as string;
+
+      // URL will be encoded, check for the encoded version
+      assert.ok(url.includes("filter="));
+      assert.ok(decodeURIComponent(url).includes('content.contains("Hello")'));
+    });
+
+    it("should escape quotes in search query", async () => {
+      const mockResponse = { memos: [] };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      );
+
+      await client.searchMemos('test "quoted" text');
+
+      const callArgs = mockFetch.mock.calls[0];
+      const url = callArgs?.arguments[0] as string;
+
+      // Check decoded URL contains escaped quotes
+      const decodedUrl = decodeURIComponent(url);
+      assert.ok(decodedUrl.includes('\\"quoted\\"'));
+    });
+
+    it("should pass additional options to listMemos", async () => {
+      const mockResponse = { memos: [] };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      );
+
+      await client.searchMemos("test", { pageSize: 10, state: "ARCHIVED" });
+
+      const callArgs = mockFetch.mock.calls[0];
+      const url = callArgs?.arguments[0] as string;
+
+      assert.ok(url.includes("pageSize=10"));
+      assert.ok(url.includes("state=ARCHIVED"));
+    });
+  });
+
+  describe("searchByTag", () => {
+    it("should search memos by tag", async () => {
+      const mockResponse = {
+        memos: [{ name: "memos/1", content: "#important task", tags: ["important"] }],
+      };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      );
+
+      await client.searchByTag("important");
+
+      const callArgs = mockFetch.mock.calls[0];
+      const url = callArgs?.arguments[0] as string;
+
+      // Check URL contains filter parameter with tag
+      assert.ok(url.includes("filter="));
+      assert.ok(url.includes("important"));
+    });
+  });
+
+  describe("getCurrentUser", () => {
+    it("should get current user info", async () => {
+      const mockUser = { name: "users/1", username: "testuser" };
+
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify(mockUser), { status: 200 })),
+      );
+
+      const result = await client.getCurrentUser();
+
+      assert.deepStrictEqual(result, { name: "users/1", username: "testuser" });
+
+      const callArgs = mockFetch.mock.calls[0];
+      assert.strictEqual(callArgs?.arguments[0], "https://memos.example.com/api/v1/auth/me");
+    });
+  });
+
+  describe("testConnection", () => {
+    it("should return true on successful connection", async () => {
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response(JSON.stringify({ name: "users/1" }), { status: 200 })),
+      );
+
+      const result = await client.testConnection();
+
+      assert.strictEqual(result, true);
+    });
+
+    it("should return false on failed connection", async () => {
+      mockFetch.mock.mockImplementationOnce(() =>
+        Promise.resolve(new Response("Unauthorized", { status: 401, statusText: "Unauthorized" })),
+      );
+
+      const result = await client.testConnection();
+
+      assert.strictEqual(result, false);
+    });
+
+    it("should return false on network error", async () => {
+      mockFetch.mock.mockImplementationOnce(() => Promise.reject(new Error("Network error")));
+
+      const result = await client.testConnection();
+
+      assert.strictEqual(result, false);
+    });
+  });
+});