# openproject-local-mcp

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

## 方針

- OpenProjectは直接クラウド側へ公開せず、開発者PC上のローカルMCPサーバーからAPI v3へ接続します。
- APIトークンは専用ユーザーの最小権限トークンを使います。
- 初期状態では読み取り中心です。`create_work_package`と`add_work_package_comment`は`OPENPROJECT_ENABLE_WRITE=true`の場合だけ動きます。
- OpenProject固有の名称、HAL+JSON、フィルター形式をそのまま扱います。

## 機能

- プロジェクト一覧
- Work Packageの検索、詳細取得、自分の担当項目の取得
- 明示的に有効化した場合のみ、Work Package作成とコメント追加
- Bearer認証（標準）とAPIトークンのBasic認証

## セットアップ

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

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

```text
OPENPROJECT_URL=https://openproject.example.local
OPENPROJECT_API_TOKEN=xxxxxxxxxxxxxxxx
OPENPROJECT_AUTH_MODE=bearer
OPENPROJECT_ENABLE_WRITE=false
```

`OPENPROJECT_URL`にはインスタンスのルートURLを指定します。`/api/v3`は付けません。現行OpenProjectではAPIトークンをBearerまたはBasic認証で利用できます。既定値は`bearer`です。

## MCPクライアント設定

### Codex CLI

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

[mcp_servers.openproject.env]
OPENPROJECT_URL = "https://openproject.example.local"
OPENPROJECT_API_TOKEN = "xxxxxxxxxxxxxxxx"
OPENPROJECT_AUTH_MODE = "bearer"
OPENPROJECT_ENABLE_WRITE = "false"
```

### GitHub Copilot CLI

```bash
copilot mcp add openproject \
  --env OPENPROJECT_URL=https://openproject.example.local \
  --env OPENPROJECT_API_TOKEN=xxxxxxxxxxxxxxxx \
  --env OPENPROJECT_ENABLE_WRITE=false \
  -- node /path/to/openproject-local-mcp/dist/index.js
```

## 提供ツール

- `list_projects`: APIユーザーから見えるプロジェクト一覧
- `search_work_packages`: 一般的な条件またはAPI v3のカスタムフィルターによる検索
- `get_work_package`: 数値IDによる詳細取得
- `get_my_work_packages`: APIユーザーに割り当てられたWork Package
- `create_work_package`: Work Package作成（書き込みの明示許可が必要）
- `add_work_package_comment`: コメント追加（書き込みの明示許可が必要）

## Agent Skill

OpenProject MCPの使い分けと書き込み時の確認ルールを`agent-skills/openproject-workflows/SKILL.md`に同梱しています。利用するエージェント環境の個人用Skillsディレクトリへ手動でコピーしてください。SkillにはAPIトークンや実URLを含めないでください。

OpenProjectの`offset`は件数ではなく、1から始まるページ番号です。`custom_filters`は次の形式で指定できます。

```json
[
  {
    "name": "status",
    "operator": "=",
    "values": ["5"]
  }
]
```

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

```text
OPENPROJECT_ENABLE_WRITE=true
```

`create_work_package`では、OpenProjectが作成時に必要とする`project_id`、`type_id`、`subject`を必須にしています。

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

コメント追加例:

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

## 開発

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

テストではHTTP通信をモックし、実OpenProjectには接続しません。

## セキュリティ

- APIトークンは専用ユーザーの最小権限トークンを利用してください。
- `.env`や実URLを含むMCPクライアント設定をコミットしないでください。
- 書き込みツールは`OPENPROJECT_ENABLE_WRITE=true`を明示した場合だけ有効です。
- OpenProjectのAPIがHTTPSで利用できる環境ではHTTPSを使用してください。

詳細は[設計メモ](docs/code-guide.md)を参照してください。

OpenProject API仕様:

- [API v3 Introduction](https://www.openproject.org/docs/api/introduction/)
- [Projects endpoint](https://www.openproject.org/docs/api/endpoints/projects/)
- [Work Packages endpoint](https://www.openproject.org/docs/api/endpoints/work-packages/)
- [Filters](https://www.openproject.org/docs/api/filters/)

## ライセンス

MIT License