F
licenseNot graded
qualityD
maintenanceExposes a SQLite database to AI assistants with structured, read-safe access. Includes five tools for schema exploration, querying, and sampling data.
-
BugPilot MCP Server
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 |
|
| 이슈 키, 제목, 요약 또는 설명에서 키워드로 버그 검색. |
2 |
|
| 단일 버그의 전체 세부 정보(심각도, 우선순위, 근본 원인, 비즈니스 영향, 환경, 재현 단계, 수정 버전) 검색. |
3 |
|
| 집계된 버그 수, 열린 버그와 해결된 버그 분포, 심각도별 분류. |
4 |
|
| 월별 생성 대 해결 추세 및 과거 스프린트 완료 속도. |
5 |
|
| SLA 위험을 강조하기 위해 지연 일수 기준 내림차순으로 정렬된 열린 결함. |
6 |
|
| 해결됨/종료됨에서 열림/진행 중으로 전환된 결함( |
7 |
|
| 컴포넌트 수준 위험 점수(0–100), 활성 열린 이슈 수, 블래스트 반경 지표. |
8 |
|
| 수정 버전/릴리스 준비 상태 평가, 전체 위험 점수 및 배포 결정. |
9 |
|
| 상태 전환의 시간순 이력, 재개발 타임스탬프 및 개발자 토론 댓글. |
10 |
|
| 컴포넌트 컨텍스트, 기술적 근본 원인 또는 명시적으로 연결된 이슈 ID를 공유하는 관련 결함. |
3. 동적 ReAct 오케스트레이션 및 비교 분석
오케스트레이터 에이전트는 진정한 추론 + 행동 (ReAct) 루프로 작동합니다:
의도 및 도메인 외 가드레일 — 초기 검사는 LLM/도구 호출을 낭비하지 않고 비엔지니어링 쿼리를 필터링합니다.
동적 도구 선택 — LLM은 쿼리, 동적으로 발견된 도구 및 축적된 관찰 결과를 기반으로 각 작업(
CALL_TOOL,DELEGATE또는FINISH)을 결정합니다.반복적 다중 후보 검사 — 비교 및 순위 쿼리("인증 버그를 분석하고 가장 위험도가 높은 이슈 식별")의 경우
search_bugs가 후보를 발견하고, 오케스트레이터는FINISH를 허용하기 전에 각 후보 결함에 대해 반복적으로get_bug를 호출하여 전체 기술적 증거(근본 원인, 블래스트 반경, 재현 단계)가 수집되도록 합니다.차별화된 증거 기반 위험 점수 계산 — 심각도, 우선순위, 상태, 프로덕션 환경, 보안 영향(예: SOC2/세션 하이재킹) 및 기술적 근본 원인(예: 경쟁 조건, 크래시)을 평가합니다. 인위적인 100/100 동점을 피하기 위해 비포화 점수(0.0–99.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 ( |
도구 프로토콜 | 도구 계층 | 공식 Python MCP SDK ( |
데이터 계층 | 영구 데이터베이스 | SQLAlchemy 2.0 ORM + SQLite ( |
보안 | 인증 및 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 responses2. 독립형 MCP 서버 실행
# Windows
.\.venv\Scripts\python -m mcp_server.server
# macOS / Linux
.venv/bin/python -m mcp_server.server3. 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 devVite 개발 서버는 /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초) |
통과하지 못한 두 쿼리는 의도 라우팅의 경계 사례(예: METRIC 대신 COMPONENT_ANALYSIS로 분류된 쿼리)였으며, 환각이나 실패가 아닙니다. 에이전트는 23개 테스트 사례 중 어느 것에서도 정보를 조작하지 않았습니다.
동시성/부하 테스트(1–50명의 동시 사용자)도 evaluation/load_tester.py를 통해 포함되어 있습니다. 최대 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
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Sandbox workspace tools: search, file read, DB queries, integrations. Returns synthetic data.
- mcpOAuthcom.vibgrate
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
- dataOAuthco.thinair
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to explore and query SQLite databases through read-only tools, with defense-in-depth sandboxing preventing any data modifications.MIT
- AlicenseCqualityAmaintenanceEnables 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.6Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to safely query and explore SQLite databases through read-only, guard-protected tools that block writes, sensitive table access, and runaway queries.1MIT