완성

완성 (Completion)

서버가 프롬프트와 리소스 템플릿의 인자에 대한 자동 완성(autocompletion) 제안을 제공하는 표준화된 방법을 설명하는 페이지예요. 사용자가 특정 프롬프트(이름으로 식별)나 리소스 템플릿(URI로 식별)의 인자 값을 채우고 있을 때, 서버가 컨텍스트 기반 제안을 제공할 수 있어요.

출처: 문서

본문

Model Context Protocol (MCP)은 서버가 프롬프트와 리소스 템플릿의 인자에 대한 자동 완성 제안을 제공하는 표준화된 방법을 제공해요. 사용자가 특정 프롬프트(이름으로 식별)나 리소스 템플릿(URI로 식별)의 인자 값을 채우고 있을 때, 서버가 컨텍스트 기반 제안을 제공할 수 있어요.

참고 (Note): 간결함을 위해 이 페이지의 요청 예시는 _meta 요청 메타데이터(io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities)를 생략해요. 모든 요청은 MUST 필수 _meta 필드를 포함해야 해요. _meta를 참조하세요.

사용자 상호작용 모델 (User Interaction Model)

MCP의 완성은 IDE 코드 완성과 유사한 대화형 사용자 경험을 지원하도록 설계됐어요.

예를 들어 애플리케이션은 사용자가 입력할 때 드롭다운이나 팝업 메뉴로 완성 제안을 보여주고, 사용 가능한 옵션을 필터링·선택할 수 있게 해요.

하지만 구현자는 자신의 필요에 맞는 어떤 인터페이스 패턴으로든 완성을 노출할 자유가 있어요. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않아요.

기능 (Capabilities)

완성을 지원하는 서버는 MUST completions 기능을 선언해야 해요:

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

프로토콜 메시지 (Protocol Messages)

완성 요청하기 (Requesting Completions)

완성 제안을 얻으려면 클라이언트는 참조 유형(reference type)을 통해 무엇을 완성 중인지 지정하는 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": {
    "resultType": "complete",
    "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": {
    "resultType": "complete",
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

참조 유형 (Reference Types)

프로토콜은 두 가지 완성 참조 유형을 지원해요:

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

완성 결과 (Completion Results)

서버는 관련성 순으로 정렬된 완성 값 배열을 반환해요:

응답당 최대 100개 항목
사용 가능한 일치 항목의 선택적 총 개수
추가 결과가 존재하는지 나타내는 불리언

메시지 흐름 (Message Flow)

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

데이터 타입 (Data Types)

CompleteRequest

ref: PromptReference 또는 ResourceTemplateReference. ResourceTemplateReference의 경우 uri는 URI 또는 URI 템플릿이다.
argument: 다음을 포함하는 객체:
- name: 인자 이름
- value: 현재 값
context: 다음을 포함하는 객체:
- arguments: 이미 해결된 인자 이름에서 그 값으로의 매핑.

CompleteResult

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

오류 처리 (Error Handling)

서버는 SHOULD 일반적인 실패 사례에 표준 JSON-RPC 오류를 반환해야 해요:

메서드를 찾을 수 없음: -32601 (Capability not supported)
유효하지 않은 프롬프트 이름: -32602 (Invalid params)
필수 인자 누락: -32602 (Invalid params)
내부 오류: -32603 (Internal error)

구현 고려 사항 (Implementation Considerations)

서버는 SHOULD:
- 제안을 관련성 순으로 정렬해 반환한다
- 적절한 곳에 퍼지 매칭(fuzzy matching)을 구현한다
- 완성 요청에 비율 제한을 적용한다
- 모든 입력을 검증한다
클라이언트는 SHOULD:
- 빠른 완성 요청을 디바운스(debounce)한다
- 적절한 곳에 완성 결과를 캐시한다
- 누락되거나 부분적인 결과를 우아하게 처리한다

보안 (Security)

구현은 MUST:

모든 완성 입력을 검증한다
적절한 비율 제한을 구현한다
민감한 제안에 대한 접근을 통제한다
완성 기반 정보 노출을 방지한다

완성