Skip to content

Commit 1ec994e

Browse files
phillip-krugerphillip-kruger
authored
Merge pull request #49105 from phillip-kruger/dev-mcp-documentation
Dev MCP Documentation
2 parents 49a8a39 + 6c64a76 commit 1ec994e

File tree

2 files changed

+149
-0
lines changed

2 files changed

+149
-0
lines changed

‎docs/src/main/asciidoc/dev-mcp.adoc

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
////
2+
This guide is maintained in the main Quarkus repository
3+
and pull requests should be submitted there:
4+
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
5+
////
6+
= Dev MCP
7+
include::_attributes.adoc[]
8+
:categories: writing-extensions
9+
:summary: Learn more about Dev MCP
10+
:topics: dev-mcp,dev-ui
11+
12+
[IMPORTANT]
13+
.Experimental
14+
====
15+
This feature is currently experimental. To enable it, set `quarkus.dev-mcp.enabled=true` in your application properties.
16+
====
17+
18+
== Overview
19+
20+
When you run a Quarkus application in dev mode, you can expose a Model Context Protocol (MCP) server.
21+
It presents the methods used by the DevUI *MCP tools* (methods you can call) and the data exposed by *MCP resources*.
22+
23+
=== Connecting an MCP client
24+
25+
Open the **Dev MCP** menu in the Dev UI to see the MCP server’s URL. (Default `http://localhost:8080/q/dev-mcp`).
26+
Any MCP client that supports the https://modelcontextprotocol.io/specification/2025-03-26[Streamable Protocol, version 2025‑03‑26] can connect using that URL.
27+
After a client connects, it appears on the *MCP Info* page of the Dev UI.
28+
29+
image::dev_mcp_info_screen.png[Dev MCP Info, width=100%]
30+
31+
== Guide for extension developers
32+
33+
Extensions can contribute additional tools and resources to the Dev MCP server. The integration is similar to contributing to the xref:dev-ui.adoc[Dev UI], but descriptions are mandatory.
34+
A single JSON‑RPC service can be used for both Dev UI and Dev MCP; methods without a description only show up in Dev UI, while methods with a description appear in both.
35+
36+
=== MCP resources
37+
38+
A resource is data exposed by your extension. There are two ways to create a resource.
39+
40+
==== MCP Resources against build time data
41+
42+
Build‑time data that is already exposed to the xref:dev-ui.adoc#optional-build-time-data[Dev UI] can also be made available to Dev MCP. Provide a description when calling `addBuildTimeData()`:
43+
44+
[source,java]
45+
----
46+
footerPageBuildItem.addBuildTimeData(
47+
"jokes",
48+
jokesBuildItem.getJokes(),
49+
"Some funny jokes that the user might enjoy"
50+
);
51+
----
52+
53+
The extra `description` argument is new: without it the data only appears in the Dev UI. Once supplied, the `jokes` data becomes an MCP resource.
54+
55+
==== MCP Resources against a recorded value
56+
57+
To expose recorded values (data produced at runtime by a recorder) as an MCP resource, define a xref:dev-ui.adoc#jsonrpc-against-a-recorded-value[build‑time action] in the deployment module. The action must include a description:
58+
59+
[source,java]
60+
----
61+
@BuildStep(onlyIf = IsLocalDevelopment.class)
62+
BuildTimeActionBuildItem createBuildTimeActions() {
63+
BuildTimeActionBuildItem item = new BuildTimeActionBuildItem(); //<1>
64+
item.actionBuilder() //<2>
65+
.methodName("getMyRecordedValue")
66+
.description("A well‑thought‑out description") //<3>
67+
.runtime(runtimeValue) //<4>
68+
.build();
69+
return item;
70+
}
71+
----
72+
<1> Return or produce a `BuildTimeActionBuildItem`.
73+
<2> Use the builder to configure the action.
74+
<3> Set a human‑readable description.
75+
<4> Provide the runtime value returned by your recorder.
76+
77+
=== MCP tools
78+
79+
A tool corresponds to a method that a client can call. Any JSON‑RPC method can be exposed as a tool by supplying descriptions on the method and its parameters.
80+
Tools can run on either the runtime or deployment classpath.
81+
82+
==== MCP Tools against the Runtime classpath
83+
84+
To expose runtime information or actions (for example, changing log levels), define a xref:dev-ui.adoc#jsonrpc-against-the-runtime-classpath[JSON‑RPC service] in your runtime or runtime‑dev module and annotate the methods and parameters with `@JsonRpcDescription`:
85+
86+
[source,java]
87+
----
88+
public class MyExtensionRPCService {
89+
90+
@JsonRpcDescription("Update a specific logger's level in this Quarkus application") // <1>
91+
public JsonObject updateLogLevel(
92+
@JsonRpcDescription("The logger name as defined in the logging implementation") String loggerName,
93+
@JsonRpcDescription("The new log level") String levelValue) { // <2>
94+
// implementation…
95+
}
96+
}
97+
----
98+
<1> Description of the method.
99+
<2> Description of each parameter.
100+
101+
You must register the JSON‑RPC service in the deployment module:
102+
103+
[source,java]
104+
----
105+
@BuildStep
106+
JsonRPCProvidersBuildItem registerRpcService() { // <1>
107+
return new JsonRPCProvidersBuildItem(MyExtensionRPCService.class); // <2>
108+
}
109+
----
110+
<1> Produce a `JsonRPCProvidersBuildItem`.
111+
<2> Specify the class in your runtime or runtime‑dev module that contains the methods.
112+
113+
`@JsonRpcDescription` is mandatory for Dev MCP; without it the method is only available in the Dev UI.
114+
The method can return primitives, `String`, `JsonObject`, `JsonArray`, or any POJO that can be serialised to JSON.
115+
Asynchronous methods (`Uni`, `CompletionStage` or methods annotated with `@NonBlocking`) are also supported.
116+
117+
==== MCP Tools against the Deployment classpath
118+
119+
Sometimes you need to run xref:dev-ui.adoc#jsonrpc-against-the-deployment-classpath[actions on the deployment classpath] (for example, writing configuration files). In that case you do not create a JSON‑RPC service; instead you provide a supplier via a `BuildTimeActionBuildItem`:
120+
121+
[source,java]
122+
----
123+
@BuildStep(onlyIf = IsLocalDevelopment.class)
124+
BuildTimeActionBuildItem createBuildTimeActions() {
125+
BuildTimeActionBuildItem actions = new BuildTimeActionBuildItem();
126+
actions.actionBuilder()
127+
.methodName("updateProperty")
128+
.description("Update a configuration/property in the Quarkus application") // <1>
129+
.parameter("name", "The name of the configuration/property to update") // <2>
130+
.parameter("value", "The new value for the configuration/property")
131+
.function(map -> {
132+
Map<String, String> values = Collections.singletonMap(
133+
map.get("name"), map.get("value"));
134+
updateConfig(values);
135+
return true;
136+
})
137+
.build();
138+
return actions;
139+
}
140+
----
141+
<1> Description of the method.
142+
<2> Description of each parameter.
143+
144+
The code in the `function` runs on the deployment classpath. The function can return a plain value, a `CompletionStage` or `CompletableFuture` for asynchronous work.
145+
146+
=== JSON‑RPC usage
147+
148+
By default all JSON‑RPC methods are visible in the Dev UI. Only methods with descriptions are exposed via Dev MCP.
149+
You can override this behaviour with the `@JsonRpcUsage` annotation. Pass one or both of the `Usage` enums (`DEV_UI`, `DEV_MCP`) to control where a method is exposed.

‎docs/src/main/asciidoc/images/dev_mcp_info_screen.png

77.1 KB
Loading

0 commit comments

Comments
 (0)