Skip to content

Commit acb2479

Browse files
dsp-antdsp-ant
committed
Add argument completion and sampling specifications
The commit adds two new specification documents to MCP: argument completion for prompts/resources and sampling for LLM text generation. Argument completion enables servers to provide contextual suggestions for argument values, while sampling defines how servers can request LLM generations via clients with user approval and permission controls.
1 parent 28ef483 commit acb2479

File tree

2 files changed

+395
-0
lines changed

2 files changed

+395
-0
lines changed

‎docs/spec/completion.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
title: Argument Completion
3+
type: docs
4+
weight: 6
5+
---
6+
Argument Completion enables servers to provide argument completion for prompt and resource URI arguments. Clients can request completion options for specific arguments, and servers can return ranked suggestions. This allows clients to build rich user interfaces with intelligent argument completion for argument values.
7+
8+
> **_NOTE:_** Argument Completion in MCP is similar to traditional IDE argument completion - it provides contextual suggestions based on available options, rather than AI-powered completion. The server maintains a fixed set of valid values for each argument and returns matching suggestions based on partial input.
9+
10+
## Capabilities
11+
12+
Support for argument completion is not indicated by a dedicated capability - servers that expose prompts or resources with arguments implicitly support argument completion for those arguments. Clients may attempt argument completion requests for any prompt or resource argument.
13+
14+
## Concepts
15+
16+
### Completion References
17+
18+
When requesting completions, clients must specify what is being completed using a reference type:
19+
20+
- `ref/prompt`: References a prompt by name
21+
- `ref/resource`: References a resource by URI
22+
23+
The reference identifies the context for completion suggestions.
24+
25+
### Completion Results
26+
27+
Servers return an array of completion values ranked by relevance, with a maximum of 100 items per response. If more results are available beyond the first 100, servers MUST set `hasMore: true` in the response to indicate that additional results can be retrieved with subsequent requests. The optional `total` field allows servers to specify the complete number of matches available, even if not all are returned in a single response.
28+
29+
> **_NOTE:_** MCP does not currently support pagination of completion results - clients that need more than the first 100 matches must issue new completion requests with more specific argument values to narrow down the results.
30+
31+
## Use Cases
32+
33+
Common use cases for argument completion include:
34+
35+
### Prompt Argument Completion
36+
37+
A client requesting completion options for a prompt argument:
38+
39+
```json
40+
{
41+
"ref": {
42+
"type": "ref/prompt",
43+
"name": "code_review"
44+
},
45+
"argument": {
46+
"name": "language",
47+
"value": "py"
48+
}
49+
}
50+
```
51+
52+
The server might respond with language suggestions:
53+
54+
```json
55+
{
56+
"completion": {
57+
"values": ["python", "pytorch", "pyside", "pyyaml"],
58+
"total": 10,
59+
"hasMore": true
60+
}
61+
}
62+
```
63+
64+
### Resource URI Completion
65+
66+
A client completing a path in a resource URI template:
67+
68+
```json
69+
{
70+
"ref": {
71+
"type": "ref/resource",
72+
"uri": "file://{path}"
73+
},
74+
"argument": {
75+
"name": "path",
76+
"value": "/home/user/doc"
77+
}
78+
}
79+
```
80+
81+
The server could respond with matching paths:
82+
83+
```json
84+
{
85+
"completion": {
86+
"values": [
87+
"/home/user/documents",
88+
"/home/user/docker",
89+
"/home/user/downloads"
90+
],
91+
"hasMore": false
92+
}
93+
}
94+
```
95+
96+
## Diagram
97+
98+
The following diagram visualizes a typical argument completion interaction between client and server:
99+
100+
```mermaid
101+
sequenceDiagram
102+
participant Client
103+
participant Server
104+
105+
Note over Client,Server: Client requests completion options
106+
Client->>Server: completion/complete
107+
Server-->>Client: CompleteResult
108+
109+
Note over Client,Server: Client may request more specific results
110+
opt New completions requested
111+
Client->>Server: completion/complete
112+
Server-->>Client: CompleteResult
113+
end
114+
```
115+
116+
## Messages
117+
118+
This section defines the protocol messages for argument completion in the Model Context Protocol (MCP).
119+
120+
### Requesting Completions
121+
122+
#### Request
123+
124+
To get completion suggestions, the client MUST send a `completion/complete` request.
125+
126+
Method: `completion/complete`
127+
Params:
128+
- `ref`: A `PromptReference` or `ResourceReference` indicating what is being completed
129+
- `argument`: Object containing:
130+
- `name`: The name of the argument being completed
131+
- `value`: The current value to get completions for
132+
133+
Example:
134+
```json
135+
{
136+
"jsonrpc": "2.0",
137+
"id": 1,
138+
"method": "completion/complete",
139+
"params": {
140+
"ref": {
141+
"type": "ref/prompt",
142+
"name": "code_review"
143+
},
144+
"argument": {
145+
"name": "language",
146+
"value": "py"
147+
}
148+
}
149+
}
150+
```
151+
152+
#### Response
153+
154+
The server MUST respond with a `CompleteResult` containing:
155+
156+
- `completion`: Object containing:
157+
- `values`: Array of completion suggestions (maximum 100)
158+
- `total`: Optional total number of matches available
159+
- `hasMore`: Optional boolean indicating if additional results exist
160+
161+
Example:
162+
```json
163+
{
164+
"jsonrpc": "2.0",
165+
"id": 1,
166+
"result": {
167+
"completion": {
168+
"values": ["python", "pytorch", "pyside"],
169+
"total": 10,
170+
"hasMore": true
171+
}
172+
}
173+
}
174+
```
175+
176+
## Error Handling
177+
178+
Servers MUST return appropriate errors if:
179+
- The referenced prompt or resource does not exist
180+
- The argument name is invalid
181+
- Completion cannot be provided for other reasons
182+
183+
Clients SHOULD be prepared to handle cases where completion is temporarily unavailable or returns errors.
184+
185+
## Security Considerations
186+
187+
Implementations MUST carefully consider:
188+
- Rate limiting completion requests to prevent abuse
189+
- Access control for sensitive completion suggestions
190+
- Validation of completion inputs to prevent injection attacks

‎docs/spec/sampling.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
title: Sampling
3+
type: docs
4+
weight: 7
5+
description: "MCP protocol specification for language model sampling and text generation"
6+
draft: false
7+
params:
8+
author: Anthropic
9+
keywords: ["mcp", "sampling", "llm", "protocols"]
10+
---
11+
12+
Sampling enables servers to request generations from a language model via the client, enabling clients to have control over which model to use and what prompts are accepted. Clients can approve or reject incoming sampling requests, and control permissions around which servers can access which models. Servers can optionally request context from other MCP servers to be included in prompts. Because sampling requests go from server to client, this is the only request type in MCP that flows in this direction.
13+
14+
## Capabilities
15+
16+
Clients indicate support for sampling by including a `sampling` capability in their `ClientCapabilities` during initialization. The `sampling` capability SHOULD be an empty object:
17+
18+
```json
19+
{
20+
"capabilities": {
21+
"sampling": {}
22+
}
23+
}
24+
```
25+
26+
Servers SHOULD check for this capability before attempting to use sampling functionality.
27+
28+
## Concepts
29+
30+
### Sampling Request
31+
32+
A Sampling Request in the Model Context Protocol (MCP) represents a request from a server to generate text from a language model via the client. Each request contains messages to send to the model, optional system prompts, and sampling parameters like temperature and maximum tokens. The client has full discretion over which model to use and whether to approve the request.
33+
34+
### Message Content
35+
36+
Message content can be either text or images, allowing for multimodal interactions where supported by the model. Text content is provided directly as strings, while image content must be base64 encoded with an appropriate MIME type.
37+
38+
## Use Cases
39+
40+
Common use cases for sampling include generating responses in chat interfaces, code completion, and content generation. Here are some example sampling scenarios:
41+
42+
### Chat Response
43+
44+
A server requesting a chat response:
45+
46+
```json
47+
{
48+
"messages": [
49+
{
50+
"role": "user",
51+
"content": {
52+
"type": "text",
53+
"text": "What is the capital of France?"
54+
}
55+
}
56+
],
57+
"maxTokens": 100,
58+
"temperature": 0.7
59+
}
60+
```
61+
62+
### Image Analysis
63+
64+
A server requesting analysis of an image:
65+
66+
```json
67+
{
68+
"messages": [
69+
{
70+
"role": "user",
71+
"content": {
72+
"type": "image",
73+
"data": "base64_encoded_image_data",
74+
"mimeType": "image/jpeg"
75+
}
76+
},
77+
{
78+
"role": "user",
79+
"content": {
80+
"type": "text",
81+
"text": "Describe what you see in this image."
82+
}
83+
}
84+
],
85+
"maxTokens": 200
86+
}
87+
```
88+
89+
## Diagram
90+
91+
The following diagram visualizes the sampling request flow between
92+
server and client:
93+
94+
```mermaid
95+
sequenceDiagram
96+
participant Server
97+
participant Client
98+
participant User
99+
participant LLM
100+
101+
Note over Server,Client: Server requests sampling
102+
Server->>Client: sampling/createMessage
103+
opt User approval
104+
Client->>User: Request approval
105+
User-->>Client: Approve request
106+
end
107+
Client->>LLM: Forward request
108+
LLM-->>Client: Generated response
109+
opt User approval
110+
Client->>User: Review response
111+
User-->>Client: Approve response
112+
end
113+
Client-->>Server: CreateMessageResult
114+
```
115+
116+
## Messages
117+
118+
This section defines the protocol messages for sampling in the Model Context Protocol (MCP).
119+
120+
### Creating a Message
121+
122+
#### Request
123+
124+
To request sampling from an LLM via the client, the server MUST send a `sampling/createMessage` request.
125+
126+
Method: `sampling/createMessage`
127+
Params:
128+
- `messages`: Array of `SamplingMessage` objects representing the conversation history
129+
- `systemPrompt`: Optional system prompt to use
130+
- `includeContext`: Optional request to include context from MCP servers
131+
- `temperature`: Optional sampling temperature
132+
- `maxTokens`: Maximum tokens to generate
133+
- `stopSequences`: Optional array of sequences that will stop generation
134+
- `metadata`: Optional provider-specific metadata
135+
136+
Example:
137+
```json
138+
{
139+
"jsonrpc": "2.0",
140+
"id": 1,
141+
"method": "sampling/createMessage",
142+
"params": {
143+
"messages": [
144+
{
145+
"role": "user",
146+
"content": {
147+
"type": "text",
148+
"text": "What is the capital of France?"
149+
}
150+
}
151+
],
152+
"systemPrompt": "You are a helpful assistant.",
153+
"maxTokens": 100,
154+
"temperature": 0.7,
155+
"includeContext": "none"
156+
}
157+
}
158+
```
159+
160+
#### Response
161+
162+
The client MUST respond with a `CreateMessageResult` containing:
163+
164+
- `role`: The role of the message (always "assistant")
165+
- `content`: The generated content
166+
- `model`: The name of the model used
167+
- `stopReason`: Why generation stopped
168+
169+
Example:
170+
```json
171+
{
172+
"jsonrpc": "2.0",
173+
"id": 1,
174+
"result": {
175+
"role": "assistant",
176+
"content": {
177+
"type": "text",
178+
"text": "The capital of France is Paris."
179+
},
180+
"model": "gpt-4",
181+
"stopReason": "endTurn"
182+
}
183+
}
184+
```
185+
186+
## Error Handling
187+
188+
Clients MUST be prepared to handle both user rejection of sampling requests and model API errors. Common error scenarios include:
189+
190+
- User denies the sampling request
191+
- Model API is unavailable
192+
- Invalid sampling parameters
193+
- Context length exceeded
194+
195+
The client SHOULD return appropriate error responses to the server in these cases.
196+
197+
## Security Considerations
198+
199+
Implementations MUST carefully consider the security implications of allowing servers to request model generations, including:
200+
201+
- User consent and approval of sampling requests
202+
- Permissions around which servers can access which models
203+
- Content filtering and moderation
204+
- Rate limiting to prevent abuse
205+
- Privacy considerations around included context

0 commit comments

Comments
 (0)