@fredrika/mcp-mochi 1.0.5 → 1.0.6-beta.1

package/README.md

@@ -5,126 +5,149 @@ This MCP server provides integration with the Mochi flashcard system, allowing y
 ## Features
 
 - Create, update, and delete flashcards
+- Create cards from templates with automatic field name-to-ID mapping
+- Add attachments (images, audio) to cards
+- Get cards due for review
 - List flashcards, decks, and templates
 
-## Setup
+## Usage with Claude Desktop
+
+Add the following to your `claude_desktop_config.json`:
+
+### NPX (recommended)
+
+```json
+{
+  "mcpServers": {
+    "mochi": {
+      "command": "npx",
+      "args": ["-y", "@fredrika/mcp-mochi"],
+      "env": {
+        "MOCHI_API_KEY": "<YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+### Local Development
+
+```json
+{
+  "mcpServers": {
+    "mochi": {
+      "command": "node",
+      "args": ["/path/to/mcp-mochi/dist/index.js"],
+      "env": {
+        "MOCHI_API_KEY": "<YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+## Local Development Setup
 
-1. Install dependencies:
+1. Clone and install dependencies:
    ```bash
+   git clone https://github.com/fredrika/mcp-mochi.git
+   cd mcp-mochi
    npm install
    ```
 
-2. Configure your Mochi API token:
-   - Copy `.env.example` to `.env`
-   - Replace `your_mochi_api_token_here` with your actual Mochi API token
-
-3. Build the project:
+2. Build the project:
    ```bash
    npm run build
    ```
 
-4. Start the server:
+3. Test with MCP Inspector:
    ```bash
-   npm start
+   MOCHI_API_KEY=<YOUR_TOKEN> npx @modelcontextprotocol/inspector node dist/index.js
    ```
 
 ## Available Tools
 
-### `mochi_create_card`
+### `mochi_create_flashcard`
 Create a new flashcard in Mochi.
-- Parameters:
-  - `content`: string (Markdown content of the card. Separate front and back using a horizontal rule `---`)
-  - `deck-id`: string (ID of the deck to create the card in)
-  - `template-id`: string (optional, template to use for the card)
-  - `manual-tags`: string[] (optional, tags to add to the card)
-  - `fields`: object (map of field IDs to field values, required if using a template)
-
-### `mochi_update_card`
-Update or delete an existing flashcard in Mochi. To delete, set `trashed` to true.
-- Parameters:
-  - `card-id`: string (ID of the card to update)
-  - Any updatable card fields (see code for all options)
-  - To delete: set `trashed?` to `'true'` (string)
-
-### `mochi_list_cards`
-List cards (paginated).
-- Parameters:
-  - `deck-id`: string (optional, filter by deck)
-  - `limit`: number (optional, 1-100)
-  - `bookmark`: string (optional, for pagination)
+- `content`: Markdown content (separate front/back with `---`)
+- `deck-id`: ID of the deck (use `mochi_list_decks` to find)
+- `template-id`: (optional) Template to use
+- `fields`: (optional) Map of field IDs to values (required with template)
+- `manual-tags`: (optional) Array of tags
+
+### `mochi_create_card_from_template`
+Create a flashcard using a template with field **names** (not IDs). The MCP automatically maps names to IDs.
+- `template-id`: Template ID (use `mochi_list_templates` to find)
+- `deck-id`: Deck ID
+- `fields`: Map of field names to values (e.g., `{"Front": "Question?", "Back": "Answer"}`)
+- `manual-tags`: (optional) Array of tags
+
+### `mochi_update_flashcard`
+Update or delete a flashcard. Set `trashed?` to `true` to delete.
+- `card-id`: ID of the card to update
+- Any updatable card fields
+
+### `mochi_add_attachment`
+Add an attachment (image, audio, etc.) to a card using base64 data.
+- `card-id`: ID of the card
+- `data`: Base64-encoded file data
+- `filename`: Filename with extension (e.g., `image.png`)
+- `content-type`: (optional) MIME type (inferred from filename if omitted)
+
+### `mochi_list_flashcards`
+List flashcards (paginated).
+- `deck-id`: (optional) Filter by deck
+- `limit`: (optional) 1-100
+- `bookmark`: (optional) Pagination token
 
 ### `mochi_list_decks`
 List all decks.
-- Parameters:
-  - `bookmark`: string (optional, for pagination)
+- `bookmark`: (optional) Pagination token
 
 ### `mochi_list_templates`
-List all templates.
-- Parameters:
-  - `bookmark`: string (optional, for pagination)
-
-## Example Usage
+List all templates with their field definitions.
+- `bookmark`: (optional) Pagination token
 
-Here's how to use the MCP server with the MCP Inspector:
-
-1. Start the server:
-   ```bash
-   npm start
-   ```
+### `mochi_get_due_cards`
+Get flashcards due for review.
+- `deck-id`: (optional) Filter by deck
+- `date`: (optional) ISO 8601 date (defaults to today)
 
-2. In another terminal, use the MCP Inspector to interact with the server:
-   ```bash
-   mcp-inspector
-   ```
+## Examples
 
-3. Create a new flashcard:
-   ```json
-   {
-     "tool": "mochi_create_card",
-     "params": {
-       "content": "What is MCP?\n---\nModel Context Protocol - a protocol for providing context to LLMs",
-       "deck-id": "<YOUR_DECK_ID>"
-     }
-   }
-   ```
+### Create a simple flashcard
 
-4. List all decks:
-   ```json
-   {
-     "tool": "mochi_list_decks",
-     "params": {}
-   }
-   ```
-
-5. Delete a flashcard (set `trashed` to true via update):
-   ```json
-   {
-     "tool": "mochi_update_card",
-     "params": {
-       "card-id": "<CARD_ID>",
-       "trashed?": "true"
-     }
-   }
-   ```
-
-## Usage with Claude Desktop
-To use this with Claude Desktop, add the following to your `claude_desktop_config.json`:
+```json
+{
+  "tool": "mochi_create_flashcard",
+  "params": {
+    "content": "What is MCP?\n---\nModel Context Protocol - a protocol for providing context to LLMs",
+    "deck-id": "<DECK_ID>"
+  }
+}
+```
 
-### NPX
+### Create a card from template
 
 ```json
 {
-  "mcpServers": {
-    "mochi": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@fredrika/mcp-mochi"
-      ],
-      "env": {
-        "MOCHI_API_KEY": "<YOUR_TOKEN>"
-      }
+  "tool": "mochi_create_card_from_template",
+  "params": {
+    "template-id": "<TEMPLATE_ID>",
+    "deck-id": "<DECK_ID>",
+    "fields": {
+      "Front": "What is the capital of France?",
+      "Back": "Paris"
     }
   }
 }
 ```
+
+### Get today's due cards
+
+```json
+{
+  "tool": "mochi_get_due_cards",
+  "params": {}
+}
+```

package/dist/index.d.ts

@@ -2,102 +2,69 @@
 import { z } from "zod";
 declare const CreateCardRequestSchema: z.ZodObject<{
     content: z.ZodString;
-    "deck-id": z.ZodString;
-    "template-id": z.ZodDefault<z.ZodNullable<z.ZodOptional<z.ZodString>>>;
-    "manual-tags": z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    deckId: z.ZodString;
+    templateId: z.ZodDefault<z.ZodNullable<z.ZodOptional<z.ZodString>>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         id: z.ZodString;
         value: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        value: string;
-    }, {
-        id: string;
-        value: string;
-    }>>>;
-}, "strip", z.ZodTypeAny, {
-    content: string;
-    "deck-id": string;
-    "template-id": string | null;
-    "manual-tags"?: string[] | undefined;
-    fields?: Record<string, {
-        id: string;
-        value: string;
-    }> | undefined;
-}, {
-    content: string;
-    "deck-id": string;
-    "template-id"?: string | null | undefined;
-    "manual-tags"?: string[] | undefined;
-    fields?: Record<string, {
-        id: string;
-        value: string;
-    }> | undefined;
-}>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 declare const UpdateCardRequestSchema: z.ZodObject<{
     content: z.ZodOptional<z.ZodString>;
-    "deck-id": z.ZodOptional<z.ZodString>;
-    "template-id": z.ZodOptional<z.ZodString>;
-    "archived?": z.ZodOptional<z.ZodBoolean>;
-    "trashed?": z.ZodOptional<z.ZodString>;
+    deckId: z.ZodOptional<z.ZodString>;
+    templateId: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+    trashed: z.ZodOptional<z.ZodBoolean>;
     fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         id: z.ZodString;
         value: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        value: string;
-    }, {
-        id: string;
-        value: string;
-    }>>>;
-}, "strip", z.ZodTypeAny, {
-    content?: string | undefined;
-    "deck-id"?: string | undefined;
-    "template-id"?: string | undefined;
-    fields?: Record<string, {
-        id: string;
-        value: string;
-    }> | undefined;
-    "archived?"?: boolean | undefined;
-    "trashed?"?: string | undefined;
-}, {
-    content?: string | undefined;
-    "deck-id"?: string | undefined;
-    "template-id"?: string | undefined;
-    fields?: Record<string, {
-        id: string;
-        value: string;
-    }> | undefined;
-    "archived?"?: boolean | undefined;
-    "trashed?"?: string | undefined;
-}>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 declare const ListDecksParamsSchema: z.ZodObject<{
     bookmark: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    bookmark?: string | undefined;
-}, {
-    bookmark?: string | undefined;
-}>;
+}, z.core.$strip>;
 declare const ListCardsParamsSchema: z.ZodObject<{
-    "deck-id": z.ZodOptional<z.ZodString>;
+    deckId: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
     bookmark: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    "deck-id"?: string | undefined;
-    bookmark?: string | undefined;
-    limit?: number | undefined;
-}, {
-    "deck-id"?: string | undefined;
-    bookmark?: string | undefined;
-    limit?: number | undefined;
-}>;
+}, z.core.$strip>;
 declare const ListTemplatesParamsSchema: z.ZodObject<{
     bookmark: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    bookmark?: string | undefined;
-}, {
-    bookmark?: string | undefined;
-}>;
+}, z.core.$strip>;
+declare const GetDueCardsParamsSchema: z.ZodObject<{
+    deckId: z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const CreateCardFromTemplateSchema: z.ZodObject<{
+    templateId: z.ZodString;
+    deckId: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const AddAttachmentSchema: z.ZodObject<{
+    cardId: z.ZodString;
+    data: z.ZodString;
+    filename: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AddAttachmentRequest = z.infer<typeof AddAttachmentSchema>;
+declare const TemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    content: z.ZodString;
+    pos: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        pos: z.ZodString;
+        type: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        source: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        options: z.ZodOptional<z.ZodObject<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 declare const ListTemplatesResponseSchema: z.ZodObject<{
     bookmark: z.ZodString;
     docs: z.ZodArray<z.ZodObject<{
@@ -109,161 +76,41 @@ declare const ListTemplatesResponseSchema: z.ZodObject<{
             id: z.ZodString;
             name: z.ZodString;
             pos: z.ZodString;
+            type: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+            source: z.ZodNullable<z.ZodOptional<z.ZodString>>;
             options: z.ZodOptional<z.ZodObject<{
                 "multi-line?": z.ZodOptional<z.ZodBoolean>;
-            }, "strip", z.ZodTypeAny, {
-                "multi-line?"?: boolean | undefined;
-            }, {
-                "multi-line?"?: boolean | undefined;
-            }>>;
-        }, "strip", z.ZodTypeAny, {
-            name: string;
-            id: string;
-            pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
-        }, {
-            name: string;
-            id: string;
-            pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        id: string;
-        content: string;
-        fields: Record<string, {
-            name: string;
-            id: string;
-            pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
-        }>;
-        pos: string;
-    }, {
-        name: string;
-        id: string;
-        content: string;
-        fields: Record<string, {
-            name: string;
-            id: string;
-            pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
-        }>;
-        pos: string;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    bookmark: string;
-    docs: {
-        name: string;
-        id: string;
-        content: string;
-        fields: Record<string, {
-            name: string;
-            id: string;
-            pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
-        }>;
-        pos: string;
-    }[];
-}, {
-    bookmark: string;
-    docs: {
-        name: string;
-        id: string;
-        content: string;
-        fields: Record<string, {
-            name: string;
-            id: string;
-            pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
-        }>;
-        pos: string;
-    }[];
-}>;
+            }, z.core.$loose>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 type ListTemplatesParams = z.infer<typeof ListTemplatesParamsSchema>;
 type ListTemplatesResponse = z.infer<typeof ListTemplatesResponseSchema>;
 type ListCardsParams = z.infer<typeof ListCardsParamsSchema>;
 type ListDecksParams = z.infer<typeof ListDecksParamsSchema>;
 type CreateCardRequest = z.infer<typeof CreateCardRequestSchema>;
 type UpdateCardRequest = z.infer<typeof UpdateCardRequestSchema>;
+type GetDueCardsParams = z.infer<typeof GetDueCardsParamsSchema>;
+type CreateCardFromTemplateParams = z.infer<typeof CreateCardFromTemplateSchema>;
 declare const CreateCardResponseSchema: z.ZodObject<{
     id: z.ZodString;
-    tags: z.ZodArray<z.ZodString, "many">;
+    tags: z.ZodArray<z.ZodString>;
     content: z.ZodString;
     name: z.ZodString;
     "deck-id": z.ZodString;
     fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    id: string;
-    content: string;
-    "deck-id": string;
-    tags: string[];
-    fields?: Record<string, unknown> | undefined;
-}, {
-    name: string;
-    id: string;
-    content: string;
-    "deck-id": string;
-    tags: string[];
-    fields?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 declare const ListCardsResponseSchema: z.ZodObject<{
     bookmark: z.ZodString;
     docs: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        tags: z.ZodArray<z.ZodString, "many">;
+        tags: z.ZodArray<z.ZodString>;
         content: z.ZodString;
         name: z.ZodString;
         "deck-id": z.ZodString;
         fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        id: string;
-        content: string;
-        "deck-id": string;
-        tags: string[];
-        fields?: Record<string, unknown> | undefined;
-    }, {
-        name: string;
-        id: string;
-        content: string;
-        "deck-id": string;
-        tags: string[];
-        fields?: Record<string, unknown> | undefined;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    bookmark: string;
-    docs: {
-        name: string;
-        id: string;
-        content: string;
-        "deck-id": string;
-        tags: string[];
-        fields?: Record<string, unknown> | undefined;
-    }[];
-}, {
-    bookmark: string;
-    docs: {
-        name: string;
-        id: string;
-        content: string;
-        "deck-id": string;
-        tags: string[];
-        fields?: Record<string, unknown> | undefined;
-    }[];
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 type CreateCardResponse = z.infer<typeof CreateCardResponseSchema>;
 type ListDecksResponse = z.infer<typeof ListDecksResponseSchema>["docs"];
 type ListCardsResponse = z.infer<typeof ListCardsResponseSchema>;
@@ -273,35 +120,21 @@ declare const ListDecksResponseSchema: z.ZodObject<{
         id: z.ZodString;
         sort: z.ZodNumber;
         name: z.ZodString;
-        archived: z.ZodOptional<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
-        sort: number;
-        name: string;
-        id: string;
-        archived?: boolean | undefined;
-    }, {
-        sort: number;
-        name: string;
-        id: string;
-        archived?: boolean | undefined;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    bookmark: string;
-    docs: {
-        sort: number;
-        name: string;
-        id: string;
-        archived?: boolean | undefined;
-    }[];
-}, {
-    bookmark: string;
-    docs: {
-        sort: number;
-        name: string;
-        id: string;
-        archived?: boolean | undefined;
-    }[];
-}>;
+        "archived?": z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+        "trashed?": z.ZodNullable<z.ZodOptional<z.ZodObject<{
+            date: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const GetDueCardsResponseSchema: z.ZodObject<{
+    cards: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodString;
+        name: z.ZodString;
+        "deck-id": z.ZodString;
+        "new?": z.ZodBoolean;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
 export declare class MochiClient {
     private api;
     private token;
@@ -311,5 +144,12 @@ export declare class MochiClient {
     listDecks(params?: ListDecksParams): Promise<ListDecksResponse>;
     listCards(params?: ListCardsParams): Promise<ListCardsResponse>;
     listTemplates(params?: ListTemplatesParams): Promise<ListTemplatesResponse>;
+    getDueCards(params?: GetDueCardsParams): Promise<z.infer<typeof GetDueCardsResponseSchema>>;
+    getTemplate(templateId: string): Promise<z.infer<typeof TemplateSchema>>;
+    createCardFromTemplate(request: CreateCardFromTemplateParams): Promise<CreateCardResponse>;
+    addAttachment(request: AddAttachmentRequest): Promise<{
+        filename: string;
+        markdown: string;
+    }>;
 }
 export {};