DevContext

DevContext는 AI 코딩 어시스턴트와 엔지니어에게 런타임 관측 가능성 데이터(로그, 배포, 헬스 메트릭)를 제공하여 인시던트 트라이아지를 지원하는 프로토타입 Model Context Protocol(MCP) 서버이자 CLI 도구입니다.

개요

코딩 어시스턴트는 소스 저장소를 조사하고 수정안을 작성할 수 있지만, 런타임 인시던트(예: 최근 배포, 오류율 급증, 디스크 포화, 다운스트림 API 장애) 중 발생하는 상황에 대한 가시성은 부족한 경우가 많습니다. DevContext는 명령줄 인터페이스(CLI)와 표준 MCP 도구 호출을 통해 런타임 컨텍스트를 노출하는 개념 증명 도구입니다.

Related MCP server: Nibble

CLI 및 도구 명령

DevContext는 명령줄에서 직접 실행하거나 MCP 서버로 등록할 수 있습니다.

1. devcontext diagnose

내장된 데이터셋 또는 사용자 지정 파일/폴더를 대상으로 자동화된 인시던트 트래니지를 실행합니다:

# Diagnose built-in service dataset
devcontext diagnose --service order-processing

# Output raw JSON format
devcontext diagnose --service order-processing --json

# Point at custom log, deploy, and health paths (files or log directories)
devcontext diagnose --log-path /var/log/app/ --deploys-path deploys.json --health-path health.json

# Enable experimental Groq LLM extraction
devcontext diagnose --service order-processing --use-llm

2. devcontext serve

MCP 호스트(예: Claude Desktop, Antigravity)에 연결하기 위한 stdio MCP 서버를 시작합니다:

devcontext serve

로그 파싱 옵션

1. 결정적 파서 (parser.py): 휴리스틱을 사용하여 로그 줄을 샘플링하고 구조 일치(JSON-lines, CSV, key-value 쌍 또는 기본적인 대괄호/공백 구분 타임스탬프)를 시도합니다.

   • 한계: 단순한 단일 행 수준의 로그에 가장 적합합니다. 복잡한 여러 줄 스택 트레이스 또는 비표준 사용자 지정 형식은 기본적인 줄 일치로 폴백될 수 있습니다.

2. 실험적 LLM 추출 (extraction.py): 로그 청크를 Groq API(response_format={"type": "json_object"})에 전송하여 구조화 이벤트 객체를 추출합니다.

   • 한계: API 대기 시간(~200–400ms)과 토큰 비용이 발생합니다. API 키가 없거나 호출이 시간 초과되면 결정적 파서로 폴백됩니다.

데이터 소스 옵션

• 내장 Mock 데이터: 서비스 이름(예: service_name="order-processing")을 전달하면 포함된 데모 데이터를 조회합니다.

• 사용자 지정 파일 또는 디렉터리 경로:

  • log_path: 단일 로그 파일 또는 분할된 .log / .txt 파일이 있는 디렉터리의 경로입니다.

  • deploys_path: 사용자 지정 deploys.json 파일의 경로입니다.

  • health_path: 사용자 지정 health.json 파일의 경로입니다.

평가 및 테스트 시나리오

이 저장소에는 5개의 합성 테스트 시나리오로 검증된 평가 하네스(eval.py)가 포함되어 있습니다:

한계 및 범위

• 소규모 테스트 스위트: 이 평가 스위트는 검증을 위해 만들어진 5개의 합성 테스트 케이스로 구성되어 있습니다. 포괄적인 프로덕션 벤치마크는 아닙니다.

• 휴리스틱 매칭: diagnose()는 단순한 규칙(예: 첫 번째 오류 발생 최근 10분 내에 배포가 있었는지 확인)을 사용합니다. 실제 인프라 인시던트는 더 복잡하고 여러 가지 요인이 서로 상호 작용하는 경우가 많습니다.

아키텍처

┌─────────────────────────────────────────────────────────┐
│              CLI / MCP Clients                          │
│     (devcontext CLI / Claude Desktop / Antigravity)     │
└───────────────────────────┬─────────────────────────────┘
                            │ CLI Args / stdio JSON-RPC
┌───────────────────────────▼─────────────────────────────┐
│              DevContext Entry Point                     │
│               (cli.py / server.py)                      │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                 Diagnostic Core (tools.py)               │
└───────┬───────────────────┬─────────────────────┬───────┘
        │                   │                     │
┌───────▼───────────┐ ┌─────▼─────────────┐ ┌─────▼─────────────┐
│ Structure Parser  │ │ Deployment Engine │ │ Health Observer   │
│   (parser.py)     │ │ (deploys.json)    │ │ (health.json)     │
└───────┬───────────┘ └───────────────────┘ └───────────────────┘
        │
┌───────┴─────────────────────────────────────────┐
│  Groq API (Optional LLM log extraction)         │
└─────────────────────────────────────────────────┘

빠른 시작 및 설정

1. 설치

git clone https://github.com/your-username/devcontext.git
cd devcontext
pip install -e .

2. CLI로 서비스 진단

devcontext diagnose --service order-processing

3. MCP 서버로 등록 (Claude Desktop)

DevContext를 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "devcontext": {
      "command": "devcontext",
      "args": [
        "serve"
      ]
    }
  }
}

4. 평가 스위트 실행

python eval.py

5. 선택 API 키 설정

실험적 LLM 로그 추출에 Groq를 사용하는 경우 .env.example을 .env에 복사하세요:

cp .env.example .env

의존성 및 요구 사항

• Python 3.10+

• mcp (Model Context Protocol SDK)

• groq (선택, LLM 추출용)

향후 확장

• 플러그형 어댑터: CloudWatch, Datadog, Grafana Loki 또는 Prometheus API에 직접 연결.

• 확률적 신뢰 점수: 단일 결정적 문자열 대신 근본 확률 분포(예: 95% confidence: bad deploy)를 출력.

• 자동 롤백 제안: 진단과 함께 검증된 git revert 커밋 또는 Kubernetes 패치 스펙을 생성.

라이선스

MIT License에 따라 배포됩니다.