LLDB mainline
Protocol.h
Go to the documentation of this file.
1//===- Protocol.h ---------------------------------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file contains POD structs based on the MCP specification at
10// https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2024-11-05/schema.json
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLDB_PROTOCOL_MCP_PROTOCOL_H
15#define LLDB_PROTOCOL_MCP_PROTOCOL_H
16
17#include "llvm/ADT/StringRef.h"
18#include "llvm/Support/JSON.h"
19#include <optional>
20#include <string>
21#include <variant>
22#include <vector>
23
24namespace lldb_protocol::mcp {
25
26static llvm::StringLiteral kProtocolVersion = "2024-11-05";
27
28/// A Request or Response 'id'.
29///
30/// NOTE: This differs from the JSON-RPC 2.0 spec. The MCP spec says this must
31/// be a string or number, excluding a json 'null' as a valid id.
32using Id = std::variant<int64_t, std::string>;
33
34/// A request that expects a response.
35struct Request {
36 /// The request id.
37 Id id = 0;
38 /// The method to be invoked.
39 std::string method;
40 /// The method's params.
41 std::optional<llvm::json::Value> params;
42};
43llvm::json::Value toJSON(const Request &);
44bool fromJSON(const llvm::json::Value &, Request &, llvm::json::Path);
45bool operator==(const Request &, const Request &);
46
47enum ErrorCode : signed {
48 /// Invalid JSON was received by the server. An error occurred on the server
49 /// while parsing the JSON text.
51 /// The JSON sent is not a valid Request object.
53 /// The method does not exist / is not available.
55 /// Invalid method parameter(s).
57 /// Internal JSON-RPC error.
59};
60
61struct Error {
62 /// The error type that occurred.
63 int64_t code = 0;
64 /// A short description of the error. The message SHOULD be limited to a
65 /// concise single sentence.
66 std::string message;
67 /// Additional information about the error. The value of this member is
68 /// defined by the sender (e.g. detailed error information, nested errors
69 /// etc.).
70 std::optional<llvm::json::Value> data = std::nullopt;
71};
72llvm::json::Value toJSON(const Error &);
73bool fromJSON(const llvm::json::Value &, Error &, llvm::json::Path);
74bool operator==(const Error &, const Error &);
75
76/// A response to a request, either an error or a result.
77struct Response {
78 /// The request id.
79 Id id = 0;
80 /// The result of the request, either an Error or the JSON value of the
81 /// response.
82 std::variant<Error, llvm::json::Value> result;
83};
84llvm::json::Value toJSON(const Response &);
85bool fromJSON(const llvm::json::Value &, Response &, llvm::json::Path);
86bool operator==(const Response &, const Response &);
87
88/// A notification which does not expect a response.
90 /// The method to be invoked.
91 std::string method;
92 /// The notification's params.
93 std::optional<llvm::json::Value> params;
94};
95llvm::json::Value toJSON(const Notification &);
96bool fromJSON(const llvm::json::Value &, Notification &, llvm::json::Path);
97bool operator==(const Notification &, const Notification &);
98
99/// A general message as defined by the JSON-RPC 2.0 spec.
100using Message = std::variant<Request, Response, Notification>;
101// With clang-cl and MSVC STL 202208, convertible can be false later if we do
102// not force it to be checked early here.
103static_assert(std::is_convertible_v<Message, Message>,
104 "Message is not convertible to itself");
105bool fromJSON(const llvm::json::Value &, Message &, llvm::json::Path);
106llvm::json::Value toJSON(const Message &);
107
108/// A known resource that the server is capable of reading.
109struct Resource {
110 /// The URI of this resource.
111 std::string uri;
112
113 /// A human-readable name for this resource.
114 std::string name;
115
116 /// A description of what this resource represents.
117 std::string description = "";
118
119 /// The MIME type of this resource, if known.
120 std::string mimeType = "";
121};
122
123llvm::json::Value toJSON(const Resource &);
124bool fromJSON(const llvm::json::Value &, Resource &, llvm::json::Path);
125
126/// The server’s response to a resources/list request from the client.
128 std::vector<Resource> resources;
129};
130llvm::json::Value toJSON(const ListResourcesResult &);
131bool fromJSON(const llvm::json::Value &, ListResourcesResult &,
132 llvm::json::Path);
133
134/// The contents of a specific resource or sub-resource.
136 /// The URI of this resource.
137 std::string uri;
138
139 /// The text of the item. This must only be set if the item can actually be
140 /// represented as text (not binary data).
141 std::string text;
142
143 /// The MIME type of this resource, if known.
144 std::string mimeType;
145};
146
147llvm::json::Value toJSON(const TextResourceContents &);
148bool fromJSON(const llvm::json::Value &, TextResourceContents &,
149 llvm::json::Path);
150
151/// Sent from the client to the server, to read a specific resource URI.
153 /// The URI of the resource to read. The URI can use any protocol; it is up to
154 /// the server how to interpret it.
155 std::string uri;
156};
157llvm::json::Value toJSON(const ReadResourceParams &);
158bool fromJSON(const llvm::json::Value &, ReadResourceParams &,
159 llvm::json::Path);
160
161/// The server's response to a resources/read request from the client.
163 std::vector<TextResourceContents> contents;
164};
165llvm::json::Value toJSON(const ReadResourceResult &);
166bool fromJSON(const llvm::json::Value &, ReadResourceResult &,
167 llvm::json::Path);
168
169/// Text provided to or from an LLM.
171 /// The text content of the message.
172 std::string text;
173};
174llvm::json::Value toJSON(const TextContent &);
175bool fromJSON(const llvm::json::Value &, TextContent &, llvm::json::Path);
176
177/// Definition for a tool the client can call.
179 /// Unique identifier for the tool.
180 std::string name;
181
182 /// Human-readable description.
183 std::string description;
184
185 // JSON Schema for the tool's parameters.
186 std::optional<llvm::json::Value> inputSchema;
187};
188llvm::json::Value toJSON(const ToolDefinition &);
189bool fromJSON(const llvm::json::Value &, ToolDefinition &, llvm::json::Path);
190
191using ToolArguments = std::variant<std::monostate, llvm::json::Value>;
192
193/// Describes the name and version of an MCP implementation, with an optional
194/// title for UI representation.
196 /// Intended for programmatic or logical use, but used as a display name in
197 /// past specs or fallback (if title isn’t present).
198 std::string name;
199
200 std::string version;
201
202 /// Intended for UI and end-user contexts — optimized to be human-readable and
203 /// easily understood, even by those unfamiliar with domain-specific
204 /// terminology.
205 ///
206 /// If not provided, the name should be used for display (except for Tool,
207 /// where annotations.title should be given precedence over using name, if
208 /// present).
209 std::string title = "";
210};
211llvm::json::Value toJSON(const Implementation &);
212bool fromJSON(const llvm::json::Value &, Implementation &, llvm::json::Path);
213
214/// Capabilities a client may support. Known capabilities are defined here, in
215/// this schema, but this is not a closed set: any client can define its own,
216/// additional capabilities.
218llvm::json::Value toJSON(const ClientCapabilities &);
219bool fromJSON(const llvm::json::Value &, ClientCapabilities &,
220 llvm::json::Path);
221
222/// Capabilities that a server may support. Known capabilities are defined here,
223/// in this schema, but this is not a closed set: any server can define its own,
224/// additional capabilities.
226 bool supportsToolsList = false;
229
230 /// Utilities.
232 bool supportsLogging = false;
233};
234llvm::json::Value toJSON(const ServerCapabilities &);
235bool fromJSON(const llvm::json::Value &, ServerCapabilities &,
236 llvm::json::Path);
237
238/// Initialization
239
240/// This request is sent from the client to the server when it first connects,
241/// asking it to begin initialization.
243 /// The latest version of the Model Context Protocol that the client supports.
244 /// The client MAY decide to support older versions as well.
245 std::string protocolVersion;
246
248
250};
251llvm::json::Value toJSON(const InitializeParams &);
252bool fromJSON(const llvm::json::Value &, InitializeParams &, llvm::json::Path);
253
254/// After receiving an initialize request from the client, the server sends this
255/// response.
257 /// The version of the Model Context Protocol that the server wants to use.
258 /// This may not match the version that the client requested. If the client
259 /// cannot support this version, it MUST disconnect.
260 std::string protocolVersion;
261
264
265 /// Instructions describing how to use the server and its features.
266 ///
267 /// This can be used by clients to improve the LLM's understanding of
268 /// available tools, resources, etc. It can be thought of like a "hint" to the
269 /// model. For example, this information MAY be added to the system prompt.
270 std::string instructions = "";
271};
272llvm::json::Value toJSON(const InitializeResult &);
273bool fromJSON(const llvm::json::Value &, InitializeResult &, llvm::json::Path);
274
275/// Special case parameter or result that has no value.
276using Void = std::monostate;
277llvm::json::Value toJSON(const Void &);
278bool fromJSON(const llvm::json::Value &, Void &, llvm::json::Path);
279
280/// The server's response to a `tools/list` request from the client.
282 std::vector<ToolDefinition> tools;
283};
284llvm::json::Value toJSON(const ListToolsResult &);
285bool fromJSON(const llvm::json::Value &, ListToolsResult &, llvm::json::Path);
286
287/// Supported content types, currently only TextContent, but the spec includes
288/// additional content types.
290
291/// Used by the client to invoke a tool provided by the server.
293 std::string name;
294 std::optional<llvm::json::Value> arguments;
295};
296llvm::json::Value toJSON(const CallToolParams &);
297bool fromJSON(const llvm::json::Value &, CallToolParams &, llvm::json::Path);
298
299/// The server’s response to a tool call.
301 /// A list of content objects that represent the unstructured result of the
302 /// tool call.
303 std::vector<ContentBlock> content;
304
305 /// Whether the tool call ended in an error.
306 ///
307 /// If not set, this is assumed to be false (the call was successful).
308 ///
309 /// Any errors that originate from the tool SHOULD be reported inside the
310 /// result object, with `isError` set to true, not as an MCP protocol-level
311 /// error response. Otherwise, the LLM would not be able to see that an error
312 /// occurred and self-correct.
313 ///
314 /// However, any errors in finding the tool, an error indicating that the
315 /// server does not support tool calls, or any other exceptional conditions,
316 /// should be reported as an MCP error response.
317 bool isError = false;
318
319 /// An optional JSON object that represents the structured result of the tool
320 /// call.
321 std::optional<llvm::json::Value> structuredContent = std::nullopt;
322};
323llvm::json::Value toJSON(const CallToolResult &);
324bool fromJSON(const llvm::json::Value &, CallToolResult &, llvm::json::Path);
325
327MakeRequest(int64_t id, llvm::StringRef method,
328 std::optional<llvm::json::Value> params);
329
330} // namespace lldb_protocol::mcp
331
332#endif
std::variant< Request, Response, Notification > Message
A general message as defined by the JSON-RPC 2.0 spec.
Definition Protocol.h:100
std::monostate Void
Special case parameter or result that has no value.
Definition Protocol.h:276
std::variant< int64_t, std::string > Id
A Request or Response 'id'.
Definition Protocol.h:32
std::variant< std::monostate, llvm::json::Value > ToolArguments
Definition Protocol.h:191
@ eErrorCodeMethodNotFound
The method does not exist / is not available.
Definition Protocol.h:54
@ eErrorCodeInvalidParams
Invalid method parameter(s).
Definition Protocol.h:56
@ eErrorCodeInvalidRequest
The JSON sent is not a valid Request object.
Definition Protocol.h:52
@ eErrorCodeInternalError
Internal JSON-RPC error.
Definition Protocol.h:58
@ eErrorCodeParseError
Invalid JSON was received by the server.
Definition Protocol.h:50
TextContent ContentBlock
Supported content types, currently only TextContent, but the spec includes additional content types.
Definition Protocol.h:289
llvm::json::Value toJSON(const Request &)
Definition Protocol.cpp:66
lldb_protocol::mcp::Request MakeRequest(int64_t id, llvm::StringRef method, std::optional< llvm::json::Value > params)
bool operator==(const Request &, const Request &)
Definition Protocol.cpp:80
static llvm::StringLiteral kProtocolVersion
Definition Protocol.h:26
bool fromJSON(const llvm::json::Value &, Request &, llvm::json::Path)
Definition Protocol.cpp:74
Used by the client to invoke a tool provided by the server.
Definition Protocol.h:292
std::optional< llvm::json::Value > arguments
Definition Protocol.h:294
The server’s response to a tool call.
Definition Protocol.h:300
std::vector< ContentBlock > content
A list of content objects that represent the unstructured result of the tool call.
Definition Protocol.h:303
std::optional< llvm::json::Value > structuredContent
An optional JSON object that represents the structured result of the tool call.
Definition Protocol.h:321
bool isError
Whether the tool call ended in an error.
Definition Protocol.h:317
Capabilities a client may support.
Definition Protocol.h:217
std::string message
A short description of the error.
Definition Protocol.h:66
std::optional< llvm::json::Value > data
Additional information about the error.
Definition Protocol.h:70
int64_t code
The error type that occurred.
Definition Protocol.h:63
Describes the name and version of an MCP implementation, with an optional title for UI representation...
Definition Protocol.h:195
std::string title
Intended for UI and end-user contexts — optimized to be human-readable and easily understood,...
Definition Protocol.h:209
std::string name
Intended for programmatic or logical use, but used as a display name in past specs or fallback (if ti...
Definition Protocol.h:198
std::string protocolVersion
The latest version of the Model Context Protocol that the client supports.
Definition Protocol.h:245
After receiving an initialize request from the client, the server sends this response.
Definition Protocol.h:256
std::string protocolVersion
The version of the Model Context Protocol that the server wants to use.
Definition Protocol.h:260
std::string instructions
Instructions describing how to use the server and its features.
Definition Protocol.h:270
The server’s response to a resources/list request from the client.
Definition Protocol.h:127
std::vector< Resource > resources
Definition Protocol.h:128
The server's response to a tools/list request from the client.
Definition Protocol.h:281
std::vector< ToolDefinition > tools
Definition Protocol.h:282
A notification which does not expect a response.
Definition Protocol.h:89
std::optional< llvm::json::Value > params
The notification's params.
Definition Protocol.h:93
std::string method
The method to be invoked.
Definition Protocol.h:91
Sent from the client to the server, to read a specific resource URI.
Definition Protocol.h:152
std::string uri
The URI of the resource to read.
Definition Protocol.h:155
The server's response to a resources/read request from the client.
Definition Protocol.h:162
std::vector< TextResourceContents > contents
Definition Protocol.h:163
A request that expects a response.
Definition Protocol.h:35
std::optional< llvm::json::Value > params
The method's params.
Definition Protocol.h:41
std::string method
The method to be invoked.
Definition Protocol.h:39
A known resource that the server is capable of reading.
Definition Protocol.h:109
std::string description
A description of what this resource represents.
Definition Protocol.h:117
std::string uri
The URI of this resource.
Definition Protocol.h:111
std::string mimeType
The MIME type of this resource, if known.
Definition Protocol.h:120
std::string name
A human-readable name for this resource.
Definition Protocol.h:114
A response to a request, either an error or a result.
Definition Protocol.h:77
std::variant< Error, llvm::json::Value > result
The result of the request, either an Error or the JSON value of the response.
Definition Protocol.h:82
Capabilities that a server may support.
Definition Protocol.h:225
Text provided to or from an LLM.
Definition Protocol.h:170
std::string text
The text content of the message.
Definition Protocol.h:172
The contents of a specific resource or sub-resource.
Definition Protocol.h:135
std::string text
The text of the item.
Definition Protocol.h:141
std::string uri
The URI of this resource.
Definition Protocol.h:137
std::string mimeType
The MIME type of this resource, if known.
Definition Protocol.h:144
Definition for a tool the client can call.
Definition Protocol.h:178
std::string description
Human-readable description.
Definition Protocol.h:183
std::string name
Unique identifier for the tool.
Definition Protocol.h:180
std::optional< llvm::json::Value > inputSchema
Definition Protocol.h:186