MCP 도구 주석

MCP 도구의 안전 메타데이터 — 읽기/쓰기/파괴적 힌트로 올바른 클라이언트 확인 UI 제공.

AACWorkflow에 의해 노출되는 모든 MCP 도구는 안전 메타데이터로 주석이 달려 있어서 MCP 클라이언트 (Claude, ChatGPT, 사용자 정의 도구)가 올바른 확인 UI를 렌더링하고 민감한 작업 호출 전 적절한 보호를 강제할 수 있습니다.

주석 유형

주석	의미	예시
`ReadOnlyHint`	상태 수정 안 함	`list_issues`, `get_issue`, `dashboard_usage_daily`
`DestructiveHint`	데이터 삭제 또는 덮어쓰기 가능	`delete_issue`, `delete_comment`
`IdempotentHint`	반복 호출이 추가 효과 없음	`update_issue`, `assign_issue_to_agent`
`OpenWorldHint`	외부 시스템 건드림	GitHub, Telegram 또는 제3자 API 호출 도구

도구 분류

도구	읽기만	파괴적	멱등	범위
`list_issues`	✓		✓	`issues:read`
`get_issue`	✓		✓	`issues:read`
`list_comments`	✓		✓	`comments:read`
`dashboard_usage_daily`	✓		✓	`dashboard:read`
`create_issue`				`issues:write`
`update_issue`			✓	`issues:write`
`comment_issue`				`comments:write`
`assign_issue_to_agent`			✓	`agents:write`
`trigger_autopilot`				`autopilot:run`
`delete_issue` (추가 시)		✓	✓	`issues:write`

클라이언트 동작

읽기만 도구

MCP 호스트는 읽기만 작업에 대해 확인을 요구하지 않습니다. 도구를 사용자 상호작용 없이 안전하게 호출할 수 있습니다.

파괴적 도구

파괴적 도구 호출 전 MCP 호스트는:

사용자 확인 요청 — 「이 issue를 삭제하시겠습니까?」
도구 인수에서 confirm: true 전달

서버는 confirm: true가 있는지 검증합니다. 없으면 호출이 400 Bad Request로 거부됩니다:

{
  "error": "confirm: true required for destructive operations"
}

멱등 도구

멱등 도구는 부작용 없이 안전하게 재시도될 수 있습니다. MCP 호스트는 여러 번 호출 (예: 일시적 장애 탄력성) 가능하며 동일한 결과를 얻습니다.

읽기-쓰기 도구 (비멱등)

create_issue 및 comment_issue 같이 새 엔티티를 생성하는 도구는 비멱등입니다. MCP 호스트는 실패 시 재시도하면 안 됩니다 — 중복 레코드 생성됩니다.

서버 강제

주석은 클라이언트에게 권고이지만 서버에서 권위입니다:

범위가 강제됨 — 파괴적 호출이 토큰이 issues:write 없으면 여전히 실패, 클라이언트 힌트와 무관하게
파괴적 플래그 검사됨 — 파괴적 도구에서 confirm: true 누락이 서버 측에서 거부됨
읽기만 쿼리가 감사됨 — 읽기만 호출도 규정 준수를 위해 로깅되지만 확인 필요 없음

예: 파괴적 도구 호출

클라이언트가 issue 삭제 원함. 흐름:

클라이언트가 도구 주석 확인하고 DestructiveHint: true 봄
클라이언트가 사용자에게 묻기: 「Issue AAC-42 삭제?」
사용자 확인
클라이언트가 confirm: true로 도구 호출

{
  "name": "delete_issue",
  "arguments": {
    "issue_id": "550e8400-e29b-41d4-a716-446655440000",
    "confirm": true
  }
}

서버 검증:

토큰이 issues:write 범위 가짐
confirm: true 존재
Issue가 존재하고 토큰 워크스페이스에 속함
사용자가 권한 가짐

모든 검사 통과 시 issue 삭제. 그 외 400 또는 403 오류 반환.

구현 주석

읽기만 도구 핸들러는 절대 Queries.Update* 또는 Delete* 메서드 호출 안 함. CI 테스트가 ReadOnlyHint: true로 태그된 모든 도구에 이 불변성 강제.

각 도구 핸들러가 그 주석으로 표시됨
주석이 MCP 서버 등록 시 MCP Tool 정의에 포함됨
동일 주석이 /tools introspection 엔드포인트로 반환되어 클라이언트가 능력 발견 가능
범위 검사가 토큰 계층에서 발생; 주석이 보완하지만 범위 강제 대체 안 함

감사 추적

모든 도구 호출 (읽기 또는 쓰기, 성공 또는 거부)이 커넥터 감사 로그에 기록됨:

{
  "tool": "delete_issue",
  "outcome": "denied",
  "reason": "destructive_flag_missing",
  "scopes_provided": ["issues:write"],
  "timestamp": "2025-06-22T15:30:00Z"
}

이를 통해 관리자가 어떤 도구가 호출되는지 모니터링하고 비정상 패턴 감지 가능.

이 페이지에서