핵심 아키텍처: BugPilot은 완전한 종단 간 분리 파이프라인으로 작동합니다: React / Vite → FastAPI 백엔드 → ReAct 오케스트레이터 → 전문 에이전트 → MCP 클라이언트 → MCP 서버 → 10개의 읽기 전용 도구 → SQLite 데이터베이스(합성 Jira 데이터).
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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: mcp-sqlite-manager
10개 도구는 모두 엄격하게 읽기 전용이며, 테넌트 범위(org_id)가 지정되고, MCP 프로토콜을 통해 동적으로 발견됩니다:
# | 도구 이름 | 필수/선택적 매개변수 | 설명 및 반환되는 증거 |
1 |
|
| 이슈 키, 제목, 요약 또는 설명에서 키워드로 버그 검색. |
2 |
|
| 단일 버그의 전체 세부 정보(심각도, 우선순위, 근본 원인, 비즈니스 영향, 환경, 재현 단계, 수정 버전) 검색. |
3 |
|
| 집계된 버그 수, 열린 버그와 해결된 버그 분포, 심각도별 분류. |
4 |
|
| 월별 생성 대 해결 추세 및 과거 스프린트 완료 속도. |
5 |
|
| SLA 위험을 강조하기 위해 지연 일수 기준 내림차순으로 정렬된 열린 결함. |
6 |
|
| 해결됨/종료됨에서 열림/진행 중으로 전환된 결함( |
7 |
|
| 컴포넌트 수준 위험 점수(0–100), 활성 열린 이슈 수, 블래스트 반경 지표. |
8 |
|
| 수정 버전/릴리스 준비 상태 평가, 전체 위험 점수 및 배포 결정. |
9 |
|
| 상태 전환의 시간순 이력, 재개발 타임스탬프 및 개발자 토론 댓글. |
10 |
|
| 컴포넌트 컨텍스트, 기술적 근본 원인 또는 명시적으로 연결된 이슈 ID를 공유하는 관련 결함. |
오케스트레이터 에이전트는 진정한 추론 + 행동 (ReAct) 루프로 작동합니다:
의도 및 도메인 외 가드레일 — 초기 검사는 LLM/도구 호출을 낭비하지 않고 비엔지니어링 쿼리를 필터링합니다.
동적 도구 선택 — LLM은 쿼리, 동적으로 발견된 도구 및 축적된 관찰 결과를 기반으로 각 작업(CALL_TOOL, DELEGATE 또는 FINISH)을 결정합니다.
반복적 다중 후보 검사 — 비교 및 순위 쿼리("인증 버그를 분석하고 가장 위험도가 높은 이슈 식별")의 경우 search_bugs가 후보를 발견하고, 오케스트레이터는 FINISH를 허용하기 전에 각 후보 결함에 대해 반복적으로 get_bug를 호출하여 전체 기술적 증거(근본 원인, 블래스트 반경, 재현 단계)가 수집되도록 합니다.
차별화된 증거 기반 위험 점수 계산 — 심각도, 우선순위, 상태, 프로덕션 환경, 보안 영향(예: SOC2/세션 하이재킹) 및 기술적 근본 원인(예: 경쟁 조건, 크래시)을 평가합니다. 인위적인 100/100 동점을 피하기 위해 비포화 점수(0.0–99.5)를 생성합니다.
반영 에이전트 품질 평가 — 생성된 보고서를 실제 MCP 데이터와 비교하여 환각을 방지하고 정확한 보고를 확인합니다.
테넌트 격리 — 모든 데이터베이스 레코드(issues, sprints, users, audit_logs)는 organization_id(예: org-acme)로 엄격하게 범위가 지정됩니다. 조직 간 데이터 접근은 리포지토리 및 MCP 계층에서 차단됩니다.
역할 기반 접근 제어 (RBAC):
관리자 — 전체 접근, 사용자 관리 및 이슈 관리.
엔지니어 / 개발자 — 이슈 생성, 업데이트, 전환 및 분석.
뷰어 — 이슈, 분석 및 보고서에 대한 읽기 전용 접근.
비밀 관리 — 비밀 키나 자격 증명이 하드코딩되지 않습니다. JWT 비밀, API 키 및 환경 변수는 엄격하게 .env에서 로드되며 버전 관리에서 제외됩니다.
계층 | 컴포넌트 | 기술 |
프론트엔드 | 대화형 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% 통과) |
Python 3.12+
Node.js 18+ (프론트엔드용)
Groq API 키 (선택 사항 — 키 없이도 앱이 실행되며 로컬 Ollama 또는 결정론적 모드로 폴백)
# 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# Windows
.\.venv\Scripts\python -m mcp_server.server
# macOS / Linux
.venv/bin/python -m mcp_server.serveruvicorn 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에서 정상 작동을 확인하세요.
cd frontend
npm install
npm run devVite 개발 서버는 /api 요청을 포트 8000의 FastAPI 백엔드로 프록시 처리하므로(vite.config.ts 참조), 두 서비스를 함께 실행해야 합니다.
# Run all unit and integration tests (329 tests)
pytest tests/unit tests/integration -q테스트 중에는 LLM 호출이 모킹되므로(tests/conftest.py 참조), Groq/Ollama 연결 없이도 결정론적으로 실행됩니다. 여러 테스트가 새 MCP 서버 하위 프로세스를 시작하기 때문에 전체 스위트를 실행하는 데 몇 분 정도 걸립니다. 이는 정상적인 현상이며 중단이 아닙니다.
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 사용 데이터가 아닙니다. 대략적인 지표로 간주하고 청구 수치로 사용하지 마십시오.
검토자를 위한 투명성을 위해 다음을 공개합니다:
동시성 한계 — 부하 테스트 결과 동시 사용자 50명에서 오류율이 급격히 증가합니다(위 참조). 현재 상태로는 데모/소규모 팀 사용에 적합합니다. 대규모 프로덕션 트래픽을 위해서는 연결 풀링/비동기 튜닝이 필요합니다.
추정된(측정되지 않은) 토큰/비용 추적 — 평가 보고서의 비용 수치는 단어 수를 기반으로 한 휴리스틱 추정치이며 실제 API 사용량 계산이 아닙니다.
작은 골든 평가 세트 — 자동화된 평가는 23개의 대표적인 쿼리를 다룹니다. 더 넓은 범위(더 많은 적대적/프롬프트 주입 사례, 더 많은 경계 사례)는 신뢰도를 더욱 강화할 것입니다.
generate_pdf.py 는 Windows 기본 출력 경로가 있는 독립형 문서화 내보내기 유틸리티입니다. macOS/Linux에서는 명시적인 파일명 인수를 전달하십시오.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
SEO research, audits, backlinks, GSC, and content workflow tools for AI agents.
Read-only tools over the Safer Agentic AI framework: 238 patterns + 14 heuristics.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PS-minalprasad/Bugpilot'
If you have feedback or need assistance with the MCP directory API, please join our Discord server