René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"completion/complete should return EMPTY_COMPLETION_RESULT when no handler registered","articleBody":"**Bug description**\n\nWhen a prompt has at least one `@McpComplete` handler registered somewhere in the server, the `completions` capability gets enabled globally. After that, the upstream MCP Inspector (and any well-behaved client) fires `completion/complete` for every keystroke in any prompt-argument or resource-template-argument input.\n\nThe problem is that the Java server throws `-32602 \"AsyncCompletionSpecification not found\"` for any prompt or resource template that does not have its own matching `@McpComplete`. The Inspector shows this as a red error toast on every keystroke, which is pretty bad UX for what should be a silent \"no suggestions\" case.\n\nThe TypeScript and Python reference SDKs handle this gracefully, they just return an empty completion result. The Java SDK already returns an empty result in several sibling branches of the same handler (including the one fixed by #934). Only the final \"no spec registered for this ref\" branch still throws.\n\n**Environment**\n\n- `io.modelcontextprotocol.sdk:mcp-core` 0.18.2\n- Spring AI 1.1.7 with `spring-ai-starter-mcp-server-webmvc`\n- `org.springaicommunity:mcp-annotations` 0.9.0\n- Spring Boot 3.5.14, Java 17\n- Client: MCP Inspector 0.21.2, but any client that calls `completion/complete` on a partially-covered prompt reproduces it\n\nThe same throw site exists unchanged in every released version I checked: `v0.18.2`, `1.0.0-RC3`, `v1.1.0`, `v1.1.2`, `v1.1.3`, `v2.0.0 M3` and on `main`, atm no open PR/Issue currently with this problem\n\n**Steps to reproduce**\n\nThe bug lives in the server classes, not in the transports. The same `if (specification == null) { return Mono.error(...) }` block exists in two places:\n- `McpAsyncServer.completionCompleteRequestHandler()` used by all stateful transports (Streamable HTTP, SSE, stdio)\n- `McpStatelessAsyncServer.completionCompleteRequestHandler()` used by the stateless HTTP transport\n\n`McpSyncServer` and `McpStatelessSyncServer` are thin wrappers over the async counterparts and inherit the same behavior. Reproduced the `-32602` on **Streamable HTTP**, **SSE**, and **stateless HTTP**.\n\n1. Build a Spring AI MCP server with two prompts, where only one of them has an `@McpComplete` handler. The presence of any `@McpComplete` is enough to enable the `completions` capability for the whole server.\n2. Connect the MCP Inspector and open the prompt that has no completion handler.\n3. Type anything in one of its argument fields.\n\nThe server responds:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 42,\n  \"error\": {\n    \"code\": -32602,\n    \"message\": \"AsyncCompletionSpecification not found: PromptReference[type=ref/prompt, name=greeting, title=null]\"\n  }\n}\n```\n\nThe Inspector renders this as a red error toast on every keystroke.\n\u003cimg width=\"1908\" height=\"946\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/410bfb65-2955-4fe5-9326-115ad624115f\" /\u003e\n\n**Expected behavior**\n\nA well-formed `completion/complete` request for a ref that has no registered handler should return an empty result:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 42,\n  \"result\": {\n    \"completion\": {\n      \"values\": [],\n      \"total\": 0,\n      \"hasMore\": false\n    }\n  }\n}\n```\n\nThe client UI then shows \"no suggestions\" silently, which is what users see when they talk to a TypeScript or Python MCP server.\n\nThe current strict throw is still appropriate when the ref itself is malformed, unknown prompt name, missing resource template, or an argument that is not actually a template variable. Those cases are already handled and should stay as they are.\n\n**Minimal Complete Reproducible example**\n\n```java\n@SpringBootApplication\npublic class DemoApplication {\n    public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); }\n\n    @Component\n    public static class Prompts {\n\n        // covered by a completion handler\n        @McpPrompt(name = \"covered\", description = \"Prompt with completion\")\n        public GetPromptResult covered(@McpArg(name = \"topic\", required = true) String topic) {\n            return new GetPromptResult(\"\", List.of(new PromptMessage(Role.USER, new TextContent(topic))));\n        }\n\n        @McpComplete(prompt = \"covered\")\n        public List\u003cString\u003e coveredTopic(String value) {\n            return List.of(\"alpha\", \"beta\", \"gamma\");\n        }\n\n        // no @McpComplete completion/complete on its argument throws\n        @McpPrompt(name = \"uncovered\", description = \"Prompt with no completion handler\")\n        public GetPromptResult uncovered(@McpArg(name = \"name\", required = true) String name) {\n            return new GetPromptResult(\"\", List.of(new PromptMessage(Role.USER, new TextContent(\"Hi \" + name))));\n        }\n    }\n}\n```\n\n```yaml\nspring:\n  ai:\n    mcp:\n      server:\n        protocol: STREAMABLE\n        streamable-http:\n          mcp-endpoint: /mcp\n```\n\nAfter `initialize` + `notifications/initialized`:\n\n```bash\ncurl -H \"Accept: application/json, text/event-stream\" \\\n     -H \"Content-Type: application/json\" \\\n     -H \"mcp-session-id: \u003csession\u003e\" \\\n     -X POST http://localhost:8080/mcp \\\n     -d '{\n       \"jsonrpc\":\"2.0\",\"id\":42,\"method\":\"completion/complete\",\n       \"params\":{\n         \"ref\":{\"type\":\"ref/prompt\",\"name\":\"uncovered\"},\n         \"argument\":{\"name\":\"name\",\"value\":\"A\"}\n       }\n     }'\n```\n\nThe server returns the `-32602` error shown above. Expected: an empty completion result.\n\n**How the other SDKs handle this**\n\nIn the TypeScript SDK, [`handlePromptCompletion`](https://github.com/modelcontextprotocol/typescript-sdk/blob/e12cbd7078db388152f6e839abdbe09ba01f3f32/src/server/mcp.ts#L431-L457) only throws when the prompt name itself is unknown or the prompt is disabled. If the prompt has no `argsSchema`, no `completable()` field, or no completer function, it returns an empty result.\n\nThe Python SDK does it through a single decorator-style [handler](https://github.com/modelcontextprotocol/python-sdk/blob/62137874ff26dd74d2fea80ff528a7fd9ca7a5e7/src/mcp/server/lowlevel/server.py#L610-L638), when the user-provided function returns `None`, the SDK wraps it as `Completion(values=[], total=None, hasMore=None)`.\n\nThe Java SDK already does the same in several places inside `completionCompleteRequestHandler`. The constant `EMPTY_COMPLETION_RESULT` is used for missing argument names and for fixed (non-template) resource URIs. The TS-style comment in the resource branch (\"not an error in the spec (but probably should be)\") is even copied verbatim into the Java file. So the intent is clearly aligned with the other SDKs, only this one branch was left strict.\n\n**Propose fix**\n\nChange in both `McpAsyncServer.java` and `McpStatelessAsyncServer.java`, [`completionCompleteRequestHandler()`](https://github.com/modelcontextprotocol/java-sdk/blob/304650c5a0df3a4be0536bf9eb5bfa3728632823/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java#L919-L1020) [`completionCompleteRequestHandler()`](https://github.com/modelcontextprotocol/java-sdk/blob/304650c5a0df3a4be0536bf9eb5bfa3728632823/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java#L704-L803) methods:\n\n```diff\n- if (specification == null) {\n-     return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)\n-         .message(\"AsyncCompletionSpecification not found: \" + request.ref())\n-         .build());\n- }\n+ if (specification == null) {\n+     logger.debug(\"No completion specification for ref: {}\", request.ref());\n+     return EMPTY_COMPLETION_RESULT;\n+ }\n```\n\nReady to discuss and open PR\n\n**Related**\n\n- #784 same pattern\n- #932 / PR #934 the recent fix for problem like this","author":{"url":"https://github.com/a-simeshin","@type":"Person","name":"a-simeshin"},"datePublished":"2026-05-30T10:36:57.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/991/java-sdk/issues/991"}