feat(server,lambda): route completion/complete through registered providers

McpCompletion providers registered via .completion_provider(...) were
stored but never consulted — both McpServerBuilder and
LambdaMcpServerBuilder registered a static CompletionHandler that ignored
its input and answered ["example1","example2"] (red phase showed the
placeholder verbatim on the wire).

- CompletionHandler now parses typed params (2026 CompleteRequestParams /
  frozen-2025 CompleteParams, lane-split) — malformed input → -32602,
  including reference-type literals "ref/prompt"/"ref/resource" the
  untagged union would otherwise accept open-ended.
- Deterministic routing: exact reference match first, can_handle fallback;
  priority desc then insertion order (provider storage HashMap → Vec —
  the first implementation was order-flaky and the tests caught it).
- Provider validate_request runs on the live path; the spec's 100-item
  completion.values cap is enforced (truncation sets total/hasMore).
- No matching provider → empty values; placeholder removed on both lanes.

Tests: completion_complete_routes_to_registered_provider,
completion_values_are_capped_at_100,
malformed_completion_params_are_rejected_with_32602 (+ existing shape
test). Revert-and-fail: red phase recorded before the handler rewrite.
Gates: scripts/ci-gates.sh all → ALL GATES PASSED (from-clean rebuild).

Closes spec-compliance driver gaps UTIL/COMP-1 (P1) + UTIL/COMP-3 (P2).

Author: hortovanyi

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`completion/complete` now dispatches to registered `McpCompletion` providers (2026-06-11).** Providers registered via `.completion_provider(...)` were stored but never consulted — the handler always answered with hardcoded placeholder values and ignored its input. The handler now parses typed `CompleteRequestParams` (malformed input → `-32602`, including reference-type literals `"ref/prompt"`/`"ref/resource"` that the untagged union would otherwise accept open-ended), routes deterministically (exact reference match first, `can_handle` fallback; priority desc then insertion order — provider storage moved from `HashMap` to `Vec` to make the tiebreak stable), runs the provider's `validate_request`, and enforces the spec's 100-item `completion.values` cap (truncation sets `total`/`hasMore`). No matching provider → empty values (the placeholder junk is gone). The same gap existed verbatim in `LambdaMcpServerBuilder` (providers stored, static handler answered) — mirrored fix there. Closes spec-compliance driver gaps **UTIL/COMP-1 (P1)** and **UTIL/COMP-3 (P2)**; red-phase wire tests in `discover_stateless_2026.rs`.
 - **Mode-aware MRTR capability gating (2026-06-11).** The server's `-32003` gate on `InputRequiredResult` now enforces sub-capabilities, not just top-level presence: URL-mode elicitation requires the client's `elicitation.url` declaration ("Servers MUST NOT send elicitation requests with modes that are not supported by the client"; an empty `elicitation: {}` declares form-only), and tool-enabled sampling (`tools`/`toolChoice` present) requires `sampling.tools` ("Servers MUST NOT send tool-enabled sampling requests to Clients that have not declared support"). Closes spec-compliance driver gaps **CF/GAP-CF-1 + CF/GAP-CF-2 (both P1)**; red-phase wire tests in `mrtr_2026.rs`.
 - **`roots/list` removed from the 2026 default surface (2026-06-11).** On 2026-07-28, roots is a client feature: the server requests roots via MRTR input requests and never hosts an inbound `roots/list` RPC; `notifications/roots/list_changed` has no binding in the pinned schema. The builder's `roots/list` + roots-notification registrations are now gated to the `protocol-2025-11-25` opt-in; on the 2026 default they answer 404 + `-32601` like every other non-2026 method. Closes spec-compliance driver gap **CF/GAP-CF-4 (P1)**; red-phase recorded in `error_mapping_2026.rs`.
 - **Client MRTR completion for `resources/read` + `prompts/get`, and `resultType` discipline (2026-06-11, ADR-030 revision log).** The bilingual client's `parse_read_resource`/`parse_get_prompt` now surface `InputRequiredResult` as `McpClientError::InputRequired` (previously a serde "missing field" error that discarded `inputRequests`/`requestState`), with retry APIs `read_resource_with_input_responses` / `get_prompt_with_input_responses` mirroring `call_tool_with_input_responses`. All 2026 result parsers now enforce basic §Responses ("a resultType of any value unrecognized by the client MUST be considered invalid"): unknown discriminators are `ProtocolError::InvalidResponse` instead of being treated as complete results. Closes spec-compliance driver gaps CF/GAP-CF-3, PRM/PR-2026-02, RES-G1, PAT/G3, BP-1 (all P1 except PAT/G3). Real-server e2e round-trips added; revert-and-fail recorded.

crates/turul-mcp-aws-lambda/src/builder.rs

@@ -99,7 +99,7 @@ pub struct LambdaMcpServerBuilder {
     sampling: HashMap<String, Arc<dyn McpSampling>>,
 
     /// Completion providers registered with the server
-    completions: HashMap<String, Arc<dyn McpCompletion>>,
+    completions: Vec<Arc<dyn McpCompletion>>,
 
     /// Loggers registered with the server
     #[cfg(feature = "protocol-2025-11-25")]
@@ -176,7 +176,7 @@ impl LambdaMcpServerBuilder {
         handlers.insert("ping".to_string(), Arc::new(PingHandler));
         handlers.insert(
             "completion/complete".to_string(),
-            Arc::new(CompletionHandler),
+            Arc::new(CompletionHandler::new()),
         );
         handlers.insert(
             "resources/list".to_string(),
@@ -273,7 +273,7 @@ impl LambdaMcpServerBuilder {
             elicitations: HashMap::new(),
             #[cfg(feature = "protocol-2025-11-25")]
             sampling: HashMap::new(),
-            completions: HashMap::new(),
+            completions: Vec::new(),
             #[cfg(feature = "protocol-2025-11-25")]
             loggers: HashMap::new(),
             root_providers: HashMap::new(),
@@ -468,8 +468,7 @@ impl LambdaMcpServerBuilder {
 
     /// Register a completion provider with the server
     pub fn completion_provider<C: McpCompletion + 'static>(mut self, completion: C) -> Self {
-        let key = format!("completion_{}", self.completions.len());
-        self.completions.insert(key, Arc::new(completion));
+        self.completions.push(Arc::new(completion));
         self
     }
 
@@ -596,7 +595,7 @@ impl LambdaMcpServerBuilder {
     pub fn with_completion(mut self) -> Self {
         use turul_mcp_protocol::initialize::CompletionsCapabilities;
         self.capabilities.completions = Some(CompletionsCapabilities::default());
-        self.handler(CompletionHandler)
+        self.handler(CompletionHandler::new())
     }
 
     /// Add prompts support
@@ -1124,6 +1123,14 @@ impl LambdaMcpServerBuilder {
 
         // Add RootsHandler if roots were configured (same pattern as MCP server)
         let mut handlers = self.handlers;
+
+        // Route completion/complete through the registered providers.
+        if !self.completions.is_empty() {
+            handlers.insert(
+                "completion/complete".to_string(),
+                Arc::new(CompletionHandler::new().with_providers(self.completions.clone())),
+            );
+        }
         if !self.roots.is_empty() {
             let mut roots_handler = RootsHandler::new();
             for root in &self.roots {

crates/turul-mcp-aws-lambda/src/server.rs

@@ -47,7 +47,7 @@ pub struct LambdaMcpServer {
     #[cfg(feature = "protocol-2025-11-25")]
     sampling: HashMap<String, Arc<dyn McpSampling>>,
     /// Registered completion providers
-    completions: HashMap<String, Arc<dyn McpCompletion>>,
+    completions: Vec<Arc<dyn McpCompletion>>,
     /// Registered loggers
     #[cfg(feature = "protocol-2025-11-25")]
     loggers: HashMap<String, Arc<dyn McpLogger>>,
@@ -111,7 +111,7 @@ impl LambdaMcpServer {
             Arc<dyn McpElicitation>,
         >,
         #[cfg(feature = "protocol-2025-11-25")] sampling: HashMap<String, Arc<dyn McpSampling>>,
-        completions: HashMap<String, Arc<dyn McpCompletion>>,
+        completions: Vec<Arc<dyn McpCompletion>>,
         #[cfg(feature = "protocol-2025-11-25")] loggers: HashMap<String, Arc<dyn McpLogger>>,
         root_providers: HashMap<String, Arc<dyn McpRoot>>,
         notifications: HashMap<String, Arc<dyn McpNotification>>,

crates/turul-mcp-server/src/builder.rs

@@ -50,7 +50,7 @@ pub struct McpServerBuilder {
     sampling: HashMap<String, Arc<dyn McpSampling>>,
 
     /// Completion providers registered with the server
-    completions: HashMap<String, Arc<dyn McpCompletion>>,
+    completions: Vec<Arc<dyn McpCompletion>>,
 
     /// Loggers registered with the server
     #[cfg(feature = "protocol-2025-11-25")]
@@ -137,7 +137,7 @@ impl McpServerBuilder {
         handlers.insert("ping".to_string(), Arc::new(PingHandler));
         handlers.insert(
             "completion/complete".to_string(),
-            Arc::new(CompletionHandler),
+            Arc::new(CompletionHandler::new()),
         );
         handlers.insert(
             "resources/list".to_string(),
@@ -241,7 +241,7 @@ impl McpServerBuilder {
             elicitations: HashMap::new(),
             #[cfg(feature = "protocol-2025-11-25")]
             sampling: HashMap::new(),
-            completions: HashMap::new(),
+            completions: Vec::new(),
             #[cfg(feature = "protocol-2025-11-25")]
             loggers: HashMap::new(),
             root_providers: HashMap::new(),
@@ -918,8 +918,7 @@ impl McpServerBuilder {
 
     /// Register a completion provider with the server
     pub fn completion_provider<C: McpCompletion + 'static>(mut self, completion: C) -> Self {
-        let key = format!("completion_{}", self.completions.len());
-        self.completions.insert(key, Arc::new(completion));
+        self.completions.push(Arc::new(completion));
         self
     }
 
@@ -1084,7 +1083,7 @@ impl McpServerBuilder {
     /// Add completion support
     pub fn with_completion(mut self) -> Self {
         self.capabilities.completions = Some(CompletionsCapabilities::default());
-        self.handler(CompletionHandler)
+        self.handler(CompletionHandler::new())
     }
 
     /// Add prompts support
@@ -1729,6 +1728,14 @@ impl McpServerBuilder {
             handlers.insert("roots/list".to_string(), Arc::new(roots_handler));
         }
 
+        // Route completion/complete through the registered providers.
+        if !self.completions.is_empty() {
+            handlers.insert(
+                "completion/complete".to_string(),
+                Arc::new(CompletionHandler::new().with_providers(self.completions.clone())),
+            );
+        }
+
         // Add PromptsHandlers if prompts were configured
         if !self.prompts.is_empty() {
             let mut prompts_list_handler = PromptsListHandler::new();

crates/turul-mcp-server/src/handlers/mod.rs

@@ -234,20 +234,112 @@ impl McpHandler for PingHandler {
     }
 }
 
-/// Completion handler for completion/complete endpoint
-pub struct CompletionHandler;
+/// Completion handler for the completion/complete endpoint.
+///
+/// Routes to registered [`McpCompletion`](crate::McpCompletion) providers:
+/// highest `priority()` first, first `can_handle()` wins. Responses honor the
+/// spec's 100-item cap on `completion.values` (oversized provider output is
+/// truncated with `total`/`hasMore` reflecting the cut). With no matching
+/// provider the result carries empty values.
+#[derive(Default)]
+pub struct CompletionHandler {
+    providers: Vec<Arc<dyn crate::McpCompletion>>,
+}
+
+impl CompletionHandler {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_providers(mut self, providers: Vec<Arc<dyn crate::McpCompletion>>) -> Self {
+        self.providers = providers;
+        // Stable sort: priority desc, insertion order as the tiebreak.
+        self.providers
+            .sort_by_key(|p| std::cmp::Reverse(p.priority()));
+        self
+    }
+}
+
+/// Does a provider's declared reference target the request's reference?
+fn completion_reference_matches(
+    declared: &turul_mcp_protocol::completion::CompletionReference,
+    requested: &turul_mcp_protocol::completion::CompletionReference,
+) -> bool {
+    use turul_mcp_protocol::completion::CompletionReference as Ref;
+    match (declared, requested) {
+        (Ref::Prompt(a), Ref::Prompt(b)) => a.name == b.name,
+        (Ref::ResourceTemplate(a), Ref::ResourceTemplate(b)) => a.uri == b.uri,
+        _ => false,
+    }
+}
+
+/// `completion.values` carries "Maximum 100 items" per the Completion spec.
+const COMPLETION_VALUES_CAP: usize = 100;
 
 #[async_trait]
 impl McpHandler for CompletionHandler {
-    async fn handle(&self, _params: Option<Value>) -> McpResult<Value> {
-        use turul_mcp_protocol::completion::{CompleteResult, CompletionResult};
+    async fn handle(&self, params: Option<Value>) -> McpResult<Value> {
+        use turul_mcp_protocol::completion::{CompleteRequest, CompleteResult, CompletionResult};
+        // The params struct is `CompleteRequestParams` on 2026-07-28 (required
+        // `_meta`) and `CompleteParams` on the frozen 2025-11-25 snapshot.
+        #[cfg(feature = "protocol-2025-11-25")]
+        use turul_mcp_protocol::completion::CompleteParams as TypedCompleteParams;
+        #[cfg(feature = "protocol-2026-07-28")]
+        use turul_mcp_protocol::completion::CompleteRequestParams as TypedCompleteParams;
 
-        // Default implementation - can be overridden by users
-        let values = vec!["example1".to_string(), "example2".to_string()];
+        let params = params.ok_or_else(|| {
+            McpError::InvalidParameters("completion/complete requires params".to_string())
+        })?;
+        let typed: TypedCompleteParams = serde_json::from_value(params)
+            .map_err(|e| McpError::InvalidParameters(format!("invalid completion params: {e}")))?;
+        // The untagged reference union accepts any `type` string — enforce
+        // the schema's literals ("ref/prompt" / "ref/resource") here.
+        let ref_type = match &typed.reference {
+            turul_mcp_protocol::completion::CompletionReference::Prompt(p) => {
+                (&p.ref_type, "ref/prompt")
+            }
+            turul_mcp_protocol::completion::CompletionReference::ResourceTemplate(r) => {
+                (&r.ref_type, "ref/resource")
+            }
+        };
+        if ref_type.0 != ref_type.1 {
+            return Err(McpError::InvalidParameters(format!(
+                "unknown completion reference type {:?} (expected \"ref/prompt\" or \"ref/resource\")",
+                ref_type.0
+            )));
+        }
+        let request = CompleteRequest {
+            method: "completion/complete".to_string(),
+            params: typed,
+        };
 
-        let completion_result = CompletionResult::new(values);
-        let response = CompleteResult::new(completion_result);
-        serde_json::to_value(response).map_err(McpError::from)
+        // Providers declaring the request's exact reference win; a provider
+        // whose can_handle accepts the request is the fallback. Both passes
+        // run in (priority desc, insertion) order, so routing is
+        // deterministic.
+        let provider = self
+            .providers
+            .iter()
+            .find(|p| {
+                completion_reference_matches(p.reference(), &request.params.reference)
+                    && p.can_handle(&request)
+            })
+            .or_else(|| self.providers.iter().find(|p| p.can_handle(&request)));
+        let result = match provider {
+            Some(provider) => {
+                crate::McpCompletion::validate_request(provider.as_ref(), &request).await?;
+                let mut result = provider.complete(request).await?;
+                let len = result.completion.values.len();
+                if len > COMPLETION_VALUES_CAP {
+                    result.completion.values.truncate(COMPLETION_VALUES_CAP);
+                    result.completion.has_more = Some(true);
+                    result.completion.total.get_or_insert(len as u32);
+                }
+                result
+            }
+            None => CompleteResult::new(CompletionResult::new(Vec::new())),
+        };
+        serde_json::to_value(result).map_err(McpError::from)
     }
 
     fn supported_methods(&self) -> Vec<String> {