Skip to content

Commit d0d5730

Browse files
Copilot0xrinegade
Copilot
and
0xrinegade
committed
Implement proper MCP JSON-RPC 2.0 specification compliance
Co-authored-by: 0xrinegade <[email protected]>
1 parent abe387c commit d0d5730

File tree

5 files changed

+469
-61
lines changed

5 files changed

+469
-61
lines changed

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,26 @@ The Solana MCP Server supports dynamic scaling to handle variable load efficient
9191
- **Kubernetes HPA** with CPU, memory, and custom metrics
9292
- **Docker scaling** guidelines and automation scripts
9393
- **Health checks** at `/health` endpoint
94+
- **MCP JSON-RPC API** for web service integration
95+
96+
### Web Service API
97+
98+
The server now supports both traditional stdio transport and HTTP JSON-RPC mode:
99+
100+
```bash
101+
# Run as stdio transport (default)
102+
solana-mcp-server stdio
103+
104+
# Run as web service
105+
solana-mcp-server web --port 3000
106+
```
107+
108+
**API Endpoints:**
109+
- `POST /api/mcp` - Full MCP JSON-RPC 2.0 API
110+
- `GET /health` - Health check with capability information
111+
- `GET /metrics` - Prometheus metrics
112+
113+
**[📚 Complete MCP JSON-RPC API Documentation](./docs/mcp-json-rpc-api.md)**
94114

95115
### Metrics Exposed
96116
- `solana_mcp_rpc_requests_total` - Total RPC requests by method and network

‎docs/mcp-json-rpc-api.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
# MCP JSON-RPC API Specification
2+
3+
This document describes the Model Context Protocol (MCP) JSON-RPC API implementation for the Solana MCP Server.
4+
5+
## Overview
6+
7+
The Solana MCP Server implements the full MCP JSON-RPC 2.0 specification, providing a standards-compliant interface for AI clients to interact with the Solana blockchain.
8+
9+
## API Endpoints
10+
11+
### HTTP Web Service Mode
12+
13+
When running in web service mode, the server exposes the following endpoints:
14+
15+
- `POST /api/mcp` - MCP JSON-RPC 2.0 API endpoint
16+
- `GET /health` - Health check and capability information
17+
- `GET /metrics` - Prometheus metrics (Prometheus format)
18+
19+
## MCP JSON-RPC 2.0 Specification
20+
21+
All MCP requests and responses follow the JSON-RPC 2.0 specification with MCP-specific extensions.
22+
23+
### Request Format
24+
25+
```json
26+
{
27+
"jsonrpc": "2.0",
28+
"id": 1,
29+
"method": "methodName",
30+
"params": {
31+
// Method-specific parameters
32+
}
33+
}
34+
```
35+
36+
### Response Format
37+
38+
#### Success Response
39+
```json
40+
{
41+
"jsonrpc": "2.0",
42+
"id": 1,
43+
"result": {
44+
// Method-specific result data
45+
}
46+
}
47+
```
48+
49+
#### Error Response
50+
```json
51+
{
52+
"jsonrpc": "2.0",
53+
"id": 1,
54+
"error": {
55+
"code": -32603,
56+
"message": "Internal error",
57+
"data": {
58+
"protocolVersion": "2024-11-05"
59+
}
60+
}
61+
}
62+
```
63+
64+
## Content Types
65+
66+
The MCP specification supports multiple content types with optional annotations:
67+
68+
### Text Content
69+
```json
70+
{
71+
"type": "text",
72+
"text": "Content text here",
73+
"annotations": {
74+
"audience": ["user", "assistant"],
75+
"priority": 0.8,
76+
"lastModified": "2024-01-15T10:00:00Z"
77+
}
78+
}
79+
```
80+
81+
### Image Content
82+
```json
83+
{
84+
"type": "image",
85+
"data": "base64-encoded-image-data",
86+
"mimeType": "image/png",
87+
"annotations": {
88+
"audience": ["user"],
89+
"priority": 1.0
90+
}
91+
}
92+
```
93+
94+
### Resource Content
95+
```json
96+
{
97+
"type": "resource",
98+
"resource": {
99+
"uri": "https://example.com/resource",
100+
"mimeType": "application/json"
101+
},
102+
"annotations": {
103+
"priority": 0.5
104+
}
105+
}
106+
```
107+
108+
## Annotations
109+
110+
Annotations provide metadata about content objects:
111+
112+
- `audience`: Array of intended recipients (`["user", "assistant"]`)
113+
- `priority`: Importance level (0.0 = least important, 1.0 = most important)
114+
- `lastModified`: ISO 8601 timestamp of last modification
115+
116+
## Error Codes
117+
118+
Standard JSON-RPC 2.0 error codes are used:
119+
120+
- `-32700`: Parse error
121+
- `-32600`: Invalid Request
122+
- `-32601`: Method not found
123+
- `-32602`: Invalid params
124+
- `-32603`: Internal error
125+
- `-32002`: Server not initialized (MCP-specific)
126+
127+
## Health Check Response
128+
129+
The `/health` endpoint returns detailed server information:
130+
131+
```json
132+
{
133+
"status": "ok",
134+
"service": "solana-mcp-server",
135+
"version": "1.0.2",
136+
"protocol": "2024-11-05",
137+
"capabilities": {
138+
"tools": true,
139+
"resources": true,
140+
"prompts": false,
141+
"sampling": false
142+
}
143+
}
144+
```
145+
146+
## Headers
147+
148+
### Request Headers
149+
- `Content-Type: application/json` (required)
150+
- `Accept: application/json` (recommended)
151+
152+
### Response Headers
153+
- `Content-Type: application/json`
154+
- `X-MCP-Version: 2024-11-05` (protocol version)
155+
- `Cache-Control: no-cache`
156+
157+
## Client Usage Examples
158+
159+
### Python Example
160+
```python
161+
import requests
162+
import json
163+
164+
# Initialize MCP session
165+
init_request = {
166+
"jsonrpc": "2.0",
167+
"id": 1,
168+
"method": "initialize",
169+
"params": {
170+
"protocolVersion": "2024-11-05",
171+
"capabilities": {},
172+
"clientInfo": {
173+
"name": "my-client",
174+
"version": "1.0.0"
175+
}
176+
}
177+
}
178+
179+
response = requests.post(
180+
"http://localhost:3000/api/mcp",
181+
headers={"Content-Type": "application/json"},
182+
json=init_request
183+
)
184+
185+
print(response.json())
186+
```
187+
188+
### JavaScript Example
189+
```javascript
190+
const mcpRequest = {
191+
jsonrpc: "2.0",
192+
id: 2,
193+
method: "tools/call",
194+
params: {
195+
name: "getBalance",
196+
arguments: {
197+
pubkey: "11111111111111111111111111111112"
198+
}
199+
}
200+
};
201+
202+
fetch("http://localhost:3000/api/mcp", {
203+
method: "POST",
204+
headers: {
205+
"Content-Type": "application/json"
206+
},
207+
body: JSON.stringify(mcpRequest)
208+
})
209+
.then(response => response.json())
210+
.then(data => console.log(data));
211+
```
212+
213+
## Validation
214+
215+
The server performs strict validation on all requests:
216+
217+
1. **JSON-RPC 2.0 compliance**: Validates `jsonrpc`, `method`, and `id` fields
218+
2. **Content-Type validation**: Ensures `application/json` content type
219+
3. **Parameter validation**: Validates method-specific parameters
220+
4. **Protocol version compatibility**: Checks MCP protocol version
221+
222+
## Security Considerations
223+
224+
- All HTTP responses include appropriate caching headers
225+
- Request validation prevents malformed JSON-RPC requests
226+
- Parameter sanitization prevents injection attacks
227+
- Network detection for proper metrics labeling
228+
- Rate limiting should be implemented at the reverse proxy level
229+
230+
## Compatibility
231+
232+
This implementation follows:
233+
- JSON-RPC 2.0 specification
234+
- MCP Protocol version 2024-11-05
235+
- HTTP/1.1 and HTTP/2 standards
236+
- OpenAPI 3.0 compatible (documentation available separately)
237+
238+
The server maintains full backward compatibility with existing stdio transport clients while providing modern HTTP JSON-RPC capabilities for web-based integrations.

‎docs/web-service.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
# Solana MCP Server - Web Service Mode
22

3-
The Solana MCP Server can run in web service mode, providing HTTP endpoints for MCP JSON-RPC communication alongside the traditional stdio transport.
3+
The Solana MCP Server supports running as an HTTP web service, providing full MCP JSON-RPC 2.0 API compliance for web-based integrations.
4+
5+
## Overview
6+
7+
When running in web service mode, the server provides:
8+
- **Full MCP JSON-RPC 2.0 compliance** following the official specification
9+
- **Proper content type handling** with annotations support
10+
- **Standards-compliant error responses** with protocol versioning
11+
- **Health checks** with capability information
12+
- **Prometheus metrics** integration
413

514
## Running as Web Service
615

@@ -10,7 +19,7 @@ The Solana MCP Server can run in web service mode, providing HTTP endpoints for
1019
# Run on default port 3000
1120
solana-mcp-server web
1221

13-
# Run on custom port
22+
# Run on custom port
1423
solana-mcp-server web --port 8000
1524
```
1625

@@ -19,14 +28,15 @@ solana-mcp-server web --port 8000
1928
When running in web service mode, the server provides:
2029

2130
#### POST /api/mcp
22-
- **Purpose**: MCP JSON-RPC API endpoint
23-
- **Content-Type**: `application/json`
24-
- **Description**: Accepts MCP JSON-RPC requests and returns responses
31+
- **Purpose**: MCP JSON-RPC 2.0 API endpoint
32+
- **Content-Type**: `application/json` (required)
33+
- **Description**: Accepts MCP JSON-RPC requests following the 2024-11-05 specification
34+
- **Features**: Full protocol validation, proper error handling, content annotations
2535

2636
#### GET /health
27-
- **Purpose**: Health check endpoint
28-
- **Response**: `{"status":"ok","service":"solana-mcp-server"}`
29-
- **Description**: Returns server health status
37+
- **Purpose**: Health check and capability information
38+
- **Response**: Detailed server status including protocol version and capabilities
39+
- **Description**: Returns comprehensive server health and MCP capability information
3040

3141
#### GET /metrics
3242
- **Purpose**: Prometheus metrics endpoint

0 commit comments

Comments
 (0)