# redmine-mcp

Redmine のチケットを操作する MCP（Model Context Protocol）サーバーです。Cursor や Claude Desktop などから、チケットの取得・一覧・作成・更新ができます。

## 要件

- Node.js 18.0.0 以上
- Redmine で REST API が有効であること
- Redmine の API アクセスキー（個人設定で取得）

## セットアップ

クローンやビルドは不要で、次の 2 ファイルを置くだけです。

1. **`.cursor/redmine.json`** を作成する。次のいずれかに配置する。
   - **ワークスペースのルート**（推奨）: プロジェクトごとに設定を変えたい場合
   - **`~/.cursor/redmine.json`**（ホーム）: 複数プロジェクトで同じ設定を使う場合。ワークスペースに設定が無いときにフォールバックとして読まれる

```json
{
  "redmineUrl": "https://your-redmine.example.com",
  "apiKey": "your-api-access-key"
}
```

2. **`.cursor/mcp.json`** に本サーバーを追加する。

```json
{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "github:ytakeuchi0222/redmine-mcp"]
    }
  }
}
```

初回実行時はリポジトリの取得とビルドが走るため、少し時間がかかります。MCP サーバーは起動時の**カレントディレクトリ**を基準に `.cursor/redmine.json` を探します（Cursor で MCP を起動する場合、カレントディレクトリは通常「開いているフォルダ」＝ワークスペースのルートに設定されます）。

**注意**: `redmine.json` には API キーが含まれるため、git で管理する場合は`.gitignore` に含めてリポジトリにコミットしないでください。

## 提供ツール

| ツール名 | 説明 |
|----------|------|
| `get_issue` | チケット 1 件を取得（`issue_id` 必須） |
| `list_issues` | チケット一覧を取得（`project_id`, `status_id`, `assigned_to_id`, `limit`, `offset` で絞り込み可能。`limit` は最大 100） |
| `create_issue` | チケットを新規作成（`project_id`, `subject` 必須） |
| `update_issue` | チケットを更新（`issue_id` 必須。`subject`, `description`, `status_id`, `assigned_to_id` は任意） |

## 具体的な使い方

### 1. 準備の確認

- **Redmine の API キー**: Redmine にログイン → 個人設定 → API アクセスキーで「表示」し、キーをコピーする。
- **設定ファイル**: このリポジトリを開いた状態で、`.cursor/redmine.json` に以下を保存する（値は自分の環境に合わせる）。

```json
{
  "redmineUrl": "https://あなたのRedmineのURL",
  "apiKey": "ここにAPIキーを貼る"
}
```

### 2. Cursor で使う

このリポジトリをワークスペースで開いた状態で、**チャット（Composer や Chat）**で次のように話しかけると、AI が Redmine MCP のツールを呼び出します。

| やりたいこと | チャットで入力する例 |
|--------------|----------------------|
| チケット 1 件を見る | 「チケット #123 の内容を教えて」 |
| 一覧を取得する | 「プロジェクト 5 のチケット一覧を 10 件出して」 |
| 担当チケットだけ | 「自分にアサインされているチケット一覧を出して」 |
| 未完了だけ | 「ステータスが open のチケットを 20 件」 |
| チケットを作成 | 「プロジェクト 1 に『〇〇の不具合』という件名でチケットを作成して」 |
| チケットを更新 | 「チケット #456 のステータスを『対応済み』に変更して」 |

ツール名を指定せず、**やりたいことを日本語で書く**だけで、AI が `get_issue` / `list_issues` / `create_issue` / `update_issue` を選んで実行します。

### 3. 各ツールのパラメータ（参考）

- **get_issue**: `issue_id`（例: 123）
- **list_issues**: `project_id`, `status_id`（数値 or `open` / `closed` / `*`）, `assigned_to_id`（数値 or `me`）, `limit`, `offset`（いずれも任意）
- **create_issue**: `project_id`, `subject`（必須）, `description`, `tracker_id`, `status_id`, `priority_id`, `assigned_to_id`（任意）
- **update_issue**: `issue_id`（必須）, `subject`, `description`, `status_id`, `assigned_to_id`（任意）

### 4. うまく動かないとき

- **「No server info found」**: MCP サーバーが起動していない。`.cursor/mcp.json` の設定が正しいか確認し、MCP を再起動する。
- **「設定ファイルが見つかりません」**: MCP は (1) ワークスペースの `.cursor/redmine.json`、(2) `~/.cursor/redmine.json` の順で探します。どちらかに `redmine.json` を置いているか確認してください。両方無い場合は「ワークスペースの .cursor/redmine.json と ~/.cursor/redmine.json のどちらも見つかりません」と表示されます。
- **4xx / 5xx エラー**: Redmine の URL・API キー、REST API 有効化、プロジェクト ID やチケット ID が正しいか確認する。

---

## 参照

- 要求定義・要件定義・実装方針: `docs/` 配下の Markdown
- [Redmine REST API (Issues)](https://www.redmine.org/projects/redmine/wiki/rest_issues)