@fredrika/mcp-mochi 1.0.6-beta.1 → 2.1.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

@@ -5,10 +5,6 @@ declare const CreateCardRequestSchema: z.ZodObject<{
     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;
-    }, z.core.$strip>>>;
 }, z.core.$strip>;
 declare const UpdateCardRequestSchema: z.ZodObject<{
     content: z.ZodOptional<z.ZodString>;
@@ -112,7 +108,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 +116,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 +129,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 +144,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

@@ -34,7 +34,7 @@ const CreateCardRequestSchema = z.object({
     content: z
         .string()
         .min(1)
-        .describe("Markdown content of the card. Separate front and back using a horizontal rule (---) or use brackets for {{cloze deletion}}."),
+        .describe("Markdown content of the card. Separate the question and answer with a horizontal rule surrounded by newlines: '\\n---\\n'"),
     deckId: z.string().min(1).describe("ID of the deck to create the card in"),
     templateId: z
         .string()
@@ -46,10 +46,6 @@ const CreateCardRequestSchema = z.object({
         .array(z.string())
         .optional()
         .describe("Optional array of tags to add to the card"),
-    fields: z
-        .record(z.string(), CreateCardFieldSchema)
-        .optional()
-        .describe("Map of field IDs to field values. Required only when using a template"),
 });
 const UpdateCardRequestSchema = z.object({
     content: z
@@ -90,6 +86,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()
@@ -104,14 +103,14 @@ const CreateCardFromTemplateSchema = z.object({
     templateId: z
         .string()
         .min(1)
-        .describe("ID of the template to use. Get this from mochi_list_templates."),
+        .describe("ID of the template to use. Get this from list_templates."),
     deckId: z
         .string()
         .min(1)
-        .describe("ID of the deck to create the card in. Get this from mochi_list_decks."),
+        .describe("ID of the deck to create the card in. Get this from 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" }'),
+        .describe('Map of field NAMES (not IDs) to values. E.g., { "Word": "serendipity" }'),
     tags: z
         .array(z.string())
         .optional()
@@ -217,7 +216,7 @@ const CardSchema = z
         .describe("Array of tags associated with the card"),
     content: z
         .string()
-        .describe('Markdown content of the card. Separate front and back of card with "---"'),
+        .describe('Markdown content of the card. Separate the question and answer with "---"'),
     name: z.string().describe("Display name of the card"),
     "deck-id": z.string().describe("ID of the deck containing the card"),
     fields: z
@@ -239,6 +238,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 +252,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,21 +267,24 @@ 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({
     cards: z.array(DueCardSchema).describe("Array of cards due for review"),
 });
 function getApiKey() {
-    const apiKey = process.env.MOCHI_API_KEY;
+    const apiKey = process.env.API_KEY;
     if (!apiKey) {
-        console.error("MOCHI_API_KEY environment variable is not set");
+        console.error("API_KEY environment variable is not set");
         process.exit(1);
     }
     return apiKey;
 }
-const MOCHI_API_KEY = getApiKey();
+const API_KEY = getApiKey();
 export class MochiClient {
     api;
     token;
@@ -290,6 +297,24 @@ export class MochiClient {
                 "Content-Type": "application/json",
             },
         });
+        // Add response interceptor for error handling
+        this.api.interceptors.response.use((response) => response, (error) => {
+            if (axios.isAxiosError(error) && error.response) {
+                const { status, data } = error.response;
+                // Mochi API returns errors as arrays or objects
+                if (data && (Array.isArray(data) || typeof data === "object")) {
+                    throw new MochiError(data, status);
+                }
+                // Fallback for string error messages
+                if (typeof data === "string" && data.length > 0) {
+                    throw new MochiError([data], status);
+                }
+                // Generic error with status
+                throw new MochiError([`Request failed with status ${status}`], status);
+            }
+            // Re-throw non-axios errors
+            throw error;
+        });
     }
     async createCard(request) {
         const mochiRequest = toMochiCreateCardRequest(request);
@@ -306,9 +331,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
@@ -372,11 +401,13 @@ export class MochiClient {
             content,
             deckId: request.deckId,
             templateId: request.templateId,
-            fields,
             tags: request.tags,
         };
         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 +457,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({
@@ -436,7 +494,7 @@ const AddAttachmentResponseSchema = z.object({
         .describe("Markdown reference to use in card content, e.g. ![](@media/filename)"),
 });
 // Create Mochi client
-const mochiClient = new MochiClient(MOCHI_API_KEY);
+const mochiClient = new MochiClient(API_KEY);
 // Helper to format errors for tool responses
 function formatToolError(error) {
     if (error instanceof z.ZodError) {
@@ -480,9 +538,9 @@ function formatToolError(error) {
 }
 // Register tools
 // Note: Using type assertions due to Zod version compatibility between SDK (v4) and project (v3)
-server.registerTool("mochi_create_flashcard", {
+server.registerTool("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 list_decks first. Use create_card_from_template if the deck has a template-id defined.",
     inputSchema: CreateCardRequestSchema,
     outputSchema: CreateCardResponseSchema,
     annotations: {
@@ -503,9 +561,9 @@ server.registerTool("mochi_create_flashcard", {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_create_card_from_template", {
+server.registerTool("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 list_templates, decks with list_decks.",
     inputSchema: CreateCardFromTemplateSchema,
     outputSchema: CreateCardResponseSchema,
     annotations: {
@@ -526,9 +584,9 @@ server.registerTool("mochi_create_card_from_template", {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_update_flashcard", {
+server.registerTool("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 delete_flashcard to delete or archive_flashcard to archive.",
     inputSchema: UpdateFlashcardToolSchema,
     outputSchema: UpdateCardResponseSchema,
     annotations: {
@@ -550,7 +608,63 @@ server.registerTool("mochi_update_flashcard", {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_add_attachment", {
+// 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("delete_flashcard", {
+    title: "Delete flashcard on Mochi",
+    description: "Permanently delete a flashcard and its attachments. WARNING: This cannot be undone. For soft deletion, use 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("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("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.",
     inputSchema: AddAttachmentSchema,
@@ -573,7 +687,7 @@ server.registerTool("mochi_add_attachment", {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_list_flashcards", {
+server.registerTool("list_flashcards", {
     title: "List flashcards on Mochi",
     description: "List flashcards, optionally filtered by deck. Returns paginated results.",
     inputSchema: ListCardsParamsSchema.shape,
@@ -596,7 +710,7 @@ server.registerTool("mochi_list_flashcards", {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_list_decks", {
+server.registerTool("list_decks", {
     title: "List decks on Mochi",
     description: "List all decks. Use to get deckId for other operations.",
     inputSchema: ListDecksParamsSchema.shape,
@@ -612,16 +726,16 @@ 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) {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_list_templates", {
+server.registerTool("list_templates", {
     title: "List templates on Mochi",
-    description: "List all templates. Use with mochi_create_card_from_template for easy template-based card creation.",
+    description: "List all templates. Use with create_card_from_template for easy template-based card creation.",
     inputSchema: ListTemplatesParamsSchema.shape,
     outputSchema: ListTemplatesResponseSchema,
     annotations: {
@@ -642,7 +756,30 @@ server.registerTool("mochi_list_templates", {
         return formatToolError(error);
     }
 });
-server.registerTool("mochi_get_due_cards", {
+server.registerTool("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("get_due_cards", {
     title: "Get due flashcards on Mochi",
     description: "Get flashcards due for review on a specific date (defaults to today).",
     inputSchema: GetDueCardsParamsSchema.shape,
@@ -670,13 +807,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 +853,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 create_card_from_template if the deck has a template-id defined. Otherwise use create_flashcard.
 Input: ${input}
 `,
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fredrika/mcp-mochi",
-  "version": "1.0.6-beta.1",
+  "version": "2.1.0",
   "description": "MCP server for Mochi flashcard integration",
   "main": "dist/index.js",
   "type": "module",
@@ -17,7 +17,9 @@
     "dev": "ts-node-esm src/index.ts",
     "dev:inspect": "npx @modelcontextprotocol/inspector ts-node-esm src/index.ts",
     "test": "jest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "version:minor": "npm version minor",
+    "release:minor": "npm run version:minor && npm publish"
   },
   "keywords": [
     "mcp",
@@ -28,6 +30,9 @@
   ],
   "author": "",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
     "axios": "^1.6.7",