maimemo-mcp

Servidor MCP personal de solo lectura para los datos de estudio de Maimemo.

Características

• Transporte stdio para clientes MCP locales.

• Transporte HTTP con streaming en /mcp.

• Cuatro herramientas de solo lectura:

  • maimemo_get_today_progress

  • maimemo_list_today_words

  • maimemo_get_due_words

  • maimemo_find_vocabulary

  • maimemo_list_notepads

  • maimemo_get_notepad

• Autenticación Bearer para solicitudes a la OpenAPI de Maimemo.

• Limitación de tasa local de ventana deslizante para los límites documentados de Maimemo: 20/10s, 40/60s y 2000/5h.

• Protección de host, origen y token bearer opcional para el transporte HTTP.

Instalación

npm install
npm run build

Utilice Node.js 20 o superior.

Configuración

Obligatorio:

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

Opcional:

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

Cuando MAIMEMO_HTTP_HOST no es 127.0.0.1, localhost o ::1, MCP_SERVER_AUTH_TOKEN es obligatorio:

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

No confirme tokens reales. Los archivos .env se ignoran por defecto.

Ejecutar con Stdio

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

Para una descarga local:

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

Ejemplo de comando de cliente MCP:

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

Ejecutar con HTTP con streaming

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

Endpoint por defecto:

http://127.0.0.1:3333/mcp

Para enlaces que no sean de loopback:

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

Los clientes deben enviar entonces:

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

Entradas de las herramientas

maimemo_get_today_progress no tiene entrada.

maimemo_list_today_words:

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

status puede ser all, unfinished o finished. freshness puede ser all, new o review. limit debe estar entre 1 y 1000.

maimemo_get_due_words:

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

Las fechas aceptan YYYY-MM-DD o instantes ISO. Se normalizan a Asia/Shanghai antes de llamar a Maimemo.

maimemo_find_vocabulary:

{
  "spellings": ["hello"]
}

o:

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

Proporcione exactamente uno de spellings o ids.

maimemo_list_notepads:

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

limit debe estar entre 1 y 100.

maimemo_get_notepad:

{
  "id": "notepad-id"
}

Devuelve el contenido completo del bloc de notas y la lista de palabras analizada.

Desarrollo

npm test
npm run typecheck
npm run build