maimemo-mcp

Persönlicher schreibgeschützter MCP-Server für Maimemo-Lerndaten.

Funktionen

• stdio-Transport für lokale MCP-Clients.

• Streamfähiger HTTP-Transport unter /mcp.

• Vier schreibgeschützte Tools:

  • maimemo_get_today_progress

  • maimemo_list_today_words

  • maimemo_get_due_words

  • maimemo_find_vocabulary

  • maimemo_list_notepads

  • maimemo_get_notepad

• Bearer-Authentifizierung für Maimemo-OpenAPI-Anfragen.

• Lokale Ratenbegrenzung (Rolling-Window) für die dokumentierten Maimemo-Limits: 20/10s, 40/60s und 2000/5h.

• Host-, Origin- und optionaler Bearer-Token-Schutz für den HTTP-Transport.

Installation

npm install
npm run build

Verwenden Sie Node.js 20 oder neuer.

Konfiguration

Erforderlich:

export MAIMEMO_TOKEN="your-maimemo-openapi-token"

Optional:

export MAIMEMO_BASE_URL="https://open.maimemo.com/open"
export MAIMEMO_HTTP_HOST="127.0.0.1"
export MAIMEMO_HTTP_PORT="3333"

Wenn MAIMEMO_HTTP_HOST nicht 127.0.0.1, localhost oder ::1 ist, ist MCP_SERVER_AUTH_TOKEN erforderlich:

export MCP_SERVER_AUTH_TOKEN="your-local-mcp-http-token"

Übertragen Sie keine echten Tokens. .env-Dateien werden standardmäßig ignoriert.

Ausführung mit Stdio

MAIMEMO_TOKEN="your-token" npx maimemo-mcp --transport=stdio

Für einen lokalen Checkout:

MAIMEMO_TOKEN="your-token" node dist/cli.js --transport=stdio

Beispiel für einen MCP-Client-Befehl:

{
  "mcpServers": {
    "maimemo": {
      "command": "node",
      "args": ["/absolute/path/to/momo-skills/dist/cli.js", "--transport=stdio"],
      "env": {
        "MAIMEMO_TOKEN": "your-token"
      }
    }
  }
}

Ausführung mit streamfähigem HTTP

MAIMEMO_TOKEN="your-token" node dist/cli.js --transport=http

Standard-Endpunkt:

http://127.0.0.1:3333/mcp

Für Nicht-Loopback-Bindung:

MAIMEMO_TOKEN="your-token" \
MAIMEMO_HTTP_HOST="0.0.0.0" \
MCP_SERVER_AUTH_TOKEN="your-local-mcp-http-token" \
node dist/cli.js --transport=http

Clients müssen dann Folgendes senden:

Authorization: Bearer your-local-mcp-http-token

Tool-Eingaben

maimemo_get_today_progress hat keine Eingabe.

maimemo_list_today_words:

{
  "status": "all",
  "freshness": "all",
  "limit": 50,
  "spellings": ["hello", "world"]
}

status kann all, unfinished oder finished sein. freshness kann all, new oder review sein. limit muss zwischen 1 und 1000 liegen.

maimemo_get_due_words:

{
  "startDate": "2026-04-18",
  "endDate": "2026-04-20",
  "spellings": ["hello"],
  "limit": 50,
  "countOnly": false
}

Daten akzeptieren YYYY-MM-DD oder ISO-Zeitstempel. Sie werden vor dem Aufruf von Maimemo auf Asia/Shanghai normalisiert.

maimemo_find_vocabulary:

{
  "spellings": ["hello"]
}

oder:

{
  "ids": ["vocabulary-id"]
}

Geben Sie genau eines von spellings oder ids an.

maimemo_list_notepads:

{
  "limit": 20,
  "offset": 0,
  "ids": ["notepad-id"]
}

limit muss zwischen 1 und 100 liegen.

maimemo_get_notepad:

{
  "id": "notepad-id"
}

Gibt den vollständigen Notizblockinhalt und die geparste Wortliste zurück.

Entwicklung

npm test
npm run typecheck
npm run build