1use std::{borrow::Cow, fmt, sync::Arc};
7
8use rmcp::{
9 ErrorData, RoleServer, ServerHandler,
10 model::{
11 CallToolRequestParams, CallToolResponse, CompleteRequestParams, CompleteResult,
12 CustomRequest, CustomResult, DiscoverResult, ErrorCode, GetPromptRequestParams,
13 GetPromptResponse, Implementation, ListPromptsResult, ListResourceTemplatesResult,
14 ListResourcesResult, ListToolsResult, PaginatedRequestParams, PromptsCapability,
15 ProtocolVersion, ReadResourceRequestParams, ReadResourceResponse, ResourcesCapability,
16 ServerCapabilities, ServerConfig, Tool, ToolsCapability,
17 },
18 service::RequestContext,
19};
20use thiserror::Error;
21
22use crate::{
23 McpServerApplicationOptions, McpServerCompletionProvider, McpServerPromptAuthorization,
24 McpServerPromptCatalog, McpServerPromptRenderer, McpServerPromptService,
25 McpServerPromptServiceBuildError, McpServerResourceAuthorization, McpServerResourceCatalog,
26 McpServerResourceReader, McpServerResourceService, McpServerResourceServiceBuildError,
27 McpServerSkillAuthorization, McpServerSkillCatalog, McpServerSkillService,
28 McpServerSkillServiceBuildError, McpServerToolAuthorization, McpServerToolRegistry,
29 McpServerToolService, McpServerToolServiceBuildError,
30};
31
32pub struct McpServerApplicationBuilder {
34 options: McpServerApplicationOptions,
35 tools: Option<McpServerToolService>,
36 resources: Option<McpServerResourceService>,
37 skills: Option<McpServerSkillService>,
38 prompts: Option<McpServerPromptService>,
39 completion: Option<Arc<dyn McpServerCompletionProvider>>,
40}
41
42impl McpServerApplicationBuilder {
43 #[must_use]
45 pub fn new(options: McpServerApplicationOptions) -> Self {
46 Self {
47 options,
48 tools: None,
49 resources: None,
50 skills: None,
51 prompts: None,
52 completion: None,
53 }
54 }
55
56 pub fn with_tools<A>(
58 mut self,
59 registry: McpServerToolRegistry,
60 authorization: A,
61 ) -> Result<Self, McpServerApplicationBuildError>
62 where
63 A: McpServerToolAuthorization,
64 {
65 if self.tools.is_some() {
66 return Err(McpServerApplicationBuildError::DuplicateTools);
67 }
68 self.tools = Some(
69 McpServerToolService::new(registry, self.options.clone(), authorization)
70 .map_err(McpServerApplicationBuildError::ToolService)?,
71 );
72 Ok(self)
73 }
74
75 pub fn with_resources<R, A>(
77 mut self,
78 catalog: McpServerResourceCatalog,
79 reader: R,
80 authorization: A,
81 ) -> Result<Self, McpServerApplicationBuildError>
82 where
83 R: McpServerResourceReader,
84 A: McpServerResourceAuthorization,
85 {
86 if self.resources.is_some() {
87 return Err(McpServerApplicationBuildError::DuplicateResources);
88 }
89 self.resources = Some(
90 McpServerResourceService::new(catalog, self.options.clone(), reader, authorization)
91 .map_err(McpServerApplicationBuildError::ResourceService)?,
92 );
93 Ok(self)
94 }
95
96 pub fn with_skills<A>(
98 mut self,
99 catalog: McpServerSkillCatalog,
100 authorization: A,
101 ) -> Result<Self, McpServerApplicationBuildError>
102 where
103 A: McpServerSkillAuthorization,
104 {
105 if self.skills.is_some() {
106 return Err(McpServerApplicationBuildError::DuplicateSkills);
107 }
108 self.skills = Some(
109 McpServerSkillService::new(catalog, self.options.clone(), authorization)
110 .map_err(McpServerApplicationBuildError::SkillService)?,
111 );
112 Ok(self)
113 }
114
115 pub fn with_prompts<R, A>(
117 mut self,
118 catalog: McpServerPromptCatalog,
119 renderer: R,
120 authorization: A,
121 ) -> Result<Self, McpServerApplicationBuildError>
122 where
123 R: McpServerPromptRenderer,
124 A: McpServerPromptAuthorization,
125 {
126 if self.prompts.is_some() {
127 return Err(McpServerApplicationBuildError::DuplicatePrompts);
128 }
129 self.prompts = Some(
130 McpServerPromptService::new(catalog, self.options.clone(), renderer, authorization)
131 .map_err(McpServerApplicationBuildError::PromptService)?,
132 );
133 Ok(self)
134 }
135
136 pub fn with_completion_provider<C>(
138 mut self,
139 provider: C,
140 ) -> Result<Self, McpServerApplicationBuildError>
141 where
142 C: McpServerCompletionProvider,
143 {
144 if self.completion.is_some() {
145 return Err(McpServerApplicationBuildError::DuplicateCompletion);
146 }
147 self.completion = Some(Arc::new(provider));
148 Ok(self)
149 }
150
151 pub fn build(mut self) -> Result<McpServerApplication, McpServerApplicationBuildError> {
153 if self.tools.is_none()
154 && self.resources.is_none()
155 && self.skills.is_none()
156 && self.prompts.is_none()
157 {
158 return Err(McpServerApplicationBuildError::Empty);
159 }
160 if let (Some(resources), Some(skills)) = (&self.resources, &self.skills)
161 && skills
162 .resource_uris()
163 .any(|uri| resources.contains_resource(uri))
164 {
165 return Err(McpServerApplicationBuildError::ConflictingResourceUri);
166 }
167 if let Some(completion) = self.completion {
168 let prompts = self
169 .prompts
170 .take()
171 .ok_or(McpServerApplicationBuildError::CompletionRequiresPrompts)?;
172 self.prompts = Some(prompts.with_shared_completion_provider(completion));
173 }
174 Ok(McpServerApplication {
175 options: self.options,
176 tools: self.tools,
177 resources: self.resources,
178 skills: self.skills,
179 prompts: self.prompts,
180 })
181 }
182}
183
184impl fmt::Debug for McpServerApplicationBuilder {
185 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
186 formatter
187 .debug_struct("McpServerApplicationBuilder")
188 .field("options", &self.options)
189 .field("tools", &self.tools.is_some())
190 .field("resources", &self.resources.is_some())
191 .field("skills", &self.skills.is_some())
192 .field("prompts", &self.prompts.is_some())
193 .field("completion", &self.completion.is_some())
194 .finish_non_exhaustive()
195 }
196}
197
198#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
200#[non_exhaustive]
201pub enum McpServerApplicationBuildError {
202 #[error("MCP server application has no capabilities")]
204 Empty,
205 #[error("MCP tool surface is already configured")]
207 DuplicateTools,
208 #[error("MCP resource surface is already configured")]
210 DuplicateResources,
211 #[error("MCP Skill surface is already configured")]
213 DuplicateSkills,
214 #[error("MCP prompt surface is already configured")]
216 DuplicatePrompts,
217 #[error("MCP completion surface is already configured")]
219 DuplicateCompletion,
220 #[error("MCP completion requires a configured prompt surface")]
222 CompletionRequiresPrompts,
223 #[error("MCP Resource and Skill catalogs contain the same URI")]
225 ConflictingResourceUri,
226 #[error("invalid MCP tool service: {0}")]
228 ToolService(McpServerToolServiceBuildError),
229 #[error("invalid MCP resource service: {0}")]
231 ResourceService(McpServerResourceServiceBuildError),
232 #[error("invalid MCP Skill service: {0}")]
234 SkillService(McpServerSkillServiceBuildError),
235 #[error("invalid MCP prompt service: {0}")]
237 PromptService(McpServerPromptServiceBuildError),
238}
239
240#[derive(Clone)]
242pub struct McpServerApplication {
243 options: McpServerApplicationOptions,
244 tools: Option<McpServerToolService>,
245 resources: Option<McpServerResourceService>,
246 skills: Option<McpServerSkillService>,
247 prompts: Option<McpServerPromptService>,
248}
249
250impl McpServerApplication {
251 #[must_use]
253 pub const fn has_tools(&self) -> bool {
254 self.tools.is_some()
255 }
256
257 #[must_use]
259 pub const fn has_resources(&self) -> bool {
260 self.resources.is_some() || self.skills.is_some()
261 }
262
263 #[must_use]
265 pub const fn has_skills(&self) -> bool {
266 self.skills.is_some()
267 }
268
269 #[must_use]
271 pub const fn has_prompts(&self) -> bool {
272 self.prompts.is_some()
273 }
274
275 #[must_use]
277 pub fn has_completion(&self) -> bool {
278 self.prompts
279 .as_ref()
280 .is_some_and(|service| service.get_info().capabilities.completions.is_some())
281 }
282
283 fn capabilities(&self) -> ServerCapabilities {
284 let mut capabilities = ServerCapabilities::default();
285 if self.tools.is_some() {
286 capabilities.tools = Some(ToolsCapability::default());
287 }
288 if self.resources.is_some() || self.skills.is_some() {
289 capabilities.resources = Some(ResourcesCapability::default());
290 }
291 if self.skills.is_some() {
292 capabilities.extensions = McpServerSkillService::capabilities().extensions;
293 }
294 if self.prompts.is_some() {
295 capabilities.prompts = Some(PromptsCapability::default());
296 }
297 if self.has_completion() {
298 capabilities.completions = Some(serde_json::Map::new());
299 }
300 capabilities
301 }
302}
303
304impl fmt::Debug for McpServerApplication {
305 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
306 formatter
307 .debug_struct("McpServerApplication")
308 .field("options", &self.options)
309 .field("tools", &self.has_tools())
310 .field("resources", &self.has_resources())
311 .field("skills", &self.has_skills())
312 .field("prompts", &self.has_prompts())
313 .field("completion", &self.has_completion())
314 .finish_non_exhaustive()
315 }
316}
317
318impl ServerHandler for McpServerApplication {
319 fn supported_protocol_versions(&self) -> Cow<'static, [ProtocolVersion]> {
320 Cow::Borrowed(&[ProtocolVersion::V_2026_07_28])
321 }
322
323 fn get_info(&self) -> ServerConfig {
324 let mut info =
325 ServerConfig::new(self.capabilities()).with_server_info(Implementation::new(
326 self.options.server_name.to_string(),
327 self.options.server_version.to_string(),
328 ));
329 if let Some(instructions) = &self.options.instructions {
330 info = info.with_instructions(instructions.to_string());
331 }
332 info
333 }
334
335 async fn discover(
336 &self,
337 _context: RequestContext<RoleServer>,
338 ) -> Result<DiscoverResult, ErrorData> {
339 Ok(
340 DiscoverResult::from_server_info(vec![ProtocolVersion::V_2026_07_28], self.get_info())
341 .with_ttl_ms(self.options.cache_ttl_ms)
342 .with_cache_scope(self.options.cache_scope.into()),
343 )
344 }
345
346 fn get_tool(&self, name: &str) -> Option<Tool> {
347 self.tools
348 .as_ref()
349 .and_then(|service| ServerHandler::get_tool(service, name))
350 }
351
352 async fn list_tools(
353 &self,
354 request: Option<PaginatedRequestParams>,
355 context: RequestContext<RoleServer>,
356 ) -> Result<ListToolsResult, ErrorData> {
357 let Some(service) = &self.tools else {
358 return Err(method_not_found("tools/list"));
359 };
360 ServerHandler::list_tools(service, request, context).await
361 }
362
363 async fn call_tool(
364 &self,
365 request: CallToolRequestParams,
366 context: RequestContext<RoleServer>,
367 ) -> Result<CallToolResponse, ErrorData> {
368 let Some(service) = &self.tools else {
369 return Err(method_not_found("tools/call"));
370 };
371 ServerHandler::call_tool(service, request, context).await
372 }
373
374 async fn on_custom_request(
375 &self,
376 request: CustomRequest,
377 context: RequestContext<RoleServer>,
378 ) -> Result<CustomResult, ErrorData> {
379 let Some(service) = &self.skills else {
380 return Err(method_not_found_owned(request.method));
381 };
382 service.dispatch_custom(request, context).await
383 }
384
385 async fn list_resources(
386 &self,
387 request: Option<PaginatedRequestParams>,
388 context: RequestContext<RoleServer>,
389 ) -> Result<ListResourcesResult, ErrorData> {
390 if let Some(service) = &self.resources {
391 return ServerHandler::list_resources(service, request, context).await;
392 }
393 if let Some(service) = &self.skills {
394 return ServerHandler::list_resources(service, request, context).await;
395 }
396 Err(method_not_found("resources/list"))
397 }
398
399 async fn list_resource_templates(
400 &self,
401 request: Option<PaginatedRequestParams>,
402 context: RequestContext<RoleServer>,
403 ) -> Result<ListResourceTemplatesResult, ErrorData> {
404 if let Some(service) = &self.resources {
405 return ServerHandler::list_resource_templates(service, request, context).await;
406 }
407 if let Some(service) = &self.skills {
408 return ServerHandler::list_resource_templates(service, request, context).await;
409 }
410 Err(method_not_found("resources/templates/list"))
411 }
412
413 async fn read_resource(
414 &self,
415 request: ReadResourceRequestParams,
416 context: RequestContext<RoleServer>,
417 ) -> Result<ReadResourceResponse, ErrorData> {
418 if let Some(service) = &self.skills
419 && service.contains_resource(&request.uri)
420 {
421 return service.dispatch_read(request, context).await;
422 }
423 if let Some(service) = &self.resources {
424 return ServerHandler::read_resource(service, request, context).await;
425 }
426 if let Some(service) = &self.skills {
427 return service.dispatch_read(request, context).await;
428 }
429 Err(method_not_found("resources/read"))
430 }
431
432 async fn list_prompts(
433 &self,
434 request: Option<PaginatedRequestParams>,
435 context: RequestContext<RoleServer>,
436 ) -> Result<ListPromptsResult, ErrorData> {
437 let Some(service) = &self.prompts else {
438 return Err(method_not_found("prompts/list"));
439 };
440 ServerHandler::list_prompts(service, request, context).await
441 }
442
443 async fn get_prompt(
444 &self,
445 request: GetPromptRequestParams,
446 context: RequestContext<RoleServer>,
447 ) -> Result<GetPromptResponse, ErrorData> {
448 let Some(service) = &self.prompts else {
449 return Err(method_not_found("prompts/get"));
450 };
451 ServerHandler::get_prompt(service, request, context).await
452 }
453
454 async fn complete(
455 &self,
456 request: CompleteRequestParams,
457 context: RequestContext<RoleServer>,
458 ) -> Result<CompleteResult, ErrorData> {
459 let Some(service) = &self.prompts else {
460 return Err(method_not_found("completion/complete"));
461 };
462 ServerHandler::complete(service, request, context).await
463 }
464}
465
466fn method_not_found(method: &'static str) -> ErrorData {
467 ErrorData::new(ErrorCode::METHOD_NOT_FOUND, method, None)
468}
469
470fn method_not_found_owned(method: String) -> ErrorData {
471 ErrorData::new(ErrorCode::METHOD_NOT_FOUND, method, None)
472}
473
474#[cfg(test)]
475mod tests {
476 use std::time::Duration;
477
478 use bytes::Bytes;
479 use http::{Request, StatusCode};
480 use http_body_util::{BodyExt as _, Full};
481 use serde_json::{Value, json};
482 use tower_service::Service as _;
483
484 use super::*;
485 use crate::{
486 AllowMcpServerPromptAuthorization, AllowMcpServerResourceAuthorization,
487 AllowMcpServerSkillAuthorization, AllowMcpServerToolAuthorization, MCP_SKILLS_EXTENSION_ID,
488 McpServerAuthentication, McpServerCacheScope, McpServerContent, McpServerHttpOptions,
489 McpServerHttpService, McpServerPromptCatalogBuilder, McpServerPromptContext,
490 McpServerPromptDefinition, McpServerPromptMessage, McpServerPromptOutcome,
491 McpServerPromptRender, McpServerPromptRendererError, McpServerPromptResult,
492 McpServerPromptRole, McpServerResourceCatalogBuilder, McpServerResourceContent,
493 McpServerResourceContext, McpServerResourceDefinition, McpServerResourceOutcome,
494 McpServerResourceRead, McpServerResourceReaderError, McpServerResourceResult,
495 McpServerSkillCatalogBuilder, McpServerSkillDefinition, McpServerSkillFile,
496 McpServerToolCall, McpServerToolContext, McpServerToolDefinition,
497 McpServerToolHandlerError, McpServerToolOutcome, McpServerToolRegistryBuilder,
498 McpServerToolResult,
499 };
500
501 #[derive(Clone, Copy)]
502 struct TestTool;
503
504 impl crate::McpServerToolHandler for TestTool {
505 fn call(
506 &self,
507 _call: McpServerToolCall,
508 _context: McpServerToolContext,
509 ) -> stateknot_core::BoxFuture<'_, Result<McpServerToolOutcome, McpServerToolHandlerError>>
510 {
511 Box::pin(async {
512 let content = McpServerContent::text("tool").unwrap();
513 Ok(McpServerToolResult::success([content]).unwrap().into())
514 })
515 }
516 }
517
518 #[derive(Clone, Copy)]
519 struct TestReader;
520
521 impl McpServerResourceReader for TestReader {
522 fn read(
523 &self,
524 request: McpServerResourceRead,
525 _context: McpServerResourceContext,
526 ) -> stateknot_core::BoxFuture<
527 '_,
528 Result<McpServerResourceOutcome, McpServerResourceReaderError>,
529 > {
530 let uri = request.uri().to_owned();
531 Box::pin(async move {
532 let content =
533 McpServerResourceContent::text(uri, Some("text/plain"), "resource").unwrap();
534 Ok(McpServerResourceResult::new(
535 [content],
536 Duration::ZERO,
537 McpServerCacheScope::Private,
538 )
539 .unwrap()
540 .into())
541 })
542 }
543 }
544
545 #[derive(Clone, Copy)]
546 struct TestRenderer;
547
548 impl McpServerPromptRenderer for TestRenderer {
549 fn render(
550 &self,
551 _request: McpServerPromptRender,
552 _context: McpServerPromptContext,
553 ) -> stateknot_core::BoxFuture<
554 '_,
555 Result<McpServerPromptOutcome, McpServerPromptRendererError>,
556 > {
557 Box::pin(async {
558 let content = McpServerContent::text("prompt").unwrap();
559 Ok(McpServerPromptResult::new([McpServerPromptMessage::new(
560 McpServerPromptRole::User,
561 content,
562 )])
563 .unwrap()
564 .into())
565 })
566 }
567 }
568
569 fn application() -> McpServerHttpService<McpServerApplication> {
570 let mut tools = McpServerToolRegistryBuilder::default();
571 tools
572 .register(
573 McpServerToolDefinition::new(
574 "test_tool",
575 json!({ "type": "object", "additionalProperties": false }),
576 )
577 .unwrap(),
578 TestTool,
579 )
580 .unwrap();
581 let mut resources = McpServerResourceCatalogBuilder::default();
582 resources
583 .register_resource(McpServerResourceDefinition::new("test://one", "One").unwrap())
584 .unwrap();
585 let mut prompts = McpServerPromptCatalogBuilder::default();
586 prompts
587 .register(McpServerPromptDefinition::new("test_prompt").unwrap())
588 .unwrap();
589 let mut skills = McpServerSkillCatalogBuilder::default();
590 skills
591 .register(
592 McpServerSkillDefinition::new(
593 "skill://test-skill/SKILL.md",
594 [McpServerSkillFile::text(
595 "SKILL.md",
596 "text/markdown",
597 "---\nname: test-skill\ndescription: Composite application test Skill.\n---\n",
598 )
599 .unwrap()],
600 )
601 .unwrap(),
602 )
603 .unwrap();
604 let options = McpServerApplicationOptions::new(
605 "stateknot-composite-test",
606 "0.0.0",
607 32,
608 Duration::from_secs(60),
609 McpServerCacheScope::Private,
610 )
611 .unwrap();
612 let application = McpServerApplicationBuilder::new(options)
613 .with_tools(tools.build().unwrap(), AllowMcpServerToolAuthorization)
614 .unwrap()
615 .with_resources(
616 resources.build().unwrap(),
617 TestReader,
618 AllowMcpServerResourceAuthorization,
619 )
620 .unwrap()
621 .with_skills(skills.build().unwrap(), AllowMcpServerSkillAuthorization)
622 .unwrap()
623 .with_prompts(
624 prompts.build().unwrap(),
625 TestRenderer,
626 AllowMcpServerPromptAuthorization,
627 )
628 .unwrap()
629 .build()
630 .unwrap();
631 McpServerHttpService::new(
632 application,
633 McpServerHttpOptions::loopback(32127).unwrap(),
634 McpServerAuthentication::anonymous_loopback(),
635 )
636 .unwrap()
637 }
638
639 fn request(method: &str, mut params: Value) -> Request<Full<Bytes>> {
640 params.as_object_mut().unwrap().insert(
641 "_meta".to_owned(),
642 json!({
643 "io.modelcontextprotocol/protocolVersion": "2026-07-28",
644 "io.modelcontextprotocol/clientInfo": { "name": "test", "version": "0" },
645 "io.modelcontextprotocol/clientCapabilities": {
646 "extensions": { (MCP_SKILLS_EXTENSION_ID): {} }
647 }
648 }),
649 );
650 let body = serde_json::to_vec(&json!({
651 "jsonrpc": "2.0", "id": 1, "method": method, "params": params
652 }))
653 .unwrap();
654 Request::builder()
655 .method("POST")
656 .uri("http://127.0.0.1:32127/mcp")
657 .header("host", "127.0.0.1:32127")
658 .header("origin", "http://127.0.0.1:32127")
659 .header("content-type", "application/json")
660 .header("accept", "application/json, text/event-stream")
661 .header("mcp-protocol-version", "2026-07-28")
662 .header("mcp-method", method)
663 .body(Full::new(Bytes::from(body)))
664 .unwrap()
665 }
666
667 #[tokio::test]
668 async fn composite_discovery_advertises_only_configured_surfaces() {
669 let mut service = application();
670 let response = service
671 .call(request("server/discover", json!({})))
672 .await
673 .unwrap();
674 assert_eq!(response.status(), StatusCode::OK);
675 let bytes = response.into_body().collect().await.unwrap().to_bytes();
676 let value: Value = serde_json::from_slice(&bytes).unwrap();
677 assert!(value.pointer("/result/capabilities/tools").is_some());
678 assert!(value.pointer("/result/capabilities/resources").is_some());
679 assert!(value.pointer("/result/capabilities/prompts").is_some());
680 assert!(value.pointer("/result/capabilities/completions").is_none());
681 assert_eq!(
682 value.pointer("/result/capabilities/extensions/io.modelcontextprotocol~1skills"),
683 Some(&json!({}))
684 );
685 }
686
687 #[tokio::test]
688 async fn composite_dispatches_the_skills_extension() {
689 let mut service = application();
690 let response = service
691 .call(request(
692 "skills/get",
693 json!({ "uri": "skill://test-skill/SKILL.md" }),
694 ))
695 .await
696 .unwrap();
697 assert_eq!(response.status(), StatusCode::OK);
698 let bytes = response.into_body().collect().await.unwrap().to_bytes();
699 let value: Value = serde_json::from_slice(&bytes).unwrap();
700 assert_eq!(
701 value.pointer("/result/skill/frontmatter/name"),
702 Some(&json!("test-skill"))
703 );
704 }
705}