# redmine-mcp

Redmine の REST API を MCP (Model Context Protocol) の tool として公開するサーバーです。
Streamable HTTP と stdio の 2 つの transport に対応しています。

## 必要なもの

- Node.js 20 以上 (ローカル実行の場合)
- もしくは Docker / Docker Compose
- Redmine の REST API 有効化と API キー (Redmine の個人設定画面から取得)

## セットアップ

`.env.sample` をコピーして `.env` を作成し、`REDMINE_URL` と `REDMINE_API_KEY` を設定してください。

```sh
cp .env.sample .env
```

| 環境変数 | 説明 | 既定値 |
| --- | --- | --- |
| `REDMINE_URL` | Redmine の URL (末尾スラッシュは自動で除去) | なし (必須) |
| `REDMINE_API_KEY` | Redmine REST API の API キー | なし (必須) |
| `PORT` | HTTP transport の listen ポート | `3333` |
| `MCP_TRANSPORT` | `http` または `stdio` | `http` |
| `REDMINE_MCP_PORT` | docker compose のホスト側公開ポート | `3333` |
| `REDMINE_MAX_INLINE_BYTES` | 添付ファイルを MCP レスポンスに直接載せる上限 (byte) | `5242880` (5MiB) |

`REDMINE_URL` / `REDMINE_API_KEY` が未設定でも起動はしますが、tool 実行時にエラーになります。

## 起動

### Docker Compose (HTTP transport)

```sh
docker compose up -d --build
```

ヘルスチェック:

```sh
curl http://127.0.0.1:${REDMINE_MCP_PORT:-3333}/healthz
```

停止:

```sh
docker compose down
```

### ローカル実行

```sh
npm ci

# HTTP transport (.env を読み込む)
npm run start:env

# stdio transport
MCP_TRANSPORT=stdio npm start
```

## MCP クライアント設定

### Claude Code (HTTP)

```sh
claude mcp add --transport http redmine http://127.0.0.1:3333/mcp
```

### Claude Code (stdio)

```sh
claude mcp add redmine -- node "$(pwd)/src/server.mjs"
```

stdio の場合は `MCP_TRANSPORT=stdio` と Redmine の接続情報を env として渡してください
(`.mcp.json.sample` を参照)。

### Codex (HTTP)

```toml
[mcp_servers.redmine]
url = "http://127.0.0.1:3333/mcp"
enabled = true
default_tools_approval_mode = "prompt"
```

## 公開している tool

| tool | 種別 | 説明 |
| --- | --- | --- |
| `redmine_get_issue` | 読み取り | チケット ID 1 件を取得 |
| `redmine_list_issues` | 読み取り | フィルタ付きでチケット一覧を取得 (`query` で subject/description の部分一致を追加絞り込み) |
| `redmine_list_projects` | 読み取り | 参照可能なプロジェクト一覧を取得 |
| `redmine_create_issue` | 書き込み | チケットを作成 |
| `redmine_update_issue` | 書き込み | チケットのフィールドを更新 |
| `redmine_add_comment` | 書き込み | チケットに注記を追加 |
| `redmine_list_issue_attachments` | 読み取り | チケットの添付ファイル一覧 (メタデータ) を取得 |
| `redmine_get_attachment` | 読み取り | 添付ファイル 1 件のメタデータを取得 |
| `redmine_download_attachment` | 読み取り | 添付ファイルの実体を取得 (インライン返却 / ローカル保存) |
| `redmine_upload_file` | 書き込み | ファイルをアップロードし、トークン取得またはチケットへ添付 |
| `redmine_update_attachment` | 書き込み | 添付ファイルのファイル名・説明を変更 (Redmine 4.0 以降) |
| `redmine_delete_attachment` | 破壊的 | 添付ファイルを削除 |

一覧系の `limit` は既定 25 件、最大 100 件です。

## 添付ファイルの扱い

### 取得

`redmine_download_attachment` は添付の実体を返します。

- `save_path` を指定すると、そのパス (末尾 `/` や既存ディレクトリなら元のファイル名で配下) に保存し、保存先だけを返します。
- `save_path` なしの場合は MCP レスポンスに直接載せます。content type に応じて画像は image、テキストは text、その他は base64 の blob として返します (`as` で強制指定可)。
- インライン返却は `REDMINE_MAX_INLINE_BYTES` (既定 5MiB、`max_bytes` で上書き) を超えるとエラーになります。大きいファイルは `save_path` を使ってください。

添付の実体は Redmine が返す `content_url` から取得しますが、`REDMINE_URL` と同一オリジンでなければ取得を拒否します。

### アップロード

`redmine_upload_file` は `file_path` / `content_text` / `content_base64` のいずれか 1 つを受け取ります。

- `issue_id` を指定すると、アップロードしてそのままチケットへ添付します (`notes` で注記も同時に追加)。
- `issue_id` を省略するとアップロードトークンだけを返します。これを `redmine_create_issue` / `redmine_update_issue` の `uploads` に渡せば、チケット作成・更新と同時に添付できます。
- `file_path` は MCP サーバープロセスから見えるパスです。Docker で動かしている場合はコンテナ内のパスになる点に注意してください。

## HTTP エンドポイント

| メソッド | パス | 説明 |
| --- | --- | --- |
| `GET` | `/healthz` | 稼働確認と設定状況 (URL / API キーの設定有無) |
| `POST` | `/mcp` | MCP リクエスト (初回はセッション初期化) |
| `GET` | `/mcp` | SSE でのサーバー → クライアント通知 |
| `DELETE` | `/mcp` | セッション終了 |

## 構成

```
.
├── docker-compose.yml   # HTTP transport のコンテナ定義
├── Dockerfile
├── .env.sample
└── src/server.mjs       # MCP サーバー本体 (tool 定義 + transport)
```