maimemo-mcp

Персональный MCP-сервер с доступом только для чтения к учебным данным Maimemo.

Функции

• Транспорт stdio для локальных MCP-клиентов.

• Потоковый HTTP-транспорт по адресу /mcp.

• Четыре инструмента с доступом только для чтения:

  • maimemo_get_today_progress

  • maimemo_list_today_words

  • maimemo_get_due_words

  • maimemo_find_vocabulary

  • maimemo_list_notepads

  • maimemo_get_notepad

• Bearer-аутентификация для запросов к OpenAPI Maimemo.

• Локальное ограничение частоты запросов (rolling-window) согласно документации Maimemo: 20/10с, 40/60с и 2000/5ч.

• Защита хоста, источника (origin) и опциональный токен доступа для HTTP-транспорта.

Установка

npm install
npm run build

Используйте Node.js версии 20 или новее.

Конфигурация

Обязательно:

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

Опционально:

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

Когда MAIMEMO_HTTP_HOST не является 127.0.0.1, localhost или ::1, требуется MCP_SERVER_AUTH_TOKEN:

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

Не добавляйте реальные токены в репозиторий. Файлы .env игнорируются по умолчанию.

Запуск через Stdio

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

Для локальной копии:

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

Пример команды для MCP-клиента:

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

Запуск через потоковый HTTP

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

Конечная точка по умолчанию:

http://127.0.0.1:3333/mcp

Для привязки к внешнему адресу:

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

Клиенты должны отправлять:

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

Входные данные инструментов

maimemo_get_today_progress не требует входных данных.

maimemo_list_today_words:

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

status может принимать значения all, unfinished или finished. freshness может принимать значения all, new или review. limit должен быть от 1 до 1000.

maimemo_get_due_words:

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

Даты принимаются в формате YYYY-MM-DD или ISO. Перед вызовом Maimemo они нормализуются к часовому поясу Asia/Shanghai.

maimemo_find_vocabulary:

{
  "spellings": ["hello"]
}

или:

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

Укажите только один из параметров: spellings или ids.

maimemo_list_notepads:

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

limit должен быть от 1 до 100.

maimemo_get_notepad:

{
  "id": "notepad-id"
}

Возвращает полное содержимое блокнота и разобранный список слов.

Разработка

npm test
npm run typecheck
npm run build