---
title: MCP 도구 레퍼런스
description: OpenTester MCP의 피드백 조회, 수정 작업 생성, PR 연결 도구 입력과 결과입니다.
---

# MCP 도구 레퍼런스

도구 입력은 JSON 객체입니다. 명시하지 않은 추가 필드는 허용하지 않으며, UUID 자리에는 실제 OpenTester 리소스 ID를 사용합니다. 모든 도구는 서버에 설정한 앱 하나만 대상으로 합니다.

| 도구                    | 필요한 토큰 권한   | 동작                    |
| ----------------------- | ------------------ | ----------------------- |
| `list_feedback`         | `feedback:read`    | 피드백 목록 조회        |
| `get_feedback`          | `feedback:read`    | 피드백 상세 조회        |
| `create_change_request` | `work-items:write` | 수정 작업 생성          |
| `list_change_requests`  | `work-items:read`  | 수정 작업 목록 조회     |
| `get_change_request`    | `work-items:read`  | 수정 작업 상세 조회     |
| `attach_pull_request`   | `work-items:write` | 기존 GitHub PR URL 연결 |

## 공통 결과

성공 시 REST API 응답 객체를 MCP의 `structuredContent`와 JSON 문자열인 텍스트 `content`로 반환합니다. 예를 들어 `get_feedback` 결과의 `structuredContent`는 `{ "feedback": { ... } }`입니다. 객체 전체 필드는 [피드백 API](/api/feedback)와 [수정 작업 API](/api/change-requests)에서 확인할 수 있습니다.

API 또는 통신 오류는 `isError: true`와 `error` 객체로 반환합니다. 입력 스키마 오류는 도구 실행 전에 MCP 계층에서 거절될 수 있습니다. 오류 코드와 복구 방법은 [오류 해결](/mcp/troubleshooting)을 참고하세요.

## `list_feedback`

피드백을 최신 생성 순으로 조회합니다. 선택 필터를 생략하면 해당 앱의 전체 피드백을 대상으로 합니다.

| 입력     | 형식         | 기본값 · 범위                          |
| -------- | ------------ | -------------------------------------- |
| `kind`   | 문자열, 선택 | `bug` 또는 `feedback`                  |
| `status` | 문자열, 선택 | `open`, `confirmed`, `fixed`, `closed` |
| `limit`  | 정수, 선택   | 기본 `20`, 최소 `1`, 최대 `50`         |
| `offset` | 정수, 선택   | 기본 `0`, 최소 `0`, 최대 `100000`      |

```json
{
  "kind": "bug",
  "status": "open",
  "limit": 10,
  "offset": 0
}
```

반환 구조는 `{ feedback: Feedback[], total, limit, offset }`입니다. 다음 페이지는 `offset + limit`으로 요청합니다. `total`은 필터에 일치하는 전체 건수입니다.

## `get_feedback`

```json
{
  "issueId": "22222222-2222-4222-8222-222222222222"
}
```

`issueId`는 필수 UUID입니다. `{ feedback: Feedback }`를 반환하며 제목, 설명, 재현 단계, 기대·실제 결과, 앱 버전, 기기 정보, 종류와 상태를 확인할 수 있습니다. 보고자의 이름·이메일이나 보상 내역은 반환하지 않습니다.

## `create_change_request`

하나 이상의 피드백을 수정 작업에 연결하고 목표를 기록합니다.

| 입력                 | 형식            | 제한                                 |
| -------------------- | --------------- | ------------------------------------ |
| `title`              | 문자열, 필수    | 앞뒤 공백 제거 후 `1–160`자          |
| `instructions`       | 문자열, 필수    | 앞뒤 공백 제거 후 `1–10000`자        |
| `acceptanceCriteria` | 문자열, 선택    | 최대 `10000`자, 생략 시 빈 문자열    |
| `issueIds`           | UUID 배열, 필수 | 같은 앱의 피드백 `1–20`개, 중복 불가 |
| `clientRequestId`    | UUID, 필수      | 이 작업 생성 요청의 재시도 식별자    |

```json
{
  "title": "오프라인에서 보고서 제출 실패 안내 개선",
  "instructions": "보고서 제출 중 네트워크 연결이 끊기면 입력 내용을 유지하고 재시도 안내를 보여 주세요.",
  "acceptanceCriteria": "네트워크 실패 후에도 입력이 유지되고, 연결 복구 후 동일 보고서를 한 번만 제출할 수 있어야 합니다.",
  "issueIds": ["22222222-2222-4222-8222-222222222222"],
  "clientRequestId": "33333333-3333-4333-8333-333333333333"
}
```

반환 구조는 `{ changeRequest: ChangeRequest }`이며 새 작업의 상태는 `open`, `pullRequestUrl`은 `null`입니다. 반환한 `changeRequest.id`를 이후 도구의 `changeRequestId`로 사용합니다.

::: warning 재시도 시 ID 유지
실제 요청마다 예시 UUID를 재사용하지 말고 새 작업용 UUID를 생성하세요. 같은 작업을 재시도할 때는 원래 `clientRequestId`와 입력을 유지합니다. 같은 앱·생성자·ID로 다른 내용을 보내면 `conflict`가 발생합니다. 다른 ID로 같은 문제를 요청하면 별도 작업이 생길 수 있으므로 생성 전에 기존 작업을 조회합니다.
:::

이 호출은 작업 기록을 저장합니다. 소스 코드를 수정하거나 에이전트 실행을 시작하지 않습니다.

## `list_change_requests`

```json
{
  "limit": 20,
  "offset": 0
}
```

두 입력은 선택 사항이며 범위는 `list_feedback`과 같습니다. `{ changeRequests: ChangeRequest[], total, limit, offset }`을 반환합니다. 목록은 생성 시각 기준 최신 순이며, 상태 필터는 제공하지 않습니다.

## `get_change_request`

```json
{
  "changeRequestId": "44444444-4444-4444-8444-444444444444"
}
```

필수 UUID 하나를 받으며 `{ changeRequest: ChangeRequest }`를 반환합니다. 작업 설명, 검증 기준, 연결한 피드백 ID, `open` 또는 `pr_linked` 상태와 PR URL을 확인할 수 있습니다.

## `attach_pull_request`

```json
{
  "changeRequestId": "44444444-4444-4444-8444-444444444444",
  "url": "https://github.com/example/android-app/pull/42"
}
```

| 입력              | 형식         | 제한                                                         |
| ----------------- | ------------ | ------------------------------------------------------------ |
| `changeRequestId` | UUID, 필수   | 수정 작업 ID                                                 |
| `url`             | 문자열, 필수 | 최대 `2048`자, `https://github.com/owner/repo/pull/양의정수` |

GitHub.com PR 주소만 지원합니다. 쿼리·해시·인증 정보·포트가 붙은 URL과 GitHub Enterprise·GitLab 주소는 허용하지 않습니다. 소유자와 저장소 이름은 소문자로 정규화하고 끝의 `/`는 제거해 저장합니다.

반환 구조는 `{ changeRequest: ChangeRequest }`이며 상태가 `pr_linked`로 변경됩니다. 작업당 PR은 하나입니다. 같은 URL을 다시 연결하는 것은 허용하지만 다른 URL을 연결하면 `conflict`가 발생합니다.

URL 연결은 GitHub의 PR 존재·소유권·병합 상태를 확인하지 않습니다. 피드백 상태와 보상도 변경하지 않습니다. 실제 PR 생성, 리뷰, 병합, 배포는 별도 GitHub·CI/CD 절차에서 수행합니다.