# maimemo-mcp

Personal read-only MCP server for Maimemo study data.

## Features

- `stdio` transport for local MCP clients.
- Streamable HTTP transport at `/mcp`.
- Four read-only tools:
  - `maimemo_get_today_progress`
  - `maimemo_list_today_words`
  - `maimemo_get_due_words`
  - `maimemo_find_vocabulary`
  - `maimemo_list_notepads`
  - `maimemo_get_notepad`
- Bearer authentication for Maimemo OpenAPI requests.
- Local rolling-window rate limiting for the documented Maimemo limits:
  `20/10s`, `40/60s`, and `2000/5h`.
- Host, origin, and optional bearer-token protection for HTTP transport.

## Install

```bash
npm install
npm run build
```

Use Node.js 20 or newer.

## Configuration

Required:

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

Optional:

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

When `MAIMEMO_HTTP_HOST` is not `127.0.0.1`, `localhost`, or `::1`,
`MCP_SERVER_AUTH_TOKEN` is required:

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

Do not commit real tokens. `.env` files are ignored by default.

## Run With Stdio

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

For a local checkout:

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

Example MCP client command:

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

## Run With Streamable HTTP

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

Default endpoint:

```text
http://127.0.0.1:3333/mcp
```

For non-loopback binding:

```bash
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 must then send:

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

## Tool Inputs

`maimemo_get_today_progress` has no input.

`maimemo_list_today_words`:

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

`status` can be `all`, `unfinished`, or `finished`.
`freshness` can be `all`, `new`, or `review`.
`limit` must be between 1 and 1000.

`maimemo_get_due_words`:

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

Dates accept `YYYY-MM-DD` or ISO instants. They are normalized to
`Asia/Shanghai` before calling Maimemo.

`maimemo_find_vocabulary`:

```json
{
  "spellings": ["hello"]
}
```

or:

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

Provide exactly one of `spellings` or `ids`.

`maimemo_list_notepads`:

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

`limit` must be between 1 and 100.

`maimemo_get_notepad`:

```json
{
  "id": "notepad-id"
}
```

Returns full notepad content and parsed word list.

## Development

```bash
npm test
npm run typecheck
npm run build
```