@fredrika/mcp-mochi 1.0.2 → 1.0.3

package/README.md

@@ -1,14 +1,11 @@
 # Mochi MCP Server
 
-This MCP server provides integration with the Mochi flashcard system, allowing you to manage and review your flashcards through the Model Context Protocol.
+This MCP server provides integration with the Mochi flashcard system, allowing you to manage your flashcards through the Model Context Protocol.
 
 ## Features
 
 - Create, update, and delete flashcards
-- Get flashcards due for review
-- Review flashcards and track progress
-- View study statistics
-- Tag-based organization
+- List flashcards, decks, and templates
 
 ## Setup
 
@@ -33,40 +30,38 @@ This MCP server provides integration with the Mochi flashcard system, allowing y
 
 ## Available Tools
 
-### `createFlashcard`
-Create a new flashcard.
+### `mochi_create_card`
+Create a new flashcard in Mochi.
 - Parameters:
-  - `front`: string (front side content)
-  - `back`: string (back side content)
-  - `tags`: string[] (optional tags)
-
-### `updateFlashcard`
-Update an existing flashcard.
+  - `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:
-  - `id`: string (flashcard ID)
-  - `front`: string (optional)
-  - `back`: string (optional)
-  - `tags`: string[] (optional)
+  - `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)
 
-### `deleteFlashcard`
-Delete a flashcard.
+### `mochi_list_cards`
+List cards (paginated).
 - Parameters:
-  - `id`: string (flashcard ID)
-
-### `getDueFlashcards`
-Get a list of flashcards that are due for review.
-- No parameters required
+  - `deck-id`: string (optional, filter by deck)
+  - `limit`: number (optional, 1-100)
+  - `bookmark`: string (optional, for pagination)
 
-### `reviewFlashcard`
-Submit a review for a flashcard.
+### `mochi_list_decks`
+List all decks.
 - Parameters:
-  - `id`: string (flashcard ID)
-  - `success`: boolean (whether the review was successful)
-  - `timeSpentMs`: number (time spent reviewing in milliseconds)
+  - `bookmark`: string (optional, for pagination)
 
-### `getStats`
-Get study statistics.
-- No parameters required
+### `mochi_list_templates`
+List all templates.
+- Parameters:
+  - `bookmark`: string (optional, for pagination)
 
 ## Example Usage
 
@@ -85,29 +80,34 @@ Here's how to use the MCP server with the MCP Inspector:
 3. Create a new flashcard:
    ```json
    {
-     "tool": "createFlashcard",
+     "tool": "mochi_create_card",
      "params": {
-       "front": "What is MCP?",
-       "back": "Model Context Protocol - a protocol for providing context to LLMs",
-       "tags": ["tech", "protocols"]
+       "content": "What is MCP?\n---\nModel Context Protocol - a protocol for providing context to LLMs",
+       "deck-id": "<YOUR_DECK_ID>"
      }
    }
    ```
 
-4. Get flashcards due for review:
+4. List all decks:
    ```json
    {
-     "tool": "getDueFlashcards"
+     "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"
+     }
+   }
+   ```
 
-## Setup
-
-### Personal Access Token
-TODO
-
-### Usage with Claude Desktop
+## Usage with Claude Desktop
 To use this with Claude Desktop, add the following to your `claude_desktop_config.json`:
 
 #### Docker

package/dist/index.d.ts

@@ -3,9 +3,9 @@ import { z } from "zod";
 declare const CreateCardRequestSchema: z.ZodObject<{
     content: z.ZodString;
     "deck-id": z.ZodString;
-    "template-id": z.ZodOptional<z.ZodString>;
+    "template-id": z.ZodDefault<z.ZodNullable<z.ZodOptional<z.ZodString>>>;
     "manual-tags": z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         id: z.ZodString;
         value: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -14,25 +14,25 @@ declare const CreateCardRequestSchema: z.ZodObject<{
     }, {
         id: string;
         value: string;
-    }>>;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     content: string;
     "deck-id": string;
-    fields: Record<string, {
+    "template-id": string | null;
+    "manual-tags"?: string[] | undefined;
+    fields?: Record<string, {
         id: string;
         value: string;
-    }>;
-    "template-id"?: string | undefined;
-    "manual-tags"?: string[] | undefined;
+    }> | undefined;
 }, {
     content: string;
     "deck-id": string;
-    fields: Record<string, {
+    "template-id"?: string | null | undefined;
+    "manual-tags"?: string[] | undefined;
+    fields?: Record<string, {
         id: string;
         value: string;
-    }>;
-    "template-id"?: string | undefined;
-    "manual-tags"?: string[] | undefined;
+    }> | undefined;
 }>;
 declare const UpdateCardRequestSchema: z.ZodObject<{
     content: z.ZodOptional<z.ZodString>;

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -28,90 +28,143 @@ class MochiError extends Error {
 }
 // Zod schemas for request validation
 const CreateCardFieldSchema = z.object({
-    id: z.string(),
-    value: z.string(),
+    id: z.string().describe("Unique identifier for the field"),
+    value: z.string().describe("Value of the field"),
 });
 const CreateCardRequestSchema = z.object({
-    content: z.string().min(1),
-    "deck-id": z.string().min(1),
-    "template-id": z.string().optional(),
-    "manual-tags": z.array(z.string()).optional(),
-    fields: z.record(z.string(), CreateCardFieldSchema),
+    content: z
+        .string()
+        .min(1)
+        .describe("Markdown content of the card. Separate front and back using a horizontal rule (---)"),
+    "deck-id": z.string().min(1).describe("ID of the deck to create the card in"),
+    "template-id": z
+        .string()
+        .optional()
+        .nullable()
+        .default(null)
+        .describe("Optional template ID to use for the card. Defaults to null if not set."),
+    "manual-tags": z
+        .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.string().optional(),
-    "deck-id": z.string().optional(),
-    "template-id": z.string().optional(),
-    "archived?": z.boolean().optional(),
-    "trashed?": z.string().optional(),
-    fields: z.record(z.string(), CreateCardFieldSchema).optional(),
+    content: z
+        .string()
+        .optional()
+        .describe("Updated markdown content of the card"),
+    "deck-id": z
+        .string()
+        .optional()
+        .describe("ID of the deck to move the card to"),
+    "template-id": z
+        .string()
+        .optional()
+        .describe("Template ID to use for the card"),
+    "archived?": z.boolean().optional().describe("Whether the card is archived"),
+    "trashed?": z.string().optional().describe("Whether the card is trashed"),
+    fields: z
+        .record(z.string(), CreateCardFieldSchema)
+        .optional()
+        .describe("Updated map of field IDs to field values"),
 });
 const ListDecksParamsSchema = z.object({
-    bookmark: z.string().optional(),
+    bookmark: z
+        .string()
+        .optional()
+        .describe("Pagination bookmark for fetching next page of results"),
 });
 const ListCardsParamsSchema = z.object({
-    "deck-id": z.string().optional(),
-    limit: z.number().min(1).max(100).optional(),
-    bookmark: z.string().optional(),
+    "deck-id": z.string().optional().describe("Get cards from deck ID"),
+    limit: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of cards to return per page (1-100)"),
+    bookmark: z
+        .string()
+        .optional()
+        .describe("Pagination bookmark for fetching next page of results"),
 });
 const ListTemplatesParamsSchema = z.object({
-    bookmark: z.string().optional(),
+    bookmark: z
+        .string()
+        .optional()
+        .describe("Pagination bookmark for fetching next page of results"),
 });
 const TemplateFieldSchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    pos: z.string(),
+    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"),
     options: z
         .object({
-        "multi-line?": z.boolean().optional(),
+        "multi-line?": z
+            .boolean()
+            .optional()
+            .describe("Whether the field supports multiple lines of text"),
     })
-        .optional(),
+        .optional()
+        .describe("Additional options for the field"),
 });
 const TemplateSchema = z
     .object({
-    id: z.string(),
-    name: z.string(),
-    content: z.string(),
-    pos: z.string(),
-    fields: z.record(z.string(), TemplateFieldSchema),
+    id: z.string().describe("Unique identifier for the template"),
+    name: z.string().describe("Display name of the template"),
+    content: z.string().describe("Template content in markdown format"),
+    pos: z.string().describe("Position of the template in the list"),
+    fields: z
+        .record(z.string(), TemplateFieldSchema)
+        .describe("Map of field IDs to field definitions"),
 })
     .strip();
 const ListTemplatesResponseSchema = z
     .object({
-    bookmark: z.string(),
-    docs: z.array(TemplateSchema),
+    bookmark: z.string().describe("Pagination bookmark for fetching next page"),
+    docs: z.array(TemplateSchema).describe("Array of templates"),
 })
     .strip();
 // Response Zod schemas
 const CardSchema = z
     .object({
-    id: z.string(),
-    tags: z.array(z.string()),
-    content: z.string(),
-    name: z.string(),
-    "deck-id": z.string(),
-    fields: z.record(z.unknown()).optional(),
+    id: z.string().describe("Unique identifier for the card"),
+    tags: z
+        .array(z.string())
+        .describe("Array of tags associated with the card"),
+    content: z
+        .string()
+        .describe('Markdown content of the card. Separate front and back of card with "---"'),
+    name: z.string().describe("Display name of the card"),
+    "deck-id": z.string().describe("ID of the deck containing the card"),
+    fields: z
+        .record(z.unknown())
+        .optional()
+        .describe("Map of field IDs to field values. Need to match the field IDs in the template"),
 })
     .strip();
 const CreateCardResponseSchema = CardSchema.strip();
 const ListCardsResponseSchema = z
     .object({
-    bookmark: z.string(),
-    docs: z.array(CardSchema),
+    bookmark: z.string().describe("Pagination bookmark for fetching next page"),
+    docs: z.array(CardSchema).describe("Array of cards"),
 })
     .strip();
 const DeckSchema = z
     .object({
-    id: z.string(),
-    sort: z.number(),
-    name: z.string(),
-    archived: z.boolean().optional(),
+    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"),
 })
     .strip();
 const ListDecksResponseSchema = z
     .object({
-    bookmark: z.string(),
-    docs: z.array(DeckSchema),
+    bookmark: z.string().describe("Pagination bookmark for fetching next page"),
+    docs: z.array(DeckSchema).describe("Array of decks"),
 })
     .strip();
 function getApiKey() {
@@ -171,11 +224,12 @@ export class MochiClient {
 // Server setup
 const server = new Server({
     name: "mcp-server/mochi",
-    version: "1.0.2",
+    version: "1.0.3",
 }, {
     capabilities: {
         tools: {},
         resources: {},
+        prompts: {},
     },
 });
 // Set up request handlers
@@ -193,10 +247,19 @@ ALWAYS look up deck-id with the mochi_list_decks tool.
 ### content (required)
 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.
+
 ### fields (optional)
-A map of field IDs (keyword) to field values. The field IDs should correspond to the fields defined on the template used by the card.
+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.
 
-## Example
+## Example without template
+{
+  "content": "What is the capital of France?\n---\nParis",
+  "deck-id": "btmZUXWM"
+}
+
+## Example with template
 {
   "content": "New card from API. ![](@media/foobar03.png)",
   "deck-id": "btmZUXWM",
@@ -209,12 +272,11 @@ A map of field IDs (keyword) to field values. The field IDs should correspond to
     "JNEnw1e7": {
       "id": "JNEnw1e7",
       "value": "World!"
-    },
-  },
+    }
+  }
 }
 
-## Good cards:
-- **concise**: as short question and answer as possible.
+## Properties of good flashcards:
 - **focused:** A question or answer involving too much detail will dull your concentration and stimulate incomplete retrievals, leaving some bulbs unlit.
 - **precise** about what they're asking for. Vague questions will elicit vague answers, which won't reliably light the bulbs you're targeting.
 - **consistent** answers, lighting the same bulbs each time you perform the task.
@@ -232,7 +294,7 @@ A map of field IDs (keyword) to field values. The field IDs should correspond to
         },
         {
             name: "mochi_update_card",
-            description: `Update an existing flashcard in Mochi.`,
+            description: `Update or delete an existing flashcard in Mochi. To delete set trashed to true.`,
             inputSchema: zodToJsonSchema(z.object({
                 "card-id": z.string(),
                 ...UpdateCardRequestSchema.shape,
@@ -369,6 +431,49 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         }
     }
 });
+const CreateFlashcardPromptSchema = z.object({
+    input: z
+        .string()
+        .describe("The information to base the flashcard on.")
+        .optional(),
+});
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "write-flashcard",
+                description: "Write a flashcard based on user-provided information.",
+                arguments: [
+                    {
+                        name: "input",
+                        description: "The information to base the flashcard on.",
+                    },
+                ],
+            },
+        ],
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const params = CreateFlashcardPromptSchema.parse(request.params.arguments);
+    const { input } = params;
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Create a flashcard using the info below while adhering to these principles: 
+- Keep questions and answers atomic.
+- 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.
+Input: ${input}
+`,
+                },
+            },
+        ],
+    };
+});
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (request.params.name) {

package/package.json

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