Skip to content

Commit 80ed385

Browse files
zcklyzckly
committed
migrated specs
1 parent 5f8e53e commit 80ed385

File tree

12 files changed

+2558
-0
lines changed

12 files changed

+2558
-0
lines changed

‎mint.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,22 @@
104104
"api-reference/typescript/class-reference",
105105
"api-reference/typescript/type-definitions"
106106
]
107+
},
108+
{
109+
"group": "Specification",
110+
"pages": [
111+
"specification/overview",
112+
"specification/jsonrpc",
113+
"specification/lifecycle",
114+
"specification/prompts",
115+
"specification/resources",
116+
"specification/cancellation",
117+
"specification/logging",
118+
"specification/tools",
119+
"specification/completion",
120+
"specification/sampling",
121+
"specification/roots"
122+
]
107123
}
108124
],
109125
"footerSocials": {

‎specification/cancellation.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Cancellation
3+
---
4+
5+
MCP supports request cancellation through a dedicated notification message. This allows either party to signal that they are no longer interested in the result of an in-flight request.
6+
7+
## Cancellation Protocol
8+
9+
When a party wants to cancel a request, they send a "cancelled" notification containing the ID of the request they wish to cancel:
10+
11+
For example, initiating a request:
12+
13+
```json
14+
{
15+
"jsonrpc": "2.0",
16+
"id": "abc123",
17+
"method": "resources/read",
18+
"params": {
19+
"uri": "example://large-file"
20+
}
21+
}
22+
```
23+
24+
… then some time later, cancelling that request:
25+
26+
```json
27+
{
28+
"jsonrpc": "2.0",
29+
"method": "notifications/cancelled",
30+
"params": {
31+
"requestId": "abc123",
32+
"reason": "User interrupted operation"
33+
}
34+
}
35+
```
36+
37+
## Handling Cancellation
38+
39+
Upon receiving a cancellation notification, the receiver SHOULD:
40+
41+
1. Stop any processing related to the cancelled request
42+
2. Free any resources associated with that request
43+
3. Not send a response for the cancelled request (even if already computed)
44+
45+
However, due to race conditions and message latency:
46+
47+
- The notification may arrive after processing is complete
48+
- A response may already be in transit when cancellation is received
49+
- Multiple cancellation notifications for the same request ID may be received
50+
51+
## Special Cases
52+
53+
### Initialize Request
54+
55+
The client MUST NOT attempt to cancel its `initialize` request. Cancelling initialization leaves the protocol in an undefined state.
56+
57+
### Long-Running Operations
58+
59+
For long-running operations that support progress notifications, progress notifications SHOULD stop being sent after receiving cancellation.
60+
61+
## Best Practices
62+
63+
1. Implement cancellation handlers for all long-running operations
64+
2. Free resources promptly when receiving cancellation
65+
3. Make cancellation handling idempotent
66+
4. Include meaningful reason strings to aid debugging
67+
5. Log cancellations appropriately for troubleshooting

‎specification/completion.mdx‎

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

0 commit comments

Comments
 (0)