Skip to main content
Glama
deenesjakoruzh
PS-minalprasad

BugPilot MCP Server

by PS-minalprasad
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BugPilot

AI搭載エンジニアリングバグインテリジェンスエージェント

コアアーキテクチャ: BugPilotは、エンドツーエンドで疎結合されたクリーンなパイプラインで動作します: React / Vite → FastAPI Backend → ReAct Orchestrator → Specialist Agents → MCP Client → MCP Server → 10個の読み取り専用ツール → SQLite Database (Synthetic Jira Data)。

1. システムアーキテクチャ

┌─────────────────────────────────────────────────────────────────────────────┐
│                       React / Vite Frontend (TypeScript)                     │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ HTTP REST API (JWT + RBAC + Tenant Isolation)
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          FastAPI Backend (Port 8000)                         │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        ReAct Orchestrator Agent                              │
│         Dynamic reasoning loop: Goal → LLM Decision → Tool Call →            │
│                    Observation → Next Decision → FINISH                     │
│               [Groq Primary API + Local Ollama Fallback]                    │
└───────────┬──────────────────────────┼──────────────────────────┬───────────┘
            │                          │                          │
            ▼                          ▼                          ▼
┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
│  Bug Analyst Agent   │   │ Trend Analyst Agent  │   │ Risk Analyst Agent   │
└───────────┬──────────┘   └──────────┬───────────┘   └──────────┬───────────┘
            │                          │                          │
            └──────────────────────────┼──────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                 MCP Client                                   │
│                 Dynamic tool discovery, timeout & sandboxing                 │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ stdio JSON-RPC Transport
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          MCP Server (mcp_server)                            │
│                  Exposes 10 Strict READ-ONLY Tools                          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              AnalyticsService                                │
│              Deterministic metric calculation & statistical trends          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                 DataProvider Interface (SQLDataProvider / SQLite)            │
│                 Multi-tenant tenant isolation (`organization_id`)           │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    SQLite Database (`sqlite:///./bugpilot.db`)              │
│       Realistic Jira-style Defect Catalog, Sprints, Users & Audit Trails    │
└─────────────────────────────────────────────────────────────────────────────┘

厳格なデータアクセス契約

✅ Agent → MCP Client → MCP Server → AnalyticsService → DataProvider → SQLite Data
❌ Agent → Direct Database Access (FORBIDDEN)
❌ Agent → Direct Data File Reading (FORBIDDEN)
❌ External Vector Database / RAG dependencies (FORBIDDEN)

エージェントは動的に発見されたMCPツールとのみ対話し、サンドボックス化と完全なテスト容易性を維持します。

Related MCP server: sqlite-analyst

2. 10のMCPツールリファレンス

全10ツールは厳密に読み取り専用、テナントスコープ付き（org_id）、そしてMCPプロトコルを介して動的に発見されます:

#

ツール名

必須/オプションパラメータ

説明と返される証拠

1

search_bugs

query: str, limit: int = 20

課題キー、タイトル、要約、説明内のキーワードでバグを検索します。

2

get_bug

bug_id: str

単一バグの完全な詳細（重要度、優先度、根本原因、ビジネス影響、環境、再現手順、修正バージョン）を取得します。

3

get_bug_metrics

sprint_id: Optional[str], component: Optional[str], project: Optional[str]

集計されたバグ数、未解決対解決済みの分布、重要度別の内訳。

4

get_bug_trends

sprint_id: Optional[str], component: Optional[str], project: Optional[str]

月別の作成対解決の傾向と、過去のスプリント完了速度。

5

get_aging_bugs

min_age_days: float = 0.0, limit: int = 50

経過日数で降順にソートされた未解決の欠陥。SLAリスクを強調します。

6

get_reopened_bugs

component: Optional[str], limit: int = 50

解決済み/クローズから未解決/進行中に遷移した欠陥（reopen_count > 0）。

7

get_component_risk

component: Optional[str], project: Optional[str]

コンポーネントレベルのリスクスコア（0–100）、アクティブな未解決課題数、影響範囲インジケーター。

8

get_release_risk

release: Optional[str]

修正バージョン/リリースの準備状況評価、全体的なリスクスコア、デプロイ判断。

9

get_bug_history

bug_id: str

時系列のステータス遷移履歴、再オープンタイムスタンプ、開発者の議論コメント。

10

get_related_bugs

bug_id: str, limit: int = 10

コンポーネントコンテキスト、技術的根本原因、または明示的にリンクされた課題IDを共有する関連欠陥。

3. 動的ReActオーケストレーションと比較分析

オーケストレーターエージェントは、純粋な**推論＋アクション（ReAct）**ループで動作します:

  1. 意図とドメイン外ガードレール — 初期チェックにより、LLM/ツール呼び出しを無駄費することなく、エンジニアリング以外のクエリをフィルタリングします。

  2. 動的ツール選択 — LLMがクエリ、動的に発見されたツール、蓄積された観察結果に基づいて、各アクション（CALL_TOOL、DELEGATE、FINISH）を決定します。

  3. 反復的な複数候補の検査 — 比較やランキングのクエリ（"認証バグを分析し、最高リスクの課題を特定"）の場合、search_bugsが候補を発見し、オーケストレーターが各候補欠陥に対してget_bugを反復的に呼び出してからFINISHを許可することで、完全な技術的証拠（根本原因、影響範囲、再現手順）が収集されることを保証します。

  4. 差別化された証拠に基づくリス久スコア — 重要度、優先度、ステータス、本番環境、セキュリティ影響（例：SOC2/セッションハイジャック）、技術的根本原因（例：競合状態、クLラッシュ）を評価します。飽和を避けるたあ、非飽和スコア（0.0–99.5）を生生成し、人工的な100/100の同点を防ぎます。

  5. リフレクションエージェント品質評価 — 生生成されたレポー Lトを、グランドトルースのMCPデー Lタと照合わ Lせて、幻覚を防ぎ、正確な報告を確認します。

4. マルチテナンシーとRBACセキュリティ

  • テナント分離 — すべてのデー Lタベースレコー Lド（issues、sprints、users、audit_logs）は、organization_id（例：org-acme）によって厳密にスコープされまス。組織間のデー Lタアクセスは、リポジトリ MB び M C P 層でブ L ッ久されます。

  • ロ Lールベースのアクセス制御（RBAC）:

    • 管理員 — 完全アクセス、ユーザー管理、課題管理。

    • エンジニア/開発者 — 課題の作成、更新、遷移、分析。

    • 観覧者 — 課題、アナリティクス、レポートへの読み取り専用アクセス。

  • 秘密情報管理 — 秘密キーや認証情情報はハー Lドコ Lードされていまセん。JWT秘密、APIキー、環境変数は.envから厳密に読み込まれ、バージョン管理から除 L外さレています。

5. 技術スタック

層

コンポーネント

技術

フロンエンド

対話 UI

React 18 + TypeScript + Vite

バックエンドAPI

REST API Server

FastAPI + Uvicorn + Pydantic v2

オーケストレーション

エージェントループ

ReAct Agent Framework + Specialist Delegation

LLMゲートウェイ

推論エンジン

Groq API (llama-3.3-70b-versatile) プライマリ + ローカル Ollama (llama3.1:8b) フォ Lルバック

ツールプロトコル

ツーリン Lグレ Lヤー

オフイシ Lャル Python MCP SDK (mcp>=1.0.0) via stdio

デー Lタ層

永続デー Lタベース

SQLAlchemy 2.0 ORM + S QLite (sqlite:///./bugpilot.db)

セキュリテイ

認証とRBAC

PyJWT (HS256) + Passlib (bcrypt) + ヘ Lダーベースのテナントスコーピン Lグ

品質

リフレクションとテスト

Reflection Agent Grounding + Pytest (329テス Lト、100%通過)

6. セッ Lトアップと実ガイ Lド

前提条件

  • Python 3.12+

  • Node.js 18+（フロンエンド用）

  • Groq APIキー（オプション — なくてもアプ Lリはローケ Lル O Lla Lma ま Lたは決定的モ Lドにフォ Lルバックして実行されます）

1. バックエンドのセッ Lトアップ

# Clone and enter project
git clone <repo-url> bugpilot
cd bugpilot

# Create and activate virtual environment
python -m venv .venv
# Windows: .\.venv\Scripts\activate | macOS/Linux: source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment (defaults to SQLite with zero setup)
cp .env.example .env
# Optional: add your GROQ_API_KEY to .env for live LLM responses

2. スタンドアロ Lン MC P サ Lバの実

# Windows
.\.venv\Scripts\python -m mcp_server.server

# macOS / Linux
.venv/bin/python -m mcp_server.server

3. Fas tAP I バックエンドの実

uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

デー Lタベースは最初の起動時に自動的に作作成お Lよびシ Lドされます — マ イグレーションのス Lテッ久は不要です。http://127.0.0.1:8000/api/v1/health お Lよび http://127.0.0.1:8000/docs で正常に動していることを確認してください。

4. フロンエンドのビル Lドお Lよび実

cd frontend
npm install
npm run dev

Vite 開発サ Lバは /api リクエス Lトをポ Lト 8000 の Fas tAP I バックエンドにプ Lロキシします（vite.config.ts を参照）。したがって、両方のサ Lバを同時に実する必要があります。

5. テス Lトス Lイトの実

# Run all unit and integration tests (329 tests)
pytest tests/unit tests/integration -q

テス Lト中は L L M 呼び出しはモ Lックされます（tests/conftest.py を参照）。したがって、Groq/Ollama 接続なしで決定的に実行されます。いくつかのテス Lトは新しい MC P サ Lバのサブプロセスを起動するため、全テス Lトス Lイトには数分かかります — これは想定内で、ハングではありません。

7. 評価お Lよび品質結果

BugPilot には自動評価ハーネス（evaluation/）が含まれており、23のクエリからなるゴ Lルデンデー Lタセ Lットに対して、意図の正確さ、ツール選択、グランドトルース性、幻覚率、トラジェク Lトリーの妥当性、指示従準、安全性、レ Lイテンシの 11 次元で手動評価なしでスコアリン Lグを行います。以下で自分自身で実してください:

python -m evaluation.run_eval

最新のコミット結果（evaluation_report.json）:

メトリックス

結果

タスク成功率

21 / 23 (91.3%)

幻覚率

0.0%

ツール呼び出し成功率

100%

エージェントルーティン Lグ精度

95.7%

平均レイテンシ

2.3s (P95: 4.6s)

通過しなかった 2 つのクエリは、意図ルーティン Lグの端境界事例（例：METRIC の代わりに COMPONENT_ANALYSIS と分類されたクエリ）であり、幻覚や失敗ではありません — エージェントは 23 のテス Lトケースのいずれでも情報を捏造していませ。

同時実行/負荷テス Lト（1–50 同時ユーザー）も evaluation/load_tester.py を介して含まれていま。最大 25 同時ユーザーまで、システムは 0% のエラ Lーレ Lトを維持します。50 同時ユーザーでは、エラ Lーレ Lトは約 66% に上昇し、現在のシング Lルインスタンス構成はまだ高同時実行の本番トラフィックに調整されてせん。以下の 既知の制限 を参照してくださ。

コ Lスト/ト Lークン数に関する注意: evaluation_report.json の estimated_total_cost_usd お Lよび average_tokens_per_query の値は、実 L際の Groq API 使用デー Lタではなく、単語数ベースの推定値です。大まかな指標として扱い、請 L求額としては扱わないでくださ。

8. 既知の制限

レビュアーのたあの透明明性の観点から:

  • 同時実行の上限 — 負荷テス Lトでは、50 同時ユーザーでエラーレートが急上昇します（上記参照）。現状ではデモ/小チーム用に適しています。大規模な本番トラフィックにはコネクションプーリング/非同期チューニングが必要です。

  • 推定（未測定）のトークン/コスト追跡 — 評価レポートのコスト数値は、単語数に基づくヒューリステックス推定値であり、実 L際の API 使用量計算ではありません。

  • 小さなゴールデン評価セット — 自動評価は 23 の代表的なクエリをカバーしています。より広範なカバレッジ（より多くの敵対的/プロンプトインジェクションケース、より多くのエッジケース）があれば、さらに信頼性が向上します。

  • generate_pdf.py はスタンドアロンのドキュメントエクスポートユーティリティで、Windows 固有のデフォルト出力パスを持ちます。macOS/Linux では明示的なファイル名引数を渡してください。

---.

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SQL MCP Server

    apoorva183
    F
    license
    Not graded
    quality
    D
    maintenance
    Exposes a SQLite database to AI assistants with structured, read-safe access. Includes five tools for schema exploration, querying, and sampling data.
    -

  • sqlite-analyst

    yogaibhh
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to explore and query SQLite databases through read-only tools, with defense-in-depth sandboxing preventing any data modifications.
    MIT

  • RepoImmune MCP Server

    Alex0AI
    A
    license
    C
    quality
    A
    maintenance
    Enables querying a repository's resolved bug history through six read-only tools, allowing agents to check patches against past failures, retrieve regression tests, and replay behavior cases to prevent regressions.
    6
    Apache 2.0

  • sql-guard-mcp

    egoring
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to safely query and explore SQLite databases through read-only, guard-protected tools that block writes, sensitive table access, and runaway queries.
    1
    MIT