# bluemind-mcp

MCP (Model Context Protocol) server to read and search **emails** and **calendar events** from a [BlueMind](https://www.bluemind.net/) account (built against the BlueMind 5.x REST API).

Read-only: no tool modifies, sends or deletes anything.

## Configuration

Three required environment variables:

| Variable | Description |
|---|---|
| `BLUEMIND_URL` | Server URL, e.g. `https://mail.example.com` |
| `BLUEMIND_EMAIL` | User login (email address) |
| `BLUEMIND_PASSWORD` | Password |
| `BLUEMIND_ALLOW_INSECURE_TLS` | *(optional)* `1` to accept self-signed certificates |

Authentication goes through `POST /api/auth/login`; the session `authKey` is then sent as the `X-BM-ApiKey` header on every call. The session is renewed automatically when it expires.

## Usage

Add this to your MCP client configuration (`mcp_config.json`, `claude_desktop_config.json`, etc.):

```json
{
  "mcpServers": {
    "bluemind": {
      "command": "npx",
      "args": ["-y", "github:AlexMili/bluemind-mcp"],
      "env": {
        "BLUEMIND_URL": "https://mail.example.com",
        "BLUEMIND_EMAIL": "john.doe@example.com",
        "BLUEMIND_PASSWORD": "..."
      }
    }
  }
}
```

Or from a local checkout:

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

```json
{
  "mcpServers": {
    "bluemind": {
      "command": "node",
      "args": ["/path/to/bluemind-mcp/dist/index.js"],
      "env": {
        "BLUEMIND_URL": "https://mail.example.com",
        "BLUEMIND_EMAIL": "john.doe@example.com",
        "BLUEMIND_PASSWORD": "..."
      }
    }
  }
}
```

## Tools

### Mail

- **`list_mail_folders`** — list mail folders (INBOX, Sent, …) with their `folder_uid`.
- **`search_emails`** — full-text search (Elasticsearch `query_string` syntax): `invoice`, `subject:meeting AND from:peter`, `has:attachments`… Searches the whole mailbox by default, or a single folder. Parameters: `query`, `folder_uid?`, `folder_name?`, `limit`, `offset`.
- **`list_recent_emails`** — latest messages of a folder (default INBOX), with an `unread_only` option.
- **`read_email`** — full message content (`folder_uid` + `item_id` as returned by the two tools above): headers, text body (HTML converted to text), attachment list. Option `prefer_html`.

### Calendar

- **`list_calendars`** — calendars accessible to the user, with their `calendar_uid`. The default calendar is `calendar:Default:<USERID>`.
- **`search_events`** — text search over events (`POST /api/calendars/{uid}/_search`), with an optional date range. Parameters: `query`, `calendar_uid?`, `date_min?`, `date_max?`, `limit`, `offset`.
- **`list_events`** — agenda view over a date range (`date_min`/`date_max`, `YYYY-MM-DD` or ISO format). Recurring events are returned as series with their recurrence rule.

## Development

```bash
npm run dev    # tsc --watch
```

Quick protocol check without an MCP client:

```bash
printf '%s\n%s\n%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
 | BLUEMIND_URL=... BLUEMIND_EMAIL=... BLUEMIND_PASSWORD=... node dist/index.js
```

## License

MIT