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

package/README.md

@@ -1,6 +1,6 @@
 # Mochi MCP Server
 
-This MCP server provides integration with the Mochi flashcard system, allowing you to manage your flashcards through the Model Context Protocol.
+MCP server for [Mochi](https://mochi.cards) flashcard integration, allowing you to manage your flashcards through the Model Context Protocol.
 
 ## Features
 
@@ -67,51 +67,32 @@ Add the following to your `claude_desktop_config.json`:
 
 ## Available Tools
 
-### `mochi_create_flashcard`
-Create a new flashcard in Mochi.
-- `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.
-- `bookmark`: (optional) Pagination token
-
-### `mochi_list_templates`
-List all templates with their field definitions.
-- `bookmark`: (optional) Pagination token
-
-### `mochi_get_due_cards`
-Get flashcards due for review.
-- `deck-id`: (optional) Filter by deck
-- `date`: (optional) ISO 8601 date (defaults to today)
+| Tool | Description |
+|------|-------------|
+| `mochi_create_flashcard` | Create a new flashcard in Mochi |
+| `mochi_create_card_from_template` | Create a flashcard using a template with field names (auto-maps to IDs) |
+| `mochi_update_flashcard` | Update a flashcard's content, deck, template, or fields. Can also soft-delete with `trashed` property |
+| `mochi_delete_flashcard` | Permanently delete a flashcard and its attachments (cannot be undone) |
+| `mochi_archive_flashcard` | Archive or unarchive a flashcard |
+| `mochi_add_attachment` | Add an attachment (image, audio, etc.) to a card using base64 data |
+| `mochi_list_flashcards` | List flashcards, optionally filtered by deck |
+| `mochi_list_decks` | List all decks |
+| `mochi_list_templates` | List all templates with their field definitions |
+| `mochi_get_template` | Get a single template by ID |
+| `mochi_get_due_cards` | Get flashcards due for review |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `mochi://decks` | List of all decks |
+| `mochi://templates` | List of all templates |
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `write-flashcard` | Generates a well-structured flashcard following best practices (atomic questions, cloze deletions, etc.) |
 
 ## Examples
 
@@ -122,7 +103,7 @@ Get flashcards due for review.
   "tool": "mochi_create_flashcard",
   "params": {
     "content": "What is MCP?\n---\nModel Context Protocol - a protocol for providing context to LLMs",
-    "deck-id": "<DECK_ID>"
+    "deckId": "<DECK_ID>"
   }
 }
 ```
@@ -133,8 +114,8 @@ Get flashcards due for review.
 {
   "tool": "mochi_create_card_from_template",
   "params": {
-    "template-id": "<TEMPLATE_ID>",
-    "deck-id": "<DECK_ID>",
+    "templateId": "<TEMPLATE_ID>",
+    "deckId": "<DECK_ID>",
     "fields": {
       "Front": "What is the capital of France?",
       "Back": "Paris"

package/dist/index.d.ts

@@ -112,7 +112,7 @@ declare const ListCardsResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 type CreateCardResponse = z.infer<typeof CreateCardResponseSchema>;
-type ListDecksResponse = z.infer<typeof ListDecksResponseSchema>["docs"];
+type ListDecksResponse = z.infer<typeof ListDecksResponseSchema>;
 type ListCardsResponse = z.infer<typeof ListCardsResponseSchema>;
 declare const ListDecksResponseSchema: z.ZodObject<{
     bookmark: z.ZodString;
@@ -120,6 +120,7 @@ declare const ListDecksResponseSchema: z.ZodObject<{
         id: z.ZodString;
         sort: z.ZodNumber;
         name: z.ZodString;
+        "template-id": z.ZodNullable<z.ZodOptional<z.ZodString>>;
         "archived?": z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
         "trashed?": z.ZodNullable<z.ZodOptional<z.ZodObject<{
             date: z.ZodString;
@@ -132,7 +133,7 @@ declare const GetDueCardsResponseSchema: z.ZodObject<{
         content: z.ZodString;
         name: z.ZodString;
         "deck-id": z.ZodString;
-        "new?": z.ZodBoolean;
+        "new?": z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 }, z.core.$strip>;
 export declare class MochiClient {
@@ -147,6 +148,7 @@ export declare class MochiClient {
     getDueCards(params?: GetDueCardsParams): Promise<z.infer<typeof GetDueCardsResponseSchema>>;
     getTemplate(templateId: string): Promise<z.infer<typeof TemplateSchema>>;
     createCardFromTemplate(request: CreateCardFromTemplateParams): Promise<CreateCardResponse>;
+    deleteCard(cardId: string): Promise<void>;
     addAttachment(request: AddAttachmentRequest): Promise<{
         filename: string;
         markdown: string;

package/dist/index.js

@@ -90,6 +90,9 @@ const ListTemplatesParamsSchema = z.object({
         .optional()
         .describe("Pagination bookmark for fetching next page of results"),
 });
+const GetTemplateParamsSchema = z.object({
+    templateId: z.string().min(1).describe("ID of the template to fetch"),
+});
 const GetDueCardsParamsSchema = z.object({
     deckId: z
         .string()
@@ -239,6 +242,11 @@ 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"),
+    "template-id": z
+        .string()
+        .optional()
+        .nullable()
+        .describe("Template ID associated with this deck, if any"),
     "archived?": z
         .boolean()
         .optional()
@@ -248,7 +256,7 @@ const DeckSchema = z
         .object({ date: z.string() })
         .optional()
         .nullable()
-        .describe("Whether the deck is trashed"),
+        .describe("Timestamp when the deck was trashed, in ISO 8601 format (matching JavaScript's Date#toJSON)"),
 })
     .strip();
 const ListDecksResponseSchema = z
@@ -263,7 +271,10 @@ const DueCardSchema = z
     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)"),
+    "new?": z
+        .boolean()
+        .optional()
+        .describe("Whether the card is new (never reviewed)"),
 })
     .passthrough();
 const GetDueCardsResponseSchema = z.object({
@@ -306,9 +317,13 @@ 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?"] && !deck["trashed?"])
-            .sort((a, b) => a.sort - b.sort);
+        const parsed = ListDecksResponseSchema.parse(response.data);
+        return {
+            bookmark: parsed.bookmark,
+            docs: parsed.docs
+                .filter((deck) => !deck["archived?"] && !deck["trashed?"])
+                .sort((a, b) => a.sort - b.sort),
+        };
     }
     async listCards(params) {
         const validatedParams = params
@@ -377,6 +392,9 @@ export class MochiClient {
         };
         return this.createCard(createRequest);
     }
+    async deleteCard(cardId) {
+        await this.api.delete(`/cards/${cardId}`);
+    }
     async addAttachment(request) {
         // Infer content-type from filename if not provided
         let contentType = request.contentType;
@@ -426,7 +444,34 @@ const server = new McpServer({
 // Schema for update flashcard tool (combines cardId with update fields)
 const UpdateFlashcardToolSchema = z.object({
     cardId: z.string().describe("ID of the card to update"),
-    ...UpdateCardRequestSchema.shape,
+    content: z
+        .string()
+        .optional()
+        .describe("Updated markdown content of the card"),
+    deckId: z.string().optional().describe("ID of the deck to move the card to"),
+    templateId: z.string().optional().describe("Template ID to use for the card"),
+    fields: z
+        .record(z.string(), CreateCardFieldSchema)
+        .optional()
+        .describe("Updated map of field IDs to field values"),
+    trashed: z
+        .boolean()
+        .optional()
+        .describe("Set to true to soft-delete (move to trash). This can be undone by setting to false."),
+});
+// Schema for delete flashcard tool
+const DeleteFlashcardToolSchema = z.object({
+    cardId: z
+        .string()
+        .describe("ID of the card to permanently delete. This cannot be undone."),
+});
+// Schema for archive flashcard tool
+const ArchiveFlashcardToolSchema = z.object({
+    cardId: z.string().describe("ID of the card to archive"),
+    archived: z
+        .boolean()
+        .default(true)
+        .describe("Set to true to archive, false to unarchive"),
 });
 // Output schema for attachment response
 const AddAttachmentResponseSchema = z.object({
@@ -482,7 +527,7 @@ function formatToolError(error) {
 // Note: Using type assertions due to Zod version compatibility between SDK (v4) and project (v3)
 server.registerTool("mochi_create_flashcard", {
     title: "Create flashcard on Mochi",
-    description: "Create a new flashcard in Mochi. Look up deckId with mochi_list_decks first. For template-based cards, prefer mochi_create_card_from_template.",
+    description: "Create a new flashcard in Mochi. Look up deckId with mochi_list_decks first. Use mochi_create_card_from_template if the deck has a template-id defined.",
     inputSchema: CreateCardRequestSchema,
     outputSchema: CreateCardResponseSchema,
     annotations: {
@@ -505,7 +550,7 @@ server.registerTool("mochi_create_flashcard", {
 });
 server.registerTool("mochi_create_card_from_template", {
     title: "Create flashcard from template on Mochi",
-    description: "Create a flashcard using a template with field names (not IDs). Preferred way to create template-based cards. Automatically maps field names to IDs. Get templates with mochi_list_templates, decks with mochi_list_decks.",
+    description: "Create a flashcard using a template with field names (not IDs). Automatically maps field names to IDs. Get templates with mochi_list_templates, decks with mochi_list_decks.",
     inputSchema: CreateCardFromTemplateSchema,
     outputSchema: CreateCardResponseSchema,
     annotations: {
@@ -528,7 +573,7 @@ server.registerTool("mochi_create_card_from_template", {
 });
 server.registerTool("mochi_update_flashcard", {
     title: "Update flashcard on Mochi",
-    description: "Update or delete an existing flashcard. Set trashed to true to delete.",
+    description: "Update an existing flashcard's content, deck, template, or fields. Use mochi_delete_flashcard to delete or mochi_archive_flashcard to archive.",
     inputSchema: UpdateFlashcardToolSchema,
     outputSchema: UpdateCardResponseSchema,
     annotations: {
@@ -550,6 +595,62 @@ server.registerTool("mochi_update_flashcard", {
         return formatToolError(error);
     }
 });
+// Output schema for delete response
+const DeleteFlashcardResponseSchema = z
+    .object({
+    success: z.boolean().describe("Whether the deletion was successful"),
+    cardId: z.string().describe("ID of the deleted card"),
+})
+    .strict();
+server.registerTool("mochi_delete_flashcard", {
+    title: "Delete flashcard on Mochi",
+    description: "Permanently delete a flashcard and its attachments. WARNING: This cannot be undone. For soft deletion, use mochi_update_flashcard with trashed: true.",
+    inputSchema: DeleteFlashcardToolSchema,
+    outputSchema: DeleteFlashcardResponseSchema,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (args) => {
+    try {
+        await mochiClient.deleteCard(args.cardId);
+        const response = { success: true, cardId: args.cardId };
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+            structuredContent: response,
+        };
+    }
+    catch (error) {
+        return formatToolError(error);
+    }
+});
+server.registerTool("mochi_archive_flashcard", {
+    title: "Archive flashcard on Mochi",
+    description: "Archive or unarchive a flashcard. Archived cards are hidden from review but not deleted.",
+    inputSchema: ArchiveFlashcardToolSchema,
+    outputSchema: UpdateCardResponseSchema,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (args) => {
+    try {
+        const response = await mochiClient.updateCard(args.cardId, {
+            archived: args.archived,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+            structuredContent: response,
+        };
+    }
+    catch (error) {
+        return formatToolError(error);
+    }
+});
 server.registerTool("mochi_add_attachment", {
     title: "Add attachment to flashcard on Mochi",
     description: "Add an attachment (image, audio, etc.) to a card using base64 data. For URL-based images, just use markdown directly in card content instead.",
@@ -612,7 +713,7 @@ server.registerTool("mochi_list_decks", {
         const response = await mochiClient.listDecks(args);
         return {
             content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
-            structuredContent: { bookmark: "", docs: response },
+            structuredContent: response,
         };
     }
     catch (error) {
@@ -642,6 +743,29 @@ server.registerTool("mochi_list_templates", {
         return formatToolError(error);
     }
 });
+server.registerTool("mochi_get_template", {
+    title: "Get template by ID on Mochi",
+    description: "Get a single template by its ID. Use to see template fields and structure.",
+    inputSchema: GetTemplateParamsSchema.shape,
+    outputSchema: TemplateSchema,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async (args) => {
+    try {
+        const response = await mochiClient.getTemplate(args.templateId);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+            structuredContent: response,
+        };
+    }
+    catch (error) {
+        return formatToolError(error);
+    }
+});
 server.registerTool("mochi_get_due_cards", {
     title: "Get due flashcards on Mochi",
     description: "Get flashcards due for review on a specific date (defaults to today).",
@@ -670,13 +794,13 @@ server.registerResource("decks", "mochi://decks", {
     description: "List of all decks in Mochi.",
     mimeType: "application/json",
 }, async () => {
-    const decks = await mochiClient.listDecks();
+    const response = await mochiClient.listDecks();
     return {
         contents: [
             {
                 uri: "mochi://decks",
                 mimeType: "application/json",
-                text: JSON.stringify(decks.map((deck) => ({ id: deck.id, name: deck.name })), null, 2),
+                text: JSON.stringify(response.docs.map((deck) => ({ id: deck.id, name: deck.name })), null, 2),
             },
         ],
     };
@@ -716,6 +840,7 @@ server.registerPrompt("write-flashcard", {
 - Utilize cloze prompts when applicable, like "This is a text with {{hidden}} part. Then don't use '---' separator.".
 - Focus on effective retrieval practice by being concise and clear.
 - Make it just challenging enough to reinforce specific facts.
+- Only use mochi_create_card_from_template if the deck has a template-id defined. Otherwise use mochi_create_flashcard.
 Input: ${input}
 `,
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fredrika/mcp-mochi",
-  "version": "1.0.6-beta.1",
+  "version": "2.0.0",
   "description": "MCP server for Mochi flashcard integration",
   "main": "dist/index.js",
   "type": "module",