Skip to main content
Glama
deenesjakoruzh
PS-minalprasad

BugPilot MCP Server

by PS-minalprasad
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BugPilot

基于AI的工程缺陷智能分析代理

核心架构：BugPilot运行在清晰的端到端解耦流水线上： React / Vite → FastAPI后端 → ReAct编排器 → 专业代理 → MCP客户端 → MCP服务器 → 10个只读工具 → SQLite数据库（合成Jira数据）。

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发现候选对象，编排器在允许FINISH之前迭代地对每个候选缺陷调用get_bug，确保收集完整的技术证据（根本原因、影响范围、复现步骤）。

  4. 差异化证据驱动的风险评分 — 评估严重程度、优先级、状态、生产环境、安全影响（例如SOC2/会话劫持）以及技术根本原因（例如竞态条件、崩溃）。生成非饱和评分（0.0–99.5），避免人为的100/100平局。

  5. 反思代理质量评估 — 根据真实MCP数据验证生成的报告，防止幻觉并确保准确报告。

4. 多租户与RBAC安全

  • 租户隔离 — 每条数据库记录（issues、sprints、users、audit_logs）均严格按organization_id（例如org-acme）限定范围。跨组织数据访问在存储库和MCP层被阻止。

  • 基于角色的访问控制（RBAC）：

    • 管理员 — 完全访问权限、用户管理和问题管理。

    • 工程师/开发者 — 创建、更新、转换和分析问题。

    • 查看者 — 对问题、分析和报告的只读访问权限。

  • 密钥管理 — 无硬编码的密钥或凭据。JWT密钥、API密钥和环境变量严格从.env加载，并排除在版本控制之外。

5. 技术栈

层

组件

技术

前端

交互式UI

React 18 + TypeScript + Vite

后端API

REST API服务器

FastAPI + Uvicorn + Pydantic v2

编排

代理循环

ReAct代理框架 + 专业委派

LLM网关

推理引擎

Groq API（llama-3.3-70b-versatile）主引擎 + 本地Ollama（llama3.1:8b）备用引擎

工具协议

工具层

官方Python MCP SDK（mcp>=1.0.0）通过stdio

数据层

持久化数据库

SQLAlchemy 2.0 ORM + SQLite（sqlite:///./bugpilot.db）

安全

认证与RBAC

PyJWT（HS256）+ Passlib（bcrypt）+ 基于请求头的租户范围限定

质量

反思与测试

反思代理基础验证 + Pytest（329个测试，100%通过）

6. 设置与执行指南

前提条件

  • Python 3.12+

  • Node.js 18+（用于前端）

  • Groq API密钥（可选 — 应用无需密钥即可运行，回退到本地Ollama或确定性模式）

1. 后端设置

# 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. 运行独立MCP服务器

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

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

3. 运行FastAPI后端

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

数据库在首次启动时自动创建并填充种子数据 — 无需迁移步骤。通过http://127.0.0.1:8000/api/v1/health和http://127.0.0.1:8000/docs验证其健康状态。

4. 构建并运行前端

cd frontend
npm install
npm run dev

Vite开发服务器将/api请求代理到端口8000上的FastAPI后端（参见vite.config.ts），因此两个服务需要同时运行。

5. 执行测试套件

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

LLM调用在测试期间被模拟（参见tests/conftest.py），因此测试套件无需Groq/Ollama连接即可确定性运行。由于多个测试会启动新的MCP服务器子进程，完整套件需要几分钟时间 — 这是预期行为，并非挂起。

7. 评估与质量结果

BugPilot附带一个自动化评估框架（evaluation/），该框架根据23个查询的黄金数据集对代理进行评分，涵盖11个维度 — 意图准确性、工具选择、基础验证、幻觉率、轨迹有效性、指令遵循、安全性和延迟 — 无需手动评分。使用以下命令自行运行：

python -m evaluation.run_eval

最新提交的结果（evaluation_report.json）：

指标

结果

任务成功率

21 / 23（91.3%）

幻觉率

0.0%

工具调用成功率

100%

代理路由准确率

95.7%

平均延迟

2.3秒（P95：4.6秒）

两个未通过的查询是意图路由的边缘情况（例如，查询被分类为COMPONENT_ANALYSIS而非METRIC），而非幻觉或失败 — 代理在23个测试用例中从未编造信息。

还通过evaluation/load_tester.py包含了一个并发/负载测试（1–50个并发用户）。在最多25个并发用户时，系统保持0%的错误率；在50个并发用户时，错误率上升至约66%，表明当前的单实例设置尚未针对高并发生产流量进行调优。请参见下面的已知限制。

关于成本/令牌数量的说明： evaluation_report.json中的estimated_total_cost_usd和average_tokens_per_query值是基于单词数量的估算值，而非真实的Groq API使用数据。请将其视为粗略指标，而非计费数据。

8. 已知限制

为便于审阅者了解情况：

  • 并发上限 — 负载测试显示，在50个并发用户时错误率急剧上升（见上文）。当前适用于演示/小团队使用；需要连接池/异步调优以应对更大的生产流量。

  • 估算（而非实测）的令牌/成本跟踪 — 评估报告中的成本数据是基于单词数量的启发式估算，而非真实的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