# redmine-local-mcp

Redmine REST API を MCP ツールとして公開するローカル STDIO サーバーです。
Codex CLI / GitHub Copilot CLI などの MCP クライアントから、Redmine のプロジェクトやチケットを参照できます。

## 方針

- Redmine は直接クラウド側へ公開せず、開発者 PC 上のローカル MCP サーバーから REST API に接続します。
- API キーは専用ユーザーの最小権限キーを使います。
- 初期状態では読み取り中心です。書き込み系の `create_issue` / `add_issue_note` は `REDMINE_ENABLE_WRITE=true` のときだけ動きます。

## 機能

- プロジェクト一覧の取得
- チケット検索、チケット詳細取得、自分の担当チケット取得
- 明示的に有効化した場合のみ、チケット作成とコメント追加

## セットアップ

```bash
git clone https://github.com/<owner>/redmine-local-mcp.git
cd redmine-local-mcp
npm install
npm run build
```

`.env.example` を参考に、MCP クライアント側の環境変数として次の値を渡してください。
`.env` はローカル開発用で、Git にコミットしないでください。

```bash
REDMINE_URL=https://redmine.example.local
REDMINE_API_KEY=xxxxxxxxxxxxxxxx
REDMINE_ENABLE_WRITE=false
```

## MCP クライアント設定

以下の例では、このリポジトリを `/path/to/redmine-local-mcp` に clone したものとして書いています。
実際の環境に合わせてパスを置き換えてください。

### Codex CLI

```toml
[mcp_servers.redmine]
command = "node"
args = ["/path/to/redmine-local-mcp/dist/index.js"]
default_tools_approval_mode = "prompt"

[mcp_servers.redmine.env]
REDMINE_URL = "https://redmine.example.local"
REDMINE_API_KEY = "xxxxxxxxxxxxxxxx"
REDMINE_ENABLE_WRITE = "false"
```

### GitHub Copilot CLI

```bash
copilot mcp add redmine \
  --env REDMINE_URL=https://redmine.example.local \
  --env REDMINE_API_KEY=xxxxxxxxxxxxxxxx \
  --env REDMINE_ENABLE_WRITE=false \
  -- node /path/to/redmine-local-mcp/dist/index.js
```

## Agent Skill

Redmine MCP の使い方や安全ルールをまとめた Agent Skill を同梱しています。
このリポジトリでは Skill の原本だけを管理し、使う環境のユーザープロファイルへ手動でコピーします。

Skill 本体:

```text
agent-skills/redmine-workflows/SKILL.md
```

GitHub Copilot の個人用 Skill として使う場合のコピー例:

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.copilot\skills\redmine-workflows"
Copy-Item -Recurse -Force .\agent-skills\redmine-workflows\* "$env:USERPROFILE\.copilot\skills\redmine-workflows\"
```

`.agents` 配下で Skill を管理する環境では、コピー先を次のように置き換えます。

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills\redmine-workflows"
Copy-Item -Recurse -Force .\agent-skills\redmine-workflows\* "$env:USERPROFILE\.agents\skills\redmine-workflows\"
```

この Skill には API キーや Redmine URL は含めません。接続情報は MCP クライアント設定の環境変数で渡してください。

## 提供ツール

- `list_projects`: プロジェクト一覧を取得します。
- `search_issues`: チケットを検索します。
- `get_issue`: チケット詳細を取得します。
- `get_my_issues`: 自分に割り当てられたチケットを取得します。
- `create_issue`: チケットを作成します。`REDMINE_ENABLE_WRITE=true` が必要です。
- `add_issue_note`: チケットにコメントを追加します。`REDMINE_ENABLE_WRITE=true` が必要です。

## 設計メモ

設計判断や拡張時の注意点は [docs/code-guide.md](docs/code-guide.md) にまとめています。

主なファイル:

- `src/index.ts`: MCPツールを登録する入口です。
- `src/redmineClient.ts`: Redmine REST APIを呼び出す処理です。
- `src/config.ts`: 環境変数を読み込む処理です。
- `tests/`: 実Redmineへ接続せずに動作を確認するテストです。

## 書き込み系を有効にする

チケット作成やコメント追加を行う場合は、環境変数を次のように設定します。

```bash
REDMINE_ENABLE_WRITE=true
```

`create_issue` の最小入力例:

```json
{
  "project_id": "sample-project",
  "subject": "ログイン画面のエラーを確認する",
  "description": "再現手順と期待結果を整理する。"
}
```

`add_issue_note` の入力例:

```json
{
  "id": 1234,
  "notes": "調査を開始しました。再現条件を確認中です。"
}
```

## 開発

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

テストは実 Redmine へ接続せず、HTTP 呼び出しをモックします。

## セキュリティ

- `REDMINE_API_KEY` は専用ユーザーの最小権限キーを使ってください。
- `.env` や実 URL を含む MCP クライアント設定はコミットしないでください。
- 書き込みツールは `REDMINE_ENABLE_WRITE=true` を明示した場合だけ有効です。
- 脆弱性や秘密情報の混入を見つけた場合は、公開 issue ではなくリポジトリ管理者へ非公開で連絡してください。

## 公開前チェックリスト

- `.env` が Git 管理対象になっていないことを確認する。
- README 内の `<owner>` と `/path/to/redmine-local-mcp` を公開先に合わせる。
- Agent Skill に実 Redmine の URL、API キー、社内固有の非公開ルールが含まれていないことを確認する。
- 実 Redmine の URL、API キー、社内プロジェクト名が含まれていないことを確認する。
- `npm run typecheck`、`npm run build`、`npm test` が通ることを確認する。

## ライセンス

MIT License