자동 완성

Completion · 원문: modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

MCP(Model Context Protocol)는 서버가 프롬프트와 리소스 템플릿의 인수에 대한 자동 완성 제안을 제공하기 위한 표준화된 방법을 제공합니다. 사용자가 특정 프롬프트(이름으로 식별) 또는 리소스 템플릿(URI로 식별)의 인수 값을 입력할 때, 서버는 컨텍스트에 맞는 제안을 제공할 수 있습니다.

사용자 상호작용 모델

MCP의 자동 완성은 IDE 코드 완성과 유사한 인터랙티브한 사용자 경험을 지원하도록 설계되어 있습니다.

예를 들어, 애플리케이션은 사용자가 입력하는 동안 드롭다운이나 팝업 메뉴에 완성 제안을 표시하고, 사용 가능한 옵션을 필터링하고 선택할 수 있도록 할 수 있습니다.

단, 구현체는 필요에 맞는 어떤 인터페이스 패턴으로든 자동 완성을 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.

기능(Capabilities)

자동 완성을 지원하는 서버는 completions 기능을 반드시 선언해야 합니다(MUST).

코드 · 명령

{
  "capabilities": {
    "completions": {}
  }
}

프로토콜 메시지

완성 요청

완성 제안을 얻기 위해 클라이언트는 참조 타입을 통해 완성할 대상을 지정하는 completion/complete 요청을 보냅니다.

요청:

코드 · 명령

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "language",
      "value": "py"
    }
  }
}

응답:

코드 · 명령

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}

여러 인수를 가진 프롬프트나 URI 템플릿의 경우, 클라이언트는 후속 요청에 컨텍스트를 제공하기 위해 이전 완성 결과를 context.arguments 객체에 포함해야 합니다.

요청:

코드 · 명령

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "framework",
      "value": "fla"
    },
    "context": {
      "arguments": {
        "language": "python"
      }
    }
  }
}

응답:

코드 · 명령

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

참조 타입

프로토콜은 두 가지 완성 참조 타입을 지원합니다.

Type	Description	Example
`ref/prompt`	References a prompt by name	`{"type": "ref/prompt", "name": "code_review"}`
`ref/resource`	References a resource URI	`{"type": "ref/resource", "uri": "file:///{path}"}`

완성 결과

서버는 관련성 순으로 정렬된 완성 값의 배열을 반환합니다.

응답당 최대 100개 항목
사용 가능한 전체 일치 수(선택 사항)
추가 결과 존재 여부를 나타내는 불리언(boolean)

메시지 흐름

코드 · 명령

sequenceDiagram
    participant Client
    participant Server

    Note over Client: User types argument
    Client->>Server: completion/complete
    Server-->>Client: Completion suggestions

    Note over Client: User continues typing
    Client->>Server: completion/complete
    Server-->>Client: Refined suggestions

데이터 타입

CompleteRequest

ref: PromptReference 또는 ResourceReference
argument: 다음을 포함하는 객체:
name: 인수 이름
value: 현재 값
context: 다음을 포함하는 객체:
arguments: 이미 해결된 인수 이름과 값의 매핑

CompleteResult

completion: 다음을 포함하는 객체:
values: 제안 배열 (최대 100개)
total: 선택적 전체 일치 수
hasMore: 추가 결과 플래그

오류 처리

서버는 일반적인 실패 사례에 대해 표준 JSON-RPC 오류를 반환해야 합니다(SHOULD).

메서드를 찾을 수 없음: -32601 (기능 미지원)
잘못된 프롬프트 이름: -32602 (Invalid params)
필수 인수 누락: -32602 (Invalid params)
내부 오류: -32603 (Internal error)

구현 고려 사항

서버는 다음을 수행해야 합니다(SHOULD). * 관련성 순으로 정렬된 제안 반환 * 적절한 경우 퍼지 매칭(fuzzy matching) 구현 * 완성 요청 속도 제한 * 모든 입력 검증
클라이언트는 다음을 수행해야 합니다(SHOULD). * 빠른 완성 요청 디바운스(debounce) 처리 * 적절한 경우 완성 결과 캐시 * 누락되거나 부분적인 결과를 우아하게 처리

보안

구현체는 다음을 반드시 수행해야 합니다(MUST).

모든 완성 입력 검증
적절한 속도 제한 구현
민감한 제안에 대한 접근 제어
완성 기반 정보 노출 방지

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion

문서 이동

‹ 프롬프트 로깅 › · 전체 목차