# QueryPie AIP Release Readiness Agent

技術課題用のローカル MCP Server と `release-readiness-review` Skill です。MCP はサンプル JSON から事実だけを返し、リリース判定は Skill が担当します。

## 構成

```text
.
├── src/                         MCP Server 実装
├── sample-data/                 課題で提供された JSON（3 ファイルを変更せず使用）
├── skill/release-readiness-review/
│   ├── SKILL.md
│   └── references/release-policy.md
├── artifacts/
│   ├── querypie-compatible/
│   │   └── release-readiness-review.zip
│   └── submission/
│       └── querypie-release-readiness-agent.zip
├── test/                        データ、MCP、Skill パッケージのテスト
├── docs/
│   ├── agent-instruction.md
│   └── test-results.md
└── DESIGN.md                    責務分離、エラー処理、制約
```

`sample-data/README.md` と `sample-data/expected-results.json` はメール添付 ZIP に含まれていた補助ファイルですが、実装からは参照せず、提出対象にも含めません。MCP が読み込むのは `projects.json`、`builds.json`、`issues.json` のみです。

## 動作環境

- Node.js 20 以上
- npm 10 以上を推奨
- QueryPie Edge Tunnel は Node.js 18.20.8 以上（20 LTS 以上を推奨）

## インストールとローカル実行

```bash
npm ci
npm run build
npm start
```

既定値:

| 項目 | 値 |
| --- | --- |
| bind address | `127.0.0.1` |
| port | `3000` |
| data directory | `./sample-data` |
| QueryPie 用 SSE URL | `http://127.0.0.1:3000/sse` |
| Streamable HTTP URL | `http://127.0.0.1:3000/mcp` |
| health check | `http://127.0.0.1:3000/health` |

必要な場合だけ環境変数で変更できます。

```powershell
$env:MCP_PORT = "3100"
$env:MCP_DATA_DIR = ".\sample-data"
npm start
```

`MCP_HOST` の既定値は `127.0.0.1` です。課題では公衆ネットワークへ bind せず、Edge Tunnel を使用してください。

## MCP Tool

| Tool | 入力 | 成功時の主な出力 | エラー例 |
| --- | --- | --- | --- |
| `list_projects` | なし | `asOf`, `projects[]` (`id`, `name`, `description`, `ownerTeam`) | データファイル不備は起動時エラー |
| `get_project_status` | `projectId` | `asOf`, `project`, `release` | `PROJECT_NOT_FOUND` |
| `get_latest_build` | `projectId` | `asOf`, `projectId`, `build` | `PROJECT_NOT_FOUND`, `BUILD_NOT_FOUND` |
| `get_open_issues` | `projectId` | `asOf`, `projectId`, `count`, `issues[]` | `PROJECT_NOT_FOUND` |

すべての成功応答は `success: true` を、Tool エラーは `success: false`、`error.code`、`error.message`、可能な場合は `error.details` を含みます。未解決 Issue が 0 件の場合は正常応答として空配列を返します。

## ローカルテスト

```bash
npm test
```

このコマンドは以下を一度に実行します。

1. TypeScript の本番コードとテストコードをコンパイル
2. `artifacts/querypie-compatible/release-readiness-review.zip` を再生成
3. 提供 JSON を変更しないこと、ファイル/スキーマエラー、4 Tool のデータ取得を検証
4. 公式 MCP Client で `/mcp` と QueryPie 用 `/sse` の両方を実接続
5. Skill ZIP の直下構造と 4 種類の判定境界を検証

手動確認には MCP Inspector も利用できます。別の端末で Server を起動してから実行してください。

```bash
npm run inspector:sse
```

## QueryPie AIP への接続

2026-09-11 時点で、MCP、Skill、Personal Agent の設定と AIP 上の動作確認まで完了しています。接続を再現する場合は以下の手順を使用します。

### 1. MCP Server と Edge Tunnel

1. `npm start` で Server を起動します。
2. QueryPie AIP で **Use Edge Tunnel** を有効にします。
3. 左下の Edge Tunnel ポップオーバーから表示されたコマンドをコピーし、別の端末で実行します。キーを README やリポジトリへ保存しないでください。
4. ポップオーバーが `Connected`、接続数が `1` になったことを確認します。

### 2. Custom MCP Integration

QueryPie AIP の **Integrations → All Integrations → Custom MCP Integration Setup** で次を設定します。

| 項目 | 値 |
| --- | --- |
| Name | `リリース判定データ MCP (release-readiness-data)` |
| Description | `リリース可否判断に必要なプロジェクト情報、最新ビルド、未解決課題を取得します。` |
| MCP Server URL (SSE) | `http://localhost:3000/sse` |
| Use Edge Tunnel | 有効 |
| Authentication / Headers | なし |

インストール後、Tool 一覧に `list_projects`、`get_project_status`、`get_latest_build`、`get_open_issues` の 4 件と各入力スキーマが表示されることを確認します。

### 3. Skill のアップロード

1. AIP の **Skills → Add** を開きます。
2. `skill/release-readiness-review` フォルダ全体をドラッグしてアップロードします。
3. 自動入力された名前が `release-readiness-review` であることを確認します。

ZIP が必要な場合は `npm run package:skill` で `artifacts/querypie-compatible/release-readiness-review.zip` を生成できます。

ZIP の直下は次の構成です。Skill 名の親フォルダは ZIP に含めていません。

```text
release-readiness-review.zip
├── SKILL.md
└── references/release-policy.md
```

### 4. Personal Agent の作成

`docs/agent-instruction.md` の設定値と Instruction を使って `リリース判定エージェント` を作成し、上記 MCP Integration と Skill の両方を接続します。Agent 内の MCP 名はツール探索を安定させるため `リリース判定データ MCP (release-readiness-data)` とします。

### 5. AIP テスト

Skill を更新または再アップロードした後は、必ず新しいチャットで次を実行します。

```text
payment-api を来週リリースしても問題ないか確認してください。
現在のプロジェクトから、すぐにリリースできるものを探してください。
unknown-service のリリース準備状況を確認してください。
legacy-reporting のリリース可否と、追加で必要な情報を教えてください。
```

実測結果と QueryPie 公式 Share Conversation リンクは `docs/test-results.md` の AIP 欄に記録しています。

全提出物をひとつの ZIP にまとめる場合は、テスト後に次を実行します。

```powershell
npm run package:submission
```

出力先は `artifacts/submission/querypie-release-readiness-agent.zip` です。ZIP 内には `node_modules`、TypeScript コンパイル生成物、作業用一時ディレクトリ、接続キーを含めません。

作成後の ZIP は次のコマンドで、必須ファイル、サンプルデータ同一性、公式共有リンク 4 件、Skill ZIP、パス安全性、PNG 不在、代表的な秘密情報パターンを検証できます。

```powershell
npm run validate:submission
```

## 判定基準

MCP 応答の `asOf` を使い、現在時刻は使いません。判定の優先順位は次の通りです。

1. `UNKNOWN`: 最新ビルドが 7 日以上前、テスト結果なし、または必要データ取得失敗
2. `NO_GO`: 最新ビルド失敗、または未解決 BLOCKER / CRITICAL Issue
3. `CONDITIONAL`: テスト成功率 95% 未満、または未解決 MAJOR Issue
4. `GO`: 7 日未満の SUCCESS ビルド、成功率 95% 以上、未解決の重大 Issue なし

詳細は `skill/release-readiness-review/references/release-policy.md` を参照してください。

## 参考資料

- [QueryPie AIP Custom MCP Server Integration](https://aip-docs.app.querypie.com/en/user-guide/special-features/custom-mcp)
- [QueryPie AIP Edge Tunnel](https://aip-docs.app.querypie.com/en/user-guide/special-features/edge-tunnel)
- [QueryPie AIP Skills](https://aip-docs.app.querypie.com/en/user-guide/skills)
- [MCP TypeScript SDK v1 Server Guide](https://ts.sdk.modelcontextprotocol.io/server)