Skip to content

Commit 8177c3d

Browse files
committed
Let prompts and resource templates define their own completions
Completion in the modern server was a single function registered through CompletionsFeature. It received every completion/complete request, so it had to know about every prompt and resource template and keep its own copy of which arguments each of them takes. A prompt now carries its completion handler, set with McpSyncPrompt.withCompletionHandler, and a resource template does the same through the new McpSyncResourceTemplate, which a resource repository returns from findTemplate(ctx, uriTemplate). A repository opts in with supportsCompletion(), as it already does for subscriptions with supportsSubscribe(). The server then serves completion/complete and advertises completions on its own; there is no feature to register. The server rejects a reference to an unknown prompt or template, or an argument it does not declare, with invalid params, and answers with no values when a prompt or template has no completion handler. Custom features can complete their own reference types through McpFeature.completionRefTypes() and McpFeature.complete(). CompletionsFeature and McpSync/AsyncCompletionRepository are removed; the completion function itself is now McpSync/AsyncCompletionHandler. This brings completions in line with the rest of the modern feature model, where each feature is responsible for its own primitives. Fixes #1312 Signed-off-by: Dariusz Jedrzejczyk <2554306+chemicL@users.noreply.github.com>
1 parent 29a1c76 commit 8177c3d

20 files changed

Lines changed: 775 additions & 150 deletions

File tree

‎conformance-tests/server-servlet-modern/src/main/java/io/modelcontextprotocol/conformance/server/modern/ModernConformanceServlet.java‎

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
import io.modelcontextprotocol.modern.McpSchema.CallToolRequest;
1818
import io.modelcontextprotocol.modern.McpSchema.CallToolResult;
1919
import io.modelcontextprotocol.modern.McpSchema.ClientCapabilities;
20+
import io.modelcontextprotocol.modern.McpSchema.CompleteRequest;
2021
import io.modelcontextprotocol.modern.McpSchema.CompleteResult;
2122
import io.modelcontextprotocol.modern.McpSchema.CreateMessageRequest;
2223
import io.modelcontextprotocol.modern.McpSchema.ElicitFormRequest;
@@ -44,13 +45,13 @@
4445
import io.modelcontextprotocol.modern.server.McpServer;
4546
import io.modelcontextprotocol.modern.server.McpSyncNotifier;
4647
import io.modelcontextprotocol.modern.server.McpSyncResponse;
47-
import io.modelcontextprotocol.modern.server.feature.CompletionsFeature;
4848
import io.modelcontextprotocol.modern.server.feature.McpChangeBroadcaster;
4949
import io.modelcontextprotocol.modern.server.feature.McpChangeFeed;
5050
import io.modelcontextprotocol.modern.server.feature.McpSyncPrompt;
5151
import io.modelcontextprotocol.modern.server.feature.McpSyncPromptRepository;
5252
import io.modelcontextprotocol.modern.server.feature.McpSyncResource;
5353
import io.modelcontextprotocol.modern.server.feature.McpSyncResourceRepository;
54+
import io.modelcontextprotocol.modern.server.feature.McpSyncResourceTemplate;
5455
import io.modelcontextprotocol.modern.server.feature.McpSyncTool;
5556
import io.modelcontextprotocol.modern.server.feature.McpSyncToolRepository;
5657
import io.modelcontextprotocol.modern.server.feature.PromptsFeature;
@@ -135,14 +136,11 @@ public static void main(String[] args) throws Exception {
135136
logger.info("Starting MCP Conformance Tests - Modern Servlet Server");
136137

137138
McpChangeFeed changes = new McpChangeFeed();
138-
139139
McpServer mcpServer = McpServer.builder()
140140
.serverInfo(Implementation.builder("mcp-modern-conformance-server", "1.0.0").build())
141141
.feature(ToolsFeature.ofSync(new ConformanceTools(changes)))
142142
.feature(ResourcesFeature.ofSync(new ConformanceResources()))
143143
.feature(PromptsFeature.ofSync(new ConformancePrompts()))
144-
.feature(CompletionsFeature
145-
.ofSync((ctx, request) -> CompleteResult.of(new CompleteResult.Completion(List.of()))))
146144
.subscriptions(changes)
147145
.build();
148146

@@ -201,6 +199,12 @@ private static CallToolResult text(String text) {
201199
return CallToolResult.builder().addContent(TextContent.builder(text).build()).build();
202200
}
203201

202+
private static CompleteResult completeFrom(List<String> candidates, CompleteRequest request) {
203+
String prefix = request.argument().value();
204+
return CompleteResult
205+
.of(new CompleteResult.Completion(candidates.stream().filter(value -> value.startsWith(prefix)).toList()));
206+
}
207+
204208
private static ElicitFormRequest elicitString(String message, String field) {
205209
return ElicitFormRequest
206210
.builder(message, Map.of("type", "object", "properties", Map.of(field, Map.of("type", "string")),
@@ -542,13 +546,21 @@ public ResourcesPage list(McpRequestContext ctx, String cursor) {
542546
return ResourcesPage.of(RESOURCES);
543547
}
544548

549+
private static final McpSyncResourceTemplate TEMPLATE = McpSyncResourceTemplate
550+
.of(ResourceTemplate.builder("test://template/{id}/data", "Template Resource")
551+
.description("A resource template for testing parameter substitution")
552+
.mimeType("application/json")
553+
.build())
554+
.withCompletionHandler((ctx, request) -> completeFrom(List.of("1", "2", "3"), request));
555+
545556
@Override
546557
public ResourceTemplatesPage listTemplates(McpRequestContext ctx, String cursor) {
547-
return ResourceTemplatesPage
548-
.of(List.of(ResourceTemplate.builder("test://template/{id}/data", "Template Resource")
549-
.description("A resource template for testing parameter substitution")
550-
.mimeType("application/json")
551-
.build()));
558+
return ResourceTemplatesPage.of(List.of(TEMPLATE.definition()));
559+
}
560+
561+
@Override
562+
public McpSyncResourceTemplate findTemplate(McpRequestContext ctx, String uriTemplate) {
563+
return TEMPLATE.definition().uriTemplate().equals(uriTemplate) ? TEMPLATE : null;
552564
}
553565

554566
@Override
@@ -573,6 +585,11 @@ public boolean supportsSubscribe() {
573585
return true;
574586
}
575587

588+
@Override
589+
public boolean supportsCompletion() {
590+
return true;
591+
}
592+
576593
private static ReadResourceResult textResource(String uri, String text) {
577594
return ReadResourceResult
578595
.builder(List.of(TextResourceContents.builder(uri, text).mimeType("text/plain").build()))
@@ -614,6 +631,8 @@ private static final class ConformancePrompts implements McpSyncPromptRepository
614631
args.get("arg2"));
615632
return messages(PromptMessage.builder(Role.USER, TextContent.builder(text).build()).build());
616633
}));
634+
this.prompts.computeIfPresent("test_prompt_with_arguments", (name, prompt) -> prompt
635+
.withCompletionHandler((ctx, request) -> completeFrom(List.of("alpha", "beta", "gamma"), request)));
617636
add(Prompt.builder("test_prompt_with_embedded_resource")
618637
.description("A prompt with embedded resource for testing")
619638
.arguments(List.of(PromptArgument.builder("resourceUri")
@@ -678,6 +697,11 @@ public McpSyncPrompt find(McpRequestContext ctx, String name) {
678697
return this.prompts.get(name);
679698
}
680699

700+
@Override
701+
public boolean supportsCompletion() {
702+
return true;
703+
}
704+
681705
}
682706

683707
}

‎docs/server-modern.md‎

Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -230,10 +230,10 @@ provides one feature per primitive, each backed by a **repository** you implemen
230230
| `ToolsFeature` | `tools/list`, `tools/call` | `McpSyncToolRepository` | `McpAsyncToolRepository` |
231231
| `ResourcesFeature` | `resources/list`, `resources/templates/list`, `resources/read` | `McpSyncResourceRepository` | `McpAsyncResourceRepository` |
232232
| `PromptsFeature` | `prompts/list`, `prompts/get` | `McpSyncPromptRepository` | `McpAsyncPromptRepository` |
233-
| `CompletionsFeature` | `completion/complete` | `McpSyncCompletionRepository` | `McpAsyncCompletionRepository` |
234233

235234
Create a feature with `ofSync(repository)` or `ofAsync(repository)`. Register only the features you need; the
236-
server advertises a capability only when its feature is registered.
235+
server advertises a capability only when its feature is registered. `completion/complete` has no feature of its
236+
own: the prompts and resources features answer it for their own references, see [Completions](#completions).
237237

238238
Every repository method receives the [`McpRequestContext`](#request-context), so a repository can return a
239239
different catalog per tenant or user. Two rules apply to `list`:
@@ -327,7 +327,9 @@ class FileResources implements McpSyncResourceRepository {
327327
}
328328
```
329329

330-
`listTemplates` and `supportsSubscribe` have defaults: no templates, and no subscriptions. Returning `true`
330+
`listTemplates`, `findTemplate`, `supportsSubscribe` and `supportsCompletion` have defaults: no templates, no
331+
subscriptions and no completion. `findTemplate` is only needed to [complete](#completions) template variables.
332+
Returning `true`
331333
from `supportsSubscribe` advertises `resources.subscribe` only when the server also has a change publisher
332334
registered with `subscriptions(...)`, because resource updates are only delivered over `subscriptions/listen`.
333335

@@ -352,13 +354,43 @@ McpSyncPrompt review = McpSyncPrompt.of(
352354

353355
### Completions
354356

355-
A completion repository is a single function from a `CompleteRequest` to a `CompleteResult`:
357+
Completion suggests values for a prompt argument or a resource template variable. The completion handler
358+
belongs to the prompt or template it completes:
356359

357360
```java
358-
CompletionsFeature completions = CompletionsFeature.ofSync((ctx, request) ->
359-
CompleteResult.of(new CompleteResult.Completion(List.of("python", "java", "javascript"))));
361+
McpSyncPrompt review = McpSyncPrompt.of(definition, handler)
362+
.withCompletionHandler((ctx, request) -> CompleteResult.of(new CompleteResult.Completion(
363+
languages.stream().filter(l -> l.startsWith(request.argument().value())).toList())));
364+
365+
McpSyncResourceTemplate logs = McpSyncResourceTemplate.of(ResourceTemplate.builder("file:///logs/{date}", "Daily log").build())
366+
.withCompletionHandler((ctx, request) -> CompleteResult.of(new CompleteResult.Completion(logDates())));
360367
```
361368

369+
A prompt repository returns such a prompt from `find`. A resource repository returns such a template from
370+
`findTemplate(ctx, uriTemplate)`, which is looked up by the exact `uriTemplate` string the client sends in a
371+
`ref/resource` reference. Either repository opts in by returning `true` from `supportsCompletion()`:
372+
373+
```java
374+
class Prompts implements McpSyncPromptRepository {
375+
// list, find ...
376+
377+
@Override
378+
public boolean supportsCompletion() {
379+
return true;
380+
}
381+
}
382+
```
383+
384+
The server then serves `completion/complete` and advertises `completions`, sending `ref/prompt` requests to the
385+
prompts feature and `ref/resource` requests to the resources feature. A [custom feature](#custom-features)
386+
completes its own reference types the same way, by returning them from `McpFeature.completionRefTypes()` and
387+
answering `McpFeature.complete(ctx, request)`. Two features completing the same reference type fail the build.
388+
389+
A reference type no feature completes, an unknown prompt or template, or an argument the prompt or template does not declare, is answered with an
390+
invalid-params error. A prompt or template without a completion handler completes to no values. Arguments already
391+
filled in by the user arrive in `request.context()`. At most 100 values are sent; the rest are cut and
392+
`hasMore` is set.
393+
362394
### Sync and Async
363395

364396
Sync and async repositories can be mixed in one server. A sync repository is adapted to the async API inside
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
/*
2+
* Copyright 2026-2026 the original author or authors.
3+
*/
4+
5+
package io.modelcontextprotocol.modern.server;
6+
7+
import java.util.Map;
8+
import java.util.Set;
9+
10+
import io.modelcontextprotocol.json.McpJsonMapper;
11+
import io.modelcontextprotocol.modern.McpException;
12+
import io.modelcontextprotocol.modern.McpSchema;
13+
import io.modelcontextprotocol.modern.McpSchema.CompleteRequest;
14+
import io.modelcontextprotocol.modern.McpSchema.CompleteResult;
15+
import io.modelcontextprotocol.modern.McpSchema.CompleteResult.Completion;
16+
import io.modelcontextprotocol.modern.McpSchema.Result;
17+
import io.modelcontextprotocol.modern.McpSchema.ServerCapabilities;
18+
import reactor.core.publisher.Mono;
19+
20+
/**
21+
* Serves {@code completion/complete} by routing each request to the feature that answers
22+
* its ref type.
23+
*
24+
* @author Dariusz Jędrzejczyk
25+
*/
26+
final class CompletionsFeature implements McpFeature {
27+
28+
private static final int MAX_VALUES = 100;
29+
30+
private final McpJsonMapper jsonMapper;
31+
32+
private final Map<String, McpFeature> byRefType;
33+
34+
CompletionsFeature(McpJsonMapper jsonMapper, Map<String, McpFeature> byRefType) {
35+
this.jsonMapper = jsonMapper;
36+
this.byRefType = byRefType;
37+
}
38+
39+
@Override
40+
public Set<String> methods() {
41+
return Set.of(McpSchema.METHOD_COMPLETION_COMPLETE);
42+
}
43+
44+
@Override
45+
public Mono<McpAsyncResponse<Result>> handle(McpRequestContext ctx, Object params) {
46+
if (!(params instanceof Map<?, ?> map) || !(map.get("ref") instanceof Map<?, ?> ref)) {
47+
return Mono.error(McpException.invalidParams("params.ref is required"));
48+
}
49+
// Checked here because CompleteRequest's JSON creator fills a missing one in.
50+
if (map.get("argument") == null) {
51+
return Mono.error(McpException.invalidParams("params.argument is required"));
52+
}
53+
McpFeature feature = this.byRefType.get(ref.get("type"));
54+
if (feature == null) {
55+
return Mono.error(McpException.invalidParams("Unsupported ref type: " + ref.get("type")));
56+
}
57+
CompleteRequest request;
58+
try {
59+
request = this.jsonMapper.convertValue(params, CompleteRequest.class);
60+
}
61+
catch (RuntimeException ex) {
62+
return Mono.error(McpException.invalidParams("Malformed CompleteRequest"));
63+
}
64+
return feature.complete(ctx, request).map(result -> McpAsyncResponse.result(capValues(result)));
65+
}
66+
67+
private static CompleteResult capValues(CompleteResult result) {
68+
Completion completion = result.completion();
69+
if (completion.values().size() <= MAX_VALUES) {
70+
return result;
71+
}
72+
Integer total = completion.total() != null ? completion.total() : completion.values().size();
73+
Completion capped = new Completion(completion.values().subList(0, MAX_VALUES), total, true);
74+
return new CompleteResult(capped, result.resultType(), result.meta());
75+
}
76+
77+
@Override
78+
public void capabilities(ServerCapabilities.Builder builder) {
79+
builder.completions();
80+
}
81+
82+
}

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpFeature.java‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,18 @@
77
import java.util.Set;
88

99
import io.modelcontextprotocol.modern.McpException;
10+
import io.modelcontextprotocol.modern.McpSchema.CompleteRequest;
11+
import io.modelcontextprotocol.modern.McpSchema.CompleteResult;
1012
import io.modelcontextprotocol.modern.McpSchema.InputRequired;
1113
import io.modelcontextprotocol.modern.McpSchema.Result;
1214
import io.modelcontextprotocol.modern.McpSchema.ServerCapabilities;
1315
import reactor.core.publisher.Mono;
1416

1517
/**
16-
* A composable unit of server behaviour: the methods it serves, and the capabilities it
17-
* contributes to {@code server/discover}. Core primitives (tools, resources, prompts,
18-
* completions) are features; so is anything an extension adds.
18+
* A composable unit of server behaviour: the methods it serves, the capabilities it
19+
* contributes to {@code server/discover}, and the references it completes for
20+
* {@code completion/complete}. Core primitives (tools, resources, prompts) are features;
21+
* so is anything an extension adds.
1922
*
2023
* @author Dariusz Jędrzejczyk
2124
*/
@@ -46,4 +49,22 @@ default Set<String> inputRequiredMethods() {
4649
return Set.of();
4750
}
4851

52+
/**
53+
* The {@code completion/complete} reference types, such as {@code ref/prompt}, this
54+
* feature answers through {@link #complete}. No two features may answer the same one;
55+
* the server serves {@code completion/complete} and advertises {@code completions}
56+
* when any feature answers one. Default: none.
57+
*/
58+
default Set<String> completionRefTypes() {
59+
return Set.of();
60+
}
61+
62+
/**
63+
* Answer a {@code completion/complete} whose ref type is one of
64+
* {@link #completionRefTypes()}, with the same error rules as {@link #handle}.
65+
*/
66+
default Mono<CompleteResult> complete(McpRequestContext ctx, CompleteRequest request) {
67+
return Mono.error(new UnsupportedOperationException(getClass().getName() + " does not complete"));
68+
}
69+
4970
}

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpServer.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -457,8 +457,21 @@ public McpServer build() {
457457
List<McpFeature> allFeatures = new ArrayList<>(this.features);
458458

459459
ServerCapabilities.Builder capabilitiesBuilder = ServerCapabilities.builder();
460+
Map<String, McpFeature> byRefType = new HashMap<>();
460461
for (McpFeature feature : allFeatures) {
461462
feature.capabilities(capabilitiesBuilder);
463+
for (String refType : feature.completionRefTypes()) {
464+
McpFeature existing = byRefType.putIfAbsent(refType, feature);
465+
if (existing != null) {
466+
throw new IllegalStateException("Ref type '" + refType + "' is completed by both "
467+
+ existing.getClass().getName() + " and " + feature.getClass().getName());
468+
}
469+
}
470+
}
471+
if (!byRefType.isEmpty()) {
472+
CompletionsFeature completionsFeature = new CompletionsFeature(mapper, Map.copyOf(byRefType));
473+
completionsFeature.capabilities(capabilitiesBuilder);
474+
allFeatures.add(completionsFeature);
462475
}
463476

464477
// Subscriptions and discover are wired up last: which change types

0 commit comments

Comments
 (0)