maimemo-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Personal MCP server for read-only Maimemo vocabulary study data. Exposes four tools via stdio or streamable HTTP transport.

Commands

npm run build        # Clean rebuild (tsc -p tsconfig.build.json)
npm run typecheck    # Type check without emit
npm test             # Run vitest

Architecture

Entry points:

• src/cli.ts — CLI that selects transport mode (--transport=stdio|http)
• src/index.ts — Public exports for programmatic use

Data flow:

cli.ts → config.ts → server.ts → tools/studyTools.ts → maimemo/client.ts → Maimemo API

Key modules:

• src/config.ts — Environment variable parsing, validates MAIMEMO_TOKEN is required
• src/server.ts — Creates McpServer, registers four tools with Zod schemas
• src/tools/ — Input schemas (schemas.ts) and tool handlers (studyTools.ts) that transform API responses to camelCase output
• src/maimemo/ — Client (client.ts), types (types.ts), rolling-window rate limiter (rateLimiter.ts) enforcing Maimemo's limits (20/10s, 40/60s, 2000/5h)
• src/transports/ — stdio and streamable HTTP implementations

Maimemo API interface (MaimemoStudyApi in src/maimemo/types.ts) defines the four endpoints. Client implementations inject a rate limiter.

Tool Inputs

• maimemo_get_today_progress — no input
• maimemo_list_today_words — status, freshness, limit, spellings (optional filters)
• maimemo_get_due_words — startDate, endDate, spellings, limit, countOnly (dates normalized to Asia/Shanghai)
• maimemo_find_vocabulary — exactly one of spellings or ids

Maximum batch size is 1000 across all tools.

Testing

Tests mock the MaimemoStudyApi interface directly (see tests/studyTools.test.ts). Test file pattern: tests/**/*.test.ts.