Oboe MCP

코딩 에이전트를 위한 구조화된 일대일(one-by-one) 워크플로우.

코딩 에이전트를 위해 우선순위가 지정된 세션 상태를 갖춘, 지속 가능한 일대일 검토 워크플로우용 MCP 서버입니다.

우선순위가 지정된 세션 파일에서 항목을 생성, 탐색 및 해결하기 위한 16가지 도구를 제공합니다. 여기에는 차단된 항목 처리, 승인 업데이트, 중첩된 하위 세션 등이 포함되어 /obo 워크플로우가 원시 JSON 편집 대신 MCP 작업을 사용할 수 있도록 합니다.

AGPL-3.0-or-later 라이선스가 적용되며 상업용 라이선스도 이용 가능합니다. 전체 약관은 LICENSE를 참조하십시오.

PyPI 패키지

다음 대안 중 하나를 사용하여 PyPI에서 Oboe MCP를 직접 설치하거나 실행하십시오:

• 설치 없이 실행: uvx oboe-mcp

• 현재 환경에 설치: pip install oboe-mcp

oboe-mcp를 설치하면 oboe-cli 명령어도 함께 설치됩니다:

# After pip install oboe-mcp
oboe-cli --help

# From PyPI 
uvx --from oboe-mcp oboe-cli --help

# From a local checkout (no install needed)
uvx --from /path/to/oboe-mcp oboe-cli --help

CLI 참조 (oboe-cli)

oboe-mcp를 설치하면 MCP 도구가 작동하는 동일한 세션 파일을 위한 사용자 친화적인 명령줄 도구인 oboe-cli도 함께 설치됩니다.

oboe-cli [--session SESSION] [--base-dir DIR] COMMAND [ARGS...]

전역 옵션:

Base-dir 자동 감지: --base-dir이 생략되면 oboe-cli는 .github/obo_sessions/ 폴더가 포함된 경우 현재 작업 디렉토리를 사용하며, 그렇지 않으면 현재 작업 디렉토리를 그대로 사용합니다.

명령어

빠른 시작

# Create a session from a JSON items file
oboe-cli --base-dir /path/to/project create \
    --title "Code review findings" \
    --input-file findings.json

# List sessions
oboe-cli --base-dir /path/to/project sessions

# Work through items
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json next
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
    in-progress 1
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
    complete 1 "Fixed the validation bug"

참고: 이전 버전에 포함되었던 obo_helper.py 스크립트는 이제 oboe-cli로 위임하는 얇은 폐기 예정(deprecation) 심입니다.

OBO 세션을 사용하는 이유

일대일(One-by-One) 세션은 단순한 채팅 메모가 아닙니다. 이는 다중 항목 작업을 지속 가능하고 순서가 지정된 상호작용 세션으로 처리하기 위한 워크플로우 모델입니다.

일반 채팅이나 에이전트의 내장된 후속 질문과 비교했을 때, OBO는 다음과 같은 기능을 추가로 제공합니다:

• 에이전트가 범위, 항목 수, 주요 범주 및 제안된 실행 순서로 시작할 수 있는 개요 우선 워크플로우

• 채팅에 나타난 순서가 아닌 긴급성, 중요도, 노력 및 의존성 압력에 따른 명시적 우선순위 재지정

• pending, in_progress, deferred, blocked, completed, skipped를 통한 지속 가능한 수명 주기 상태

• approval_status, approval_mode, approved_at, approval_note를 통한 별도의 승인 메타데이터

• 차단된 작업이 활성 대기열에서 조용히 사라지는 대신 표시되고 설명될 수 있도록 하는 차단자 메타데이터 저장

• 상위 세션을 일시 중지하고 하위 문제를 처리한 다음 상위 세션을 깔끔하게 재개하는 중첩된 하위 세션

• 세션 나열, 생성, 검사, 병합, 일시 중지, 재개 및 닫기를 명명된 워크플로우 객체로 관리하는 일류 세션 수명 주기 관리

• 모델 재시작, 편집기 다시 로드 또는 에이전트 교체 후 결정론적 복구

• 대화 메모리에 의존하는 대신 세션 파일에 기계가 읽을 수 있는 감사 추적 저장

이는 작업이 많은 발견 사항을 포함하거나, 명시적인 사용자 승인이 필요하거나, 중간 하위 조사에 의존하거나, 여러 에이전트 턴에 걸쳐 유지되어야 할 때 가장 중요합니다. 채팅은 대화에 적합합니다. 구조화된 질문 도구는 현재 턴에서 깔끔한 답변을 얻는 데 적합합니다. OBO는 지속 가능한 워크플로우 오케스트레이션을 위한 것입니다.

제어된 순차적 처리, 지속 가능한 대기열 상태 또는 중첩된 하위 작업이 필요할 때 OBO를 사용하십시오. 작업이 너무 작아 전체 워크플로우 객체가 가치보다 오버헤드를 더 많이 추가할 때는 일반 채팅을 사용하십시오.

상태 모델

OBO는 각 항목을 두 개의 독립적인 축에서 추적합니다.

수명 주기 축

• pending: 작업이 대기 중이지만 아직 시작되지 않음

• in_progress: 현재 활발히 작업 중

• deferred: 나중에 실행하도록 승인되었으며 활성 검토 패스가 소진되거나 사용자가 명시적으로 연기된 작업을 요청할 때까지 즉각적인 검토 대기열에서 제외되어야 함

• blocked: 외부 의존성이나 하위 문제가 해결될 때까지 작업을 계속할 수 없음

• completed: 작업이 완료되고 닫힘

• skipped: 의도적으로 실행되지 않음

승인 축

• unreviewed: 아직 명시적인 사용자 결정이 기록되지 않음

• approved: 사용자가 작업을 승인함

• denied: 사용자가 작업을 명시적으로 거부함

승인 메타데이터 필드:

• approval_status: 항목에 대한 승인 결정

• approval_mode: 승인 타이밍 결정이 기록되었을 때 immediate 또는 delayed

• approved_at: 승인이 기록된 타임스탬프

• approval_note: 승인 결정에 대한 선택적 자유 텍스트 메모

일반적인 조합:

• 즉시 승인: obo_set_approval(..., approval_status="approved", approval_mode="immediate") 호출; 항목은 일반적으로 작업이 시작되거나 in_progress로 이동될 때까지 pending 상태로 유지됨

• 지연 승인: obo_set_approval(..., approval_status="approved", approval_mode="delayed") 호출; 이는 지연 승인을 기록하고 항목을 deferred로 이동함

• 거부: approval_status=denied 설정; 항목이 대기열에서 닫히는 경우 status=skipped와 함께 사용

상호작용 모드

세 가지 일반적인 상호작용 패턴은 일반 채팅, 구조화된 질문 도구, 전체 OBO 세션입니다. 이들은 서로 다른 문제를 해결합니다.

예시 진행:

• 일반 채팅: 에이전트가 산문으로 여러 발견 사항을 나열하고 대화 자체가 처리된 내용의 유일한 기록이 됩니다.

• askQuestions: 에이전트가 깔끔한 메뉴 선택을 요청할 수 있지만, 다른 곳에 저장하지 않는 한 지속적인 항목 대기열이 없습니다.

• OBO 세션: 에이전트가 개요로 시작하고, 전체 항목 목록을 저장하고, 의도적으로 순서를 정하고, 승인, 건너뛰기 및 차단자를 기록하며, 채팅 기록에서 세션을 재구성할 필요 없이 나중에 재개할 수 있습니다.

장난감 예시: 5가지 검토 항목

에이전트가 작은 장난감 할 일 앱을 검토하고 이 원시 발견 순서대로 5가지 항목을 찾았다고 가정합니다:

1. UI의 모호한 설정 레이블 개선.

2. 백그라운드 동기화 작업의 경합 조건 해결.

3. 중복 작업 ID에 대한 회귀 테스트 추가.

4. create-task 엔드포인트에 누락된 입력 유효성 검사 추가.

5. 로그인 핸들러의 비밀번호 로깅 수정.

일반 채팅

에이전트:

장난감 앱에서 5가지 문제를 발견했습니다: 문제 1: UI의 모호한 설정 레이블 개선. 문제 2: 백그라운드 동기화 작업의 경합 조건 해결. 문제 3: 중복 작업 ID에 대한 회귀 테스트 추가. 문제 4: create-task 엔드포인트에 누락된 입력 유효성 검사 추가. 문제 5: 로그인 핸들러의 비밀번호 로깅 수정.

다음에 무엇을 하시겠습니까?

사용자:

4번과 2번을 먼저 하세요.

해설:

• 빠르지만 채팅 자체가 순서의 유일한 기록이 되며, 4번과 3번 항목 간의 의존성은 암시적입니다.

• 다른 문제의 상태는 캡처되지 않으며, 사용자는 에이전트가 다른 문제를 표시하거나 작업하도록 명시적으로 요청해야 합니다.

• 세션이 중단되면 다른 에이전트가 기록에서 상태를 재구성해야 합니다.

askQuestions 스타일 채팅

에이전트:

5가지 문제를 발견했습니다. 무엇을 먼저 할까요?

옵션: • 4. create-task 엔드포인트에 누락된 입력 유효성 검사 추가 • 2. 백그라운드 동기화 작업의 경합 조건 해결 • 5. 로그인 핸들러의 비밀번호 로깅 수정 • 3. 중복 작업 ID에 대한 회귀 테스트 추가 • 1. UI의 모호한 설정 레이블 개선

사용자:

4

에이전트:

다음 작업은?

옵션: • 2번 계속 • 남은 목록 재정렬 • 중지

해설:

• 일반 채팅보다 깔끔한 사용자 선택을 제공하지만, 도구는 여전히 그 자체로 지속 가능하고 의존성을 인식하는 워크플로우 객체를 생성하지 않습니다.

• 다른 문제의 상태는 여전히 캡처되지 않으며, 사용자는 에이전트가 다른 문제를 표시하거나 작업하도록 명시적으로 요청해야 합니다.

• 마찬가지로 세션이 중단되면 다른 에이전트가 기록에서 상태를 재구성해야 합니다.

일대일(One-by-One) 세션

OBO 에이전트 프롬프트 지침에 따라 에이전트는 다음과 같은 순서 논리를 할당합니다:

• 항목 4가 먼저 진행됩니다. 후속 회귀 테스트를 작성하기 전에 create-task 엔드포인트 동작을 안정화해야 하기 때문입니다.

• 항목 2가 다음에 옵니다. 경합 조건이 동기화 흐름 전반의 정확성에 영향을 미칠 수 있고 중첩된 조사 세션이 필요할 수 있기 때문입니다.

• 항목 5가 뒤따릅니다. 중요한 보안 수정 사항이지만 유효성 검사 및 동시성 작업을 차단하지는 않기 때문입니다.

• 항목 3은 항목 4 뒤에 유지됩니다. 회귀 테스트가 앞서기보다는 최종 유효성 검사 동작을 고정해야 하기 때문입니다.

• 항목 1은 여전히 유용하지만 다른 4개