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

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

@@ -98,6 +98,117 @@ declare const ListTemplatesParamsSchema: z.ZodObject<{
 }, {
     bookmark?: string | undefined;
 }>;
+declare const GetDueCardsParamsSchema: z.ZodObject<{
+    "deck-id": z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    date?: string | undefined;
+    "deck-id"?: string | undefined;
+}, {
+    date?: string | undefined;
+    "deck-id"?: string | undefined;
+}>;
+declare const CreateCardFromTemplateSchema: z.ZodObject<{
+    "template-id": z.ZodString;
+    "deck-id": z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    "manual-tags": z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    "deck-id": string;
+    "template-id": string;
+    fields: Record<string, string>;
+    "manual-tags"?: string[] | undefined;
+}, {
+    "deck-id": string;
+    "template-id": string;
+    fields: Record<string, string>;
+    "manual-tags"?: string[] | undefined;
+}>;
+declare const AddAttachmentSchema: z.ZodObject<{
+    "card-id": z.ZodString;
+    data: z.ZodString;
+    filename: z.ZodString;
+    "content-type": z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    data: string;
+    filename: string;
+    "card-id": string;
+    "content-type"?: string | undefined;
+}, {
+    data: string;
+    filename: string;
+    "card-id": string;
+    "content-type"?: string | undefined;
+}>;
+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>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        pos: string;
+        type?: string | null | undefined;
+        source?: string | null | undefined;
+        options?: z.objectOutputType<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        name: string;
+        id: string;
+        pos: string;
+        type?: string | null | undefined;
+        source?: string | null | undefined;
+        options?: z.objectInputType<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    content: string;
+    fields: Record<string, {
+        name: string;
+        id: string;
+        pos: string;
+        type?: string | null | undefined;
+        source?: string | null | undefined;
+        options?: z.objectOutputType<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    }>;
+    pos: string;
+}, {
+    name: string;
+    id: string;
+    content: string;
+    fields: Record<string, {
+        name: string;
+        id: string;
+        pos: string;
+        type?: string | null | undefined;
+        source?: string | null | undefined;
+        options?: z.objectInputType<{
+            "multi-line?": z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    }>;
+    pos: string;
+}>;
 declare const ListTemplatesResponseSchema: z.ZodObject<{
     bookmark: z.ZodString;
     docs: z.ZodArray<z.ZodObject<{
@@ -109,27 +220,33 @@ 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;
-            }>>;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough">>>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             id: string;
             pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
+            type?: string | null | undefined;
+            source?: string | null | undefined;
+            options?: z.objectOutputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
         }, {
             name: string;
             id: string;
             pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
+            type?: string | null | undefined;
+            source?: string | null | undefined;
+            options?: z.objectInputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         name: string;
@@ -139,9 +256,11 @@ declare const ListTemplatesResponseSchema: z.ZodObject<{
             name: string;
             id: string;
             pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
+            type?: string | null | undefined;
+            source?: string | null | undefined;
+            options?: z.objectOutputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
         }>;
         pos: string;
     }, {
@@ -152,9 +271,11 @@ declare const ListTemplatesResponseSchema: z.ZodObject<{
             name: string;
             id: string;
             pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
+            type?: string | null | undefined;
+            source?: string | null | undefined;
+            options?: z.objectInputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
         }>;
         pos: string;
     }>, "many">;
@@ -168,9 +289,11 @@ declare const ListTemplatesResponseSchema: z.ZodObject<{
             name: string;
             id: string;
             pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
+            type?: string | null | undefined;
+            source?: string | null | undefined;
+            options?: z.objectOutputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
         }>;
         pos: string;
     }[];
@@ -184,9 +307,11 @@ declare const ListTemplatesResponseSchema: z.ZodObject<{
             name: string;
             id: string;
             pos: string;
-            options?: {
-                "multi-line?"?: boolean | undefined;
-            } | undefined;
+            type?: string | null | undefined;
+            source?: string | null | undefined;
+            options?: z.objectInputType<{
+                "multi-line?": z.ZodOptional<z.ZodBoolean>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
         }>;
         pos: string;
     }[];
@@ -197,6 +322,8 @@ 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">;
@@ -273,17 +400,30 @@ declare const ListDecksResponseSchema: z.ZodObject<{
         id: z.ZodString;
         sort: z.ZodNumber;
         name: z.ZodString;
-        archived: z.ZodOptional<z.ZodBoolean>;
+        "archived?": z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+        "trashed?": z.ZodNullable<z.ZodOptional<z.ZodObject<{
+            date: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            date: string;
+        }, {
+            date: string;
+        }>>>;
     }, "strip", z.ZodTypeAny, {
         sort: number;
         name: string;
         id: string;
-        archived?: boolean | undefined;
+        "archived?"?: boolean | null | undefined;
+        "trashed?"?: {
+            date: string;
+        } | null | undefined;
     }, {
         sort: number;
         name: string;
         id: string;
-        archived?: boolean | undefined;
+        "archived?"?: boolean | null | undefined;
+        "trashed?"?: {
+            date: string;
+        } | null | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     bookmark: string;
@@ -291,7 +431,10 @@ declare const ListDecksResponseSchema: z.ZodObject<{
         sort: number;
         name: string;
         id: string;
-        archived?: boolean | undefined;
+        "archived?"?: boolean | null | undefined;
+        "trashed?"?: {
+            date: string;
+        } | null | undefined;
     }[];
 }, {
     bookmark: string;
@@ -299,9 +442,49 @@ declare const ListDecksResponseSchema: z.ZodObject<{
         sort: number;
         name: string;
         id: string;
-        archived?: boolean | undefined;
+        "archived?"?: boolean | null | undefined;
+        "trashed?"?: {
+            date: string;
+        } | null | undefined;
     }[];
 }>;
+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;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        content: z.ZodString;
+        name: z.ZodString;
+        "deck-id": z.ZodString;
+        "new?": z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        content: z.ZodString;
+        name: z.ZodString;
+        "deck-id": z.ZodString;
+        "new?": z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, "strip", z.ZodTypeAny, {
+    cards: z.objectOutputType<{
+        id: z.ZodString;
+        content: z.ZodString;
+        name: z.ZodString;
+        "deck-id": z.ZodString;
+        "new?": z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">[];
+}, {
+    cards: z.objectInputType<{
+        id: z.ZodString;
+        content: z.ZodString;
+        name: z.ZodString;
+        "deck-id": z.ZodString;
+        "new?": z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">[];
+}>;
 export declare class MochiClient {
     private api;
     private token;
@@ -311,5 +494,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 {};

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
+import FormData from "form-data";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import dotenv from "dotenv";
@@ -97,10 +98,60 @@ const ListTemplatesParamsSchema = z.object({
         .optional()
         .describe("Pagination bookmark for fetching next page of results"),
 });
+const GetDueCardsParamsSchema = z.object({
+    "deck-id": z
+        .string()
+        .optional()
+        .describe("Optional deck ID to filter due cards by a specific deck"),
+    date: z
+        .string()
+        .optional()
+        .describe("Optional ISO 8601 date to get cards due on that date. Defaults to today."),
+});
+const CreateCardFromTemplateSchema = z.object({
+    "template-id": z
+        .string()
+        .min(1)
+        .describe("ID of the template to use. Get this from mochi_list_templates."),
+    "deck-id": z
+        .string()
+        .min(1)
+        .describe("ID of the deck to create the card in. Get this from mochi_list_decks."),
+    fields: z
+        .record(z.string(), z.string())
+        .describe('Map of field NAMES (not IDs) to values. E.g., { "Word": "serendipity" } or { "Front": "Question?", "Back": "Answer" }'),
+    "manual-tags": z
+        .array(z.string())
+        .optional()
+        .describe("Optional array of tags to add to the card"),
+});
+// Schema for adding attachments
+const AddAttachmentSchema = z.object({
+    "card-id": z.string().min(1).describe("ID of the card to attach the file to"),
+    data: z.string().min(1).describe("Base64-encoded file data"),
+    filename: z
+        .string()
+        .min(1)
+        .describe("Filename with extension (e.g., 'image.png', 'audio.mp3')"),
+    "content-type": z
+        .string()
+        .optional()
+        .describe("MIME type of the file (e.g., 'image/png'). Can be inferred from filename if not provided."),
+});
 const TemplateFieldSchema = z.object({
     id: z.string().describe("Unique identifier for the template field"),
     name: z.string().describe("Display name of the field"),
     pos: z.string().describe("Position of the field in the template"),
+    type: z
+        .string()
+        .optional()
+        .nullable()
+        .describe("Field type: null/text for user input, or ai/speech/translate/dictionary for auto-generated"),
+    source: z
+        .string()
+        .optional()
+        .nullable()
+        .describe("Source field ID for auto-generated fields"),
     options: z
         .object({
         "multi-line?": z
@@ -108,6 +159,7 @@ const TemplateFieldSchema = z.object({
             .optional()
             .describe("Whether the field supports multiple lines of text"),
     })
+        .passthrough()
         .optional()
         .describe("Additional options for the field"),
 });
@@ -158,7 +210,16 @@ const DeckSchema = z
     id: z.string().describe("Unique identifier for the deck"),
     sort: z.number().describe("Sort order of the deck"),
     name: z.string().describe("Display name of the deck"),
-    archived: z.boolean().optional().describe("Whether the deck is archived"),
+    "archived?": z
+        .boolean()
+        .optional()
+        .nullable()
+        .describe("Whether the deck is archived"),
+    "trashed?": z
+        .object({ date: z.string() })
+        .optional()
+        .nullable()
+        .describe("Whether the deck is trashed"),
 })
     .strip();
 const ListDecksResponseSchema = z
@@ -167,6 +228,18 @@ const ListDecksResponseSchema = z
     docs: z.array(DeckSchema).describe("Array of decks"),
 })
     .strip();
+const DueCardSchema = z
+    .object({
+    id: z.string().describe("Unique identifier for the card"),
+    content: z.string().describe("Markdown content of the card"),
+    name: z.string().describe("Display name of the card"),
+    "deck-id": z.string().describe("ID of the deck containing the card"),
+    "new?": z.boolean().describe("Whether the card is new (never reviewed)"),
+})
+    .passthrough();
+const GetDueCardsResponseSchema = z.object({
+    cards: z.array(DueCardSchema).describe("Array of cards due for review"),
+});
 function getApiKey() {
     const apiKey = process.env.MOCHI_API_KEY;
     if (!apiKey) {
@@ -202,7 +275,7 @@ export class MochiClient {
             ? ListDecksParamsSchema.parse(params)
             : undefined;
         const response = await this.api.get("/decks", { params: validatedParams });
-        return ListDecksResponseSchema.parse(response.data).docs.filter((deck) => !deck.archived);
+        return ListDecksResponseSchema.parse(response.data).docs.filter((deck) => !deck["archived?"] && !deck["trashed?"]);
     }
     async listCards(params) {
         const validatedParams = params
@@ -220,6 +293,94 @@ export class MochiClient {
         });
         return ListTemplatesResponseSchema.parse(response.data);
     }
+    async getDueCards(params) {
+        const validatedParams = params
+            ? GetDueCardsParamsSchema.parse(params)
+            : undefined;
+        const deckId = validatedParams?.["deck-id"];
+        const endpoint = deckId ? `/due/${deckId}` : "/due";
+        const queryParams = validatedParams?.date
+            ? { date: validatedParams.date }
+            : undefined;
+        const response = await this.api.get(endpoint, { params: queryParams });
+        return GetDueCardsResponseSchema.parse(response.data);
+    }
+    async getTemplate(templateId) {
+        const response = await this.api.get(`/templates/${templateId}`);
+        return TemplateSchema.parse(response.data);
+    }
+    async createCardFromTemplate(request) {
+        // Fetch the template to get field definitions
+        const template = await this.getTemplate(request["template-id"]);
+        // Map field names to IDs
+        const fieldNameToId = {};
+        for (const [fieldId, field] of Object.entries(template.fields)) {
+            fieldNameToId[field.name] = fieldId;
+        }
+        // Build the fields object with IDs
+        const fields = {};
+        const fieldValues = [];
+        for (const [fieldName, value] of Object.entries(request.fields)) {
+            const fieldId = fieldNameToId[fieldName];
+            if (!fieldId) {
+                throw new MochiError([
+                    `Unknown field name: "${fieldName}". Available fields: ${Object.keys(fieldNameToId).join(", ")}`,
+                ], 400);
+            }
+            fields[fieldId] = { id: fieldId, value };
+            fieldValues.push(value);
+        }
+        // Build content from field values (joined with separator for multi-field templates)
+        const content = fieldValues.join("\n---\n");
+        const createRequest = {
+            content,
+            "deck-id": request["deck-id"],
+            "template-id": request["template-id"],
+            fields,
+            "manual-tags": request["manual-tags"],
+        };
+        return this.createCard(createRequest);
+    }
+    async addAttachment(request) {
+        // Infer content-type from filename if not provided
+        let contentType = request["content-type"];
+        if (!contentType) {
+            const ext = request.filename.split(".").pop()?.toLowerCase();
+            const mimeTypes = {
+                png: "image/png",
+                jpg: "image/jpeg",
+                jpeg: "image/jpeg",
+                gif: "image/gif",
+                webp: "image/webp",
+                svg: "image/svg+xml",
+                mp3: "audio/mpeg",
+                wav: "audio/wav",
+                ogg: "audio/ogg",
+                mp4: "video/mp4",
+                pdf: "application/pdf",
+            };
+            contentType = mimeTypes[ext ?? ""] ?? "application/octet-stream";
+        }
+        // Convert base64 to Buffer
+        const buffer = Buffer.from(request.data, "base64");
+        // Create form data
+        const formData = new FormData();
+        formData.append("file", buffer, {
+            filename: request.filename,
+            contentType,
+        });
+        // Upload attachment
+        await this.api.post(`/cards/${request["card-id"]}/attachments/${encodeURIComponent(request.filename)}`, formData, {
+            headers: {
+                ...formData.getHeaders(),
+                Authorization: `Basic ${Buffer.from(`${this.token}:`).toString("base64")}`,
+            },
+        });
+        return {
+            filename: request.filename,
+            markdown: `![](@media/${request.filename})`,
+        };
+    }
 }
 // Server setup
 const server = new Server({
@@ -236,7 +397,7 @@ const server = new Server({
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
-            name: "mochi_create_card",
+            name: "mochi_create_flashcard",
             description: `Create a new flashcard in Mochi. Use this whenever I ask questions about something that is interesting to remember. E.g. if I ask "What is the capital of France?", you should create a new flashcard with the content "What is the capital of France?\n---\nParis".
 
 ## Parameters
@@ -248,7 +409,7 @@ ALWAYS look up deck-id with the mochi_list_decks tool.
 The markdown content of the card. Separate front and back using a horizontal rule (---).
 
 ### template-id (optional)
-When using a template, the field ids MUST match the template ones. If not using a template, omit this field.
+When using a template, the field ids MUST match the template ones. If not using a template, omit this field. Consider using mochi_create_card_from_template instead for easier template-based card creation.
 
 ### fields (optional)
 A map of field IDs (keyword) to field values. Only required when using a template. The field IDs must correspond to the fields defined on the template.
@@ -293,7 +454,57 @@ A map of field IDs (keyword) to field values. Only required when using a templat
             },
         },
         {
-            name: "mochi_update_card",
+            name: "mochi_create_card_from_template",
+            description: `Create a flashcard using a template with field names (not IDs). This is the preferred way to create template-based cards.
+
+The MCP automatically:
+1. Fetches the template to get field definitions
+2. Maps provided field names to their IDs
+3. Builds the fields object in the format Mochi expects
+
+## Parameters
+
+### template-id (required)
+The ID of the template to use. Get available templates with mochi_list_templates.
+
+### deck-id (required)
+The ID of the deck to create the card in. Get available decks with mochi_list_decks.
+
+### fields (required)
+A map of field **names** (not IDs) to their values. The MCP will map names to IDs automatically.
+
+### manual-tags (optional)
+Array of tags to add to the card.
+
+## Example: "Word" template (single field)
+{
+  "template-id": "mzROLUuD",
+  "deck-id": "HGOW9dWP",
+  "fields": {
+    "Word": "serendipity"
+  }
+}
+
+## Example: "Basic Flashcard" template (front/back)
+{
+  "template-id": "Jyv52qHg",
+  "deck-id": "jJAIs2ZZ",
+  "fields": {
+    "Front": "What is the capital of France?",
+    "Back": "Paris"
+  }
+}`,
+            inputSchema: zodToJsonSchema(CreateCardFromTemplateSchema),
+            annotations: {
+                title: "Create flashcard from template on Mochi",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        },
+        {
+            name: "mochi_update_flashcard",
             description: `Update or delete an existing flashcard in Mochi. To delete set trashed to true.`,
             inputSchema: zodToJsonSchema(z.object({
                 "card-id": z.string(),
@@ -308,8 +519,42 @@ A map of field IDs (keyword) to field values. Only required when using a templat
             },
         },
         {
-            name: "mochi_list_cards",
-            description: "List cards in pages of 10 cards per page",
+            name: "mochi_add_attachment",
+            description: `Add an attachment (image, audio, etc.) to a card using base64 data.
+
+Use this when you have base64-encoded file data (e.g., from images inserted in chat).
+
+## Parameters
+
+### card-id (required)
+The ID of the card to attach the file to.
+
+### data (required)
+Base64-encoded file data.
+
+### filename (required)
+Filename with extension (e.g., "image.png", "audio.mp3").
+
+### content-type (optional)
+MIME type (e.g., "image/png"). Can be inferred from filename.
+
+## Returns
+The markdown reference to use in card content: \`![](@media/filename)\`
+
+## Note
+For URL-based images, just use markdown directly in card content: \`![description](https://example.com/image.png)\` - no attachment upload needed.`,
+            inputSchema: zodToJsonSchema(AddAttachmentSchema),
+            annotations: {
+                title: "Add attachment to flashcard on Mochi",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        },
+        {
+            name: "mochi_list_flashcards",
+            description: "List flashcards in pages of 10 cards per page",
             inputSchema: zodToJsonSchema(ListCardsParamsSchema),
             annotations: {
                 title: "List flashcards on Mochi",
@@ -333,7 +578,9 @@ A map of field IDs (keyword) to field values. Only required when using a templat
         },
         {
             name: "mochi_list_templates",
-            description: `Templates can be used to create cards with pre-defined fields using the template_id field. 
+            description: `List all templates. Templates can be used to create cards with pre-defined fields.
+
+Use mochi_create_card_from_template for easy template-based card creation with field names instead of IDs.
 
 Example response:
 {
@@ -372,6 +619,26 @@ Example response:
                 openWorldHint: false,
             },
         },
+        {
+            name: "mochi_get_due_cards",
+            description: `Get flashcards that are due for review. Returns cards scheduled for review on the specified date (defaults to today).
+
+## Parameters
+
+### deck-id (optional)
+Filter to only show due cards from a specific deck.
+
+### date (optional)
+ISO 8601 date string (e.g., "2026-01-11T00:00:00.000Z") to get cards due on that date. Defaults to today.`,
+            inputSchema: zodToJsonSchema(GetDueCardsParamsSchema),
+            annotations: {
+                title: "Get due flashcards on Mochi",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        },
     ],
 }));
 // Create Mochi client
@@ -408,7 +675,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
                         text: JSON.stringify(decks.map((deck) => ({
                             id: deck.id,
                             name: deck.name,
-                            archived: deck.archived,
+                            archived: deck["archived?"],
                         })), null, 2),
                     },
                 ],
@@ -477,7 +744,7 @@ Input: ${input}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (request.params.name) {
-            case "mochi_create_card": {
+            case "mochi_create_flashcard": {
                 const validatedArgs = CreateCardRequestSchema.parse(request.params.arguments);
                 const response = await mochiClient.createCard(validatedArgs);
                 return {
@@ -490,7 +757,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: false,
                 };
             }
-            case "mochi_update_card": {
+            case "mochi_create_card_from_template": {
+                const validatedArgs = CreateCardFromTemplateSchema.parse(request.params.arguments);
+                const response = await mochiClient.createCardFromTemplate(validatedArgs);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(response, null, 2),
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            case "mochi_update_flashcard": {
                 const { "card-id": cardId, ...updateArgs } = z
                     .object({
                     "card-id": z.string(),
@@ -508,6 +788,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: false,
                 };
             }
+            case "mochi_add_attachment": {
+                const validatedArgs = AddAttachmentSchema.parse(request.params.arguments);
+                const response = await mochiClient.addAttachment(validatedArgs);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(response, null, 2),
+                        },
+                    ],
+                    isError: false,
+                };
+            }
             case "mochi_list_decks": {
                 const validatedArgs = ListDecksParamsSchema.parse(request.params.arguments);
                 const response = await mochiClient.listDecks(validatedArgs);
@@ -521,7 +814,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: false,
                 };
             }
-            case "mochi_list_cards": {
+            case "mochi_list_flashcards": {
                 const validatedArgs = ListCardsParamsSchema.parse(request.params.arguments);
                 const response = await mochiClient.listCards(validatedArgs);
                 return {
@@ -547,6 +840,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: false,
                 };
             }
+            case "mochi_get_due_cards": {
+                const validatedArgs = GetDueCardsParamsSchema.parse(request.params.arguments);
+                const response = await mochiClient.getDueCards(validatedArgs);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(response, null, 2),
+                        },
+                    ],
+                    isError: false,
+                };
+            }
             default:
                 return {
                     content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fredrika/mcp-mochi",
-  "version": "1.0.5",
+  "version": "1.0.6-beta.0",
   "description": "MCP server for Mochi flashcard integration",
   "main": "dist/index.js",
   "type": "module",
@@ -32,6 +32,7 @@
     "@modelcontextprotocol/sdk": "^1.9.0",
     "axios": "^1.6.7",
     "dotenv": "^16.4.5",
+    "form-data": "^4.0.5",
     "zod": "^3.22.4"
   },
   "devDependencies": {