|
| 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. |
0 commit comments