Skip to content

Commit 8953ffa

Browse files
dsp-antdsp-ant
authored
Merge pull request modelcontextprotocol#56 from modelcontextprotocol/davidsp/cleanup
docs refactoring
2 parents a3f6ab8 + 7addb7d commit 8953ffa

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+2429
-2696
lines changed

‎docs/.DS_Store

6 KB
Binary file not shown.

‎docs/spec/_index.md renamed to ‎docs/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ cascade:
77
_**NOTE:** This is a very early draft. Feel free to discuss changes, requirements, etc._
88

99
# Goal
10-
The Model Context Protocol (MCP) is an attempt to allow implementors to provide context to various LLM surfaces such as editors/IDEs, [claude.ai](https://claude.ai), etc., in a pluggable way. It separates the concerns of providing context from the LLM loop and its usage within.
10+
The Model Context Protocol (MCP) is an attempt to allow implementors to provide context to various LLM surfaces such as IDEs, [Claude Desktop](https://claude.ai/download) and others, in a pluggable way. It separates the concerns of providing context from the LLM loop and its usage within.
1111

1212
This makes it **much** easier for anyone to script LLM applications for accomplishing their custom workflows, without the application needing to directly offer a large number of integrations.
1313

‎docs/architecture/_index.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Architecture
3+
cascade:
4+
type: docs
5+
weight: 1
6+
---
7+
8+
The Model Context Protocol (MCP) follows a client-host-server architecture where each host can run multiple client instances. This architecture enables users to integrate AI capabilities across applications while maintaining clear security boundaries and isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused on context exchange and sampling coordination between clients and servers.
9+
10+
## Core Components
11+
12+
```mermaid
13+
graph TB
14+
subgraph "Application Host Process"
15+
H[Host]
16+
C1[Client 1]
17+
C2[Client 2]
18+
C3[Client 3]
19+
H --> C1
20+
H --> C2
21+
H --> C3
22+
end
23+
S1[Server 1<br>Files & Git]
24+
S2[Server 2<br>Database]
25+
S3[Server 3<br>External APIs]
26+
C1 --> S1
27+
C2 --> S2
28+
C3 --> S3
29+
```
30+
31+
### Host
32+
The host process acts as the container and coordinator:
33+
- Creates and manages multiple client instances
34+
- Controls client connection permissions and lifecycle
35+
- Enforces security policies and consent requirements
36+
- Handles user authorization decisions
37+
- Coordinates AI/LLM integration and sampling
38+
- Manages context aggregation across clients
39+
40+
### Clients
41+
Each client maintains an isolated server connection:
42+
- Establishes one stateful session per server
43+
- Handles protocol negotiation and capability exchange
44+
- Routes protocol messages bidirectionally
45+
- Manages subscriptions and notifications
46+
- Maintains security boundaries between servers
47+
48+
### Servers
49+
Servers provide specialized context and capabilities:
50+
- Expose resources, tools and prompts via MCP primitives
51+
- Operate independently with focused responsibilities
52+
- Request sampling through client interfaces
53+
- Must respect security constraints
54+
- Can be local processes or remote services
55+
56+
## Protocol Capabilities and Flow
57+
58+
The Model Context Protocol uses a capability-based negotiation system where clients and servers explicitly declare their supported features during initialization. Capabilities determine which protocol features and primitives are available during a session.
59+
60+
- Servers declare capabilities like resource subscriptions, tool support, and prompt templates
61+
- Clients declare capabilities like sampling support and notification handling
62+
- Both parties must respect declared capabilities throughout the session
63+
- Additional capabilities can be negotiated through protocol extensions
64+
65+
```mermaid
66+
sequenceDiagram
67+
participant Host
68+
participant Client
69+
participant Server
70+
71+
Host->>Client: Initialize client
72+
Client->>Server: Initialize session with capabilities
73+
Server-->>Client: Negotiate supported capabilities
74+
75+
Note over Host,Server: Active Session with Negotiated Features
76+
77+
alt Server Request (if sampling capable)
78+
Server->>Client: Request (sampling)
79+
Client->>Host: Forward to AI
80+
Host-->>Client: AI response
81+
Client-->>Server: Response
82+
else Client Request (based on server caps)
83+
Client->>Server: Request (tools/resources)
84+
Server-->>Client: Response
85+
else Notifications (if supported)
86+
Server--)Client: Resource updates
87+
Client--)Server: Status changes
88+
end
89+
90+
Host->>Client: Terminate
91+
Client->>Server: End session
92+
```
93+
94+
Each capability unlocks specific protocol features for use during the session. For example:
95+
- Resource subscriptions require the server to declare subscription support
96+
- Tool invocation requires the server to declare tool capabilities
97+
- Sampling requires the client to declare sampling support
98+
99+
This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility.
100+
101+
### Message Types
102+
MCP defines three core message types based on [JSON-RPC 2.0](https://www.jsonrpc.org/specification):
103+
104+
- **Requests**: Bidirectional messages with method and parameters expecting a response
105+
- **Responses**: Results or errors matching specific request IDs
106+
- **Notifications**: One-way messages requiring no response
107+
108+
Each message type follows the JSON-RPC 2.0 specification for structure and delivery semantics.
109+
110+
## Protocol Features
111+
112+
### Server Features
113+
Servers implement several foundational features that provide context and capabilities to clients:
114+
115+
- **Resources**: Structured data or content exposed via URIs that can be read and optionally subscribed to for updates
116+
- **Prompts**: Pre-defined templates or instructions that guide language model interactions
117+
- **Tools**: Executable functions that allow models to perform actions or retrieve information
118+
- **Utilities**: Helper features for logging, argument completion, and other ancillary functions
119+
120+
The server features focus on exposing data and functionality in a controlled way while maintaining security boundaries.
121+
122+
### Client Features
123+
Clients provide core features for interacting with servers and coordinating with hosts:
124+
125+
- **Sampling**: Ability to request and control language model interactions
126+
- **Root Directory Access**: Controlled exposure of filesystem locations to servers
127+
128+
The client features emphasize safe integration of server capabilities while protecting user privacy and security.

‎docs/basic/_index.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Base Protocol
3+
cascade:
4+
type: docs
5+
weight: 2
6+
---
7+
8+
The Model Context Protocol (MCP) defines a set of JSON-RPC methods for communication between clients and servers in AI-assisted applications. MCP uses [JSON-RPC 2.0](https://www.jsonrpc.org/specification) as its base protocol.
9+
10+
All messages in MCP **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines three fundamental types of messages:
11+
12+
| Type | Description | Requirements |
13+
|----------------|----------------------------------------|---------------------------------------|
14+
| `Requests` | Messages sent to initiate an operation | Must include unique ID and method name|
15+
| `Responses` | Messages sent in reply to requests | Must include same ID as request |
16+
| `Notifications`| One-way messages with no reply | Must not include an ID |
17+
18+
The Model Context Protocol consists of several key components that work together:
19+
20+
**Protocol Layers:**
21+
22+
- **Base Protocol**: Core JSON-RPC message types and fundamental operations such as capability exchange
23+
- **Lifecycle Management**: Connection initialization, capability negotiation, and session control
24+
- **Server Features**: Resources, prompts, and tools exposed by servers
25+
- **Client Features**: Sampling and root directory capabilities
26+
- **Utilities**: Cross-cutting concerns like logging and argument completion
27+
28+
All implementations **MUST** support the base protocol and lifecycle management components. Other components **MAY** be implemented based on the specific needs of the application.
29+
30+
These protocol layers establish clear separation of concerns while enabling rich interactions between clients and servers. The modular design allows implementations to support exactly the features they need.
31+
32+
### Model Context Protocol specific methods
33+
34+
MCP defines methods based on JSON-RPC that clients and servers implement:
35+
36+
{{< cards >}}
37+
{{< card link="lifecycle" title="Lifecycle" icon="refresh" >}}
38+
{{< card link="resources" title="Resources" icon="document" >}}
39+
{{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}
40+
{{< card link="tools" title="Tools" icon="adjustments" >}}
41+
{{< card link="logging" title="Logging" icon="annotation" >}}
42+
{{< card link="sampling" title="Sampling" icon="code" >}}
43+
{{< /cards >}}
44+
45+
### Authentication
46+
47+
Authentication mechanisms are not part of the core MCP specification. Implementations **MAY** provide authentication based on the transport they use.
48+
49+
## Specification
50+
51+
The official specification can be found in [TypeScript source](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.ts) and [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.json) formats. The TypeScript version serves as the source of truth, while the JSON Schema version is generated from it.

‎docs/basic/lifecycle.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: Lifecycle
3+
type: docs
4+
weight: 30
5+
---
6+
7+
{{< callout type="info" >}}
8+
**Protocol Revision**: 2024-11-05 (Final)
9+
{{< /callout >}}
10+
11+
The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server connections that ensures proper capability negotiation and state management. This lifecycle consists of four distinct phases:
12+
13+
1. **Initialization**: Capability negotiation and protocol version agreement
14+
2. **Ready**: Final confirmation before beginning operations
15+
3. **Operation**: Normal protocol communication
16+
4. **Shutdown**: Graceful termination of the connection
17+
18+
```mermaid
19+
sequenceDiagram
20+
participant Client
21+
participant Server
22+
23+
Note over Client,Server: Initialization Phase
24+
Client->>Server: initialize request
25+
Server-->>Client: initialize response
26+
Client--)Server: initialized notification
27+
28+
Note over Client,Server: Operation Phase
29+
activate Client
30+
activate Server
31+
rect rgb(200, 220, 250)
32+
note over Client,Server: Normal protocol operations
33+
end
34+
deactivate Client
35+
deactivate Server
36+
37+
Note over Client,Server: Shutdown Phase
38+
Client->>Server: shutdown request
39+
Server-->>Client: shutdown response
40+
Note over Client,Server: Connection closed
41+
```
42+
43+
## Lifecycle Phases
44+
45+
### 1. Initialization Phase
46+
47+
The initialization phase MUST be the first interaction between client and server. During this phase, the client and server:
48+
49+
- Establish protocol version compatibility
50+
- Exchange and negotiate capabilities
51+
- Share implementation details
52+
53+
The client MUST initiate this phase by sending an `initialize` request containing:
54+
55+
- Protocol version supported
56+
- Client capabilities
57+
- Client implementation information
58+
59+
```json
60+
{
61+
"jsonrpc": "2.0",
62+
"id": 1,
63+
"method": "initialize",
64+
"params": {
65+
"protocolVersion": "2024-11-05",
66+
"capabilities": {
67+
"roots": {
68+
"listChanged": true
69+
},
70+
"sampling": {}
71+
},
72+
"clientInfo": {
73+
"name": "ExampleClient",
74+
"version": "1.0.0"
75+
}
76+
}
77+
}
78+
```
79+
80+
The server MUST respond with its own capabilities and information:
81+
82+
```json
83+
{
84+
"jsonrpc": "2.0",
85+
"id": 1,
86+
"result": {
87+
"protocolVersion": "2024-11-05",
88+
"capabilities": {
89+
"prompts": {
90+
"listChanged": true
91+
},
92+
"resources": {
93+
"subscribe": true,
94+
"listChanged": true
95+
},
96+
"tools": {
97+
"listChanged": true
98+
}
99+
},
100+
"serverInfo": {
101+
"name": "ExampleServer",
102+
"version": "1.0.0"
103+
}
104+
}
105+
}
106+
```
107+
108+
#### Capability Negotiation
109+
110+
The initialization phase establishes which optional protocol features will be available during the session. Key capabilities include:
111+
112+
| Category | Capability | Description |
113+
|---------------|---------------|-----------------------------------------------|
114+
| Client | `roots` | Ability to provide filesystem roots |
115+
| Client | `sampling` | Support for LLM sampling requests |
116+
| Client | `experimental`| Support for non-standard experimental features|
117+
| Server | `prompts` | Offers prompt templates |
118+
| Server | `resources` | Provides readable resources |
119+
| Server | `tools` | Exposes callable tools |
120+
| Server | `logging` | Support for structured log messages |
121+
| Server | `experimental`| Support for non-standard experimental features|
122+
123+
Capabilities can include sub-capabilities like:
124+
- `listChanged`: Support for list change notifications (for prompts, resources, and tools)
125+
- `subscribe`: Support for subscriptions (resources only)
126+
127+
### 2. Ready Phase
128+
129+
After successful initialization, the client MUST send an `initialized` notification to indicate it is ready to begin normal operations:
130+
131+
```json
132+
{
133+
"jsonrpc": "2.0",
134+
"method": "initialized"
135+
}
136+
```
137+
138+
The server MUST NOT send any protocol messages besides the initialization response until it receives this notification.
139+
140+
### 3. Operation Phase
141+
142+
During the operation phase, the client and server exchange messages according to the negotiated capabilities. Both parties MUST:
143+
144+
- Respect the negotiated protocol version
145+
- Only use capabilities that were successfully negotiated
146+
- Handle messages according to the JSON-RPC 2.0 specification
147+
148+
### 4. Shutdown Phase
149+
The shutdown phase cleanly terminates the protocol connection. No specific shutdown messages are defined - instead, the underlying transport mechanism should be used to signal connection termination:
150+
151+
- For STDIO-based transport, the MCP server process should be terminated
152+
- For HTTP-based transport, the HTTP connection should be closed
153+
154+
## Error Handling
155+
156+
Implementations MUST handle these error cases:
157+
158+
- Protocol version mismatch
159+
- Required capability negotiation failure
160+
- Initialize request timeout
161+
- Shutdown request timeout
162+
163+
Server implementations are SHOULD implement appropriate timeouts for all lifecycle phases to prevent hung connections and resource exhaustion.
164+
165+
When errors occur during initialization, the server MUST respond with an appropriate error code and SHOULD close the connection.
166+
167+
Example initialization error:
168+
```json
169+
{
170+
"jsonrpc": "2.0",
171+
"id": 1,
172+
"error": {
173+
"code": -32600,
174+
"message": "Unsupported protocol version",
175+
"data": {
176+
"supported": ["2024-11-05"],
177+
"requested": "1.0.0"
178+
}
179+
}
180+
}
181+
```

0 commit comments

Comments
 (0)