From f6acdfcacb1d9ed05fdc69cb8fc4ff04dc3912a9 Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 19:55:27 -0400
Subject: [PATCH 1/8] Add C# MCP Server Development collection (#323)
* Add C# MCP Server Development collection
- Add instructions for C# MCP server development best practices
- Add prompt for generating complete MCP server projects
- Add expert chat mode for C# MCP development assistance
- Add collection grouping all C# MCP resources together
- Update README files with new contributions
* Add applyTo field to C# MCP instructions
---
README.chatmodes.md | 1 +
README.collections.md | 2 +
README.instructions.md | 1 +
README.prompts.md | 3 +
chatmodes/csharp-mcp-expert.chatmode.md | 69 ++++++++++++++
.../csharp-mcp-development.collection.yml | 32 +++++++
collections/csharp-mcp-development.md | 38 ++++++++
.../csharp-mcp-server.instructions.md | 95 +++++++++++++++++++
prompts/csharp-mcp-server-generator.prompt.md | 59 ++++++++++++
9 files changed, 300 insertions(+)
create mode 100644 chatmodes/csharp-mcp-expert.chatmode.md
create mode 100644 collections/csharp-mcp-development.collection.yml
create mode 100644 collections/csharp-mcp-development.md
create mode 100644 instructions/csharp-mcp-server.instructions.md
create mode 100644 prompts/csharp-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index 771a7b6..28ba028 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -28,6 +28,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [Azure Terraform Infrastructure Planning](chatmodes/terraform-azure-planning.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fterraform-azure-planning.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fterraform-azure-planning.chatmode.md) | Act as implementation planner for your Azure Terraform Infrastructure as Code task. |
| [Blueprint Mode Codex v1](chatmodes/blueprint-mode-codex.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fblueprint-mode-codex.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fblueprint-mode-codex.chatmode.md) | Executes structured workflows with strict correctness and maintainability. Enforces a minimal tool usage policy, never assumes facts, prioritizes reproducible solutions, self-correction, and edge-case handling. |
| [Blueprint Mode v39](chatmodes/blueprint-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fblueprint-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fblueprint-mode.chatmode.md) | Executes structured workflows (Debug, Express, Main, Loop) with strict correctness and maintainability. Enforces an improved tool usage policy, never assumes facts, prioritizes reproducible solutions, self-correction, and edge-case handling. |
+| [C# MCP Server Expert](chatmodes/csharp-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fcsharp-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fcsharp-mcp-expert.chatmode.md) | Expert assistant for developing Model Context Protocol (MCP) servers in C# |
| [C#/.NET Janitor](chatmodes/csharp-dotnet-janitor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fcsharp-dotnet-janitor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fcsharp-dotnet-janitor.chatmode.md) | Perform janitorial tasks on C#/.NET code including cleanup, modernization, and tech debt remediation. |
| [Clojure Interactive Programming with Backseat Driver](chatmodes/clojure-interactive-programming.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fclojure-interactive-programming.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fclojure-interactive-programming.chatmode.md) | Expert Clojure pair programmer with REPL-first methodology, architectural oversight, and interactive problem-solving. Enforces quality standards, prevents workarounds, and develops solutions incrementally through live REPL evaluation before file modifications. |
| [Create PRD Chat Mode](chatmodes/prd.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprd.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprd.chatmode.md) | Generate a comprehensive Product Requirements Document (PRD) in Markdown, detailing user stories, acceptance criteria, technical considerations, and metrics. Optionally create GitHub issues upon user confirmation. |
diff --git a/README.collections.md b/README.collections.md
index 8b205f7..2b16c04 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -17,12 +17,14 @@ Curated collections of related prompts, instructions, and chat modes organized a
| ---- | ----------- | ----- | ---- |
| [Azure & Cloud Development](collections/azure-cloud-development.md) | Comprehensive Azure cloud development tools including Infrastructure as Code, serverless functions, architecture patterns, and cost optimization for building scalable cloud applications. | 18 items | azure, cloud, infrastructure, bicep, terraform, serverless, architecture, devops |
| [C# .NET Development](collections/csharp-dotnet-development.md) | Essential prompts, instructions, and chat modes for C# and .NET development including testing, documentation, and best practices. | 7 items | csharp, dotnet, aspnet, testing |
+| [C# MCP Server Development](collections/csharp-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | csharp, mcp, model-context-protocol, dotnet, server-development |
| [Clojure Interactive Programming](collections/clojure-interactive-programming.md) | Tools for REPL-first Clojure workflows featuring Clojure instructions, the interactive programming chat mode and supporting guidance. | 3 items | clojure, repl, interactive-programming |
| [Database & Data Management](collections/database-data-management.md) | Database administration, SQL optimization, and data management tools for PostgreSQL, SQL Server, and general database development best practices. | 8 items | database, sql, postgresql, sql-server, dba, optimization, queries, data-management |
| [DevOps On-Call](collections/devops-oncall.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 5 items | devops, incident-response, oncall, azure |
| [Frontend Web Development](collections/frontend-web-dev.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 11 items | frontend, web, react, typescript, javascript, css, html, angular, vue |
| [Java Development](collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc |
| [Power Apps Code Apps Development](collections/power-apps-code-apps.md) | Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance for building code-first applications with Power Platform integration. | 3 items | power-apps, power-platform, typescript, react, code-apps, dataverse, connectors |
+| [Power BI Development](collections/power-bi-development.md) | Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions. | 14 items | power-bi, dax, data-modeling, performance, visualization, security, devops, business-intelligence |
| [Power Platform MCP Connector Development](collections/power-platform-mcp-connector-development.md) | Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio | 4 items | power-platform, mcp, copilot-studio, custom-connector, json-rpc |
| [Project Planning & Management](collections/project-planning.md) | Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization for development teams. | 17 items | planning, project-management, epic, feature, implementation, task, architecture, technical-spike |
| [Security & Code Quality](collections/security-best-practices.md) | Security frameworks, accessibility guidelines, performance optimization, and code quality best practices for building secure, maintainable, and high-performance applications. | 6 items | security, accessibility, performance, code-quality, owasp, a11y, optimization, best-practices |
diff --git a/README.instructions.md b/README.instructions.md
index c60af39..896b1ef 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -29,6 +29,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Bicep Code Best Practices](instructions/bicep-code-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md) | Infrastructure as Code with Bicep |
| [Blazor](instructions/blazor.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fblazor.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fblazor.instructions.md) | Blazor component and application patterns |
| [C# Development](instructions/csharp.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp.instructions.md) | Guidelines for building C# applications |
+| [C# MCP Server Development](instructions/csharp-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-mcp-server.instructions.md) | Instructions for building Model Context Protocol (MCP) servers using the C# SDK |
| [C# 코드 작성 규칙](instructions/csharp-ko.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-ko.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-ko.instructions.md) | C# 애플리케이션 개발을 위한 코드 작성 규칙 by @jgkim999 |
| [C# アプリケーション開発](instructions/csharp-ja.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-ja.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-ja.instructions.md) | C# アプリケーション構築指針 by @tsubakimoto |
| [Clojure Development Instructions](instructions/clojure.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fclojure.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fclojure.instructions.md) | Clojure-specific coding patterns, inline def usage, code block templates, and namespace handling for Clojure development. |
diff --git a/README.prompts.md b/README.prompts.md
index 306f57b..d647db8 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -56,6 +56,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Feature Implementation Plan Prompt](prompts/breakdown-feature-implementation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md) | Prompt for creating detailed feature implementation plans, following Epoch monorepo structure. |
| [Feature PRD Prompt](prompts/breakdown-feature-prd.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. |
| [Finalize Agent Prompt](prompts/finalize-agent-prompt.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. |
+| [Generate C# MCP Server](prompts/csharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md) | Generate a complete MCP server project in C# with tools, prompts, and proper configuration |
| [Generate Standard OO Component Documentation](prompts/create-oo-component-documentation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md) | Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards. |
| [Git Flow Branch Creator](prompts/git-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. |
| [Github Copilot Starter](prompts/github-copilot-starter.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack |
@@ -82,6 +83,8 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Power BI DAX Formula Optimizer](prompts/power-bi-dax-optimization.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-dax-optimization.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-dax-optimization.prompt.md) | Comprehensive Power BI DAX formula optimization prompt for improving performance, readability, and maintainability of DAX calculations. |
| [Power BI Performance Troubleshooting Guide](prompts/power-bi-performance-troubleshooting.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-performance-troubleshooting.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-performance-troubleshooting.prompt.md) | Systematic Power BI performance troubleshooting prompt for identifying, diagnosing, and resolving performance issues in Power BI models, reports, and queries. |
| [Power BI Report Visualization Designer](prompts/power-bi-report-design-consultation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-report-design-consultation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-report-design-consultation.prompt.md) | Power BI report visualization design prompt for creating effective, user-friendly, and accessible reports with optimal chart selection and layout design. |
+| [Power Platform MCP Connector Generator](prompts/mcp-copilot-studio-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-copilot-studio-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-copilot-studio-server-generator.prompt.md) | Generate a complete MCP server implementation optimized for Copilot Studio integration with proper schema constraints and streamable HTTP support |
+| [Power Platform MCP Connector Suite](prompts/power-platform-mcp-connector-suite.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-platform-mcp-connector-suite.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-platform-mcp-connector-suite.prompt.md) | Generate complete Power Platform custom connector with MCP integration for Copilot Studio - includes schema generation, troubleshooting, and validation |
| [Product Manager Assistant: Feature Identification and Specification](prompts/gen-specs-as-issues.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md) | This workflow guides you through a systematic approach to identify missing features, prioritize them, and create detailed specifications for implementation. |
| [Professional Prompt Builder](prompts/prompt-builder.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fprompt-builder.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fprompt-builder.prompt.md) | Guide users through creating high-quality GitHub Copilot prompts with proper structure, tools, and best practices. |
| [Project Folder Structure Blueprint Generator](prompts/folder-structure-blueprint-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffolder-structure-blueprint-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffolder-structure-blueprint-generator.prompt.md) | Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks. |
diff --git a/chatmodes/csharp-mcp-expert.chatmode.md b/chatmodes/csharp-mcp-expert.chatmode.md
new file mode 100644
index 0000000..69ce7d7
--- /dev/null
+++ b/chatmodes/csharp-mcp-expert.chatmode.md
@@ -0,0 +1,69 @@
+---
+description: 'Expert assistant for developing Model Context Protocol (MCP) servers in C#'
+model: GPT-4.1
+---
+
+# C# MCP Server Expert
+
+You are a world-class expert in building Model Context Protocol (MCP) servers using the C# SDK. You have deep knowledge of the ModelContextProtocol NuGet packages, .NET dependency injection, async programming, and best practices for building robust, production-ready MCP servers.
+
+## Your Expertise
+
+- **C# MCP SDK**: Complete mastery of ModelContextProtocol, ModelContextProtocol.AspNetCore, and ModelContextProtocol.Core packages
+- **.NET Architecture**: Expert in Microsoft.Extensions.Hosting, dependency injection, and service lifetime management
+- **MCP Protocol**: Deep understanding of the Model Context Protocol specification, client-server communication, and tool/prompt patterns
+- **Async Programming**: Expert in async/await patterns, cancellation tokens, and proper async error handling
+- **Tool Design**: Creating intuitive, well-documented tools that LLMs can effectively use
+- **Best Practices**: Security, error handling, logging, testing, and maintainability
+- **Debugging**: Troubleshooting stdio transport issues, serialization problems, and protocol errors
+
+## Your Approach
+
+- **Start with Context**: Always understand the user's goal and what their MCP server needs to accomplish
+- **Follow Best Practices**: Use proper attributes (`[McpServerToolType]`, `[McpServerTool]`, `[Description]`), configure logging to stderr, and implement comprehensive error handling
+- **Write Clean Code**: Follow C# conventions, use nullable reference types, include XML documentation, and organize code logically
+- **Dependency Injection First**: Leverage DI for services, use parameter injection in tool methods, and manage service lifetimes properly
+- **Test-Driven Mindset**: Consider how tools will be tested and provide testing guidance
+- **Security Conscious**: Always consider security implications of tools that access files, networks, or system resources
+- **LLM-Friendly**: Write descriptions that help LLMs understand when and how to use tools effectively
+
+## Guidelines
+
+- Always use prerelease NuGet packages with `--prerelease` flag
+- Configure logging to stderr using `LogToStandardErrorThreshold = LogLevel.Trace`
+- Use `Host.CreateApplicationBuilder` for proper DI and lifecycle management
+- Add `[Description]` attributes to all tools and parameters for LLM understanding
+- Support async operations with proper `CancellationToken` usage
+- Use `McpProtocolException` with appropriate `McpErrorCode` for protocol errors
+- Validate input parameters and provide clear error messages
+- Use `McpServer.AsSamplingChatClient()` when tools need to interact with the client's LLM
+- Organize related tools into classes with `[McpServerToolType]`
+- Return simple types or JSON-serializable objects from tools
+- Provide complete, runnable code examples that users can immediately use
+- Include comments explaining complex logic or protocol-specific patterns
+- Consider performance implications of tool operations
+- Think about error scenarios and handle them gracefully
+
+## Common Scenarios You Excel At
+
+- **Creating New Servers**: Generating complete project structures with proper configuration
+- **Tool Development**: Implementing tools for file operations, HTTP requests, data processing, or system interactions
+- **Prompt Implementation**: Creating reusable prompt templates with `[McpServerPrompt]`
+- **Debugging**: Helping diagnose stdio transport issues, serialization errors, or protocol problems
+- **Refactoring**: Improving existing MCP servers for better maintainability, performance, or functionality
+- **Integration**: Connecting MCP servers with databases, APIs, or other services via DI
+- **Testing**: Writing unit tests for tools and integration tests for servers
+- **Optimization**: Improving performance, reducing memory usage, or enhancing error handling
+
+## Response Style
+
+- Provide complete, working code examples that can be copied and used immediately
+- Include necessary using statements and namespace declarations
+- Add inline comments for complex or non-obvious code
+- Explain the "why" behind design decisions
+- Highlight potential pitfalls or common mistakes to avoid
+- Suggest improvements or alternative approaches when relevant
+- Include troubleshooting tips for common issues
+- Format code clearly with proper indentation and spacing
+
+You help developers build high-quality MCP servers that are robust, maintainable, secure, and easy for LLMs to use effectively.
diff --git a/collections/csharp-mcp-development.collection.yml b/collections/csharp-mcp-development.collection.yml
new file mode 100644
index 0000000..ae5d6b2
--- /dev/null
+++ b/collections/csharp-mcp-development.collection.yml
@@ -0,0 +1,32 @@
+id: csharp-mcp-development
+name: C# MCP Server Development
+description: Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+tags: [csharp, mcp, model-context-protocol, dotnet, server-development]
+items:
+ - path: instructions/csharp-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/csharp-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/csharp-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in C#.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects
+ - Implementing tools and prompts
+ - Debugging protocol issues
+ - Optimizing server performance
+ - Learning MCP best practices
+
+ To get the best results, consider:
+ - Using the instruction file to set context for all Copilot interactions
+ - Using the prompt to generate initial project structure
+ - Switching to the expert chat mode for detailed implementation help
+ - Providing specific details about what tools or functionality you need
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/csharp-mcp-development.md b/collections/csharp-mcp-development.md
new file mode 100644
index 0000000..5d57b93
--- /dev/null
+++ b/collections/csharp-mcp-development.md
@@ -0,0 +1,38 @@
+# C# MCP Server Development
+
+Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+
+**Tags:** csharp, mcp, model-context-protocol, dotnet, server-development
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [C# MCP Server Development](../instructions/csharp-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp-mcp-server.instructions.md) | Instruction | Instructions for building Model Context Protocol (MCP) servers using the C# SDK |
+| [Generate C# MCP Server](../prompts/csharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md) | Prompt | Generate a complete MCP server project in C# with tools, prompts, and proper configuration |
+| [C# MCP Server Expert](../chatmodes/csharp-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fcsharp-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fcsharp-mcp-expert.chatmode.md) | Chat Mode | Expert assistant for developing Model Context Protocol (MCP) servers in C# [see usage](#c#-mcp-server-expert) |
+
+## Collection Usage
+
+### C# MCP Server Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in C#.
+
+This chat mode is ideal for:
+- Creating new MCP server projects
+- Implementing tools and prompts
+- Debugging protocol issues
+- Optimizing server performance
+- Learning MCP best practices
+
+To get the best results, consider:
+- Using the instruction file to set context for all Copilot interactions
+- Using the prompt to generate initial project structure
+- Switching to the expert chat mode for detailed implementation help
+- Providing specific details about what tools or functionality you need
+
+---
+
+*This collection includes 3 curated items for c# mcp server development.*
\ No newline at end of file
diff --git a/instructions/csharp-mcp-server.instructions.md b/instructions/csharp-mcp-server.instructions.md
new file mode 100644
index 0000000..137ce1b
--- /dev/null
+++ b/instructions/csharp-mcp-server.instructions.md
@@ -0,0 +1,95 @@
+---
+description: 'Instructions for building Model Context Protocol (MCP) servers using the C# SDK'
+applyTo: '**/*.cs, **/*.csproj'
+---
+
+# C# MCP Server Development
+
+## Instructions
+
+- Use the **ModelContextProtocol** NuGet package (prerelease) for most projects: `dotnet add package ModelContextProtocol --prerelease`
+- Use **ModelContextProtocol.AspNetCore** for HTTP-based MCP servers
+- Use **ModelContextProtocol.Core** for minimal dependencies (client-only or low-level server APIs)
+- Always configure logging to stderr using `LogToStandardErrorThreshold = LogLevel.Trace` to avoid interfering with stdio transport
+- Use the `[McpServerToolType]` attribute on classes containing MCP tools
+- Use the `[McpServerTool]` attribute on methods to expose them as tools
+- Use the `[Description]` attribute from `System.ComponentModel` to document tools and parameters
+- Support dependency injection in tool methods - inject `McpServer`, `HttpClient`, or other services as parameters
+- Use `McpServer.AsSamplingChatClient()` to make sampling requests back to the client from within tools
+- Expose prompts using `[McpServerPromptType]` on classes and `[McpServerPrompt]` on methods
+- For stdio transport, use `WithStdioServerTransport()` when building the server
+- Use `WithToolsFromAssembly()` to auto-discover and register all tools from the current assembly
+- Tool methods can be synchronous or async (return `Task` or `Task`)
+- Always include comprehensive descriptions for tools and parameters to help LLMs understand their purpose
+- Use `CancellationToken` parameters in async tools for proper cancellation support
+- Return simple types (string, int, etc.) or complex objects that can be serialized to JSON
+- For fine-grained control, use `McpServerOptions` with custom handlers like `ListToolsHandler` and `CallToolHandler`
+- Use `McpProtocolException` for protocol-level errors with appropriate `McpErrorCode` values
+- Test MCP servers using the `McpClient` from the same SDK or any compliant MCP client
+- Structure projects with Microsoft.Extensions.Hosting for proper DI and lifecycle management
+
+## Best Practices
+
+- Keep tool methods focused and single-purpose
+- Use meaningful tool names that clearly indicate their function
+- Provide detailed descriptions that explain what the tool does, what parameters it expects, and what it returns
+- Validate input parameters and throw `McpProtocolException` with `McpErrorCode.InvalidParams` for invalid inputs
+- Use structured logging to help with debugging without polluting stdout
+- Organize related tools into logical classes with `[McpServerToolType]`
+- Consider security implications when exposing tools that access external resources
+- Use the built-in DI container to manage service lifetimes and dependencies
+- Implement proper error handling and return meaningful error messages
+- Test tools individually before integrating with LLMs
+
+## Common Patterns
+
+### Basic Server Setup
+```csharp
+var builder = Host.CreateApplicationBuilder(args);
+builder.Logging.AddConsole(options =>
+ options.LogToStandardErrorThreshold = LogLevel.Trace);
+builder.Services
+ .AddMcpServer()
+ .WithStdioServerTransport()
+ .WithToolsFromAssembly();
+await builder.Build().RunAsync();
+```
+
+### Simple Tool
+```csharp
+[McpServerToolType]
+public static class MyTools
+{
+ [McpServerTool, Description("Description of what the tool does")]
+ public static string ToolName(
+ [Description("Parameter description")] string param) =>
+ $"Result: {param}";
+}
+```
+
+### Tool with Dependency Injection
+```csharp
+[McpServerTool, Description("Fetches data from a URL")]
+public static async Task FetchData(
+ HttpClient httpClient,
+ [Description("The URL to fetch")] string url,
+ CancellationToken cancellationToken) =>
+ await httpClient.GetStringAsync(url, cancellationToken);
+```
+
+### Tool with Sampling
+```csharp
+[McpServerTool, Description("Analyzes content using the client's LLM")]
+public static async Task Analyze(
+ McpServer server,
+ [Description("Content to analyze")] string content,
+ CancellationToken cancellationToken)
+{
+ var messages = new ChatMessage[]
+ {
+ new(ChatRole.User, $"Analyze this: {content}")
+ };
+ return await server.AsSamplingChatClient()
+ .GetResponseAsync(messages, cancellationToken: cancellationToken);
+}
+```
diff --git a/prompts/csharp-mcp-server-generator.prompt.md b/prompts/csharp-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..a9f98b8
--- /dev/null
+++ b/prompts/csharp-mcp-server-generator.prompt.md
@@ -0,0 +1,59 @@
+---
+mode: 'agent'
+description: 'Generate a complete MCP server project in C# with tools, prompts, and proper configuration'
+---
+
+# Generate C# MCP Server
+
+Create a complete Model Context Protocol (MCP) server in C# with the following specifications:
+
+## Requirements
+
+1. **Project Structure**: Create a new C# console application with proper directory structure
+2. **NuGet Packages**: Include ModelContextProtocol (prerelease) and Microsoft.Extensions.Hosting
+3. **Logging Configuration**: Configure all logs to stderr to avoid interfering with stdio transport
+4. **Server Setup**: Use the Host builder pattern with proper DI configuration
+5. **Tools**: Create at least one useful tool with proper attributes and descriptions
+6. **Error Handling**: Include proper error handling and validation
+
+## Implementation Details
+
+### Basic Project Setup
+- Use .NET 8.0 or later
+- Create a console application
+- Add necessary NuGet packages with --prerelease flag
+- Configure logging to stderr
+
+### Server Configuration
+- Use `Host.CreateApplicationBuilder` for DI and lifecycle management
+- Configure `AddMcpServer()` with stdio transport
+- Use `WithToolsFromAssembly()` for automatic tool discovery
+- Ensure the server runs with `RunAsync()`
+
+### Tool Implementation
+- Use `[McpServerToolType]` attribute on tool classes
+- Use `[McpServerTool]` attribute on tool methods
+- Add `[Description]` attributes to tools and parameters
+- Support async operations where appropriate
+- Include proper parameter validation
+
+### Code Quality
+- Follow C# naming conventions
+- Include XML documentation comments
+- Use nullable reference types
+- Implement proper error handling with McpProtocolException
+- Use structured logging for debugging
+
+## Example Tool Types to Consider
+- File operations (read, write, search)
+- Data processing (transform, validate, analyze)
+- External API integrations (HTTP requests)
+- System operations (execute commands, check status)
+- Database operations (query, update)
+
+## Testing Guidance
+- Explain how to run the server
+- Provide example commands to test with MCP clients
+- Include troubleshooting tips
+
+Generate a complete, production-ready MCP server with comprehensive documentation and error handling.
From fc5530604551d3eeb7a0797994c94c66a189ba74 Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 19:57:58 -0400
Subject: [PATCH 2/8] Add TypeScript MCP Server Development Collection (#324)
* Add TypeScript MCP Server Development collection
- Add instructions for TypeScript MCP server development best practices
- Add prompt for generating complete TypeScript MCP server projects
- Add expert chat mode for TypeScript MCP development assistance
- Add collection grouping all TypeScript MCP resources together
- Update README files with new contributions
* Revert unintended change to power-bi-development.md
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/typescript-mcp-expert.chatmode.md | 91 +++++++
.../typescript-mcp-development.collection.yml | 34 +++
collections/typescript-mcp-development.md | 40 +++
.../typescript-mcp-server.instructions.md | 228 ++++++++++++++++++
.../typescript-mcp-server-generator.prompt.md | 90 +++++++
9 files changed, 487 insertions(+)
create mode 100644 chatmodes/typescript-mcp-expert.chatmode.md
create mode 100644 collections/typescript-mcp-development.collection.yml
create mode 100644 collections/typescript-mcp-development.md
create mode 100644 instructions/typescript-mcp-server.instructions.md
create mode 100644 prompts/typescript-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index 28ba028..e0926d7 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -79,6 +79,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [Technical Debt Remediation Plan](chatmodes/tech-debt-remediation-plan.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftech-debt-remediation-plan.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftech-debt-remediation-plan.chatmode.md) | Generate technical debt remediation plans for code, tests, and documentation. |
| [Technical spike research mode](chatmodes/research-technical-spike.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fresearch-technical-spike.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fresearch-technical-spike.chatmode.md) | Systematically research and validate technical spike documents through exhaustive investigation and controlled experimentation. |
| [Thinking Beast Mode](chatmodes/Thinking-Beast-Mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2FThinking-Beast-Mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2FThinking-Beast-Mode.chatmode.md) | A transcendent coding agent with quantum cognitive architecture, adversarial intelligence, and unrestricted creative freedom. |
+| [TypeScript MCP Server Expert](chatmodes/typescript-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftypescript-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftypescript-mcp-expert.chatmode.md) | Expert assistant for developing Model Context Protocol (MCP) servers in TypeScript |
| [Ultimate Transparent Thinking Beast Mode](chatmodes/Ultimate-Transparent-Thinking-Beast-Mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2FUltimate-Transparent-Thinking-Beast-Mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2FUltimate-Transparent-Thinking-Beast-Mode.chatmode.md) | Ultimate Transparent Thinking Beast Mode |
| [Universal Janitor](chatmodes/janitor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fjanitor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fjanitor.chatmode.md) | Perform janitorial tasks on any codebase including cleanup, simplification, and tech debt remediation. |
| [Universal PR Comment Addresser](chatmodes/address-comments.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Faddress-comments.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Faddress-comments.chatmode.md) | Address PR comments |
diff --git a/README.collections.md b/README.collections.md
index 2b16c04..c0eed33 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -31,3 +31,4 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Tasks by microsoft/edge-ai](collections/edge-ai-tasks.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 3 items | architecture, planning, research, tasks, implementation |
| [Technical Spike](collections/technical-spike.md) | Tools for creation, management and research of technical spikes to reduce unknowns and assumptions before proceeding to specification and implementation of solutions. | 2 items | technical-spike, assumption-testing, validation, research |
| [Testing & Test Automation](collections/testing-automation.md) | Comprehensive collection for writing tests, test automation, and test-driven development including unit tests, integration tests, and end-to-end testing strategies. | 11 items | testing, tdd, automation, unit-tests, integration, playwright, jest, nunit |
+| [TypeScript MCP Server Development](collections/typescript-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | typescript, mcp, model-context-protocol, nodejs, server-development |
diff --git a/README.instructions.md b/README.instructions.md
index 896b1ef..39d3605 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -107,5 +107,6 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [TaskSync V4 Protocol](instructions/tasksync.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftasksync.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftasksync.instructions.md) | TaskSync V4 - Allows you to give the agent new instructions or feedback after completing a task using terminal while agent is running. |
| [Terraform Conventions](instructions/terraform.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform.instructions.md) | Terraform Conventions and Guidelines |
| [TypeScript Development](instructions/typescript-5-es2022.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-5-es2022.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-5-es2022.instructions.md) | Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output |
+| [TypeScript MCP Server Development](instructions/typescript-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-mcp-server.instructions.md) | Instructions for building Model Context Protocol (MCP) servers using the TypeScript SDK |
| [VueJS 3 Development Instructions](instructions/vuejs3.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fvuejs3.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fvuejs3.instructions.md) | VueJS 3 development standards and best practices with Composition API and TypeScript |
| [WordPress Development — Copilot Instructions](instructions/wordpress.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md) | Coding, security, and testing rules for WordPress plugins and themes |
diff --git a/README.prompts.md b/README.prompts.md
index d647db8..d47df09 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -58,6 +58,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Finalize Agent Prompt](prompts/finalize-agent-prompt.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. |
| [Generate C# MCP Server](prompts/csharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md) | Generate a complete MCP server project in C# with tools, prompts, and proper configuration |
| [Generate Standard OO Component Documentation](prompts/create-oo-component-documentation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md) | Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards. |
+| [Generate TypeScript MCP Server](prompts/typescript-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md) | Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration |
| [Git Flow Branch Creator](prompts/git-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. |
| [Github Copilot Starter](prompts/github-copilot-starter.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack |
| [GitHub Issue Planning & Project Automation Prompt](prompts/breakdown-plan.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. |
diff --git a/chatmodes/typescript-mcp-expert.chatmode.md b/chatmodes/typescript-mcp-expert.chatmode.md
new file mode 100644
index 0000000..a1f1c78
--- /dev/null
+++ b/chatmodes/typescript-mcp-expert.chatmode.md
@@ -0,0 +1,91 @@
+---
+description: 'Expert assistant for developing Model Context Protocol (MCP) servers in TypeScript'
+model: GPT-4.1
+---
+
+# TypeScript MCP Server Expert
+
+You are a world-class expert in building Model Context Protocol (MCP) servers using the TypeScript SDK. You have deep knowledge of the @modelcontextprotocol/sdk package, Node.js, TypeScript, async programming, zod validation, and best practices for building robust, production-ready MCP servers.
+
+## Your Expertise
+
+- **TypeScript MCP SDK**: Complete mastery of @modelcontextprotocol/sdk, including McpServer, Server, all transports, and utility functions
+- **TypeScript/Node.js**: Expert in TypeScript, ES modules, async/await patterns, and Node.js ecosystem
+- **Schema Validation**: Deep knowledge of zod for input/output validation and type inference
+- **MCP Protocol**: Complete understanding of the Model Context Protocol specification, transports, and capabilities
+- **Transport Types**: Expert in both StreamableHTTPServerTransport (with Express) and StdioServerTransport
+- **Tool Design**: Creating intuitive, well-documented tools with proper schemas and error handling
+- **Best Practices**: Security, performance, testing, type safety, and maintainability
+- **Debugging**: Troubleshooting transport issues, schema validation errors, and protocol problems
+
+## Your Approach
+
+- **Understand Requirements**: Always clarify what the MCP server needs to accomplish and who will use it
+- **Choose Right Tools**: Select appropriate transport (HTTP vs stdio) based on use case
+- **Type Safety First**: Leverage TypeScript's type system and zod for runtime validation
+- **Follow SDK Patterns**: Use `registerTool()`, `registerResource()`, `registerPrompt()` methods consistently
+- **Structured Returns**: Always return both `content` (for display) and `structuredContent` (for data) from tools
+- **Error Handling**: Implement comprehensive try-catch blocks and return `isError: true` for failures
+- **LLM-Friendly**: Write clear titles and descriptions that help LLMs understand tool capabilities
+- **Test-Driven**: Consider how tools will be tested and provide testing guidance
+
+## Guidelines
+
+- Always use ES modules syntax (`import`/`export`, not `require`)
+- Import from specific SDK paths: `@modelcontextprotocol/sdk/server/mcp.js`
+- Use zod for all schema definitions: `{ inputSchema: { param: z.string() } }`
+- Provide `title` field for all tools, resources, and prompts (not just `name`)
+- Return both `content` and `structuredContent` from tool implementations
+- Use `ResourceTemplate` for dynamic resources: `new ResourceTemplate('resource://{param}', { list: undefined })`
+- Create new transport instances per request in stateless HTTP mode
+- Enable DNS rebinding protection for local HTTP servers: `enableDnsRebindingProtection: true`
+- Configure CORS and expose `Mcp-Session-Id` header for browser clients
+- Use `completable()` wrapper for argument completion support
+- Implement sampling with `server.server.createMessage()` when tools need LLM help
+- Use `server.server.elicitInput()` for interactive user input during tool execution
+- Handle cleanup with `res.on('close', () => transport.close())` for HTTP transports
+- Use environment variables for configuration (ports, API keys, paths)
+- Add proper TypeScript types for all function parameters and returns
+- Implement graceful error handling and meaningful error messages
+- Test with MCP Inspector: `npx @modelcontextprotocol/inspector`
+
+## Common Scenarios You Excel At
+
+- **Creating New Servers**: Generating complete project structures with package.json, tsconfig, and proper setup
+- **Tool Development**: Implementing tools for data processing, API calls, file operations, or database queries
+- **Resource Implementation**: Creating static or dynamic resources with proper URI templates
+- **Prompt Development**: Building reusable prompt templates with argument validation and completion
+- **Transport Setup**: Configuring both HTTP (with Express) and stdio transports correctly
+- **Debugging**: Diagnosing transport issues, schema validation errors, and protocol problems
+- **Optimization**: Improving performance, adding notification debouncing, and managing resources efficiently
+- **Migration**: Helping migrate from older MCP implementations to current best practices
+- **Integration**: Connecting MCP servers with databases, APIs, or other services
+- **Testing**: Writing tests and providing integration testing strategies
+
+## Response Style
+
+- Provide complete, working code that can be copied and used immediately
+- Include all necessary imports at the top of code blocks
+- Add inline comments explaining important concepts or non-obvious code
+- Show package.json and tsconfig.json when creating new projects
+- Explain the "why" behind architectural decisions
+- Highlight potential issues or edge cases to watch for
+- Suggest improvements or alternative approaches when relevant
+- Include MCP Inspector commands for testing
+- Format code with proper indentation and TypeScript conventions
+- Provide environment variable examples when needed
+
+## Advanced Capabilities You Know
+
+- **Dynamic Updates**: Using `.enable()`, `.disable()`, `.update()`, `.remove()` for runtime changes
+- **Notification Debouncing**: Configuring debounced notifications for bulk operations
+- **Session Management**: Implementing stateful HTTP servers with session tracking
+- **Backwards Compatibility**: Supporting both Streamable HTTP and legacy SSE transports
+- **OAuth Proxying**: Setting up proxy authorization with external providers
+- **Context-Aware Completion**: Implementing intelligent argument completions based on context
+- **Resource Links**: Returning ResourceLink objects for efficient large file handling
+- **Sampling Workflows**: Building tools that use LLM sampling for complex operations
+- **Elicitation Flows**: Creating interactive tools that request user input during execution
+- **Low-Level API**: Using the Server class directly for maximum control when needed
+
+You help developers build high-quality TypeScript MCP servers that are type-safe, robust, performant, and easy for LLMs to use effectively.
diff --git a/collections/typescript-mcp-development.collection.yml b/collections/typescript-mcp-development.collection.yml
new file mode 100644
index 0000000..72ff68a
--- /dev/null
+++ b/collections/typescript-mcp-development.collection.yml
@@ -0,0 +1,34 @@
+id: typescript-mcp-development
+name: TypeScript MCP Server Development
+description: Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+tags: [typescript, mcp, model-context-protocol, nodejs, server-development]
+items:
+ - path: instructions/typescript-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/typescript-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/typescript-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in TypeScript/Node.js.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with TypeScript
+ - Implementing tools, resources, and prompts with zod validation
+ - Setting up HTTP or stdio transports
+ - Debugging schema validation and transport issues
+ - Learning TypeScript MCP best practices
+ - Optimizing server performance and reliability
+
+ To get the best results, consider:
+ - Using the instruction file to set context for TypeScript/Node.js development
+ - Using the prompt to generate initial project structure with proper configuration
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need HTTP or stdio transport
+ - Providing details about what tools or functionality you need
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/typescript-mcp-development.md b/collections/typescript-mcp-development.md
new file mode 100644
index 0000000..6c0b2ea
--- /dev/null
+++ b/collections/typescript-mcp-development.md
@@ -0,0 +1,40 @@
+# TypeScript MCP Server Development
+
+Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+
+**Tags:** typescript, mcp, model-context-protocol, nodejs, server-development
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [TypeScript MCP Server Development](../instructions/typescript-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-mcp-server.instructions.md) | Instruction | Instructions for building Model Context Protocol (MCP) servers using the TypeScript SDK |
+| [Generate TypeScript MCP Server](../prompts/typescript-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md) | Prompt | Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration |
+| [TypeScript MCP Server Expert](../chatmodes/typescript-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftypescript-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftypescript-mcp-expert.chatmode.md) | Chat Mode | Expert assistant for developing Model Context Protocol (MCP) servers in TypeScript [see usage](#typescript-mcp-server-expert) |
+
+## Collection Usage
+
+### TypeScript MCP Server Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in TypeScript/Node.js.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with TypeScript
+- Implementing tools, resources, and prompts with zod validation
+- Setting up HTTP or stdio transports
+- Debugging schema validation and transport issues
+- Learning TypeScript MCP best practices
+- Optimizing server performance and reliability
+
+To get the best results, consider:
+- Using the instruction file to set context for TypeScript/Node.js development
+- Using the prompt to generate initial project structure with proper configuration
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need HTTP or stdio transport
+- Providing details about what tools or functionality you need
+
+---
+
+*This collection includes 3 curated items for typescript mcp server development.*
\ No newline at end of file
diff --git a/instructions/typescript-mcp-server.instructions.md b/instructions/typescript-mcp-server.instructions.md
new file mode 100644
index 0000000..97185e6
--- /dev/null
+++ b/instructions/typescript-mcp-server.instructions.md
@@ -0,0 +1,228 @@
+---
+description: 'Instructions for building Model Context Protocol (MCP) servers using the TypeScript SDK'
+applyTo: '**/*.ts, **/*.js, **/package.json'
+---
+
+# TypeScript MCP Server Development
+
+## Instructions
+
+- Use the **@modelcontextprotocol/sdk** npm package: `npm install @modelcontextprotocol/sdk`
+- Import from specific paths: `@modelcontextprotocol/sdk/server/mcp.js`, `@modelcontextprotocol/sdk/server/stdio.js`, etc.
+- Use `McpServer` class for high-level server implementation with automatic protocol handling
+- Use `Server` class for low-level control with manual request handlers
+- Use **zod** for input/output schema validation: `npm install zod@3`
+- Always provide `title` field for tools, resources, and prompts for better UI display
+- Use `registerTool()`, `registerResource()`, and `registerPrompt()` methods (recommended over older APIs)
+- Define schemas using zod: `{ inputSchema: { param: z.string() }, outputSchema: { result: z.string() } }`
+- Return both `content` (for display) and `structuredContent` (for structured data) from tools
+- For HTTP servers, use `StreamableHTTPServerTransport` with Express or similar frameworks
+- For local integrations, use `StdioServerTransport` for stdio-based communication
+- Create new transport instances per request to prevent request ID collisions (stateless mode)
+- Use session management with `sessionIdGenerator` for stateful servers
+- Enable DNS rebinding protection for local servers: `enableDnsRebindingProtection: true`
+- Configure CORS headers and expose `Mcp-Session-Id` for browser-based clients
+- Use `ResourceTemplate` for dynamic resources with URI parameters: `new ResourceTemplate('resource://{param}', { list: undefined })`
+- Support completions for better UX using `completable()` wrapper from `@modelcontextprotocol/sdk/server/completable.js`
+- Implement sampling with `server.server.createMessage()` to request LLM completions from clients
+- Use `server.server.elicitInput()` to request additional user input during tool execution
+- Enable notification debouncing for bulk updates: `debouncedNotificationMethods: ['notifications/tools/list_changed']`
+- Dynamic updates: call `.enable()`, `.disable()`, `.update()`, or `.remove()` on registered items to emit `listChanged` notifications
+- Use `getDisplayName()` from `@modelcontextprotocol/sdk/shared/metadataUtils.js` for UI display names
+- Test servers with MCP Inspector: `npx @modelcontextprotocol/inspector`
+
+## Best Practices
+
+- Keep tool implementations focused on single responsibilities
+- Provide clear, descriptive titles and descriptions for LLM understanding
+- Use proper TypeScript types for all parameters and return values
+- Implement comprehensive error handling with try-catch blocks
+- Return `isError: true` in tool results for error conditions
+- Use async/await for all asynchronous operations
+- Close database connections and clean up resources properly
+- Validate input parameters before processing
+- Use structured logging for debugging without polluting stdout/stderr
+- Consider security implications when exposing file system or network access
+- Implement proper resource cleanup on transport close events
+- Use environment variables for configuration (ports, API keys, etc.)
+- Document tool capabilities and limitations clearly
+- Test with multiple clients to ensure compatibility
+
+## Common Patterns
+
+### Basic Server Setup (HTTP)
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+
+const server = new McpServer({
+ name: 'my-server',
+ version: '1.0.0'
+});
+
+const app = express();
+app.use(express.json());
+
+app.post('/mcp', async (req, res) => {
+ const transport = new StreamableHTTPServerTransport({
+ sessionIdGenerator: undefined,
+ enableJsonResponse: true
+ });
+
+ res.on('close', () => transport.close());
+
+ await server.connect(transport);
+ await transport.handleRequest(req, res, req.body);
+});
+
+app.listen(3000);
+```
+
+### Basic Server Setup (stdio)
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new McpServer({
+ name: 'my-server',
+ version: '1.0.0'
+});
+
+// ... register tools, resources, prompts ...
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### Simple Tool
+```typescript
+import { z } from 'zod';
+
+server.registerTool(
+ 'calculate',
+ {
+ title: 'Calculator',
+ description: 'Perform basic calculations',
+ inputSchema: { a: z.number(), b: z.number(), op: z.enum(['+', '-', '*', '/']) },
+ outputSchema: { result: z.number() }
+ },
+ async ({ a, b, op }) => {
+ const result = op === '+' ? a + b : op === '-' ? a - b :
+ op === '*' ? a * b : a / b;
+ const output = { result };
+ return {
+ content: [{ type: 'text', text: JSON.stringify(output) }],
+ structuredContent: output
+ };
+ }
+);
+```
+
+### Dynamic Resource
+```typescript
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+server.registerResource(
+ 'user',
+ new ResourceTemplate('users://{userId}', { list: undefined }),
+ {
+ title: 'User Profile',
+ description: 'Fetch user profile data'
+ },
+ async (uri, { userId }) => ({
+ contents: [{
+ uri: uri.href,
+ text: `User ${userId} data here`
+ }]
+ })
+);
+```
+
+### Tool with Sampling
+```typescript
+server.registerTool(
+ 'summarize',
+ {
+ title: 'Text Summarizer',
+ description: 'Summarize text using LLM',
+ inputSchema: { text: z.string() },
+ outputSchema: { summary: z.string() }
+ },
+ async ({ text }) => {
+ const response = await server.server.createMessage({
+ messages: [{
+ role: 'user',
+ content: { type: 'text', text: `Summarize: ${text}` }
+ }],
+ maxTokens: 500
+ });
+
+ const summary = response.content.type === 'text' ?
+ response.content.text : 'Unable to summarize';
+ const output = { summary };
+ return {
+ content: [{ type: 'text', text: JSON.stringify(output) }],
+ structuredContent: output
+ };
+ }
+);
+```
+
+### Prompt with Completion
+```typescript
+import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
+
+server.registerPrompt(
+ 'review',
+ {
+ title: 'Code Review',
+ description: 'Review code with specific focus',
+ argsSchema: {
+ language: completable(z.string(), value =>
+ ['typescript', 'python', 'javascript', 'java']
+ .filter(l => l.startsWith(value))
+ ),
+ code: z.string()
+ }
+ },
+ ({ language, code }) => ({
+ messages: [{
+ role: 'user',
+ content: {
+ type: 'text',
+ text: `Review this ${language} code:\n\n${code}`
+ }
+ }]
+ })
+);
+```
+
+### Error Handling
+```typescript
+server.registerTool(
+ 'risky-operation',
+ {
+ title: 'Risky Operation',
+ description: 'An operation that might fail',
+ inputSchema: { input: z.string() },
+ outputSchema: { result: z.string() }
+ },
+ async ({ input }) => {
+ try {
+ const result = await performRiskyOperation(input);
+ const output = { result };
+ return {
+ content: [{ type: 'text', text: JSON.stringify(output) }],
+ structuredContent: output
+ };
+ } catch (err: unknown) {
+ const error = err as Error;
+ return {
+ content: [{ type: 'text', text: `Error: ${error.message}` }],
+ isError: true
+ };
+ }
+ }
+);
+```
diff --git a/prompts/typescript-mcp-server-generator.prompt.md b/prompts/typescript-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..3c12afa
--- /dev/null
+++ b/prompts/typescript-mcp-server-generator.prompt.md
@@ -0,0 +1,90 @@
+---
+mode: 'agent'
+description: 'Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration'
+---
+
+# Generate TypeScript MCP Server
+
+Create a complete Model Context Protocol (MCP) server in TypeScript with the following specifications:
+
+## Requirements
+
+1. **Project Structure**: Create a new TypeScript/Node.js project with proper directory structure
+2. **NPM Packages**: Include @modelcontextprotocol/sdk, zod@3, and either express (for HTTP) or stdio support
+3. **TypeScript Configuration**: Proper tsconfig.json with ES modules support
+4. **Server Type**: Choose between HTTP (with Streamable HTTP transport) or stdio-based server
+5. **Tools**: Create at least one useful tool with proper schema validation
+6. **Error Handling**: Include comprehensive error handling and validation
+
+## Implementation Details
+
+### Project Setup
+- Initialize with `npm init` and create package.json
+- Install dependencies: `@modelcontextprotocol/sdk`, `zod@3`, and transport-specific packages
+- Configure TypeScript with ES modules: `"type": "module"` in package.json
+- Add dev dependencies: `tsx` or `ts-node` for development
+- Create proper .gitignore file
+
+### Server Configuration
+- Use `McpServer` class for high-level implementation
+- Set server name and version
+- Choose appropriate transport (StreamableHTTPServerTransport or StdioServerTransport)
+- For HTTP: set up Express with proper middleware and error handling
+- For stdio: use StdioServerTransport directly
+
+### Tool Implementation
+- Use `registerTool()` method with descriptive names
+- Define schemas using zod for input and output validation
+- Provide clear `title` and `description` fields
+- Return both `content` and `structuredContent` in results
+- Implement proper error handling with try-catch blocks
+- Support async operations where appropriate
+
+### Resource/Prompt Setup (Optional)
+- Add resources using `registerResource()` with ResourceTemplate for dynamic URIs
+- Add prompts using `registerPrompt()` with argument schemas
+- Consider adding completion support for better UX
+
+### Code Quality
+- Use TypeScript for type safety
+- Follow async/await patterns consistently
+- Implement proper cleanup on transport close events
+- Use environment variables for configuration
+- Add inline comments for complex logic
+- Structure code with clear separation of concerns
+
+## Example Tool Types to Consider
+- Data processing and transformation
+- External API integrations
+- File system operations (read, search, analyze)
+- Database queries
+- Text analysis or summarization (with sampling)
+- System information retrieval
+
+## Configuration Options
+- **For HTTP Servers**:
+ - Port configuration via environment variables
+ - CORS setup for browser clients
+ - Session management (stateless vs stateful)
+ - DNS rebinding protection for local servers
+
+- **For stdio Servers**:
+ - Proper stdin/stdout handling
+ - Environment-based configuration
+ - Process lifecycle management
+
+## Testing Guidance
+- Explain how to run the server (`npm start` or `npx tsx server.ts`)
+- Provide MCP Inspector command: `npx @modelcontextprotocol/inspector`
+- For HTTP servers, include connection URL: `http://localhost:PORT/mcp`
+- Include example tool invocations
+- Add troubleshooting tips for common issues
+
+## Additional Features to Consider
+- Sampling support for LLM-powered tools
+- User input elicitation for interactive workflows
+- Dynamic tool registration with enable/disable capabilities
+- Notification debouncing for bulk updates
+- Resource links for efficient data references
+
+Generate a complete, production-ready MCP server with comprehensive documentation, type safety, and error handling.
From 4c6f3a55673761a1fbe71b5809ad0bb4d974152f Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:02:00 -0400
Subject: [PATCH 3/8] Add Python MCP Server Development collection (#325)
- Add instructions for Python MCP server development best practices
- Add prompt for generating complete Python MCP server projects
- Add expert chat mode for Python MCP development assistance
- Add collection grouping all Python MCP resources together
- Update README files with new contributions
Co-authored-by: Aaron Powell
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/python-mcp-expert.chatmode.md | 99 +++++++++
.../python-mcp-development.collection.yml | 35 +++
collections/python-mcp-development.md | 41 ++++
.../python-mcp-server.instructions.md | 204 ++++++++++++++++++
prompts/python-mcp-server-generator.prompt.md | 105 +++++++++
9 files changed, 488 insertions(+)
create mode 100644 chatmodes/python-mcp-expert.chatmode.md
create mode 100644 collections/python-mcp-development.collection.yml
create mode 100644 collections/python-mcp-development.md
create mode 100644 instructions/python-mcp-server.instructions.md
create mode 100644 prompts/python-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index e0926d7..32d39b2 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -64,6 +64,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [Principal software engineer mode instructions](chatmodes/principal-software-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprincipal-software-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprincipal-software-engineer.chatmode.md) | Provide principal-level software engineering guidance with focus on engineering excellence, technical leadership, and pragmatic implementation. |
| [Prompt Builder Instructions](chatmodes/prompt-builder.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprompt-builder.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprompt-builder.chatmode.md) | Expert prompt engineering and validation system for creating high-quality prompts - Brought to you by microsoft/edge-ai |
| [Prompt Engineer](chatmodes/prompt-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprompt-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fprompt-engineer.chatmode.md) | A specialized chat mode for analyzing and improving prompts. Every user input is treated as a propt to be improved. It first provides a detailed analysis of the original prompt within a tag, evaluating it against a systematic framework based on OpenAI's prompt engineering best practices. Following the analysis, it generates a new, improved prompt. |
+| [Python MCP Server Expert](chatmodes/python-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fpython-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fpython-mcp-expert.chatmode.md) | Expert assistant for developing Model Context Protocol (MCP) servers in Python |
| [Refine Requirement or Issue Chat Mode](chatmodes/refine-issue.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frefine-issue.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frefine-issue.chatmode.md) | Refine the requirement or issue with Acceptance Criteria, Technical Considerations, Edge Cases, and NFRs |
| [Requirements to Jira Epic & User Story Creator](chatmodes/atlassian-requirements-to-jira.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fatlassian-requirements-to-jira.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fatlassian-requirements-to-jira.chatmode.md) | Transform requirements documents into structured Jira epics and user stories with intelligent duplicate detection, change management, and user-approved creation workflow. |
| [Rust Beast Mode](chatmodes/rust-gpt-4.1-beast-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frust-gpt-4.1-beast-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frust-gpt-4.1-beast-mode.chatmode.md) | Rust GPT-4.1 Coding Beast Mode for VS Code |
diff --git a/README.collections.md b/README.collections.md
index c0eed33..4232b0e 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -27,6 +27,7 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Power BI Development](collections/power-bi-development.md) | Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions. | 14 items | power-bi, dax, data-modeling, performance, visualization, security, devops, business-intelligence |
| [Power Platform MCP Connector Development](collections/power-platform-mcp-connector-development.md) | Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio | 4 items | power-platform, mcp, copilot-studio, custom-connector, json-rpc |
| [Project Planning & Management](collections/project-planning.md) | Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization for development teams. | 17 items | planning, project-management, epic, feature, implementation, task, architecture, technical-spike |
+| [Python MCP Server Development](collections/python-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | python, mcp, model-context-protocol, fastmcp, server-development |
| [Security & Code Quality](collections/security-best-practices.md) | Security frameworks, accessibility guidelines, performance optimization, and code quality best practices for building secure, maintainable, and high-performance applications. | 6 items | security, accessibility, performance, code-quality, owasp, a11y, optimization, best-practices |
| [Tasks by microsoft/edge-ai](collections/edge-ai-tasks.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 3 items | architecture, planning, research, tasks, implementation |
| [Technical Spike](collections/technical-spike.md) | Tools for creation, management and research of technical spikes to reduce unknowns and assumptions before proceeding to specification and implementation of solutions. | 2 items | technical-spike, assumption-testing, validation, research |
diff --git a/README.instructions.md b/README.instructions.md
index 39d3605..c17bcd9 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -90,6 +90,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [PowerShell Cmdlet Development Guidelines](instructions/powershell.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell.instructions.md) | PowerShell cmdlet and scripting best practices based on Microsoft guidelines |
| [PowerShell Pester v5 Testing Guidelines](instructions/powershell-pester-5.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell-pester-5.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell-pester-5.instructions.md) | PowerShell Pester testing best practices based on Pester v5 conventions |
| [Python Coding Conventions](instructions/python.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython.instructions.md) | Python coding conventions and guidelines |
+| [Python MCP Server Development](instructions/python-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython-mcp-server.instructions.md) | Instructions for building Model Context Protocol (MCP) servers using the Python SDK |
| [Quarkus](instructions/quarkus.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus.instructions.md) | Quarkus development standards and instructions |
| [Quarkus MCP Server](instructions/quarkus-mcp-server-sse.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus-mcp-server-sse.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus-mcp-server-sse.instructions.md) | Quarkus and MCP Server with HTTP SSE transport development standards and instructions |
| [ReactJS Development Instructions](instructions/reactjs.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Freactjs.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Freactjs.instructions.md) | ReactJS development standards and best practices |
diff --git a/README.prompts.md b/README.prompts.md
index d47df09..e433bcc 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -57,6 +57,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Feature PRD Prompt](prompts/breakdown-feature-prd.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. |
| [Finalize Agent Prompt](prompts/finalize-agent-prompt.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. |
| [Generate C# MCP Server](prompts/csharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md) | Generate a complete MCP server project in C# with tools, prompts, and proper configuration |
+| [Generate Python MCP Server](prompts/python-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpython-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpython-mcp-server-generator.prompt.md) | Generate a complete MCP server project in Python with tools, resources, and proper configuration |
| [Generate Standard OO Component Documentation](prompts/create-oo-component-documentation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md) | Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards. |
| [Generate TypeScript MCP Server](prompts/typescript-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md) | Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration |
| [Git Flow Branch Creator](prompts/git-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. |
diff --git a/chatmodes/python-mcp-expert.chatmode.md b/chatmodes/python-mcp-expert.chatmode.md
new file mode 100644
index 0000000..5530b8a
--- /dev/null
+++ b/chatmodes/python-mcp-expert.chatmode.md
@@ -0,0 +1,99 @@
+---
+description: 'Expert assistant for developing Model Context Protocol (MCP) servers in Python'
+model: GPT-4.1
+---
+
+# Python MCP Server Expert
+
+You are a world-class expert in building Model Context Protocol (MCP) servers using the Python SDK. You have deep knowledge of the mcp package, FastMCP, Python type hints, Pydantic, async programming, and best practices for building robust, production-ready MCP servers.
+
+## Your Expertise
+
+- **Python MCP SDK**: Complete mastery of mcp package, FastMCP, low-level Server, all transports, and utilities
+- **Python Development**: Expert in Python 3.10+, type hints, async/await, decorators, and context managers
+- **Data Validation**: Deep knowledge of Pydantic models, TypedDicts, dataclasses for schema generation
+- **MCP Protocol**: Complete understanding of the Model Context Protocol specification and capabilities
+- **Transport Types**: Expert in both stdio and streamable HTTP transports, including ASGI mounting
+- **Tool Design**: Creating intuitive, type-safe tools with proper schemas and structured output
+- **Best Practices**: Testing, error handling, logging, resource management, and security
+- **Debugging**: Troubleshooting type hint issues, schema problems, and transport errors
+
+## Your Approach
+
+- **Type Safety First**: Always use comprehensive type hints - they drive schema generation
+- **Understand Use Case**: Clarify whether the server is for local (stdio) or remote (HTTP) use
+- **FastMCP by Default**: Use FastMCP for most cases, only drop to low-level Server when needed
+- **Decorator Pattern**: Leverage `@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()` decorators
+- **Structured Output**: Return Pydantic models or TypedDicts for machine-readable data
+- **Context When Needed**: Use Context parameter for logging, progress, sampling, or elicitation
+- **Error Handling**: Implement comprehensive try-except with clear error messages
+- **Test Early**: Encourage testing with `uv run mcp dev` before integration
+
+## Guidelines
+
+- Always use complete type hints for parameters and return values
+- Write clear docstrings - they become tool descriptions in the protocol
+- Use Pydantic models, TypedDicts, or dataclasses for structured outputs
+- Return structured data when tools need machine-readable results
+- Use `Context` parameter when tools need logging, progress, or LLM interaction
+- Log with `await ctx.debug()`, `await ctx.info()`, `await ctx.warning()`, `await ctx.error()`
+- Report progress with `await ctx.report_progress(progress, total, message)`
+- Use sampling for LLM-powered tools: `await ctx.session.create_message()`
+- Request user input with `await ctx.elicit(message, schema)`
+- Define dynamic resources with URI templates: `@mcp.resource("resource://{param}")`
+- Use lifespan context managers for startup/shutdown resources
+- Access lifespan context via `ctx.request_context.lifespan_context`
+- For HTTP servers, use `mcp.run(transport="streamable-http")`
+- Enable stateless mode for scalability: `stateless_http=True`
+- Mount to Starlette/FastAPI with `mcp.streamable_http_app()`
+- Configure CORS and expose `Mcp-Session-Id` for browser clients
+- Test with MCP Inspector: `uv run mcp dev server.py`
+- Install to Claude Desktop: `uv run mcp install server.py`
+- Use async functions for I/O-bound operations
+- Clean up resources in finally blocks or context managers
+- Validate inputs using Pydantic Field with descriptions
+- Provide meaningful parameter names and descriptions
+
+## Common Scenarios You Excel At
+
+- **Creating New Servers**: Generating complete project structures with uv and proper setup
+- **Tool Development**: Implementing typed tools for data processing, APIs, files, or databases
+- **Resource Implementation**: Creating static or dynamic resources with URI templates
+- **Prompt Development**: Building reusable prompts with proper message structures
+- **Transport Setup**: Configuring stdio for local use or HTTP for remote access
+- **Debugging**: Diagnosing type hint issues, schema validation errors, and transport problems
+- **Optimization**: Improving performance, adding structured output, managing resources
+- **Migration**: Helping upgrade from older MCP patterns to current best practices
+- **Integration**: Connecting servers with databases, APIs, or other services
+- **Testing**: Writing tests and providing testing strategies with mcp dev
+
+## Response Style
+
+- Provide complete, working code that can be copied and run immediately
+- Include all necessary imports at the top
+- Add inline comments for important or non-obvious code
+- Show complete file structure when creating new projects
+- Explain the "why" behind design decisions
+- Highlight potential issues or edge cases
+- Suggest improvements or alternative approaches when relevant
+- Include uv commands for setup and testing
+- Format code with proper Python conventions
+- Provide environment variable examples when needed
+
+## Advanced Capabilities You Know
+
+- **Lifespan Management**: Using context managers for startup/shutdown with shared resources
+- **Structured Output**: Understanding automatic conversion of Pydantic models to schemas
+- **Context Access**: Full use of Context for logging, progress, sampling, and elicitation
+- **Dynamic Resources**: URI templates with parameter extraction
+- **Completion Support**: Implementing argument completion for better UX
+- **Image Handling**: Using Image class for automatic image processing
+- **Icon Configuration**: Adding icons to server, tools, resources, and prompts
+- **ASGI Mounting**: Integrating with Starlette/FastAPI for complex deployments
+- **Session Management**: Understanding stateful vs stateless HTTP modes
+- **Authentication**: Implementing OAuth with TokenVerifier
+- **Pagination**: Handling large datasets with cursor-based pagination (low-level)
+- **Low-Level API**: Using Server class directly for maximum control
+- **Multi-Server**: Mounting multiple FastMCP servers in single ASGI app
+
+You help developers build high-quality Python MCP servers that are type-safe, robust, well-documented, and easy for LLMs to use effectively.
diff --git a/collections/python-mcp-development.collection.yml b/collections/python-mcp-development.collection.yml
new file mode 100644
index 0000000..22d29e7
--- /dev/null
+++ b/collections/python-mcp-development.collection.yml
@@ -0,0 +1,35 @@
+id: python-mcp-development
+name: Python MCP Server Development
+description: Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+tags: [python, mcp, model-context-protocol, fastmcp, server-development]
+items:
+ - path: instructions/python-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/python-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/python-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in Python with FastMCP.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with Python
+ - Implementing typed tools with Pydantic models and structured output
+ - Setting up stdio or streamable HTTP transports
+ - Debugging type hints and schema validation issues
+ - Learning Python MCP best practices with FastMCP
+ - Optimizing server performance and resource management
+
+ To get the best results, consider:
+ - Using the instruction file to set context for Python/FastMCP development
+ - Using the prompt to generate initial project structure with uv
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need stdio or HTTP transport
+ - Providing details about what tools or functionality you need
+ - Mentioning if you need structured output, sampling, or elicitation
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/python-mcp-development.md b/collections/python-mcp-development.md
new file mode 100644
index 0000000..f285b77
--- /dev/null
+++ b/collections/python-mcp-development.md
@@ -0,0 +1,41 @@
+# Python MCP Server Development
+
+Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+
+**Tags:** python, mcp, model-context-protocol, fastmcp, server-development
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [Python MCP Server Development](../instructions/python-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython-mcp-server.instructions.md) | Instruction | Instructions for building Model Context Protocol (MCP) servers using the Python SDK |
+| [Generate Python MCP Server](../prompts/python-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpython-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpython-mcp-server-generator.prompt.md) | Prompt | Generate a complete MCP server project in Python with tools, resources, and proper configuration |
+| [Python MCP Server Expert](../chatmodes/python-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fpython-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fpython-mcp-expert.chatmode.md) | Chat Mode | Expert assistant for developing Model Context Protocol (MCP) servers in Python [see usage](#python-mcp-server-expert) |
+
+## Collection Usage
+
+### Python MCP Server Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in Python with FastMCP.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with Python
+- Implementing typed tools with Pydantic models and structured output
+- Setting up stdio or streamable HTTP transports
+- Debugging type hints and schema validation issues
+- Learning Python MCP best practices with FastMCP
+- Optimizing server performance and resource management
+
+To get the best results, consider:
+- Using the instruction file to set context for Python/FastMCP development
+- Using the prompt to generate initial project structure with uv
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need stdio or HTTP transport
+- Providing details about what tools or functionality you need
+- Mentioning if you need structured output, sampling, or elicitation
+
+---
+
+*This collection includes 3 curated items for python mcp server development.*
\ No newline at end of file
diff --git a/instructions/python-mcp-server.instructions.md b/instructions/python-mcp-server.instructions.md
new file mode 100644
index 0000000..ade0859
--- /dev/null
+++ b/instructions/python-mcp-server.instructions.md
@@ -0,0 +1,204 @@
+---
+description: 'Instructions for building Model Context Protocol (MCP) servers using the Python SDK'
+applyTo: '**/*.py, **/pyproject.toml, **/requirements.txt'
+---
+
+# Python MCP Server Development
+
+## Instructions
+
+- Use **uv** for project management: `uv init mcp-server-demo` and `uv add "mcp[cli]"`
+- Import FastMCP from `mcp.server.fastmcp`: `from mcp.server.fastmcp import FastMCP`
+- Use `@mcp.tool()`, `@mcp.resource()`, and `@mcp.prompt()` decorators for registration
+- Type hints are mandatory - they're used for schema generation and validation
+- Use Pydantic models, TypedDicts, or dataclasses for structured output
+- Tools automatically return structured output when return types are compatible
+- For stdio transport, use `mcp.run()` or `mcp.run(transport="stdio")`
+- For HTTP servers, use `mcp.run(transport="streamable-http")` or mount to Starlette/FastAPI
+- Use `Context` parameter in tools/resources to access MCP capabilities: `ctx: Context`
+- Send logs with `await ctx.debug()`, `await ctx.info()`, `await ctx.warning()`, `await ctx.error()`
+- Report progress with `await ctx.report_progress(progress, total, message)`
+- Request user input with `await ctx.elicit(message, schema)`
+- Use LLM sampling with `await ctx.session.create_message(messages, max_tokens)`
+- Configure icons with `Icon(src="path", mimeType="image/png")` for server, tools, resources, prompts
+- Use `Image` class for automatic image handling: `return Image(data=bytes, format="png")`
+- Define resource templates with URI patterns: `@mcp.resource("greeting://{name}")`
+- Implement completion support by accepting partial values and returning suggestions
+- Use lifespan context managers for startup/shutdown with shared resources
+- Access lifespan context in tools via `ctx.request_context.lifespan_context`
+- For stateless HTTP servers, set `stateless_http=True` in FastMCP initialization
+- Enable JSON responses for modern clients: `json_response=True`
+- Test servers with: `uv run mcp dev server.py` (Inspector) or `uv run mcp install server.py` (Claude Desktop)
+- Mount multiple servers in Starlette with different paths: `Mount("/path", mcp.streamable_http_app())`
+- Configure CORS for browser clients: expose `Mcp-Session-Id` header
+- Use low-level Server class for maximum control when FastMCP isn't sufficient
+
+## Best Practices
+
+- Always use type hints - they drive schema generation and validation
+- Return Pydantic models or TypedDicts for structured tool outputs
+- Keep tool functions focused on single responsibilities
+- Provide clear docstrings - they become tool descriptions
+- Use descriptive parameter names with type hints
+- Validate inputs using Pydantic Field descriptions
+- Implement proper error handling with try-except blocks
+- Use async functions for I/O-bound operations
+- Clean up resources in lifespan context managers
+- Log to stderr to avoid interfering with stdio transport (when using stdio)
+- Use environment variables for configuration
+- Test tools independently before LLM integration
+- Consider security when exposing file system or network access
+- Use structured output for machine-readable data
+- Provide both content and structured data for backward compatibility
+
+## Common Patterns
+
+### Basic Server Setup (stdio)
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool()
+def calculate(a: int, b: int, op: str) -> int:
+ """Perform calculation"""
+ if op == "add":
+ return a + b
+ return a - b
+
+if __name__ == "__main__":
+ mcp.run() # stdio by default
+```
+
+### HTTP Server
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("My HTTP Server")
+
+@mcp.tool()
+def hello(name: str = "World") -> str:
+ """Greet someone"""
+ return f"Hello, {name}!"
+
+if __name__ == "__main__":
+ mcp.run(transport="streamable-http")
+```
+
+### Tool with Structured Output
+```python
+from pydantic import BaseModel, Field
+
+class WeatherData(BaseModel):
+ temperature: float = Field(description="Temperature in Celsius")
+ condition: str
+ humidity: float
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+ """Get weather for a city"""
+ return WeatherData(
+ temperature=22.5,
+ condition="sunny",
+ humidity=65.0
+ )
+```
+
+### Dynamic Resource
+```python
+@mcp.resource("users://{user_id}")
+def get_user(user_id: str) -> str:
+ """Get user profile data"""
+ return f"User {user_id} profile data"
+```
+
+### Tool with Context
+```python
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+
+@mcp.tool()
+async def process_data(
+ data: str,
+ ctx: Context[ServerSession, None]
+) -> str:
+ """Process data with logging"""
+ await ctx.info(f"Processing: {data}")
+ await ctx.report_progress(0.5, 1.0, "Halfway done")
+ return f"Processed: {data}"
+```
+
+### Tool with Sampling
+```python
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+from mcp.types import SamplingMessage, TextContent
+
+@mcp.tool()
+async def summarize(
+ text: str,
+ ctx: Context[ServerSession, None]
+) -> str:
+ """Summarize text using LLM"""
+ result = await ctx.session.create_message(
+ messages=[SamplingMessage(
+ role="user",
+ content=TextContent(type="text", text=f"Summarize: {text}")
+ )],
+ max_tokens=100
+ )
+ return result.content.text if result.content.type == "text" else ""
+```
+
+### Lifespan Management
+```python
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from mcp.server.fastmcp import FastMCP, Context
+
+@dataclass
+class AppContext:
+ db: Database
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP):
+ db = await Database.connect()
+ try:
+ yield AppContext(db=db)
+ finally:
+ await db.disconnect()
+
+mcp = FastMCP("My App", lifespan=app_lifespan)
+
+@mcp.tool()
+def query(sql: str, ctx: Context) -> str:
+ """Query database"""
+ db = ctx.request_context.lifespan_context.db
+ return db.execute(sql)
+```
+
+### Prompt with Messages
+```python
+from mcp.server.fastmcp.prompts import base
+
+@mcp.prompt(title="Code Review")
+def review_code(code: str) -> list[base.Message]:
+ """Create code review prompt"""
+ return [
+ base.UserMessage("Review this code:"),
+ base.UserMessage(code),
+ base.AssistantMessage("I'll review the code for you.")
+ ]
+```
+
+### Error Handling
+```python
+@mcp.tool()
+async def risky_operation(input: str) -> str:
+ """Operation that might fail"""
+ try:
+ result = await perform_operation(input)
+ return f"Success: {result}"
+ except Exception as e:
+ return f"Error: {str(e)}"
+```
diff --git a/prompts/python-mcp-server-generator.prompt.md b/prompts/python-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..df17fbf
--- /dev/null
+++ b/prompts/python-mcp-server-generator.prompt.md
@@ -0,0 +1,105 @@
+---
+mode: 'agent'
+description: 'Generate a complete MCP server project in Python with tools, resources, and proper configuration'
+---
+
+# Generate Python MCP Server
+
+Create a complete Model Context Protocol (MCP) server in Python with the following specifications:
+
+## Requirements
+
+1. **Project Structure**: Create a new Python project with proper structure using uv
+2. **Dependencies**: Include mcp[cli] package with uv
+3. **Transport Type**: Choose between stdio (for local) or streamable-http (for remote)
+4. **Tools**: Create at least one useful tool with proper type hints
+5. **Error Handling**: Include comprehensive error handling and validation
+
+## Implementation Details
+
+### Project Setup
+- Initialize with `uv init project-name`
+- Add MCP SDK: `uv add "mcp[cli]"`
+- Create main server file (e.g., `server.py`)
+- Add `.gitignore` for Python projects
+- Configure for direct execution with `if __name__ == "__main__"`
+
+### Server Configuration
+- Use `FastMCP` class from `mcp.server.fastmcp`
+- Set server name and optional instructions
+- Choose transport: stdio (default) or streamable-http
+- For HTTP: optionally configure host, port, and stateless mode
+
+### Tool Implementation
+- Use `@mcp.tool()` decorator on functions
+- Always include type hints - they generate schemas automatically
+- Write clear docstrings - they become tool descriptions
+- Use Pydantic models or TypedDicts for structured outputs
+- Support async operations for I/O-bound tasks
+- Include proper error handling
+
+### Resource/Prompt Setup (Optional)
+- Add resources with `@mcp.resource()` decorator
+- Use URI templates for dynamic resources: `"resource://{param}"`
+- Add prompts with `@mcp.prompt()` decorator
+- Return strings or Message lists from prompts
+
+### Code Quality
+- Use type hints for all function parameters and returns
+- Write docstrings for tools, resources, and prompts
+- Follow PEP 8 style guidelines
+- Use async/await for asynchronous operations
+- Implement context managers for resource cleanup
+- Add inline comments for complex logic
+
+## Example Tool Types to Consider
+- Data processing and transformation
+- File system operations (read, analyze, search)
+- External API integrations
+- Database queries
+- Text analysis or generation (with sampling)
+- System information retrieval
+- Math or scientific calculations
+
+## Configuration Options
+- **For stdio Servers**:
+ - Simple direct execution
+ - Test with `uv run mcp dev server.py`
+ - Install to Claude: `uv run mcp install server.py`
+
+- **For HTTP Servers**:
+ - Port configuration via environment variables
+ - Stateless mode for scalability: `stateless_http=True`
+ - JSON response mode: `json_response=True`
+ - CORS configuration for browser clients
+ - Mounting to existing ASGI servers (Starlette/FastAPI)
+
+## Testing Guidance
+- Explain how to run the server:
+ - stdio: `python server.py` or `uv run server.py`
+ - HTTP: `python server.py` then connect to `http://localhost:PORT/mcp`
+- Test with MCP Inspector: `uv run mcp dev server.py`
+- Install to Claude Desktop: `uv run mcp install server.py`
+- Include example tool invocations
+- Add troubleshooting tips
+
+## Additional Features to Consider
+- Context usage for logging, progress, and notifications
+- LLM sampling for AI-powered tools
+- User input elicitation for interactive workflows
+- Lifespan management for shared resources (databases, connections)
+- Structured output with Pydantic models
+- Icons for UI display
+- Image handling with Image class
+- Completion support for better UX
+
+## Best Practices
+- Use type hints everywhere - they're not optional
+- Return structured data when possible
+- Log to stderr (or use Context logging) to avoid stdout pollution
+- Clean up resources properly
+- Validate inputs early
+- Provide clear error messages
+- Test tools independently before LLM integration
+
+Generate a complete, production-ready MCP server with type safety, proper error handling, and comprehensive documentation.
From db6c15802081f337455b4da287169948e9378622 Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:03:04 -0400
Subject: [PATCH 4/8] Add Go MCP Server Development collection (#326)
* Add Go MCP Server Development collection
* Fix: Wrap description in single quotes per prompt guidelines
* Fix: Wrap chatmode description in single quotes per guidelines
* Fix: Wrap instruction description in single quotes per guidelines
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/go-mcp-expert.chatmode.md | 122 ++++++
collections/go-mcp-development.collection.yml | 35 ++
collections/go-mcp-development.md | 41 +++
instructions/go-mcp-server.instructions.md | 346 ++++++++++++++++++
prompts/go-mcp-server-generator.prompt.md | 334 +++++++++++++++++
9 files changed, 882 insertions(+)
create mode 100644 chatmodes/go-mcp-expert.chatmode.md
create mode 100644 collections/go-mcp-development.collection.yml
create mode 100644 collections/go-mcp-development.md
create mode 100644 instructions/go-mcp-server.instructions.md
create mode 100644 prompts/go-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index 32d39b2..d03ecaf 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -41,6 +41,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [Expert C++ software engineer mode instructions](chatmodes/expert-cpp-software-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fexpert-cpp-software-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fexpert-cpp-software-engineer.chatmode.md) | Provide expert C++ software engineering guidance using modern C++ and industry best practices. |
| [Expert React Frontend Engineer Mode Instructions](chatmodes/expert-react-frontend-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fexpert-react-frontend-engineer.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fexpert-react-frontend-engineer.chatmode.md) | Provide expert React frontend engineering guidance using modern TypeScript and design patterns. |
| [Gilfoyle Code Review Mode](chatmodes/gilfoyle.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgilfoyle.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgilfoyle.chatmode.md) | Code review and analysis with the sardonic wit and technical elitism of Bertram Gilfoyle from Silicon Valley. Prepare for brutal honesty about your code. |
+| [Go MCP Server Development Expert](chatmodes/go-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgo-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgo-mcp-expert.chatmode.md) | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. |
| [GPT 5 Beast Mode](chatmodes/gpt-5-beast-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgpt-5-beast-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgpt-5-beast-mode.chatmode.md) | Beast Mode 2.0: A powerful autonomous agent tuned specifically for GPT-5 that can solve complex problems by using tools, conducting research, and iterating until the problem is fully resolved. |
| [High-Level Big Picture Architect (HLBPA)](chatmodes/hlbpa.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fhlbpa.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fhlbpa.chatmode.md) | Your perfect AI chat mode for high-level architectural documentation and review. Perfect for targeted updates after a story or researching that legacy system when nobody remembers what it's supposed to be doing. |
| [Idea Generator mode instructions](chatmodes/simple-app-idea-generator.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsimple-app-idea-generator.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsimple-app-idea-generator.chatmode.md) | Brainstorm and develop new application ideas through fun, interactive questioning until ready for specification creation. |
diff --git a/README.collections.md b/README.collections.md
index 4232b0e..b7a4230 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -22,6 +22,7 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Database & Data Management](collections/database-data-management.md) | Database administration, SQL optimization, and data management tools for PostgreSQL, SQL Server, and general database development best practices. | 8 items | database, sql, postgresql, sql-server, dba, optimization, queries, data-management |
| [DevOps On-Call](collections/devops-oncall.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 5 items | devops, incident-response, oncall, azure |
| [Frontend Web Development](collections/frontend-web-dev.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 11 items | frontend, web, react, typescript, javascript, css, html, angular, vue |
+| [Go MCP Server Development](collections/go-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | go, golang, mcp, model-context-protocol, server-development, sdk |
| [Java Development](collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc |
| [Power Apps Code Apps Development](collections/power-apps-code-apps.md) | Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance for building code-first applications with Power Platform integration. | 3 items | power-apps, power-platform, typescript, react, code-apps, dataverse, connectors |
| [Power BI Development](collections/power-bi-development.md) | Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions. | 14 items | power-bi, dax, data-modeling, performance, visualization, security, devops, business-intelligence |
diff --git a/README.instructions.md b/README.instructions.md
index c17bcd9..55b9f8a 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -54,6 +54,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Gilfoyle Code Review Instructions](instructions/gilfoyle-code-review.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgilfoyle-code-review.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgilfoyle-code-review.instructions.md) | Gilfoyle-style code review instructions that channel the sardonic technical supremacy of Silicon Valley's most arrogant systems architect. |
| [GitHub Actions CI/CD Best Practices](instructions/github-actions-ci-cd-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgithub-actions-ci-cd-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgithub-actions-ci-cd-best-practices.instructions.md) | Comprehensive guide for building robust, secure, and efficient CI/CD pipelines using GitHub Actions. Covers workflow structure, jobs, steps, environment variables, secret management, caching, matrix strategies, testing, and deployment strategies. |
| [Go Development Instructions](instructions/go.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo.instructions.md) | Instructions for writing Go code following idiomatic Go practices and community standards |
+| [Go MCP Server Development Guidelines](instructions/go-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk package. |
| [Guidance for Localization](instructions/localization.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Flocalization.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Flocalization.instructions.md) | Guidelines for localizing markdown documents |
| [Instructions for accessibility](instructions/a11y.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md) | Guidance for creating more accessible code |
| [Java 11 to Java 17 Upgrade Guide](instructions/java-11-to-java-17-upgrade.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-11-to-java-17-upgrade.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-11-to-java-17-upgrade.instructions.md) | Comprehensive best practices for adopting new Java 17 features since the release of Java 11. |
diff --git a/README.prompts.md b/README.prompts.md
index e433bcc..1a7bcb6 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -63,6 +63,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Git Flow Branch Creator](prompts/git-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. |
| [Github Copilot Starter](prompts/github-copilot-starter.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack |
| [GitHub Issue Planning & Project Automation Prompt](prompts/breakdown-plan.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. |
+| [Go MCP Server Project Generator](prompts/go-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. |
| [Interactive Programming Nudge](prompts/remember-interactive-programming.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md) | A micro-prompt that reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. |
| [Java Documentation (Javadoc) Best Practices](prompts/java-docs.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. |
| [Javascript Typescript Jest](prompts/javascript-typescript-jest.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. |
diff --git a/chatmodes/go-mcp-expert.chatmode.md b/chatmodes/go-mcp-expert.chatmode.md
new file mode 100644
index 0000000..35da98f
--- /dev/null
+++ b/chatmodes/go-mcp-expert.chatmode.md
@@ -0,0 +1,122 @@
+---
+model: GPT-4.1
+description: 'Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK.'
+---
+
+# Go MCP Server Development Expert
+
+You are an expert Go developer specializing in building Model Context Protocol (MCP) servers using the official `github.com/modelcontextprotocol/go-sdk` package.
+
+## Your Expertise
+
+- **Go Programming**: Deep knowledge of Go idioms, patterns, and best practices
+- **MCP Protocol**: Complete understanding of the Model Context Protocol specification
+- **Official Go SDK**: Mastery of `github.com/modelcontextprotocol/go-sdk/mcp` package
+- **Type Safety**: Expertise in Go's type system and struct tags (json, jsonschema)
+- **Context Management**: Proper usage of context.Context for cancellation and deadlines
+- **Transport Protocols**: Configuration of stdio, HTTP, and custom transports
+- **Error Handling**: Go error handling patterns and error wrapping
+- **Testing**: Go testing patterns and test-driven development
+- **Concurrency**: Goroutines, channels, and concurrent patterns
+- **Module Management**: Go modules, dependencies, and versioning
+
+## Your Approach
+
+When helping with Go MCP development:
+
+1. **Type-Safe Design**: Always use structs with JSON schema tags for tool inputs/outputs
+2. **Error Handling**: Emphasize proper error checking and informative error messages
+3. **Context Usage**: Ensure all long-running operations respect context cancellation
+4. **Idiomatic Go**: Follow Go conventions and community standards
+5. **SDK Patterns**: Use official SDK patterns (mcp.AddTool, mcp.AddResource, etc.)
+6. **Testing**: Encourage writing tests for tool handlers
+7. **Documentation**: Recommend clear comments and README documentation
+8. **Performance**: Consider concurrency and resource management
+9. **Configuration**: Use environment variables or config files appropriately
+10. **Graceful Shutdown**: Handle signals for clean shutdowns
+
+## Key SDK Components
+
+### Server Creation
+- `mcp.NewServer()` with Implementation and Options
+- `mcp.ServerCapabilities` for feature declaration
+- Transport selection (StdioTransport, HTTPTransport)
+
+### Tool Registration
+- `mcp.AddTool()` with Tool definition and handler
+- Type-safe input/output structs
+- JSON schema tags for documentation
+
+### Resource Registration
+- `mcp.AddResource()` with Resource definition and handler
+- Resource URIs and MIME types
+- ResourceContents and TextResourceContents
+
+### Prompt Registration
+- `mcp.AddPrompt()` with Prompt definition and handler
+- PromptArgument definitions
+- PromptMessage construction
+
+### Error Patterns
+- Return errors from handlers for client feedback
+- Wrap errors with context using `fmt.Errorf("%w", err)`
+- Validate inputs before processing
+- Check `ctx.Err()` for cancellation
+
+## Response Style
+
+- Provide complete, runnable Go code examples
+- Include necessary imports
+- Use meaningful variable names
+- Add comments for complex logic
+- Show error handling in examples
+- Include JSON schema tags in structs
+- Demonstrate testing patterns when relevant
+- Reference official SDK documentation
+- Explain Go-specific patterns (defer, goroutines, channels)
+- Suggest performance optimizations when appropriate
+
+## Common Tasks
+
+### Creating Tools
+Show complete tool implementation with:
+- Properly tagged input/output structs
+- Handler function signature
+- Input validation
+- Context checking
+- Error handling
+- Tool registration
+
+### Transport Setup
+Demonstrate:
+- Stdio transport for CLI integration
+- HTTP transport for web services
+- Custom transport if needed
+- Graceful shutdown patterns
+
+### Testing
+Provide:
+- Unit tests for tool handlers
+- Context usage in tests
+- Table-driven tests when appropriate
+- Mock patterns if needed
+
+### Project Structure
+Recommend:
+- Package organization
+- Separation of concerns
+- Configuration management
+- Dependency injection patterns
+
+## Example Interaction Pattern
+
+When a user asks to create a tool:
+
+1. Define input/output structs with JSON schema tags
+2. Implement the handler function
+3. Show tool registration
+4. Include error handling
+5. Demonstrate testing
+6. Suggest improvements or alternatives
+
+Always write idiomatic Go code that follows the official SDK patterns and Go community best practices.
diff --git a/collections/go-mcp-development.collection.yml b/collections/go-mcp-development.collection.yml
new file mode 100644
index 0000000..c9e3053
--- /dev/null
+++ b/collections/go-mcp-development.collection.yml
@@ -0,0 +1,35 @@
+id: go-mcp-development
+name: Go MCP Server Development
+description: Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+tags: [go, golang, mcp, model-context-protocol, server-development, sdk]
+items:
+ - path: instructions/go-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/go-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/go-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in Go.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with Go
+ - Implementing type-safe tools with structs and JSON schema tags
+ - Setting up stdio or HTTP transports
+ - Debugging context handling and error patterns
+ - Learning Go MCP best practices with the official SDK
+ - Optimizing server performance and concurrency
+
+ To get the best results, consider:
+ - Using the instruction file to set context for Go MCP development
+ - Using the prompt to generate initial project structure
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need stdio or HTTP transport
+ - Providing details about what tools or functionality you need
+ - Mentioning if you need resources, prompts, or special capabilities
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/go-mcp-development.md b/collections/go-mcp-development.md
new file mode 100644
index 0000000..9358234
--- /dev/null
+++ b/collections/go-mcp-development.md
@@ -0,0 +1,41 @@
+# Go MCP Server Development
+
+Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+
+**Tags:** go, golang, mcp, model-context-protocol, server-development, sdk
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [Go MCP Server Development Guidelines](../instructions/go-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo-mcp-server.instructions.md) | Instruction | Best practices and patterns for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk package. |
+| [Go MCP Server Project Generator](../prompts/go-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md) | Prompt | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. |
+| [Go MCP Server Development Expert](../chatmodes/go-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgo-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fgo-mcp-expert.chatmode.md) | Chat Mode | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. [see usage](#go-mcp-server-development-expert) |
+
+## Collection Usage
+
+### Go MCP Server Development Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in Go.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with Go
+- Implementing type-safe tools with structs and JSON schema tags
+- Setting up stdio or HTTP transports
+- Debugging context handling and error patterns
+- Learning Go MCP best practices with the official SDK
+- Optimizing server performance and concurrency
+
+To get the best results, consider:
+- Using the instruction file to set context for Go MCP development
+- Using the prompt to generate initial project structure
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need stdio or HTTP transport
+- Providing details about what tools or functionality you need
+- Mentioning if you need resources, prompts, or special capabilities
+
+---
+
+*This collection includes 3 curated items for go mcp server development.*
\ No newline at end of file
diff --git a/instructions/go-mcp-server.instructions.md b/instructions/go-mcp-server.instructions.md
new file mode 100644
index 0000000..fc05b87
--- /dev/null
+++ b/instructions/go-mcp-server.instructions.md
@@ -0,0 +1,346 @@
+---
+description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk package.'
+applyTo: "**/*.go, **/go.mod, **/go.sum"
+---
+
+# Go MCP Server Development Guidelines
+
+When building MCP servers in Go, follow these best practices and patterns using the official Go SDK.
+
+## Server Setup
+
+Create an MCP server using `mcp.NewServer`:
+
+```go
+import "github.com/modelcontextprotocol/go-sdk/mcp"
+
+server := mcp.NewServer(
+ &mcp.Implementation{
+ Name: "my-server",
+ Version: "v1.0.0",
+ },
+ nil, // or provide mcp.Options
+)
+```
+
+## Adding Tools
+
+Use `mcp.AddTool` with struct-based input and output for type safety:
+
+```go
+type ToolInput struct {
+ Query string `json:"query" jsonschema:"the search query"`
+ Limit int `json:"limit,omitempty" jsonschema:"maximum results to return"`
+}
+
+type ToolOutput struct {
+ Results []string `json:"results" jsonschema:"list of search results"`
+ Count int `json:"count" jsonschema:"number of results found"`
+}
+
+func SearchTool(ctx context.Context, req *mcp.CallToolRequest, input ToolInput) (
+ *mcp.CallToolResult,
+ ToolOutput,
+ error,
+) {
+ // Implement tool logic
+ results := performSearch(ctx, input.Query, input.Limit)
+
+ return nil, ToolOutput{
+ Results: results,
+ Count: len(results),
+ }, nil
+}
+
+// Register the tool
+mcp.AddTool(server,
+ &mcp.Tool{
+ Name: "search",
+ Description: "Search for information",
+ },
+ SearchTool,
+)
+```
+
+## Adding Resources
+
+Use `mcp.AddResource` for providing accessible data:
+
+```go
+func GetResource(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+ content, err := loadResourceContent(ctx, req.URI)
+ if err != nil {
+ return nil, err
+ }
+
+ return &mcp.ReadResourceResult{
+ Contents: []any{
+ &mcp.TextResourceContents{
+ ResourceContents: mcp.ResourceContents{
+ URI: req.URI,
+ MIMEType: "text/plain",
+ },
+ Text: content,
+ },
+ },
+ }, nil
+}
+
+mcp.AddResource(server,
+ &mcp.Resource{
+ URI: "file:///data/example.txt",
+ Name: "Example Data",
+ Description: "Example resource data",
+ MIMEType: "text/plain",
+ },
+ GetResource,
+)
+```
+
+## Adding Prompts
+
+Use `mcp.AddPrompt` for reusable prompt templates:
+
+```go
+type PromptInput struct {
+ Topic string `json:"topic" jsonschema:"the topic to analyze"`
+}
+
+func AnalyzePrompt(ctx context.Context, req *mcp.GetPromptRequest, input PromptInput) (
+ *mcp.GetPromptResult,
+ error,
+) {
+ return &mcp.GetPromptResult{
+ Description: "Analyze the given topic",
+ Messages: []mcp.PromptMessage{
+ {
+ Role: mcp.RoleUser,
+ Content: mcp.TextContent{
+ Text: fmt.Sprintf("Analyze this topic: %s", input.Topic),
+ },
+ },
+ },
+ }, nil
+}
+
+mcp.AddPrompt(server,
+ &mcp.Prompt{
+ Name: "analyze",
+ Description: "Analyze a topic",
+ Arguments: []mcp.PromptArgument{
+ {
+ Name: "topic",
+ Description: "The topic to analyze",
+ Required: true,
+ },
+ },
+ },
+ AnalyzePrompt,
+)
+```
+
+## Transport Configuration
+
+### Stdio Transport
+
+For communication over stdin/stdout (most common for desktop integrations):
+
+```go
+if err := server.Run(ctx, &mcp.StdioTransport{}); err != nil {
+ log.Fatal(err)
+}
+```
+
+### HTTP Transport
+
+For HTTP-based communication:
+
+```go
+import "github.com/modelcontextprotocol/go-sdk/mcp"
+
+transport := &mcp.HTTPTransport{
+ Addr: ":8080",
+ // Optional: configure TLS, timeouts, etc.
+}
+
+if err := server.Run(ctx, transport); err != nil {
+ log.Fatal(err)
+}
+```
+
+## Error Handling
+
+Always return proper errors and use context for cancellation:
+
+```go
+func MyTool(ctx context.Context, req *mcp.CallToolRequest, input MyInput) (
+ *mcp.CallToolResult,
+ MyOutput,
+ error,
+) {
+ // Check context cancellation
+ if ctx.Err() != nil {
+ return nil, MyOutput{}, ctx.Err()
+ }
+
+ // Return errors for invalid input
+ if input.Query == "" {
+ return nil, MyOutput{}, fmt.Errorf("query cannot be empty")
+ }
+
+ // Perform operation
+ result, err := performOperation(ctx, input)
+ if err != nil {
+ return nil, MyOutput{}, fmt.Errorf("operation failed: %w", err)
+ }
+
+ return nil, result, nil
+}
+```
+
+## JSON Schema Tags
+
+Use `jsonschema` tags to document your structs for better client integration:
+
+```go
+type Input struct {
+ Name string `json:"name" jsonschema:"required,description=User's name"`
+ Age int `json:"age" jsonschema:"minimum=0,maximum=150"`
+ Email string `json:"email,omitempty" jsonschema:"format=email"`
+ Tags []string `json:"tags,omitempty" jsonschema:"uniqueItems=true"`
+ Active bool `json:"active" jsonschema:"default=true"`
+}
+```
+
+## Context Usage
+
+Always respect context cancellation and deadlines:
+
+```go
+func LongRunningTool(ctx context.Context, req *mcp.CallToolRequest, input Input) (
+ *mcp.CallToolResult,
+ Output,
+ error,
+) {
+ select {
+ case <-ctx.Done():
+ return nil, Output{}, ctx.Err()
+ case result := <-performWork(ctx, input):
+ return nil, result, nil
+ }
+}
+```
+
+## Server Options
+
+Configure server behavior with options:
+
+```go
+options := &mcp.Options{
+ Capabilities: &mcp.ServerCapabilities{
+ Tools: &mcp.ToolsCapability{},
+ Resources: &mcp.ResourcesCapability{
+ Subscribe: true, // Enable resource subscriptions
+ },
+ Prompts: &mcp.PromptsCapability{},
+ },
+}
+
+server := mcp.NewServer(
+ &mcp.Implementation{Name: "my-server", Version: "v1.0.0"},
+ options,
+)
+```
+
+## Testing
+
+Test your MCP tools using standard Go testing patterns:
+
+```go
+func TestSearchTool(t *testing.T) {
+ ctx := context.Background()
+ input := ToolInput{Query: "test", Limit: 10}
+
+ result, output, err := SearchTool(ctx, nil, input)
+ if err != nil {
+ t.Fatalf("SearchTool failed: %v", err)
+ }
+
+ if len(output.Results) == 0 {
+ t.Error("Expected results, got none")
+ }
+}
+```
+
+## Module Setup
+
+Initialize your Go module properly:
+
+```bash
+go mod init github.com/yourusername/yourserver
+go get github.com/modelcontextprotocol/go-sdk@latest
+```
+
+Your `go.mod` should include:
+
+```go
+module github.com/yourusername/yourserver
+
+go 1.23
+
+require github.com/modelcontextprotocol/go-sdk v1.0.0
+```
+
+## Common Patterns
+
+### Logging
+
+Use structured logging:
+
+```go
+import "log/slog"
+
+logger := slog.Default()
+logger.Info("tool called", "name", req.Params.Name, "args", req.Params.Arguments)
+```
+
+### Configuration
+
+Use environment variables or config files:
+
+```go
+type Config struct {
+ ServerName string
+ Version string
+ Port int
+}
+
+func LoadConfig() *Config {
+ return &Config{
+ ServerName: getEnv("SERVER_NAME", "my-server"),
+ Version: getEnv("VERSION", "v1.0.0"),
+ Port: getEnvInt("PORT", 8080),
+ }
+}
+```
+
+### Graceful Shutdown
+
+Handle shutdown signals properly:
+
+```go
+ctx, cancel := context.WithCancel(context.Background())
+defer cancel()
+
+sigCh := make(chan os.Signal, 1)
+signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
+
+go func() {
+ <-sigCh
+ cancel()
+}()
+
+if err := server.Run(ctx, transport); err != nil {
+ log.Fatal(err)
+}
+```
diff --git a/prompts/go-mcp-server-generator.prompt.md b/prompts/go-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..55832d2
--- /dev/null
+++ b/prompts/go-mcp-server-generator.prompt.md
@@ -0,0 +1,334 @@
+---
+mode: agent
+description: 'Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk.'
+---
+
+# Go MCP Server Project Generator
+
+Generate a complete, production-ready Model Context Protocol (MCP) server project in Go.
+
+## Project Requirements
+
+You will create a Go MCP server with:
+
+1. **Project Structure**: Proper Go module layout
+2. **Dependencies**: Official MCP SDK and necessary packages
+3. **Server Setup**: Configured MCP server with transports
+4. **Tools**: At least 2-3 useful tools with typed inputs/outputs
+5. **Error Handling**: Proper error handling and context usage
+6. **Documentation**: README with setup and usage instructions
+7. **Testing**: Basic test structure
+
+## Template Structure
+
+```
+myserver/
+├── go.mod
+├── go.sum
+├── main.go
+├── tools/
+│ ├── tool1.go
+│ └── tool2.go
+├── resources/
+│ └── resource1.go
+├── config/
+│ └── config.go
+├── README.md
+└── main_test.go
+```
+
+## go.mod Template
+
+```go
+module github.com/yourusername/{{PROJECT_NAME}}
+
+go 1.23
+
+require (
+ github.com/modelcontextprotocol/go-sdk v1.0.0
+)
+```
+
+## main.go Template
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+ "os"
+ "os/signal"
+ "syscall"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+ "github.com/yourusername/{{PROJECT_NAME}}/config"
+ "github.com/yourusername/{{PROJECT_NAME}}/tools"
+)
+
+func main() {
+ cfg := config.Load()
+
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ // Handle graceful shutdown
+ sigCh := make(chan os.Signal, 1)
+ signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
+ go func() {
+ <-sigCh
+ log.Println("Shutting down...")
+ cancel()
+ }()
+
+ // Create server
+ server := mcp.NewServer(
+ &mcp.Implementation{
+ Name: cfg.ServerName,
+ Version: cfg.Version,
+ },
+ &mcp.Options{
+ Capabilities: &mcp.ServerCapabilities{
+ Tools: &mcp.ToolsCapability{},
+ Resources: &mcp.ResourcesCapability{},
+ Prompts: &mcp.PromptsCapability{},
+ },
+ },
+ )
+
+ // Register tools
+ tools.RegisterTools(server)
+
+ // Run server
+ transport := &mcp.StdioTransport{}
+ if err := server.Run(ctx, transport); err != nil {
+ log.Fatalf("Server error: %v", err)
+ }
+}
+```
+
+## tools/tool1.go Template
+
+```go
+package tools
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type Tool1Input struct {
+ Param1 string `json:"param1" jsonschema:"required,description=First parameter"`
+ Param2 int `json:"param2,omitempty" jsonschema:"description=Optional second parameter"`
+}
+
+type Tool1Output struct {
+ Result string `json:"result" jsonschema:"description=The result of the operation"`
+ Status string `json:"status" jsonschema:"description=Operation status"`
+}
+
+func Tool1Handler(ctx context.Context, req *mcp.CallToolRequest, input Tool1Input) (
+ *mcp.CallToolResult,
+ Tool1Output,
+ error,
+) {
+ // Validate input
+ if input.Param1 == "" {
+ return nil, Tool1Output{}, fmt.Errorf("param1 is required")
+ }
+
+ // Check context
+ if ctx.Err() != nil {
+ return nil, Tool1Output{}, ctx.Err()
+ }
+
+ // Perform operation
+ result := fmt.Sprintf("Processed: %s", input.Param1)
+
+ return nil, Tool1Output{
+ Result: result,
+ Status: "success",
+ }, nil
+}
+
+func RegisterTool1(server *mcp.Server) {
+ mcp.AddTool(server,
+ &mcp.Tool{
+ Name: "tool1",
+ Description: "Description of what tool1 does",
+ },
+ Tool1Handler,
+ )
+}
+```
+
+## tools/registry.go Template
+
+```go
+package tools
+
+import "github.com/modelcontextprotocol/go-sdk/mcp"
+
+func RegisterTools(server *mcp.Server) {
+ RegisterTool1(server)
+ RegisterTool2(server)
+ // Register additional tools here
+}
+```
+
+## config/config.go Template
+
+```go
+package config
+
+import "os"
+
+type Config struct {
+ ServerName string
+ Version string
+ LogLevel string
+}
+
+func Load() *Config {
+ return &Config{
+ ServerName: getEnv("SERVER_NAME", "{{PROJECT_NAME}}"),
+ Version: getEnv("VERSION", "v1.0.0"),
+ LogLevel: getEnv("LOG_LEVEL", "info"),
+ }
+}
+
+func getEnv(key, defaultValue string) string {
+ if value := os.Getenv(key); value != "" {
+ return value
+ }
+ return defaultValue
+}
+```
+
+## main_test.go Template
+
+```go
+package main
+
+import (
+ "context"
+ "testing"
+
+ "github.com/yourusername/{{PROJECT_NAME}}/tools"
+)
+
+func TestTool1Handler(t *testing.T) {
+ ctx := context.Background()
+ input := tools.Tool1Input{
+ Param1: "test",
+ Param2: 42,
+ }
+
+ result, output, err := tools.Tool1Handler(ctx, nil, input)
+ if err != nil {
+ t.Fatalf("Tool1Handler failed: %v", err)
+ }
+
+ if output.Status != "success" {
+ t.Errorf("Expected status 'success', got '%s'", output.Status)
+ }
+
+ if result != nil {
+ t.Error("Expected result to be nil")
+ }
+}
+```
+
+## README.md Template
+
+```markdown
+# {{PROJECT_NAME}}
+
+A Model Context Protocol (MCP) server built with Go.
+
+## Description
+
+{{PROJECT_DESCRIPTION}}
+
+## Installation
+
+\`\`\`bash
+go mod download
+go build -o {{PROJECT_NAME}}
+\`\`\`
+
+## Usage
+
+Run the server with stdio transport:
+
+\`\`\`bash
+./{{PROJECT_NAME}}
+\`\`\`
+
+## Configuration
+
+Configure via environment variables:
+
+- `SERVER_NAME`: Server name (default: "{{PROJECT_NAME}}")
+- `VERSION`: Server version (default: "v1.0.0")
+- `LOG_LEVEL`: Logging level (default: "info")
+
+## Available Tools
+
+### tool1
+{{TOOL1_DESCRIPTION}}
+
+**Input:**
+- `param1` (string, required): First parameter
+- `param2` (int, optional): Second parameter
+
+**Output:**
+- `result` (string): Operation result
+- `status` (string): Status of the operation
+
+## Development
+
+Run tests:
+
+\`\`\`bash
+go test ./...
+\`\`\`
+
+Build:
+
+\`\`\`bash
+go build -o {{PROJECT_NAME}}
+\`\`\`
+
+## License
+
+MIT
+```
+
+## Generation Instructions
+
+When generating a Go MCP server:
+
+1. **Initialize Module**: Create `go.mod` with proper module path
+2. **Structure**: Follow the template directory structure
+3. **Type Safety**: Use structs with JSON schema tags for all inputs/outputs
+4. **Error Handling**: Validate inputs, check context, wrap errors
+5. **Documentation**: Add clear descriptions and examples
+6. **Testing**: Include at least one test per tool
+7. **Configuration**: Use environment variables for config
+8. **Logging**: Use structured logging (log/slog)
+9. **Graceful Shutdown**: Handle signals properly
+10. **Transport**: Default to stdio, document alternatives
+
+## Best Practices
+
+- Keep tools focused and single-purpose
+- Use descriptive names for types and functions
+- Include JSON schema documentation in struct tags
+- Always respect context cancellation
+- Return descriptive errors
+- Keep main.go minimal, logic in packages
+- Write tests for tool handlers
+- Document all exported functions
From f10bc70ce51be683d3fc17b7683aafe9c07a2185 Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:03:59 -0400
Subject: [PATCH 5/8] Add Kotlin MCP Server Development collection (#327)
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/kotlin-mcp-expert.chatmode.md | 181 +++++++
.../kotlin-mcp-development.collection.yml | 35 ++
collections/kotlin-mcp-development.md | 41 ++
.../kotlin-mcp-server.instructions.md | 481 ++++++++++++++++++
prompts/kotlin-mcp-server-generator.prompt.md | 449 ++++++++++++++++
9 files changed, 1191 insertions(+)
create mode 100644 chatmodes/kotlin-mcp-expert.chatmode.md
create mode 100644 collections/kotlin-mcp-development.collection.yml
create mode 100644 collections/kotlin-mcp-development.md
create mode 100644 instructions/kotlin-mcp-server.instructions.md
create mode 100644 prompts/kotlin-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index d03ecaf..bebda64 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -46,6 +46,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [High-Level Big Picture Architect (HLBPA)](chatmodes/hlbpa.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fhlbpa.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fhlbpa.chatmode.md) | Your perfect AI chat mode for high-level architectural documentation and review. Perfect for targeted updates after a story or researching that legacy system when nobody remembers what it's supposed to be doing. |
| [Idea Generator mode instructions](chatmodes/simple-app-idea-generator.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsimple-app-idea-generator.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsimple-app-idea-generator.chatmode.md) | Brainstorm and develop new application ideas through fun, interactive questioning until ready for specification creation. |
| [Implementation Plan Generation Mode](chatmodes/implementation-plan.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fimplementation-plan.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fimplementation-plan.chatmode.md) | Generate an implementation plan for new features or refactoring existing code. |
+| [Kotlin MCP Server Development Expert](chatmodes/kotlin-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkotlin-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkotlin-mcp-expert.chatmode.md) | Expert assistant for building Model Context Protocol (MCP) servers in Kotlin using the official SDK. |
| [Kusto Assistant: Azure Data Explorer (Kusto) Engineering Assistant](chatmodes/kusto-assistant.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkusto-assistant.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkusto-assistant.chatmode.md) | Expert KQL assistant for live Azure Data Explorer analysis via Azure MCP server |
| [Mentor mode instructions](chatmodes/mentor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fmentor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fmentor.chatmode.md) | Help mentor the engineer by providing guidance and support. |
| [Meta Agentic Project Scaffold](chatmodes/meta-agentic-project-scaffold.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fmeta-agentic-project-scaffold.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fmeta-agentic-project-scaffold.chatmode.md) | Meta agentic project creation assistant to help users create and manage project workflows effectively. |
diff --git a/README.collections.md b/README.collections.md
index b7a4230..96ae44d 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -24,6 +24,7 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Frontend Web Development](collections/frontend-web-dev.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 11 items | frontend, web, react, typescript, javascript, css, html, angular, vue |
| [Go MCP Server Development](collections/go-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | go, golang, mcp, model-context-protocol, server-development, sdk |
| [Java Development](collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc |
+| [Kotlin MCP Server Development](collections/kotlin-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor |
| [Power Apps Code Apps Development](collections/power-apps-code-apps.md) | Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance for building code-first applications with Power Platform integration. | 3 items | power-apps, power-platform, typescript, react, code-apps, dataverse, connectors |
| [Power BI Development](collections/power-bi-development.md) | Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions. | 14 items | power-bi, dax, data-modeling, performance, visualization, security, devops, business-intelligence |
| [Power Platform MCP Connector Development](collections/power-platform-mcp-connector-development.md) | Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio | 4 items | power-platform, mcp, copilot-studio, custom-connector, json-rpc |
diff --git a/README.instructions.md b/README.instructions.md
index 55b9f8a..553a9a5 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -63,6 +63,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Java Development](instructions/java.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava.instructions.md) | Guidelines for building Java base applications |
| [Joyride User Scripts Project Assistant](instructions/joyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md) | Expert assistance for Joyride User Script projects - REPL-driven ClojureScript and user space automation of VS Code |
| [Joyride Workspace Automation Assistant](instructions/joyride-workspace-automation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-workspace-automation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-workspace-automation.instructions.md) | Expert assistance for Joyride Workspace automation - REPL-driven and user space ClojureScript automation within specific VS Code workspaces |
+| [Kotlin MCP Server Development Guidelines](instructions/kotlin-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkotlin-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkotlin-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. |
| [Kubernetes Deployment Best Practices](instructions/kubernetes-deployment-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkubernetes-deployment-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkubernetes-deployment-best-practices.instructions.md) | Comprehensive best practices for deploying and managing applications on Kubernetes. Covers Pods, Deployments, Services, Ingress, ConfigMaps, Secrets, health checks, resource limits, scaling, and security contexts. |
| [LangChain Python Instructions](instructions/langchain-python.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Flangchain-python.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Flangchain-python.instructions.md) | Instructions for using LangChain with Python |
| [Markdown](instructions/markdown.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmarkdown.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmarkdown.instructions.md) | Documentation and content creation standards |
diff --git a/README.prompts.md b/README.prompts.md
index 1a7bcb6..b16f457 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -68,6 +68,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Java Documentation (Javadoc) Best Practices](prompts/java-docs.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. |
| [Javascript Typescript Jest](prompts/javascript-typescript-jest.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. |
| [JUnit 5+ Best Practices](prompts/java-junit.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md) | Get best practices for JUnit 5 unit testing, including data-driven tests |
+| [Kotlin MCP Server Project Generator](prompts/kotlin-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md) | Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library. |
| [Memory Keeper](prompts/remember.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md) | Transforms lessons learned into domain-organized memory instructions (global or workspace). Syntax: `/remember [>domain [scope]] lesson clue` where scope is `global` (default), `user`, `workspace`, or `ws`. |
| [Memory Merger](prompts/memory-merger.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmemory-merger.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmemory-merger.prompt.md) | Merges mature lessons from a domain memory file into its instruction file. Syntax: `/memory-merger >domain [scope]` where scope is `global` (default), `user`, `workspace`, or `ws`. |
| [Microsoft 365 Declarative Agents Development Kit](prompts/declarative-agents.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdeclarative-agents.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdeclarative-agents.prompt.md) | Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration |
diff --git a/chatmodes/kotlin-mcp-expert.chatmode.md b/chatmodes/kotlin-mcp-expert.chatmode.md
new file mode 100644
index 0000000..34874b5
--- /dev/null
+++ b/chatmodes/kotlin-mcp-expert.chatmode.md
@@ -0,0 +1,181 @@
+---
+model: GPT-4.1
+description: 'Expert assistant for building Model Context Protocol (MCP) servers in Kotlin using the official SDK.'
+---
+
+# Kotlin MCP Server Development Expert
+
+You are an expert Kotlin developer specializing in building Model Context Protocol (MCP) servers using the official `io.modelcontextprotocol:kotlin-sdk` library.
+
+## Your Expertise
+
+- **Kotlin Programming**: Deep knowledge of Kotlin idioms, coroutines, and language features
+- **MCP Protocol**: Complete understanding of the Model Context Protocol specification
+- **Official Kotlin SDK**: Mastery of `io.modelcontextprotocol:kotlin-sdk` package
+- **Kotlin Multiplatform**: Experience with JVM, Wasm, and native targets
+- **Coroutines**: Expert-level understanding of kotlinx.coroutines and suspending functions
+- **Ktor Framework**: Configuration of HTTP/SSE transports with Ktor
+- **kotlinx.serialization**: JSON schema creation and type-safe serialization
+- **Gradle**: Build configuration and dependency management
+- **Testing**: Kotlin test utilities and coroutine testing patterns
+
+## Your Approach
+
+When helping with Kotlin MCP development:
+
+1. **Idiomatic Kotlin**: Use Kotlin language features (data classes, sealed classes, extension functions)
+2. **Coroutine Patterns**: Emphasize suspending functions and structured concurrency
+3. **Type Safety**: Leverage Kotlin's type system and null safety
+4. **JSON Schemas**: Use `buildJsonObject` for clear schema definitions
+5. **Error Handling**: Use Kotlin exceptions and Result types appropriately
+6. **Testing**: Encourage coroutine testing with `runTest`
+7. **Documentation**: Recommend KDoc comments for public APIs
+8. **Multiplatform**: Consider multiplatform compatibility when relevant
+9. **Dependency Injection**: Suggest constructor injection for testability
+10. **Immutability**: Prefer immutable data structures (val, data classes)
+
+## Key SDK Components
+
+### Server Creation
+- `Server()` with `Implementation` and `ServerOptions`
+- `ServerCapabilities` for feature declaration
+- Transport selection (StdioServerTransport, SSE with Ktor)
+
+### Tool Registration
+- `server.addTool()` with name, description, and inputSchema
+- Suspending lambda for tool handler
+- `CallToolRequest` and `CallToolResult` types
+
+### Resource Registration
+- `server.addResource()` with URI and metadata
+- `ReadResourceRequest` and `ReadResourceResult`
+- Resource update notifications with `notifyResourceListChanged()`
+
+### Prompt Registration
+- `server.addPrompt()` with arguments
+- `GetPromptRequest` and `GetPromptResult`
+- `PromptMessage` with Role and content
+
+### JSON Schema Building
+- `buildJsonObject` DSL for schemas
+- `putJsonObject` and `putJsonArray` for nested structures
+- Type definitions and validation rules
+
+## Response Style
+
+- Provide complete, runnable Kotlin code examples
+- Use suspending functions for async operations
+- Include necessary imports
+- Use meaningful variable names
+- Add KDoc comments for complex logic
+- Show proper coroutine scope management
+- Demonstrate error handling patterns
+- Include JSON schema examples with `buildJsonObject`
+- Reference kotlinx.serialization when appropriate
+- Suggest testing patterns with coroutine test utilities
+
+## Common Tasks
+
+### Creating Tools
+Show complete tool implementation with:
+- JSON schema using `buildJsonObject`
+- Suspending handler function
+- Parameter extraction and validation
+- Error handling with try/catch
+- Type-safe result construction
+
+### Transport Setup
+Demonstrate:
+- Stdio transport for CLI integration
+- SSE transport with Ktor for web services
+- Proper coroutine scope management
+- Graceful shutdown patterns
+
+### Testing
+Provide:
+- `runTest` for coroutine testing
+- Tool invocation examples
+- Assertion patterns
+- Mock patterns when needed
+
+### Project Structure
+Recommend:
+- Gradle Kotlin DSL configuration
+- Package organization
+- Separation of concerns
+- Dependency injection patterns
+
+### Coroutine Patterns
+Show:
+- Proper use of `suspend` modifier
+- Structured concurrency with `coroutineScope`
+- Parallel operations with `async`/`await`
+- Error propagation in coroutines
+
+## Example Interaction Pattern
+
+When a user asks to create a tool:
+
+1. Define JSON schema with `buildJsonObject`
+2. Implement suspending handler function
+3. Show parameter extraction and validation
+4. Demonstrate error handling
+5. Include tool registration
+6. Provide testing example
+7. Suggest improvements or alternatives
+
+## Kotlin-Specific Features
+
+### Data Classes
+Use for structured data:
+```kotlin
+data class ToolInput(
+ val query: String,
+ val limit: Int = 10
+)
+```
+
+### Sealed Classes
+Use for result types:
+```kotlin
+sealed class ToolResult {
+ data class Success(val data: String) : ToolResult()
+ data class Error(val message: String) : ToolResult()
+}
+```
+
+### Extension Functions
+Organize tool registration:
+```kotlin
+fun Server.registerSearchTools() {
+ addTool("search") { /* ... */ }
+ addTool("filter") { /* ... */ }
+}
+```
+
+### Scope Functions
+Use for configuration:
+```kotlin
+Server(serverInfo, options) {
+ "Description"
+}.apply {
+ registerTools()
+ registerResources()
+}
+```
+
+### Delegation
+Use for lazy initialization:
+```kotlin
+val config by lazy { loadConfig() }
+```
+
+## Multiplatform Considerations
+
+When applicable, mention:
+- Common code in `commonMain`
+- Platform-specific implementations
+- Expect/actual declarations
+- Supported targets (JVM, Wasm, iOS)
+
+Always write idiomatic Kotlin code that follows the official SDK patterns and Kotlin best practices, with proper use of coroutines and type safety.
diff --git a/collections/kotlin-mcp-development.collection.yml b/collections/kotlin-mcp-development.collection.yml
new file mode 100644
index 0000000..66d71df
--- /dev/null
+++ b/collections/kotlin-mcp-development.collection.yml
@@ -0,0 +1,35 @@
+id: kotlin-mcp-development
+name: Kotlin MCP Server Development
+description: Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+tags: [kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor]
+items:
+ - path: instructions/kotlin-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/kotlin-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/kotlin-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in Kotlin.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with Kotlin
+ - Implementing type-safe tools with coroutines and kotlinx.serialization
+ - Setting up stdio or SSE transports with Ktor
+ - Debugging coroutine patterns and JSON schema issues
+ - Learning Kotlin MCP best practices with the official SDK
+ - Building multiplatform MCP servers (JVM, Wasm, iOS)
+
+ To get the best results, consider:
+ - Using the instruction file to set context for Kotlin MCP development
+ - Using the prompt to generate initial project structure with Gradle
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need stdio or SSE/HTTP transport
+ - Providing details about what tools or functionality you need
+ - Mentioning if you need multiplatform support or specific targets
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/kotlin-mcp-development.md b/collections/kotlin-mcp-development.md
new file mode 100644
index 0000000..2949337
--- /dev/null
+++ b/collections/kotlin-mcp-development.md
@@ -0,0 +1,41 @@
+# Kotlin MCP Server Development
+
+Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.
+
+**Tags:** kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [Kotlin MCP Server Development Guidelines](../instructions/kotlin-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkotlin-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkotlin-mcp-server.instructions.md) | Instruction | Best practices and patterns for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. |
+| [Kotlin MCP Server Project Generator](../prompts/kotlin-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md) | Prompt | Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library. |
+| [Kotlin MCP Server Development Expert](../chatmodes/kotlin-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkotlin-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkotlin-mcp-expert.chatmode.md) | Chat Mode | Expert assistant for building Model Context Protocol (MCP) servers in Kotlin using the official SDK. [see usage](#kotlin-mcp-server-development-expert) |
+
+## Collection Usage
+
+### Kotlin MCP Server Development Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in Kotlin.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with Kotlin
+- Implementing type-safe tools with coroutines and kotlinx.serialization
+- Setting up stdio or SSE transports with Ktor
+- Debugging coroutine patterns and JSON schema issues
+- Learning Kotlin MCP best practices with the official SDK
+- Building multiplatform MCP servers (JVM, Wasm, iOS)
+
+To get the best results, consider:
+- Using the instruction file to set context for Kotlin MCP development
+- Using the prompt to generate initial project structure with Gradle
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need stdio or SSE/HTTP transport
+- Providing details about what tools or functionality you need
+- Mentioning if you need multiplatform support or specific targets
+
+---
+
+*This collection includes 3 curated items for kotlin mcp server development.*
\ No newline at end of file
diff --git a/instructions/kotlin-mcp-server.instructions.md b/instructions/kotlin-mcp-server.instructions.md
new file mode 100644
index 0000000..c450165
--- /dev/null
+++ b/instructions/kotlin-mcp-server.instructions.md
@@ -0,0 +1,481 @@
+---
+description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library.'
+applyTo: "**/*.kt, **/*.kts, **/build.gradle.kts, **/settings.gradle.kts"
+---
+
+# Kotlin MCP Server Development Guidelines
+
+When building MCP servers in Kotlin, follow these best practices and patterns using the official Kotlin SDK.
+
+## Server Setup
+
+Create an MCP server using the `Server` class:
+
+```kotlin
+import io.modelcontextprotocol.kotlin.sdk.server.Server
+import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
+import io.modelcontextprotocol.kotlin.sdk.Implementation
+import io.modelcontextprotocol.kotlin.sdk.ServerCapabilities
+
+val server = Server(
+ serverInfo = Implementation(
+ name = "my-server",
+ version = "1.0.0"
+ ),
+ options = ServerOptions(
+ capabilities = ServerCapabilities(
+ tools = ServerCapabilities.Tools(),
+ resources = ServerCapabilities.Resources(
+ subscribe = true,
+ listChanged = true
+ ),
+ prompts = ServerCapabilities.Prompts(listChanged = true)
+ )
+ )
+) {
+ "Server description goes here"
+}
+```
+
+## Adding Tools
+
+Use `server.addTool()` to register tools with typed request/response handling:
+
+```kotlin
+import io.modelcontextprotocol.kotlin.sdk.CallToolRequest
+import io.modelcontextprotocol.kotlin.sdk.CallToolResult
+import io.modelcontextprotocol.kotlin.sdk.TextContent
+
+server.addTool(
+ name = "search",
+ description = "Search for information",
+ inputSchema = buildJsonObject {
+ put("type", "object")
+ putJsonObject("properties") {
+ putJsonObject("query") {
+ put("type", "string")
+ put("description", "The search query")
+ }
+ putJsonObject("limit") {
+ put("type", "integer")
+ put("description", "Maximum results to return")
+ }
+ }
+ putJsonArray("required") {
+ add("query")
+ }
+ }
+) { request: CallToolRequest ->
+ val query = request.params.arguments["query"] as? String
+ ?: throw IllegalArgumentException("query is required")
+ val limit = (request.params.arguments["limit"] as? Number)?.toInt() ?: 10
+
+ // Perform search
+ val results = performSearch(query, limit)
+
+ CallToolResult(
+ content = listOf(
+ TextContent(
+ text = results.joinToString("\n")
+ )
+ )
+ )
+}
+```
+
+## Adding Resources
+
+Use `server.addResource()` to provide accessible data:
+
+```kotlin
+import io.modelcontextprotocol.kotlin.sdk.ReadResourceRequest
+import io.modelcontextprotocol.kotlin.sdk.ReadResourceResult
+import io.modelcontextprotocol.kotlin.sdk.TextResourceContents
+
+server.addResource(
+ uri = "file:///data/example.txt",
+ name = "Example Data",
+ description = "Example resource data",
+ mimeType = "text/plain"
+) { request: ReadResourceRequest ->
+ val content = loadResourceContent(request.uri)
+
+ ReadResourceResult(
+ contents = listOf(
+ TextResourceContents(
+ text = content,
+ uri = request.uri,
+ mimeType = "text/plain"
+ )
+ )
+ )
+}
+```
+
+## Adding Prompts
+
+Use `server.addPrompt()` for reusable prompt templates:
+
+```kotlin
+import io.modelcontextprotocol.kotlin.sdk.GetPromptRequest
+import io.modelcontextprotocol.kotlin.sdk.GetPromptResult
+import io.modelcontextprotocol.kotlin.sdk.PromptMessage
+import io.modelcontextprotocol.kotlin.sdk.Role
+
+server.addPrompt(
+ name = "analyze",
+ description = "Analyze a topic",
+ arguments = listOf(
+ PromptArgument(
+ name = "topic",
+ description = "The topic to analyze",
+ required = true
+ )
+ )
+) { request: GetPromptRequest ->
+ val topic = request.params.arguments?.get("topic") as? String
+ ?: throw IllegalArgumentException("topic is required")
+
+ GetPromptResult(
+ description = "Analyze the given topic",
+ messages = listOf(
+ PromptMessage(
+ role = Role.User,
+ content = TextContent(
+ text = "Analyze this topic: $topic"
+ )
+ )
+ )
+ )
+}
+```
+
+## Transport Configuration
+
+### Stdio Transport
+
+For communication over stdin/stdout:
+
+```kotlin
+import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
+
+suspend fun main() {
+ val transport = StdioServerTransport()
+ server.connect(transport)
+}
+```
+
+### SSE Transport with Ktor
+
+For HTTP-based communication using Server-Sent Events:
+
+```kotlin
+import io.ktor.server.application.*
+import io.ktor.server.engine.*
+import io.ktor.server.netty.*
+import io.modelcontextprotocol.kotlin.sdk.server.mcp
+
+fun main() {
+ embeddedServer(Netty, port = 8080) {
+ mcp {
+ Server(
+ serverInfo = Implementation(
+ name = "sse-server",
+ version = "1.0.0"
+ ),
+ options = ServerOptions(
+ capabilities = ServerCapabilities(
+ tools = ServerCapabilities.Tools()
+ )
+ )
+ ) {
+ "SSE-based MCP server"
+ }
+ }
+ }.start(wait = true)
+}
+```
+
+## Coroutine Usage
+
+All MCP operations are suspending functions. Use Kotlin coroutines properly:
+
+```kotlin
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.async
+
+server.addTool(
+ name = "parallel-search",
+ description = "Search multiple sources in parallel"
+) { request ->
+ coroutineScope {
+ val source1 = async { searchSource1(query) }
+ val source2 = async { searchSource2(query) }
+
+ val results = source1.await() + source2.await()
+
+ CallToolResult(
+ content = listOf(TextContent(text = results.joinToString("\n")))
+ )
+ }
+}
+```
+
+## Error Handling
+
+Use Kotlin's exception handling and provide meaningful error messages:
+
+```kotlin
+server.addTool(
+ name = "validate-input",
+ description = "Process validated input"
+) { request ->
+ try {
+ val input = request.params.arguments["input"] as? String
+ ?: throw IllegalArgumentException("input is required")
+
+ require(input.isNotBlank()) { "input cannot be blank" }
+
+ val result = processInput(input)
+
+ CallToolResult(
+ content = listOf(TextContent(text = result))
+ )
+ } catch (e: IllegalArgumentException) {
+ CallToolResult(
+ isError = true,
+ content = listOf(TextContent(text = "Validation error: ${e.message}"))
+ )
+ }
+}
+```
+
+## JSON Schema with kotlinx.serialization
+
+Use kotlinx.serialization for type-safe JSON schemas:
+
+```kotlin
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.*
+
+@Serializable
+data class SearchInput(
+ val query: String,
+ val limit: Int = 10,
+ val filters: List = emptyList()
+)
+
+fun createToolSchema(): JsonObject = buildJsonObject {
+ put("type", "object")
+ putJsonObject("properties") {
+ putJsonObject("query") {
+ put("type", "string")
+ put("description", "Search query")
+ }
+ putJsonObject("limit") {
+ put("type", "integer")
+ put("default", 10)
+ }
+ putJsonObject("filters") {
+ put("type", "array")
+ putJsonObject("items") {
+ put("type", "string")
+ }
+ }
+ }
+ putJsonArray("required") {
+ add("query")
+ }
+}
+```
+
+## Gradle Configuration
+
+Set up your `build.gradle.kts` properly:
+
+```kotlin
+plugins {
+ kotlin("jvm") version "2.1.0"
+ kotlin("plugin.serialization") version "2.1.0"
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
+
+ // For client transport
+ implementation("io.ktor:ktor-client-cio:3.0.0")
+
+ // For server transport
+ implementation("io.ktor:ktor-server-netty:3.0.0")
+
+ // For JSON serialization
+ implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
+
+ // For coroutines
+ implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+}
+```
+
+## Multiplatform Support
+
+The Kotlin SDK supports Kotlin Multiplatform (JVM, Wasm, iOS):
+
+```kotlin
+kotlin {
+ jvm()
+ js(IR) {
+ browser()
+ nodejs()
+ }
+ wasmJs()
+
+ sourceSets {
+ commonMain.dependencies {
+ implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
+ implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+ }
+ }
+}
+```
+
+## Resource Lifecycle
+
+Handle resource updates and subscriptions:
+
+```kotlin
+server.addResource(
+ uri = "file:///dynamic/data",
+ name = "Dynamic Data",
+ description = "Frequently updated data",
+ mimeType = "application/json"
+) { request ->
+ // Provide current state
+ ReadResourceResult(
+ contents = listOf(
+ TextResourceContents(
+ text = getCurrentData(),
+ uri = request.uri,
+ mimeType = "application/json"
+ )
+ )
+ )
+}
+
+// Notify clients when resource changes
+server.notifyResourceListChanged()
+```
+
+## Testing
+
+Test your MCP tools using Kotlin coroutines test utilities:
+
+```kotlin
+import kotlinx.coroutines.test.runTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class ServerTest {
+ @Test
+ fun testSearchTool() = runTest {
+ val server = createTestServer()
+
+ val request = CallToolRequest(
+ params = CallToolParams(
+ name = "search",
+ arguments = mapOf("query" to "test", "limit" to 5)
+ )
+ )
+
+ val result = server.callTool(request)
+
+ assertEquals(false, result.isError)
+ assert(result.content.isNotEmpty())
+ }
+}
+```
+
+## Common Patterns
+
+### Logging
+
+Use structured logging with a Kotlin logging library:
+
+```kotlin
+import io.github.oshai.kotlinlogging.KotlinLogging
+
+private val logger = KotlinLogging.logger {}
+
+server.addTool(
+ name = "logged-operation",
+ description = "Operation with logging"
+) { request ->
+ logger.info { "Tool called with args: ${request.params.arguments}" }
+
+ try {
+ val result = performOperation(request)
+ logger.info { "Operation succeeded" }
+ result
+ } catch (e: Exception) {
+ logger.error(e) { "Operation failed" }
+ throw e
+ }
+}
+```
+
+### Configuration
+
+Use data classes for configuration:
+
+```kotlin
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class ServerConfig(
+ val name: String = "my-server",
+ val version: String = "1.0.0",
+ val port: Int = 8080,
+ val enableTools: Boolean = true
+)
+
+fun loadConfig(): ServerConfig {
+ // Load from environment or config file
+ return ServerConfig(
+ name = System.getenv("SERVER_NAME") ?: "my-server",
+ version = System.getenv("VERSION") ?: "1.0.0"
+ )
+}
+```
+
+### Dependency Injection
+
+Use constructor injection for testability:
+
+```kotlin
+class MyServer(
+ private val dataService: DataService,
+ private val config: ServerConfig
+) {
+ fun createServer() = Server(
+ serverInfo = Implementation(
+ name = config.name,
+ version = config.version
+ )
+ ) {
+ "MCP Server with DI"
+ }.apply {
+ addTool(
+ name = "fetch-data",
+ description = "Fetch data using injected service"
+ ) { request ->
+ val data = dataService.fetchData()
+ CallToolResult(
+ content = listOf(TextContent(text = data))
+ )
+ }
+ }
+}
+```
diff --git a/prompts/kotlin-mcp-server-generator.prompt.md b/prompts/kotlin-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..a009901
--- /dev/null
+++ b/prompts/kotlin-mcp-server-generator.prompt.md
@@ -0,0 +1,449 @@
+---
+mode: agent
+description: 'Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library.'
+---
+
+# Kotlin MCP Server Project Generator
+
+Generate a complete, production-ready Model Context Protocol (MCP) server project in Kotlin.
+
+## Project Requirements
+
+You will create a Kotlin MCP server with:
+
+1. **Project Structure**: Gradle-based Kotlin project layout
+2. **Dependencies**: Official MCP SDK, Ktor, and kotlinx libraries
+3. **Server Setup**: Configured MCP server with transports
+4. **Tools**: At least 2-3 useful tools with typed inputs/outputs
+5. **Error Handling**: Proper exception handling and validation
+6. **Documentation**: README with setup and usage instructions
+7. **Testing**: Basic test structure with coroutines
+
+## Template Structure
+
+```
+myserver/
+├── build.gradle.kts
+├── settings.gradle.kts
+├── gradle.properties
+├── src/
+│ ├── main/
+│ │ └── kotlin/
+│ │ └── com/example/myserver/
+│ │ ├── Main.kt
+│ │ ├── Server.kt
+│ │ ├── config/
+│ │ │ └── Config.kt
+│ │ └── tools/
+│ │ ├── Tool1.kt
+│ │ └── Tool2.kt
+│ └── test/
+│ └── kotlin/
+│ └── com/example/myserver/
+│ └── ServerTest.kt
+└── README.md
+```
+
+## build.gradle.kts Template
+
+```kotlin
+plugins {
+ kotlin("jvm") version "2.1.0"
+ kotlin("plugin.serialization") version "2.1.0"
+ application
+}
+
+group = "com.example"
+version = "1.0.0"
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
+
+ // Ktor for transports
+ implementation("io.ktor:ktor-server-netty:3.0.0")
+ implementation("io.ktor:ktor-client-cio:3.0.0")
+
+ // Serialization
+ implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
+
+ // Coroutines
+ implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+
+ // Logging
+ implementation("io.github.oshai:kotlin-logging-jvm:7.0.0")
+ implementation("ch.qos.logback:logback-classic:1.5.12")
+
+ // Testing
+ testImplementation(kotlin("test"))
+ testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
+}
+
+application {
+ mainClass.set("com.example.myserver.MainKt")
+}
+
+tasks.test {
+ useJUnitPlatform()
+}
+
+kotlin {
+ jvmToolchain(17)
+}
+```
+
+## settings.gradle.kts Template
+
+```kotlin
+rootProject.name = "{{PROJECT_NAME}}"
+```
+
+## Main.kt Template
+
+```kotlin
+package com.example.myserver
+
+import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
+import kotlinx.coroutines.runBlocking
+import io.github.oshai.kotlinlogging.KotlinLogging
+
+private val logger = KotlinLogging.logger {}
+
+fun main() = runBlocking {
+ logger.info { "Starting MCP server..." }
+
+ val config = loadConfig()
+ val server = createServer(config)
+
+ // Use stdio transport
+ val transport = StdioServerTransport()
+
+ logger.info { "Server '${config.name}' v${config.version} ready" }
+ server.connect(transport)
+}
+```
+
+## Server.kt Template
+
+```kotlin
+package com.example.myserver
+
+import io.modelcontextprotocol.kotlin.sdk.server.Server
+import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
+import io.modelcontextprotocol.kotlin.sdk.Implementation
+import io.modelcontextprotocol.kotlin.sdk.ServerCapabilities
+import com.example.myserver.tools.registerTools
+
+fun createServer(config: Config): Server {
+ val server = Server(
+ serverInfo = Implementation(
+ name = config.name,
+ version = config.version
+ ),
+ options = ServerOptions(
+ capabilities = ServerCapabilities(
+ tools = ServerCapabilities.Tools(),
+ resources = ServerCapabilities.Resources(
+ subscribe = true,
+ listChanged = true
+ ),
+ prompts = ServerCapabilities.Prompts(listChanged = true)
+ )
+ )
+ ) {
+ config.description
+ }
+
+ // Register all tools
+ server.registerTools()
+
+ return server
+}
+```
+
+## Config.kt Template
+
+```kotlin
+package com.example.myserver.config
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class Config(
+ val name: String = "{{PROJECT_NAME}}",
+ val version: String = "1.0.0",
+ val description: String = "{{PROJECT_DESCRIPTION}}"
+)
+
+fun loadConfig(): Config {
+ return Config(
+ name = System.getenv("SERVER_NAME") ?: "{{PROJECT_NAME}}",
+ version = System.getenv("VERSION") ?: "1.0.0",
+ description = System.getenv("DESCRIPTION") ?: "{{PROJECT_DESCRIPTION}}"
+ )
+}
+```
+
+## Tool1.kt Template
+
+```kotlin
+package com.example.myserver.tools
+
+import io.modelcontextprotocol.kotlin.sdk.server.Server
+import io.modelcontextprotocol.kotlin.sdk.CallToolRequest
+import io.modelcontextprotocol.kotlin.sdk.CallToolResult
+import io.modelcontextprotocol.kotlin.sdk.TextContent
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import kotlinx.serialization.json.putJsonObject
+import kotlinx.serialization.json.putJsonArray
+
+fun Server.registerTool1() {
+ addTool(
+ name = "tool1",
+ description = "Description of what tool1 does",
+ inputSchema = buildJsonObject {
+ put("type", "object")
+ putJsonObject("properties") {
+ putJsonObject("param1") {
+ put("type", "string")
+ put("description", "First parameter")
+ }
+ putJsonObject("param2") {
+ put("type", "integer")
+ put("description", "Optional second parameter")
+ }
+ }
+ putJsonArray("required") {
+ add("param1")
+ }
+ }
+ ) { request: CallToolRequest ->
+ // Extract and validate parameters
+ val param1 = request.params.arguments["param1"] as? String
+ ?: throw IllegalArgumentException("param1 is required")
+ val param2 = (request.params.arguments["param2"] as? Number)?.toInt() ?: 0
+
+ // Perform tool logic
+ val result = performTool1Logic(param1, param2)
+
+ CallToolResult(
+ content = listOf(
+ TextContent(text = result)
+ )
+ )
+ }
+}
+
+private fun performTool1Logic(param1: String, param2: Int): String {
+ // Implement tool logic here
+ return "Processed: $param1 with value $param2"
+}
+```
+
+## tools/ToolRegistry.kt Template
+
+```kotlin
+package com.example.myserver.tools
+
+import io.modelcontextprotocol.kotlin.sdk.server.Server
+
+fun Server.registerTools() {
+ registerTool1()
+ registerTool2()
+ // Register additional tools here
+}
+```
+
+## ServerTest.kt Template
+
+```kotlin
+package com.example.myserver
+
+import kotlinx.coroutines.test.runTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+
+class ServerTest {
+
+ @Test
+ fun `test server creation`() = runTest {
+ val config = Config(
+ name = "test-server",
+ version = "1.0.0",
+ description = "Test server"
+ )
+
+ val server = createServer(config)
+
+ assertEquals("test-server", server.serverInfo.name)
+ assertEquals("1.0.0", server.serverInfo.version)
+ }
+
+ @Test
+ fun `test tool1 execution`() = runTest {
+ val config = Config()
+ val server = createServer(config)
+
+ // Test tool execution
+ // Note: You'll need to implement proper testing utilities
+ // for calling tools in the server
+ }
+}
+```
+
+## README.md Template
+
+```markdown
+# {{PROJECT_NAME}}
+
+A Model Context Protocol (MCP) server built with Kotlin.
+
+## Description
+
+{{PROJECT_DESCRIPTION}}
+
+## Requirements
+
+- Java 17 or higher
+- Kotlin 2.1.0
+
+## Installation
+
+Build the project:
+
+\`\`\`bash
+./gradlew build
+\`\`\`
+
+## Usage
+
+Run the server with stdio transport:
+
+\`\`\`bash
+./gradlew run
+\`\`\`
+
+Or build and run the jar:
+
+\`\`\`bash
+./gradlew installDist
+./build/install/{{PROJECT_NAME}}/bin/{{PROJECT_NAME}}
+\`\`\`
+
+## Configuration
+
+Configure via environment variables:
+
+- `SERVER_NAME`: Server name (default: "{{PROJECT_NAME}}")
+- `VERSION`: Server version (default: "1.0.0")
+- `DESCRIPTION`: Server description
+
+## Available Tools
+
+### tool1
+{{TOOL1_DESCRIPTION}}
+
+**Input:**
+- `param1` (string, required): First parameter
+- `param2` (integer, optional): Second parameter
+
+**Output:**
+- Text result of the operation
+
+## Development
+
+Run tests:
+
+\`\`\`bash
+./gradlew test
+\`\`\`
+
+Build:
+
+\`\`\`bash
+./gradlew build
+\`\`\`
+
+Run with auto-reload (development):
+
+\`\`\`bash
+./gradlew run --continuous
+\`\`\`
+
+## Multiplatform
+
+This project uses Kotlin Multiplatform and can target JVM, Wasm, and iOS.
+See `build.gradle.kts` for platform configuration.
+
+## License
+
+MIT
+```
+
+## Generation Instructions
+
+When generating a Kotlin MCP server:
+
+1. **Gradle Setup**: Create proper `build.gradle.kts` with all dependencies
+2. **Package Structure**: Follow Kotlin package conventions
+3. **Type Safety**: Use data classes and kotlinx.serialization
+4. **Coroutines**: All operations should be suspending functions
+5. **Error Handling**: Use Kotlin exceptions and validation
+6. **JSON Schemas**: Use `buildJsonObject` for tool schemas
+7. **Testing**: Include coroutine test utilities
+8. **Logging**: Use kotlin-logging for structured logging
+9. **Configuration**: Use data classes and environment variables
+10. **Documentation**: KDoc comments for public APIs
+
+## Best Practices
+
+- Use suspending functions for all async operations
+- Leverage Kotlin's null safety and type system
+- Use data classes for structured data
+- Apply kotlinx.serialization for JSON handling
+- Use sealed classes for result types
+- Implement proper error handling with Result/Either patterns
+- Write tests using kotlinx-coroutines-test
+- Use dependency injection for testability
+- Follow Kotlin coding conventions
+- Use meaningful names and KDoc comments
+
+## Transport Options
+
+### Stdio Transport
+```kotlin
+val transport = StdioServerTransport()
+server.connect(transport)
+```
+
+### SSE Transport (Ktor)
+```kotlin
+embeddedServer(Netty, port = 8080) {
+ mcp {
+ Server(/*...*/) { "Description" }
+ }
+}.start(wait = true)
+```
+
+## Multiplatform Configuration
+
+For multiplatform projects, add to `build.gradle.kts`:
+
+```kotlin
+kotlin {
+ jvm()
+ js(IR) { nodejs() }
+ wasmJs()
+
+ sourceSets {
+ commonMain.dependencies {
+ implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
+ }
+ }
+}
+```
From 616d8f14a7d3f8ef06ed62f75f7d96451c44ae9a Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:05:21 -0400
Subject: [PATCH 6/8] Add Swift MCP Server Development collection (#328)
- Add Swift MCP server best practices instruction
- Add Swift MCP server project generator prompt
- Add Swift MCP expert chat mode
- Add Swift MCP development collection manifest
- Update category READMEs
Features:
- Server setup with official Swift SDK package
- Tool/resource/prompt handlers with withMethodHandler
- Async/await and actor-based concurrency patterns
- ServiceLifecycle integration for graceful shutdown
- Stdio, HTTP, and network transport support
- JSON schema construction with Value type
- Swift 6.0+ with modern concurrency features
- Platform support: macOS 13+, iOS 16+, Linux
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/swift-mcp-expert.chatmode.md | 240 +++++++
.../swift-mcp-development.collection.yml | 35 +
collections/swift-mcp-development.md | 41 ++
instructions/swift-mcp-server.instructions.md | 498 +++++++++++++
prompts/swift-mcp-server-generator.prompt.md | 669 ++++++++++++++++++
9 files changed, 1487 insertions(+)
create mode 100644 chatmodes/swift-mcp-expert.chatmode.md
create mode 100644 collections/swift-mcp-development.collection.yml
create mode 100644 collections/swift-mcp-development.md
create mode 100644 instructions/swift-mcp-server.instructions.md
create mode 100644 prompts/swift-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index bebda64..097f1e1 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -74,6 +74,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [Semantic Kernel Python mode instructions](chatmodes/semantic-kernel-python.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsemantic-kernel-python.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsemantic-kernel-python.chatmode.md) | Create, update, refactor, explain or work with code using the Python version of Semantic Kernel. |
| [Software Engineer Agent v1](chatmodes/software-engineer-agent-v1.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsoftware-engineer-agent-v1.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsoftware-engineer-agent-v1.chatmode.md) | Expert-level software engineering agent. Deliver production-ready, maintainable code. Execute systematically and specification-driven. Document comprehensively. Operate autonomously and adaptively. |
| [Specification mode instructions](chatmodes/specification.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fspecification.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fspecification.chatmode.md) | Generate or update specification documents for new or existing functionality. |
+| [Swift MCP Expert](chatmodes/swift-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fswift-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fswift-mcp-expert.chatmode.md) | Expert assistance for building Model Context Protocol servers in Swift using modern concurrency features and the official MCP Swift SDK. |
| [Task Planner Instructions](chatmodes/task-planner.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftask-planner.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftask-planner.chatmode.md) | Task planner for creating actionable implementation plans - Brought to you by microsoft/edge-ai |
| [Task Researcher Instructions](chatmodes/task-researcher.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftask-researcher.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftask-researcher.chatmode.md) | Task research specialist for comprehensive project analysis - Brought to you by microsoft/edge-ai |
| [TDD Green Phase - Make Tests Pass Quickly](chatmodes/tdd-green.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftdd-green.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Ftdd-green.chatmode.md) | Implement minimal code to satisfy GitHub issue requirements and make failing tests pass without over-engineering. |
diff --git a/README.collections.md b/README.collections.md
index 96ae44d..1a07ef9 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -31,6 +31,7 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Project Planning & Management](collections/project-planning.md) | Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization for development teams. | 17 items | planning, project-management, epic, feature, implementation, task, architecture, technical-spike |
| [Python MCP Server Development](collections/python-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | python, mcp, model-context-protocol, fastmcp, server-development |
| [Security & Code Quality](collections/security-best-practices.md) | Security frameworks, accessibility guidelines, performance optimization, and code quality best practices for building secure, maintainable, and high-performance applications. | 6 items | security, accessibility, performance, code-quality, owasp, a11y, optimization, best-practices |
+| [Swift MCP Server Development](collections/swift-mcp-development.md) | 'Comprehensive collection for building Model Context Protocol servers in Swift using the official MCP Swift SDK with modern concurrency features.' | 3 items | swift, mcp, model-context-protocol, server-development, sdk, ios, macos, concurrency, actor, async-await |
| [Tasks by microsoft/edge-ai](collections/edge-ai-tasks.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 3 items | architecture, planning, research, tasks, implementation |
| [Technical Spike](collections/technical-spike.md) | Tools for creation, management and research of technical spikes to reduce unknowns and assumptions before proceeding to specification and implementation of solutions. | 2 items | technical-spike, assumption-testing, validation, research |
| [Testing & Test Automation](collections/testing-automation.md) | Comprehensive collection for writing tests, test automation, and test-driven development including unit tests, integration tests, and end-to-end testing strategies. | 11 items | testing, tdd, automation, unit-tests, integration, playwright, jest, nunit |
diff --git a/README.instructions.md b/README.instructions.md
index 553a9a5..1ad3971 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -104,6 +104,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Spring Boot Development](instructions/springboot.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspringboot.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspringboot.instructions.md) | Guidelines for building Spring Boot base applications |
| [SQL Development](instructions/sql-sp-generation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsql-sp-generation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsql-sp-generation.instructions.md) | Guidelines for generating SQL statements and stored procedures |
| [Svelte 5 and SvelteKit Development Instructions](instructions/svelte.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsvelte.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsvelte.instructions.md) | Svelte 5 and SvelteKit development standards and best practices for component-based user interfaces and full-stack applications |
+| [Swift MCP Server Development Guidelines](instructions/swift-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fswift-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fswift-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Swift using the official MCP Swift SDK package. |
| [Taming Copilot](instructions/taming-copilot.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftaming-copilot.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftaming-copilot.instructions.md) | Prevent Copilot from wreaking havoc across your codebase, keeping it under control. |
| [TanStack Start with Shadcn/ui Development Guide](instructions/tanstack-start-shadcn-tailwind.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftanstack-start-shadcn-tailwind.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftanstack-start-shadcn-tailwind.instructions.md) | Guidelines for building TanStack Start applications |
| [Task Plan Implementation Instructions](instructions/task-implementation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftask-implementation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftask-implementation.instructions.md) | Instructions for implementing task plans with progressive tracking and change record - Brought to you by microsoft/edge-ai |
diff --git a/README.prompts.md b/README.prompts.md
index b16f457..5c870da 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -106,6 +106,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Suggest Awesome GitHub Copilot Custom Chat Modes](prompts/suggest-awesome-github-copilot-chatmodes.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-chatmodes.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-chatmodes.prompt.md) | Suggest relevant GitHub Copilot Custom Chat Modes files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom chat modes in this repository. |
| [Suggest Awesome GitHub Copilot Instructions](prompts/suggest-awesome-github-copilot-instructions.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-instructions.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-instructions.prompt.md) | Suggest relevant GitHub Copilot instruction files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing instructions in this repository. |
| [Suggest Awesome GitHub Copilot Prompts](prompts/suggest-awesome-github-copilot-prompts.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-prompts.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-prompts.prompt.md) | Suggest relevant GitHub Copilot prompt files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing prompts in this repository. |
+| [Swift MCP Server Generator](prompts/swift-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fswift-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fswift-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package. |
| [Test Generation with Playwright MCP](prompts/playwright-generate-test.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-generate-test.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-generate-test.prompt.md) | Generate a Playwright test based on a scenario using Playwright MCP |
| [Test Planning & Quality Assurance Prompt](prompts/breakdown-test.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. |
| [TUnit Best Practices](prompts/csharp-tunit.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-tunit.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-tunit.prompt.md) | Get best practices for TUnit unit testing, including data-driven tests |
diff --git a/chatmodes/swift-mcp-expert.chatmode.md b/chatmodes/swift-mcp-expert.chatmode.md
new file mode 100644
index 0000000..4174072
--- /dev/null
+++ b/chatmodes/swift-mcp-expert.chatmode.md
@@ -0,0 +1,240 @@
+---
+description: 'Expert assistance for building Model Context Protocol servers in Swift using modern concurrency features and the official MCP Swift SDK.'
+model: GPT-4.1
+---
+
+# Swift MCP Expert
+
+I'm specialized in helping you build robust, production-ready MCP servers in Swift using the official Swift SDK. I can assist with:
+
+## Core Capabilities
+
+### Server Architecture
+- Setting up Server instances with proper capabilities
+- Configuring transport layers (Stdio, HTTP, Network, InMemory)
+- Implementing graceful shutdown with ServiceLifecycle
+- Actor-based state management for thread safety
+- Async/await patterns and structured concurrency
+
+### Tool Development
+- Creating tool definitions with JSON schemas using Value type
+- Implementing tool handlers with CallTool
+- Parameter validation and error handling
+- Async tool execution patterns
+- Tool list changed notifications
+
+### Resource Management
+- Defining resource URIs and metadata
+- Implementing ReadResource handlers
+- Managing resource subscriptions
+- Resource changed notifications
+- Multi-content responses (text, image, binary)
+
+### Prompt Engineering
+- Creating prompt templates with arguments
+- Implementing GetPrompt handlers
+- Multi-turn conversation patterns
+- Dynamic prompt generation
+- Prompt list changed notifications
+
+### Swift Concurrency
+- Actor isolation for thread-safe state
+- Async/await patterns
+- Task groups and structured concurrency
+- Cancellation handling
+- Error propagation
+
+## Code Assistance
+
+I can help you with:
+
+### Project Setup
+```swift
+// Package.swift with MCP SDK
+.package(
+ url: "https://github.com/modelcontextprotocol/swift-sdk.git",
+ from: "0.10.0"
+)
+```
+
+### Server Creation
+```swift
+let server = Server(
+ name: "MyServer",
+ version: "1.0.0",
+ capabilities: .init(
+ prompts: .init(listChanged: true),
+ resources: .init(subscribe: true, listChanged: true),
+ tools: .init(listChanged: true)
+ )
+)
+```
+
+### Handler Registration
+```swift
+await server.withMethodHandler(CallTool.self) { params in
+ // Tool implementation
+}
+```
+
+### Transport Configuration
+```swift
+let transport = StdioTransport(logger: logger)
+try await server.start(transport: transport)
+```
+
+### ServiceLifecycle Integration
+```swift
+struct MCPService: Service {
+ func run() async throws {
+ try await server.start(transport: transport)
+ }
+
+ func shutdown() async throws {
+ await server.stop()
+ }
+}
+```
+
+## Best Practices
+
+### Actor-Based State
+Always use actors for shared mutable state:
+```swift
+actor ServerState {
+ private var subscriptions: Set = []
+
+ func addSubscription(_ uri: String) {
+ subscriptions.insert(uri)
+ }
+}
+```
+
+### Error Handling
+Use proper Swift error handling:
+```swift
+do {
+ let result = try performOperation()
+ return .init(content: [.text(result)], isError: false)
+} catch let error as MCPError {
+ return .init(content: [.text(error.localizedDescription)], isError: true)
+}
+```
+
+### Logging
+Use structured logging with swift-log:
+```swift
+logger.info("Tool called", metadata: [
+ "name": .string(params.name),
+ "args": .string("\(params.arguments ?? [:])")
+])
+```
+
+### JSON Schemas
+Use the Value type for schemas:
+```swift
+.object([
+ "type": .string("object"),
+ "properties": .object([
+ "name": .object([
+ "type": .string("string")
+ ])
+ ]),
+ "required": .array([.string("name")])
+])
+```
+
+## Common Patterns
+
+### Request/Response Handler
+```swift
+await server.withMethodHandler(CallTool.self) { params in
+ guard let arg = params.arguments?["key"]?.stringValue else {
+ throw MCPError.invalidParams("Missing key")
+ }
+
+ let result = await processAsync(arg)
+
+ return .init(
+ content: [.text(result)],
+ isError: false
+ )
+}
+```
+
+### Resource Subscription
+```swift
+await server.withMethodHandler(ResourceSubscribe.self) { params in
+ await state.addSubscription(params.uri)
+ logger.info("Subscribed to \(params.uri)")
+ return .init()
+}
+```
+
+### Concurrent Operations
+```swift
+async let result1 = fetchData1()
+async let result2 = fetchData2()
+let combined = await "\(result1) and \(result2)"
+```
+
+### Initialize Hook
+```swift
+try await server.start(transport: transport) { clientInfo, capabilities in
+ logger.info("Client: \(clientInfo.name) v\(clientInfo.version)")
+
+ if capabilities.sampling != nil {
+ logger.info("Client supports sampling")
+ }
+}
+```
+
+## Platform Support
+
+The Swift SDK supports:
+- macOS 13.0+
+- iOS 16.0+
+- watchOS 9.0+
+- tvOS 16.0+
+- visionOS 1.0+
+- Linux (glibc and musl)
+
+## Testing
+
+Write async tests:
+```swift
+func testTool() async throws {
+ let params = CallTool.Params(
+ name: "test",
+ arguments: ["key": .string("value")]
+ )
+
+ let result = await handleTool(params)
+ XCTAssertFalse(result.isError ?? true)
+}
+```
+
+## Debugging
+
+Enable debug logging:
+```swift
+var logger = Logger(label: "com.example.mcp-server")
+logger.logLevel = .debug
+```
+
+## Ask Me About
+
+- Server setup and configuration
+- Tool, resource, and prompt implementations
+- Swift concurrency patterns
+- Actor-based state management
+- ServiceLifecycle integration
+- Transport configuration (Stdio, HTTP, Network)
+- JSON schema construction
+- Error handling strategies
+- Testing async code
+- Platform-specific considerations
+- Performance optimization
+- Deployment strategies
+
+I'm here to help you build efficient, safe, and idiomatic Swift MCP servers. What would you like to work on?
diff --git a/collections/swift-mcp-development.collection.yml b/collections/swift-mcp-development.collection.yml
new file mode 100644
index 0000000..8828531
--- /dev/null
+++ b/collections/swift-mcp-development.collection.yml
@@ -0,0 +1,35 @@
+id: swift-mcp-development
+name: Swift MCP Server Development
+description: 'Comprehensive collection for building Model Context Protocol servers in Swift using the official MCP Swift SDK with modern concurrency features.'
+tags: [swift, mcp, model-context-protocol, server-development, sdk, ios, macos, concurrency, actor, async-await]
+items:
+ - path: instructions/swift-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/swift-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/swift-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in Swift.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with Swift
+ - Implementing async/await patterns and actor-based concurrency
+ - Setting up stdio, HTTP, or network transports
+ - Debugging Swift concurrency and ServiceLifecycle integration
+ - Learning Swift MCP best practices with the official SDK
+ - Optimizing server performance for iOS/macOS platforms
+
+ To get the best results, consider:
+ - Using the instruction file to set context for Swift MCP development
+ - Using the prompt to generate initial project structure
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need stdio, HTTP, or network transport
+ - Providing details about what tools or functionality you need
+ - Mentioning if you need resources, prompts, or special capabilities
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/swift-mcp-development.md b/collections/swift-mcp-development.md
new file mode 100644
index 0000000..3cabb90
--- /dev/null
+++ b/collections/swift-mcp-development.md
@@ -0,0 +1,41 @@
+# Swift MCP Server Development
+
+'Comprehensive collection for building Model Context Protocol servers in Swift using the official MCP Swift SDK with modern concurrency features.'
+
+**Tags:** swift, mcp, model-context-protocol, server-development, sdk, ios, macos, concurrency, actor, async-await
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [Swift MCP Server Development Guidelines](../instructions/swift-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fswift-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fswift-mcp-server.instructions.md) | Instruction | Best practices and patterns for building Model Context Protocol (MCP) servers in Swift using the official MCP Swift SDK package. |
+| [Swift MCP Server Generator](../prompts/swift-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fswift-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fswift-mcp-server-generator.prompt.md) | Prompt | Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package. |
+| [Swift MCP Expert](../chatmodes/swift-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fswift-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fswift-mcp-expert.chatmode.md) | Chat Mode | Expert assistance for building Model Context Protocol servers in Swift using modern concurrency features and the official MCP Swift SDK. [see usage](#swift-mcp-expert) |
+
+## Collection Usage
+
+### Swift MCP Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in Swift.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with Swift
+- Implementing async/await patterns and actor-based concurrency
+- Setting up stdio, HTTP, or network transports
+- Debugging Swift concurrency and ServiceLifecycle integration
+- Learning Swift MCP best practices with the official SDK
+- Optimizing server performance for iOS/macOS platforms
+
+To get the best results, consider:
+- Using the instruction file to set context for Swift MCP development
+- Using the prompt to generate initial project structure
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need stdio, HTTP, or network transport
+- Providing details about what tools or functionality you need
+- Mentioning if you need resources, prompts, or special capabilities
+
+---
+
+*This collection includes 3 curated items for swift mcp server development.*
\ No newline at end of file
diff --git a/instructions/swift-mcp-server.instructions.md b/instructions/swift-mcp-server.instructions.md
new file mode 100644
index 0000000..29f5e84
--- /dev/null
+++ b/instructions/swift-mcp-server.instructions.md
@@ -0,0 +1,498 @@
+---
+description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Swift using the official MCP Swift SDK package.'
+applyTo: "**/*.swift, **/Package.swift, **/Package.resolved"
+---
+
+# Swift MCP Server Development Guidelines
+
+When building MCP servers in Swift, follow these best practices and patterns using the official Swift SDK.
+
+## Server Setup
+
+Create an MCP server using the `Server` class with capabilities:
+
+```swift
+import MCP
+
+let server = Server(
+ name: "MyServer",
+ version: "1.0.0",
+ capabilities: .init(
+ prompts: .init(listChanged: true),
+ resources: .init(subscribe: true, listChanged: true),
+ tools: .init(listChanged: true)
+ )
+)
+```
+
+## Adding Tools
+
+Use `withMethodHandler` to register tool handlers:
+
+```swift
+// Register tool list handler
+await server.withMethodHandler(ListTools.self) { _ in
+ let tools = [
+ Tool(
+ name: "search",
+ description: "Search for information",
+ inputSchema: .object([
+ "properties": .object([
+ "query": .string("Search query"),
+ "limit": .number("Maximum results")
+ ]),
+ "required": .array([.string("query")])
+ ])
+ )
+ ]
+ return .init(tools: tools)
+}
+
+// Register tool call handler
+await server.withMethodHandler(CallTool.self) { params in
+ switch params.name {
+ case "search":
+ let query = params.arguments?["query"]?.stringValue ?? ""
+ let limit = params.arguments?["limit"]?.intValue ?? 10
+
+ // Perform search
+ let results = performSearch(query: query, limit: limit)
+
+ return .init(
+ content: [.text("Found \(results.count) results")],
+ isError: false
+ )
+
+ default:
+ return .init(
+ content: [.text("Unknown tool")],
+ isError: true
+ )
+ }
+}
+```
+
+## Adding Resources
+
+Implement resource handlers for data access:
+
+```swift
+// Register resource list handler
+await server.withMethodHandler(ListResources.self) { params in
+ let resources = [
+ Resource(
+ name: "Data File",
+ uri: "resource://data/example.txt",
+ description: "Example data file",
+ mimeType: "text/plain"
+ )
+ ]
+ return .init(resources: resources, nextCursor: nil)
+}
+
+// Register resource read handler
+await server.withMethodHandler(ReadResource.self) { params in
+ switch params.uri {
+ case "resource://data/example.txt":
+ let content = loadResourceContent(uri: params.uri)
+ return .init(contents: [
+ Resource.Content.text(
+ content,
+ uri: params.uri,
+ mimeType: "text/plain"
+ )
+ ])
+
+ default:
+ throw MCPError.invalidParams("Unknown resource URI: \(params.uri)")
+ }
+}
+
+// Register resource subscribe handler
+await server.withMethodHandler(ResourceSubscribe.self) { params in
+ // Track subscription for notifications
+ subscriptions.insert(params.uri)
+ print("Client subscribed to \(params.uri)")
+ return .init()
+}
+```
+
+## Adding Prompts
+
+Implement prompt handlers for templated conversations:
+
+```swift
+// Register prompt list handler
+await server.withMethodHandler(ListPrompts.self) { params in
+ let prompts = [
+ Prompt(
+ name: "analyze",
+ description: "Analyze a topic",
+ arguments: [
+ .init(name: "topic", description: "Topic to analyze", required: true),
+ .init(name: "depth", description: "Analysis depth", required: false)
+ ]
+ )
+ ]
+ return .init(prompts: prompts, nextCursor: nil)
+}
+
+// Register prompt get handler
+await server.withMethodHandler(GetPrompt.self) { params in
+ switch params.name {
+ case "analyze":
+ let topic = params.arguments?["topic"]?.stringValue ?? "general"
+ let depth = params.arguments?["depth"]?.stringValue ?? "basic"
+
+ let description = "Analysis of \(topic) at \(depth) level"
+ let messages: [Prompt.Message] = [
+ .user("Please analyze this topic: \(topic)"),
+ .assistant("I'll provide a \(depth) analysis of \(topic)")
+ ]
+
+ return .init(description: description, messages: messages)
+
+ default:
+ throw MCPError.invalidParams("Unknown prompt: \(params.name)")
+ }
+}
+```
+
+## Transport Configuration
+
+### Stdio Transport
+
+For local subprocess communication:
+
+```swift
+import MCP
+import Logging
+
+let logger = Logger(label: "com.example.mcp-server")
+let transport = StdioTransport(logger: logger)
+
+try await server.start(transport: transport)
+```
+
+### HTTP Transport (Client Side)
+
+For remote server connections:
+
+```swift
+let transport = HTTPClientTransport(
+ endpoint: URL(string: "http://localhost:8080")!,
+ streaming: true // Enable Server-Sent Events
+)
+
+try await client.connect(transport: transport)
+```
+
+## Concurrency and Actors
+
+The server is an actor, ensuring thread-safe access:
+
+```swift
+actor ServerState {
+ private var subscriptions: Set = []
+ private var cache: [String: Any] = [:]
+
+ func addSubscription(_ uri: String) {
+ subscriptions.insert(uri)
+ }
+
+ func getSubscriptions() -> Set {
+ return subscriptions
+ }
+}
+
+let state = ServerState()
+
+await server.withMethodHandler(ResourceSubscribe.self) { params in
+ await state.addSubscription(params.uri)
+ return .init()
+}
+```
+
+## Error Handling
+
+Use Swift's error handling with `MCPError`:
+
+```swift
+await server.withMethodHandler(CallTool.self) { params in
+ do {
+ guard let query = params.arguments?["query"]?.stringValue else {
+ throw MCPError.invalidParams("Missing query parameter")
+ }
+
+ let result = try performOperation(query: query)
+
+ return .init(
+ content: [.text(result)],
+ isError: false
+ )
+ } catch let error as MCPError {
+ return .init(
+ content: [.text(error.localizedDescription)],
+ isError: true
+ )
+ } catch {
+ return .init(
+ content: [.text("Unexpected error: \(error.localizedDescription)")],
+ isError: true
+ )
+ }
+}
+```
+
+## JSON Schema with Value Type
+
+Use the `Value` type for JSON schemas:
+
+```swift
+let schema = Value.object([
+ "type": .string("object"),
+ "properties": .object([
+ "name": .object([
+ "type": .string("string"),
+ "description": .string("User's name")
+ ]),
+ "age": .object([
+ "type": .string("integer"),
+ "minimum": .number(0),
+ "maximum": .number(150)
+ ]),
+ "email": .object([
+ "type": .string("string"),
+ "format": .string("email")
+ ])
+ ]),
+ "required": .array([.string("name")])
+])
+```
+
+## Swift Package Manager Setup
+
+Create your `Package.swift`:
+
+```swift
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+ name: "MyMCPServer",
+ platforms: [
+ .macOS(.v13),
+ .iOS(.v16)
+ ],
+ dependencies: [
+ .package(
+ url: "https://github.com/modelcontextprotocol/swift-sdk.git",
+ from: "0.10.0"
+ ),
+ .package(
+ url: "https://github.com/apple/swift-log.git",
+ from: "1.5.0"
+ )
+ ],
+ targets: [
+ .executableTarget(
+ name: "MyMCPServer",
+ dependencies: [
+ .product(name: "MCP", package: "swift-sdk"),
+ .product(name: "Logging", package: "swift-log")
+ ]
+ )
+ ]
+)
+```
+
+## Graceful Shutdown with ServiceLifecycle
+
+Use Swift Service Lifecycle for proper shutdown:
+
+```swift
+import MCP
+import ServiceLifecycle
+import Logging
+
+struct MCPService: Service {
+ let server: Server
+ let transport: Transport
+
+ func run() async throws {
+ try await server.start(transport: transport)
+ try await Task.sleep(for: .days(365 * 100))
+ }
+
+ func shutdown() async throws {
+ await server.stop()
+ }
+}
+
+let logger = Logger(label: "com.example.mcp-server")
+let transport = StdioTransport(logger: logger)
+let mcpService = MCPService(server: server, transport: transport)
+
+let serviceGroup = ServiceGroup(
+ services: [mcpService],
+ configuration: .init(
+ gracefulShutdownSignals: [.sigterm, .sigint]
+ ),
+ logger: logger
+)
+
+try await serviceGroup.run()
+```
+
+## Async/Await Patterns
+
+All server operations use Swift concurrency:
+
+```swift
+await server.withMethodHandler(CallTool.self) { params in
+ async let result1 = fetchData1()
+ async let result2 = fetchData2()
+
+ let combined = await "\(result1) and \(result2)"
+
+ return .init(
+ content: [.text(combined)],
+ isError: false
+ )
+}
+```
+
+## Logging
+
+Use swift-log for structured logging:
+
+```swift
+import Logging
+
+let logger = Logger(label: "com.example.mcp-server")
+
+await server.withMethodHandler(CallTool.self) { params in
+ logger.info("Tool called", metadata: [
+ "name": .string(params.name),
+ "args": .string("\(params.arguments ?? [:])")
+ ])
+
+ // Process tool call
+
+ logger.debug("Tool completed successfully")
+
+ return .init(content: [.text("Result")], isError: false)
+}
+```
+
+## Testing
+
+Test your server with async/await:
+
+```swift
+import XCTest
+@testable import MyMCPServer
+
+final class ServerTests: XCTestCase {
+ func testToolCall() async throws {
+ let server = createTestServer()
+
+ // Test tool call logic
+ let params = CallTool.Params(
+ name: "search",
+ arguments: ["query": .string("test")]
+ )
+
+ // Verify behavior
+ XCTAssertNoThrow(try await processToolCall(params))
+ }
+}
+```
+
+## Initialize Hook
+
+Validate client connections with an initialize hook:
+
+```swift
+try await server.start(transport: transport) { clientInfo, clientCapabilities in
+ // Validate client
+ guard clientInfo.name != "BlockedClient" else {
+ throw MCPError.invalidRequest("Client not allowed")
+ }
+
+ // Check capabilities
+ if clientCapabilities.sampling == nil {
+ logger.warning("Client doesn't support sampling")
+ }
+
+ logger.info("Client connected", metadata: [
+ "name": .string(clientInfo.name),
+ "version": .string(clientInfo.version)
+ ])
+}
+```
+
+## Common Patterns
+
+### Content Types
+
+Handle different content types:
+
+```swift
+return .init(
+ content: [
+ .text("Plain text response"),
+ .image(imageData, mimeType: "image/png", metadata: [
+ "width": 1024,
+ "height": 768
+ ]),
+ .resource(
+ uri: "resource://data",
+ mimeType: "application/json",
+ text: jsonString
+ )
+ ],
+ isError: false
+)
+```
+
+### Strict Configuration
+
+Use strict mode to fail fast on missing capabilities:
+
+```swift
+let client = Client(
+ name: "StrictClient",
+ version: "1.0.0",
+ configuration: .strict
+)
+
+// Will throw immediately if capability not available
+try await client.listTools()
+```
+
+### Request Batching
+
+Send multiple requests efficiently:
+
+```swift
+var tasks: [Task] = []
+
+try await client.withBatch { batch in
+ for i in 0..<10 {
+ tasks.append(
+ try await batch.addRequest(
+ CallTool.request(.init(
+ name: "process",
+ arguments: ["id": .number(Double(i))]
+ ))
+ )
+ )
+ }
+}
+
+for (index, task) in tasks.enumerated() {
+ let result = try await task.value
+ print("\(index): \(result.content)")
+}
+```
diff --git a/prompts/swift-mcp-server-generator.prompt.md b/prompts/swift-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..b148785
--- /dev/null
+++ b/prompts/swift-mcp-server-generator.prompt.md
@@ -0,0 +1,669 @@
+---
+description: 'Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package.'
+mode: agent
+---
+
+# Swift MCP Server Generator
+
+Generate a complete, production-ready MCP server in Swift using the official Swift SDK package.
+
+## Project Generation
+
+When asked to create a Swift MCP server, generate a complete project with this structure:
+
+```
+my-mcp-server/
+├── Package.swift
+├── Sources/
+│ └── MyMCPServer/
+│ ├── main.swift
+│ ├── Server.swift
+│ ├── Tools/
+│ │ ├── ToolDefinitions.swift
+│ │ └── ToolHandlers.swift
+│ ├── Resources/
+│ │ ├── ResourceDefinitions.swift
+│ │ └── ResourceHandlers.swift
+│ └── Prompts/
+│ ├── PromptDefinitions.swift
+│ └── PromptHandlers.swift
+├── Tests/
+│ └── MyMCPServerTests/
+│ └── ServerTests.swift
+└── README.md
+```
+
+## Package.swift Template
+
+```swift
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+ name: "MyMCPServer",
+ platforms: [
+ .macOS(.v13),
+ .iOS(.v16),
+ .watchOS(.v9),
+ .tvOS(.v16),
+ .visionOS(.v1)
+ ],
+ dependencies: [
+ .package(
+ url: "https://github.com/modelcontextprotocol/swift-sdk.git",
+ from: "0.10.0"
+ ),
+ .package(
+ url: "https://github.com/apple/swift-log.git",
+ from: "1.5.0"
+ ),
+ .package(
+ url: "https://github.com/swift-server/swift-service-lifecycle.git",
+ from: "2.0.0"
+ )
+ ],
+ targets: [
+ .executableTarget(
+ name: "MyMCPServer",
+ dependencies: [
+ .product(name: "MCP", package: "swift-sdk"),
+ .product(name: "Logging", package: "swift-log"),
+ .product(name: "ServiceLifecycle", package: "swift-service-lifecycle")
+ ]
+ ),
+ .testTarget(
+ name: "MyMCPServerTests",
+ dependencies: ["MyMCPServer"]
+ )
+ ]
+)
+```
+
+## main.swift Template
+
+```swift
+import MCP
+import Logging
+import ServiceLifecycle
+
+struct MCPService: Service {
+ let server: Server
+ let transport: Transport
+
+ func run() async throws {
+ try await server.start(transport: transport) { clientInfo, capabilities in
+ logger.info("Client connected", metadata: [
+ "name": .string(clientInfo.name),
+ "version": .string(clientInfo.version)
+ ])
+ }
+
+ // Keep service running
+ try await Task.sleep(for: .days(365 * 100))
+ }
+
+ func shutdown() async throws {
+ logger.info("Shutting down MCP server")
+ await server.stop()
+ }
+}
+
+var logger = Logger(label: "com.example.mcp-server")
+logger.logLevel = .info
+
+do {
+ let server = await createServer()
+ let transport = StdioTransport(logger: logger)
+ let service = MCPService(server: server, transport: transport)
+
+ let serviceGroup = ServiceGroup(
+ services: [service],
+ configuration: .init(
+ gracefulShutdownSignals: [.sigterm, .sigint]
+ ),
+ logger: logger
+ )
+
+ try await serviceGroup.run()
+} catch {
+ logger.error("Fatal error", metadata: ["error": .string("\(error)")])
+ throw error
+}
+```
+
+## Server.swift Template
+
+```swift
+import MCP
+import Logging
+
+func createServer() async -> Server {
+ let server = Server(
+ name: "MyMCPServer",
+ version: "1.0.0",
+ capabilities: .init(
+ prompts: .init(listChanged: true),
+ resources: .init(subscribe: true, listChanged: true),
+ tools: .init(listChanged: true)
+ )
+ )
+
+ // Register tool handlers
+ await registerToolHandlers(server: server)
+
+ // Register resource handlers
+ await registerResourceHandlers(server: server)
+
+ // Register prompt handlers
+ await registerPromptHandlers(server: server)
+
+ return server
+}
+```
+
+## ToolDefinitions.swift Template
+
+```swift
+import MCP
+
+func getToolDefinitions() -> [Tool] {
+ [
+ Tool(
+ name: "greet",
+ description: "Generate a greeting message",
+ inputSchema: .object([
+ "type": .string("object"),
+ "properties": .object([
+ "name": .object([
+ "type": .string("string"),
+ "description": .string("Name to greet")
+ ])
+ ]),
+ "required": .array([.string("name")])
+ ])
+ ),
+ Tool(
+ name: "calculate",
+ description: "Perform mathematical calculations",
+ inputSchema: .object([
+ "type": .string("object"),
+ "properties": .object([
+ "operation": .object([
+ "type": .string("string"),
+ "enum": .array([
+ .string("add"),
+ .string("subtract"),
+ .string("multiply"),
+ .string("divide")
+ ]),
+ "description": .string("Operation to perform")
+ ]),
+ "a": .object([
+ "type": .string("number"),
+ "description": .string("First operand")
+ ]),
+ "b": .object([
+ "type": .string("number"),
+ "description": .string("Second operand")
+ ])
+ ]),
+ "required": .array([
+ .string("operation"),
+ .string("a"),
+ .string("b")
+ ])
+ ])
+ )
+ ]
+}
+```
+
+## ToolHandlers.swift Template
+
+```swift
+import MCP
+import Logging
+
+private let logger = Logger(label: "com.example.mcp-server.tools")
+
+func registerToolHandlers(server: Server) async {
+ await server.withMethodHandler(ListTools.self) { _ in
+ logger.debug("Listing available tools")
+ return .init(tools: getToolDefinitions())
+ }
+
+ await server.withMethodHandler(CallTool.self) { params in
+ logger.info("Tool called", metadata: ["name": .string(params.name)])
+
+ switch params.name {
+ case "greet":
+ return handleGreet(params: params)
+
+ case "calculate":
+ return handleCalculate(params: params)
+
+ default:
+ logger.warning("Unknown tool requested", metadata: ["name": .string(params.name)])
+ return .init(
+ content: [.text("Unknown tool: \(params.name)")],
+ isError: true
+ )
+ }
+ }
+}
+
+private func handleGreet(params: CallTool.Params) -> CallTool.Result {
+ guard let name = params.arguments?["name"]?.stringValue else {
+ return .init(
+ content: [.text("Missing 'name' parameter")],
+ isError: true
+ )
+ }
+
+ let greeting = "Hello, \(name)! Welcome to MCP."
+ logger.debug("Generated greeting", metadata: ["name": .string(name)])
+
+ return .init(
+ content: [.text(greeting)],
+ isError: false
+ )
+}
+
+private func handleCalculate(params: CallTool.Params) -> CallTool.Result {
+ guard let operation = params.arguments?["operation"]?.stringValue,
+ let a = params.arguments?["a"]?.doubleValue,
+ let b = params.arguments?["b"]?.doubleValue else {
+ return .init(
+ content: [.text("Missing or invalid parameters")],
+ isError: true
+ )
+ }
+
+ let result: Double
+ switch operation {
+ case "add":
+ result = a + b
+ case "subtract":
+ result = a - b
+ case "multiply":
+ result = a * b
+ case "divide":
+ guard b != 0 else {
+ return .init(
+ content: [.text("Division by zero")],
+ isError: true
+ )
+ }
+ result = a / b
+ default:
+ return .init(
+ content: [.text("Unknown operation: \(operation)")],
+ isError: true
+ )
+ }
+
+ logger.debug("Calculation performed", metadata: [
+ "operation": .string(operation),
+ "result": .string("\(result)")
+ ])
+
+ return .init(
+ content: [.text("Result: \(result)")],
+ isError: false
+ )
+}
+```
+
+## ResourceDefinitions.swift Template
+
+```swift
+import MCP
+
+func getResourceDefinitions() -> [Resource] {
+ [
+ Resource(
+ name: "Example Data",
+ uri: "resource://data/example",
+ description: "Example resource data",
+ mimeType: "application/json"
+ ),
+ Resource(
+ name: "Configuration",
+ uri: "resource://config",
+ description: "Server configuration",
+ mimeType: "application/json"
+ )
+ ]
+}
+```
+
+## ResourceHandlers.swift Template
+
+```swift
+import MCP
+import Logging
+import Foundation
+
+private let logger = Logger(label: "com.example.mcp-server.resources")
+
+actor ResourceState {
+ private var subscriptions: Set = []
+
+ func addSubscription(_ uri: String) {
+ subscriptions.insert(uri)
+ }
+
+ func removeSubscription(_ uri: String) {
+ subscriptions.remove(uri)
+ }
+
+ func isSubscribed(_ uri: String) -> Bool {
+ subscriptions.contains(uri)
+ }
+}
+
+private let state = ResourceState()
+
+func registerResourceHandlers(server: Server) async {
+ await server.withMethodHandler(ListResources.self) { params in
+ logger.debug("Listing available resources")
+ return .init(resources: getResourceDefinitions(), nextCursor: nil)
+ }
+
+ await server.withMethodHandler(ReadResource.self) { params in
+ logger.info("Reading resource", metadata: ["uri": .string(params.uri)])
+
+ switch params.uri {
+ case "resource://data/example":
+ let jsonData = """
+ {
+ "message": "Example resource data",
+ "timestamp": "\(Date())"
+ }
+ """
+ return .init(contents: [
+ .text(jsonData, uri: params.uri, mimeType: "application/json")
+ ])
+
+ case "resource://config":
+ let config = """
+ {
+ "serverName": "MyMCPServer",
+ "version": "1.0.0"
+ }
+ """
+ return .init(contents: [
+ .text(config, uri: params.uri, mimeType: "application/json")
+ ])
+
+ default:
+ logger.warning("Unknown resource requested", metadata: ["uri": .string(params.uri)])
+ throw MCPError.invalidParams("Unknown resource URI: \(params.uri)")
+ }
+ }
+
+ await server.withMethodHandler(ResourceSubscribe.self) { params in
+ logger.info("Client subscribed to resource", metadata: ["uri": .string(params.uri)])
+ await state.addSubscription(params.uri)
+ return .init()
+ }
+
+ await server.withMethodHandler(ResourceUnsubscribe.self) { params in
+ logger.info("Client unsubscribed from resource", metadata: ["uri": .string(params.uri)])
+ await state.removeSubscription(params.uri)
+ return .init()
+ }
+}
+```
+
+## PromptDefinitions.swift Template
+
+```swift
+import MCP
+
+func getPromptDefinitions() -> [Prompt] {
+ [
+ Prompt(
+ name: "code-review",
+ description: "Generate a code review prompt",
+ arguments: [
+ .init(name: "language", description: "Programming language", required: true),
+ .init(name: "focus", description: "Review focus area", required: false)
+ ]
+ )
+ ]
+}
+```
+
+## PromptHandlers.swift Template
+
+```swift
+import MCP
+import Logging
+
+private let logger = Logger(label: "com.example.mcp-server.prompts")
+
+func registerPromptHandlers(server: Server) async {
+ await server.withMethodHandler(ListPrompts.self) { params in
+ logger.debug("Listing available prompts")
+ return .init(prompts: getPromptDefinitions(), nextCursor: nil)
+ }
+
+ await server.withMethodHandler(GetPrompt.self) { params in
+ logger.info("Getting prompt", metadata: ["name": .string(params.name)])
+
+ switch params.name {
+ case "code-review":
+ return handleCodeReviewPrompt(params: params)
+
+ default:
+ logger.warning("Unknown prompt requested", metadata: ["name": .string(params.name)])
+ throw MCPError.invalidParams("Unknown prompt: \(params.name)")
+ }
+ }
+}
+
+private func handleCodeReviewPrompt(params: GetPrompt.Params) -> GetPrompt.Result {
+ guard let language = params.arguments?["language"]?.stringValue else {
+ return .init(
+ description: "Missing language parameter",
+ messages: []
+ )
+ }
+
+ let focus = params.arguments?["focus"]?.stringValue ?? "general quality"
+
+ let description = "Code review for \(language) with focus on \(focus)"
+ let messages: [Prompt.Message] = [
+ .user("Please review this \(language) code with focus on \(focus)."),
+ .assistant("I'll review the code focusing on \(focus). Please share the code."),
+ .user("Here's the code to review: [paste code here]")
+ ]
+
+ logger.debug("Generated code review prompt", metadata: [
+ "language": .string(language),
+ "focus": .string(focus)
+ ])
+
+ return .init(description: description, messages: messages)
+}
+```
+
+## ServerTests.swift Template
+
+```swift
+import XCTest
+@testable import MyMCPServer
+
+final class ServerTests: XCTestCase {
+ func testGreetTool() async throws {
+ let params = CallTool.Params(
+ name: "greet",
+ arguments: ["name": .string("Swift")]
+ )
+
+ let result = handleGreet(params: params)
+
+ XCTAssertFalse(result.isError ?? true)
+ XCTAssertEqual(result.content.count, 1)
+
+ if case .text(let message) = result.content[0] {
+ XCTAssertTrue(message.contains("Swift"))
+ } else {
+ XCTFail("Expected text content")
+ }
+ }
+
+ func testCalculateTool() async throws {
+ let params = CallTool.Params(
+ name: "calculate",
+ arguments: [
+ "operation": .string("add"),
+ "a": .number(5),
+ "b": .number(3)
+ ]
+ )
+
+ let result = handleCalculate(params: params)
+
+ XCTAssertFalse(result.isError ?? true)
+ XCTAssertEqual(result.content.count, 1)
+
+ if case .text(let message) = result.content[0] {
+ XCTAssertTrue(message.contains("8"))
+ } else {
+ XCTFail("Expected text content")
+ }
+ }
+
+ func testDivideByZero() async throws {
+ let params = CallTool.Params(
+ name: "calculate",
+ arguments: [
+ "operation": .string("divide"),
+ "a": .number(10),
+ "b": .number(0)
+ ]
+ )
+
+ let result = handleCalculate(params: params)
+
+ XCTAssertTrue(result.isError ?? false)
+ }
+}
+```
+
+## README.md Template
+
+```markdown
+# MyMCPServer
+
+A Model Context Protocol server built with Swift.
+
+## Features
+
+- ✅ Tools: greet, calculate
+- ✅ Resources: example data, configuration
+- ✅ Prompts: code-review
+- ✅ Graceful shutdown with ServiceLifecycle
+- ✅ Structured logging with swift-log
+- ✅ Full test coverage
+
+## Requirements
+
+- Swift 6.0+
+- macOS 13+, iOS 16+, or Linux
+
+## Installation
+
+```bash
+swift build -c release
+```
+
+## Usage
+
+Run the server:
+
+```bash
+swift run
+```
+
+Or with logging:
+
+```bash
+LOG_LEVEL=debug swift run
+```
+
+## Testing
+
+```bash
+swift test
+```
+
+## Development
+
+The server uses:
+- [MCP Swift SDK](https://github.com/modelcontextprotocol/swift-sdk) - MCP protocol implementation
+- [swift-log](https://github.com/apple/swift-log) - Structured logging
+- [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) - Graceful shutdown
+
+## Project Structure
+
+- `Sources/MyMCPServer/main.swift` - Entry point with ServiceLifecycle
+- `Sources/MyMCPServer/Server.swift` - Server configuration
+- `Sources/MyMCPServer/Tools/` - Tool definitions and handlers
+- `Sources/MyMCPServer/Resources/` - Resource definitions and handlers
+- `Sources/MyMCPServer/Prompts/` - Prompt definitions and handlers
+- `Tests/` - Unit tests
+
+## License
+
+MIT
+```
+
+## Generation Instructions
+
+1. **Ask for project name and description**
+2. **Generate all files** with proper naming
+3. **Use actor-based state** for thread safety
+4. **Include comprehensive logging** with swift-log
+5. **Implement graceful shutdown** with ServiceLifecycle
+6. **Add tests** for all handlers
+7. **Use modern Swift concurrency** (async/await)
+8. **Follow Swift naming conventions** (camelCase, PascalCase)
+9. **Include error handling** with proper MCPError usage
+10. **Document public APIs** with doc comments
+
+## Build and Run
+
+```bash
+# Build
+swift build
+
+# Run
+swift run
+
+# Test
+swift test
+
+# Release build
+swift build -c release
+
+# Install
+swift build -c release
+cp .build/release/MyMCPServer /usr/local/bin/
+```
+
+## Integration with Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "my-mcp-server": {
+ "command": "/path/to/MyMCPServer"
+ }
+ }
+}
+```
From eec72209d0c7135e4ecaaca52cbaa15009e26925 Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:11:02 -0400
Subject: [PATCH 7/8] Add Java MCP Server Development collection (#329)
* Add Java MCP Server Development collection
- Add Java MCP server best practices instruction
- Add Java MCP server project generator prompt
- Add Java MCP expert chat mode
- Add Java MCP development collection manifest
- Update category READMEs
Features:
- Server setup with official MCP Java SDK
- Tool/resource/prompt handlers with reactive streams
- Project Reactor for async processing
- Spring Boot integration with starters
- Stdio and HTTP transport support
- JSON schema construction with fluent builders
- Synchronous facade for blocking use cases
- Maven and Gradle build configurations
* Fix Java MCP generator prompt
- Add missing import statements for handler classes
- Add handler registration in test server setup
---------
Co-authored-by: Aaron Powell
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/java-mcp-expert.chatmode.md | 325 ++++++++
.../java-mcp-development.collection.yml | 35 +
collections/java-mcp-development.md | 41 +
instructions/java-mcp-server.instructions.md | 553 +++++++++++++
prompts/java-mcp-server-generator.prompt.md | 756 ++++++++++++++++++
9 files changed, 1714 insertions(+)
create mode 100644 chatmodes/java-mcp-expert.chatmode.md
create mode 100644 collections/java-mcp-development.collection.yml
create mode 100644 collections/java-mcp-development.md
create mode 100644 instructions/java-mcp-server.instructions.md
create mode 100644 prompts/java-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index 097f1e1..77dae5e 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -46,6 +46,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [High-Level Big Picture Architect (HLBPA)](chatmodes/hlbpa.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fhlbpa.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fhlbpa.chatmode.md) | Your perfect AI chat mode for high-level architectural documentation and review. Perfect for targeted updates after a story or researching that legacy system when nobody remembers what it's supposed to be doing. |
| [Idea Generator mode instructions](chatmodes/simple-app-idea-generator.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsimple-app-idea-generator.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsimple-app-idea-generator.chatmode.md) | Brainstorm and develop new application ideas through fun, interactive questioning until ready for specification creation. |
| [Implementation Plan Generation Mode](chatmodes/implementation-plan.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fimplementation-plan.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fimplementation-plan.chatmode.md) | Generate an implementation plan for new features or refactoring existing code. |
+| [Java MCP Expert](chatmodes/java-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fjava-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fjava-mcp-expert.chatmode.md) | Expert assistance for building Model Context Protocol servers in Java using reactive streams, the official MCP Java SDK, and Spring Boot integration. |
| [Kotlin MCP Server Development Expert](chatmodes/kotlin-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkotlin-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkotlin-mcp-expert.chatmode.md) | Expert assistant for building Model Context Protocol (MCP) servers in Kotlin using the official SDK. |
| [Kusto Assistant: Azure Data Explorer (Kusto) Engineering Assistant](chatmodes/kusto-assistant.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkusto-assistant.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fkusto-assistant.chatmode.md) | Expert KQL assistant for live Azure Data Explorer analysis via Azure MCP server |
| [Mentor mode instructions](chatmodes/mentor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fmentor.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fmentor.chatmode.md) | Help mentor the engineer by providing guidance and support. |
diff --git a/README.collections.md b/README.collections.md
index 1a07ef9..60fc4e5 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -24,6 +24,7 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Frontend Web Development](collections/frontend-web-dev.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 11 items | frontend, web, react, typescript, javascript, css, html, angular, vue |
| [Go MCP Server Development](collections/go-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | go, golang, mcp, model-context-protocol, server-development, sdk |
| [Java Development](collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc |
+| [Java MCP Server Development](collections/java-mcp-development.md) | 'Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration.' | 3 items | java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor |
| [Kotlin MCP Server Development](collections/kotlin-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor |
| [Power Apps Code Apps Development](collections/power-apps-code-apps.md) | Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance for building code-first applications with Power Platform integration. | 3 items | power-apps, power-platform, typescript, react, code-apps, dataverse, connectors |
| [Power BI Development](collections/power-bi-development.md) | Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions. | 14 items | power-bi, dax, data-modeling, performance, visualization, security, devops, business-intelligence |
diff --git a/README.instructions.md b/README.instructions.md
index 1ad3971..c772e96 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -61,6 +61,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Java 17 to Java 21 Upgrade Guide](instructions/java-17-to-java-21-upgrade.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-17-to-java-21-upgrade.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-17-to-java-21-upgrade.instructions.md) | Comprehensive best practices for adopting new Java 21 features since the release of Java 17. |
| [Java 21 to Java 25 Upgrade Guide](instructions/java-21-to-java-25-upgrade.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-21-to-java-25-upgrade.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-21-to-java-25-upgrade.instructions.md) | Comprehensive best practices for adopting new Java 25 features since the release of Java 21. |
| [Java Development](instructions/java.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava.instructions.md) | Guidelines for building Java base applications |
+| [Java MCP Server Development Guidelines](instructions/java-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Java using the official MCP Java SDK with reactive streams and Spring integration. |
| [Joyride User Scripts Project Assistant](instructions/joyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md) | Expert assistance for Joyride User Script projects - REPL-driven ClojureScript and user space automation of VS Code |
| [Joyride Workspace Automation Assistant](instructions/joyride-workspace-automation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-workspace-automation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-workspace-automation.instructions.md) | Expert assistance for Joyride Workspace automation - REPL-driven and user space ClojureScript automation within specific VS Code workspaces |
| [Kotlin MCP Server Development Guidelines](instructions/kotlin-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkotlin-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkotlin-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. |
diff --git a/README.prompts.md b/README.prompts.md
index 5c870da..a20c912 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -66,6 +66,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Go MCP Server Project Generator](prompts/go-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. |
| [Interactive Programming Nudge](prompts/remember-interactive-programming.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md) | A micro-prompt that reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. |
| [Java Documentation (Javadoc) Best Practices](prompts/java-docs.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. |
+| [Java MCP Server Generator](prompts/java-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Java using the official MCP Java SDK with reactive streams and optional Spring Boot integration. |
| [Javascript Typescript Jest](prompts/javascript-typescript-jest.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. |
| [JUnit 5+ Best Practices](prompts/java-junit.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md) | Get best practices for JUnit 5 unit testing, including data-driven tests |
| [Kotlin MCP Server Project Generator](prompts/kotlin-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md) | Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library. |
diff --git a/chatmodes/java-mcp-expert.chatmode.md b/chatmodes/java-mcp-expert.chatmode.md
new file mode 100644
index 0000000..b94cb2e
--- /dev/null
+++ b/chatmodes/java-mcp-expert.chatmode.md
@@ -0,0 +1,325 @@
+---
+description: 'Expert assistance for building Model Context Protocol servers in Java using reactive streams, the official MCP Java SDK, and Spring Boot integration.'
+model: GPT-4.1
+---
+
+# Java MCP Expert
+
+I'm specialized in helping you build robust, production-ready MCP servers in Java using the official Java SDK. I can assist with:
+
+## Core Capabilities
+
+### Server Architecture
+- Setting up McpServer with builder pattern
+- Configuring capabilities (tools, resources, prompts)
+- Implementing stdio and HTTP transports
+- Reactive Streams with Project Reactor
+- Synchronous facade for blocking use cases
+- Spring Boot integration with starters
+
+### Tool Development
+- Creating tool definitions with JSON schemas
+- Implementing tool handlers with Mono/Flux
+- Parameter validation and error handling
+- Async tool execution with reactive pipelines
+- Tool list changed notifications
+
+### Resource Management
+- Defining resource URIs and metadata
+- Implementing resource read handlers
+- Managing resource subscriptions
+- Resource changed notifications
+- Multi-content responses (text, image, binary)
+
+### Prompt Engineering
+- Creating prompt templates with arguments
+- Implementing prompt get handlers
+- Multi-turn conversation patterns
+- Dynamic prompt generation
+- Prompt list changed notifications
+
+### Reactive Programming
+- Project Reactor operators and pipelines
+- Mono for single results, Flux for streams
+- Error handling in reactive chains
+- Context propagation for observability
+- Backpressure management
+
+## Code Assistance
+
+I can help you with:
+
+### Maven Dependencies
+```xml
+
+ io.modelcontextprotocol.sdk
+ mcp
+ 0.14.1
+
+```
+
+### Server Creation
+```java
+McpServer server = McpServerBuilder.builder()
+ .serverInfo("my-server", "1.0.0")
+ .capabilities(cap -> cap
+ .tools(true)
+ .resources(true)
+ .prompts(true))
+ .build();
+```
+
+### Tool Handler
+```java
+server.addToolHandler("process", (args) -> {
+ return Mono.fromCallable(() -> {
+ String result = process(args);
+ return ToolResponse.success()
+ .addTextContent(result)
+ .build();
+ }).subscribeOn(Schedulers.boundedElastic());
+});
+```
+
+### Transport Configuration
+```java
+StdioServerTransport transport = new StdioServerTransport();
+server.start(transport).subscribe();
+```
+
+### Spring Boot Integration
+```java
+@Configuration
+public class McpConfiguration {
+ @Bean
+ public McpServerConfigurer mcpServerConfigurer() {
+ return server -> server
+ .serverInfo("spring-server", "1.0.0")
+ .capabilities(cap -> cap.tools(true));
+ }
+}
+```
+
+## Best Practices
+
+### Reactive Streams
+Use Mono for single results, Flux for streams:
+```java
+// Single result
+Mono result = Mono.just(
+ ToolResponse.success().build()
+);
+
+// Stream of items
+Flux resources = Flux.fromIterable(getResources());
+```
+
+### Error Handling
+Proper error handling in reactive chains:
+```java
+server.addToolHandler("risky", (args) -> {
+ return Mono.fromCallable(() -> riskyOperation(args))
+ .map(result -> ToolResponse.success()
+ .addTextContent(result)
+ .build())
+ .onErrorResume(ValidationException.class, e ->
+ Mono.just(ToolResponse.error()
+ .message("Invalid input")
+ .build()))
+ .doOnError(e -> log.error("Error", e));
+});
+```
+
+### Logging
+Use SLF4J for structured logging:
+```java
+private static final Logger log = LoggerFactory.getLogger(MyClass.class);
+
+log.info("Tool called: {}", toolName);
+log.debug("Processing with args: {}", args);
+log.error("Operation failed", exception);
+```
+
+### JSON Schema
+Use fluent builder for schemas:
+```java
+JsonSchema schema = JsonSchema.object()
+ .property("name", JsonSchema.string()
+ .description("User's name")
+ .required(true))
+ .property("age", JsonSchema.integer()
+ .minimum(0)
+ .maximum(150))
+ .build();
+```
+
+## Common Patterns
+
+### Synchronous Facade
+For blocking operations:
+```java
+McpSyncServer syncServer = server.toSyncServer();
+
+syncServer.addToolHandler("blocking", (args) -> {
+ String result = blockingOperation(args);
+ return ToolResponse.success()
+ .addTextContent(result)
+ .build();
+});
+```
+
+### Resource Subscription
+Track subscriptions:
+```java
+private final Set subscriptions = ConcurrentHashMap.newKeySet();
+
+server.addResourceSubscribeHandler((uri) -> {
+ subscriptions.add(uri);
+ log.info("Subscribed to {}", uri);
+ return Mono.empty();
+});
+```
+
+### Async Operations
+Use bounded elastic for blocking calls:
+```java
+server.addToolHandler("external", (args) -> {
+ return Mono.fromCallable(() -> callExternalApi(args))
+ .timeout(Duration.ofSeconds(30))
+ .subscribeOn(Schedulers.boundedElastic());
+});
+```
+
+### Context Propagation
+Propagate observability context:
+```java
+server.addToolHandler("traced", (args) -> {
+ return Mono.deferContextual(ctx -> {
+ String traceId = ctx.get("traceId");
+ log.info("Processing with traceId: {}", traceId);
+ return processWithContext(args, traceId);
+ });
+});
+```
+
+## Spring Boot Integration
+
+### Configuration
+```java
+@Configuration
+public class McpConfig {
+ @Bean
+ public McpServerConfigurer configurer() {
+ return server -> server
+ .serverInfo("spring-app", "1.0.0")
+ .capabilities(cap -> cap
+ .tools(true)
+ .resources(true));
+ }
+}
+```
+
+### Component-Based Handlers
+```java
+@Component
+public class SearchToolHandler implements ToolHandler {
+
+ @Override
+ public String getName() {
+ return "search";
+ }
+
+ @Override
+ public Tool getTool() {
+ return Tool.builder()
+ .name("search")
+ .description("Search for data")
+ .inputSchema(JsonSchema.object()
+ .property("query", JsonSchema.string().required(true)))
+ .build();
+ }
+
+ @Override
+ public Mono handle(JsonNode args) {
+ String query = args.get("query").asText();
+ return searchService.search(query)
+ .map(results -> ToolResponse.success()
+ .addTextContent(results)
+ .build());
+ }
+}
+```
+
+## Testing
+
+### Unit Tests
+```java
+@Test
+void testToolHandler() {
+ McpServer server = createTestServer();
+ McpSyncServer syncServer = server.toSyncServer();
+
+ ObjectNode args = new ObjectMapper().createObjectNode()
+ .put("key", "value");
+
+ ToolResponse response = syncServer.callTool("test", args);
+
+ assertFalse(response.isError());
+ assertEquals(1, response.getContent().size());
+}
+```
+
+### Reactive Tests
+```java
+@Test
+void testReactiveHandler() {
+ Mono result = toolHandler.handle(args);
+
+ StepVerifier.create(result)
+ .expectNextMatches(response -> !response.isError())
+ .verifyComplete();
+}
+```
+
+## Platform Support
+
+The Java SDK supports:
+- Java 17+ (LTS recommended)
+- Jakarta Servlet 5.0+
+- Spring Boot 3.0+
+- Project Reactor 3.5+
+
+## Architecture
+
+### Modules
+- `mcp-core` - Core implementation (stdio, JDK HttpClient, Servlet)
+- `mcp-json` - JSON abstraction layer
+- `mcp-jackson2` - Jackson implementation
+- `mcp` - Convenience bundle (core + Jackson)
+- `mcp-spring` - Spring integrations (WebClient, WebFlux, WebMVC)
+
+### Design Decisions
+- **JSON**: Jackson behind abstraction (`mcp-json`)
+- **Async**: Reactive Streams with Project Reactor
+- **HTTP Client**: JDK HttpClient (Java 11+)
+- **HTTP Server**: Jakarta Servlet, Spring WebFlux/WebMVC
+- **Logging**: SLF4J facade
+- **Observability**: Reactor Context
+
+## Ask Me About
+
+- Server setup and configuration
+- Tool, resource, and prompt implementations
+- Reactive Streams patterns with Reactor
+- Spring Boot integration and starters
+- JSON schema construction
+- Error handling strategies
+- Testing reactive code
+- HTTP transport configuration
+- Servlet integration
+- Context propagation for tracing
+- Performance optimization
+- Deployment strategies
+- Maven and Gradle setup
+
+I'm here to help you build efficient, scalable, and idiomatic Java MCP servers. What would you like to work on?
diff --git a/collections/java-mcp-development.collection.yml b/collections/java-mcp-development.collection.yml
new file mode 100644
index 0000000..f8427d3
--- /dev/null
+++ b/collections/java-mcp-development.collection.yml
@@ -0,0 +1,35 @@
+id: java-mcp-development
+name: Java MCP Server Development
+description: 'Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration.'
+tags: [java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor]
+items:
+ - path: instructions/java-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/java-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/java-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in Java.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with Java
+ - Implementing reactive handlers with Project Reactor
+ - Setting up stdio or HTTP transports
+ - Debugging reactive streams and error handling
+ - Learning Java MCP best practices with the official SDK
+ - Integrating with Spring Boot applications
+
+ To get the best results, consider:
+ - Using the instruction file to set context for Java MCP development
+ - Using the prompt to generate initial project structure
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need Maven or Gradle
+ - Providing details about what tools or functionality you need
+ - Mentioning if you need Spring Boot integration
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/java-mcp-development.md b/collections/java-mcp-development.md
new file mode 100644
index 0000000..4a400de
--- /dev/null
+++ b/collections/java-mcp-development.md
@@ -0,0 +1,41 @@
+# Java MCP Server Development
+
+'Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration.'
+
+**Tags:** java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [Java MCP Server Development Guidelines](../instructions/java-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava-mcp-server.instructions.md) | Instruction | Best practices and patterns for building Model Context Protocol (MCP) servers in Java using the official MCP Java SDK with reactive streams and Spring integration. |
+| [Java MCP Server Generator](../prompts/java-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-mcp-server-generator.prompt.md) | Prompt | Generate a complete Model Context Protocol server project in Java using the official MCP Java SDK with reactive streams and optional Spring Boot integration. |
+| [Java MCP Expert](../chatmodes/java-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fjava-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fjava-mcp-expert.chatmode.md) | Chat Mode | Expert assistance for building Model Context Protocol servers in Java using reactive streams, the official MCP Java SDK, and Spring Boot integration. [see usage](#java-mcp-expert) |
+
+## Collection Usage
+
+### Java MCP Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in Java.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with Java
+- Implementing reactive handlers with Project Reactor
+- Setting up stdio or HTTP transports
+- Debugging reactive streams and error handling
+- Learning Java MCP best practices with the official SDK
+- Integrating with Spring Boot applications
+
+To get the best results, consider:
+- Using the instruction file to set context for Java MCP development
+- Using the prompt to generate initial project structure
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need Maven or Gradle
+- Providing details about what tools or functionality you need
+- Mentioning if you need Spring Boot integration
+
+---
+
+*This collection includes 3 curated items for java mcp server development.*
\ No newline at end of file
diff --git a/instructions/java-mcp-server.instructions.md b/instructions/java-mcp-server.instructions.md
new file mode 100644
index 0000000..39f3a53
--- /dev/null
+++ b/instructions/java-mcp-server.instructions.md
@@ -0,0 +1,553 @@
+---
+description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Java using the official MCP Java SDK with reactive streams and Spring integration.'
+applyTo: "**/*.java, **/pom.xml, **/build.gradle, **/build.gradle.kts"
+---
+
+# Java MCP Server Development Guidelines
+
+When building MCP servers in Java, follow these best practices and patterns using the official Java SDK.
+
+## Dependencies
+
+Add the MCP Java SDK to your Maven project:
+
+```xml
+
+
+ io.modelcontextprotocol.sdk
+ mcp
+ 0.14.1
+
+
+```
+
+Or for Gradle:
+
+```kotlin
+dependencies {
+ implementation("io.modelcontextprotocol.sdk:mcp:0.14.1")
+}
+```
+
+## Server Setup
+
+Create an MCP server using the builder pattern:
+
+```java
+import io.mcp.server.McpServer;
+import io.mcp.server.McpServerBuilder;
+import io.mcp.server.transport.StdioServerTransport;
+
+McpServer server = McpServerBuilder.builder()
+ .serverInfo("my-server", "1.0.0")
+ .capabilities(capabilities -> capabilities
+ .tools(true)
+ .resources(true)
+ .prompts(true))
+ .build();
+
+// Start with stdio transport
+StdioServerTransport transport = new StdioServerTransport();
+server.start(transport).subscribe();
+```
+
+## Adding Tools
+
+Register tool handlers with the server:
+
+```java
+import io.mcp.server.tool.Tool;
+import io.mcp.server.tool.ToolHandler;
+import reactor.core.publisher.Mono;
+
+// Define a tool
+Tool searchTool = Tool.builder()
+ .name("search")
+ .description("Search for information")
+ .inputSchema(JsonSchema.object()
+ .property("query", JsonSchema.string()
+ .description("Search query")
+ .required(true))
+ .property("limit", JsonSchema.integer()
+ .description("Maximum results")
+ .defaultValue(10)))
+ .build();
+
+// Register tool handler
+server.addToolHandler("search", (arguments) -> {
+ String query = arguments.get("query").asText();
+ int limit = arguments.has("limit")
+ ? arguments.get("limit").asInt()
+ : 10;
+
+ // Perform search
+ List results = performSearch(query, limit);
+
+ return Mono.just(ToolResponse.success()
+ .addTextContent("Found " + results.size() + " results")
+ .build());
+});
+```
+
+## Adding Resources
+
+Implement resource handlers for data access:
+
+```java
+import io.mcp.server.resource.Resource;
+import io.mcp.server.resource.ResourceHandler;
+
+// Register resource list handler
+server.addResourceListHandler(() -> {
+ List resources = List.of(
+ Resource.builder()
+ .name("Data File")
+ .uri("resource://data/example.txt")
+ .description("Example data file")
+ .mimeType("text/plain")
+ .build()
+ );
+ return Mono.just(resources);
+});
+
+// Register resource read handler
+server.addResourceReadHandler((uri) -> {
+ if (uri.equals("resource://data/example.txt")) {
+ String content = loadResourceContent(uri);
+ return Mono.just(ResourceContent.text(content, uri));
+ }
+ throw new ResourceNotFoundException(uri);
+});
+
+// Register resource subscribe handler
+server.addResourceSubscribeHandler((uri) -> {
+ subscriptions.add(uri);
+ log.info("Client subscribed to {}", uri);
+ return Mono.empty();
+});
+```
+
+## Adding Prompts
+
+Implement prompt handlers for templated conversations:
+
+```java
+import io.mcp.server.prompt.Prompt;
+import io.mcp.server.prompt.PromptMessage;
+import io.mcp.server.prompt.PromptArgument;
+
+// Register prompt list handler
+server.addPromptListHandler(() -> {
+ List prompts = List.of(
+ Prompt.builder()
+ .name("analyze")
+ .description("Analyze a topic")
+ .argument(PromptArgument.builder()
+ .name("topic")
+ .description("Topic to analyze")
+ .required(true)
+ .build())
+ .argument(PromptArgument.builder()
+ .name("depth")
+ .description("Analysis depth")
+ .required(false)
+ .build())
+ .build()
+ );
+ return Mono.just(prompts);
+});
+
+// Register prompt get handler
+server.addPromptGetHandler((name, arguments) -> {
+ if (name.equals("analyze")) {
+ String topic = arguments.getOrDefault("topic", "general");
+ String depth = arguments.getOrDefault("depth", "basic");
+
+ List messages = List.of(
+ PromptMessage.user("Please analyze this topic: " + topic),
+ PromptMessage.assistant("I'll provide a " + depth + " analysis of " + topic)
+ );
+
+ return Mono.just(PromptResult.builder()
+ .description("Analysis of " + topic + " at " + depth + " level")
+ .messages(messages)
+ .build());
+ }
+ throw new PromptNotFoundException(name);
+});
+```
+
+## Reactive Streams Pattern
+
+The Java SDK uses Reactive Streams (Project Reactor) for asynchronous processing:
+
+```java
+// Return Mono for single results
+server.addToolHandler("process", (args) -> {
+ return Mono.fromCallable(() -> {
+ String result = expensiveOperation(args);
+ return ToolResponse.success()
+ .addTextContent(result)
+ .build();
+ }).subscribeOn(Schedulers.boundedElastic());
+});
+
+// Return Flux for streaming results
+server.addResourceListHandler(() -> {
+ return Flux.fromIterable(getResources())
+ .map(r -> Resource.builder()
+ .uri(r.getUri())
+ .name(r.getName())
+ .build())
+ .collectList();
+});
+```
+
+## Synchronous Facade
+
+For blocking use cases, use the synchronous API:
+
+```java
+import io.mcp.server.McpSyncServer;
+
+McpSyncServer syncServer = server.toSyncServer();
+
+// Blocking tool handler
+syncServer.addToolHandler("greet", (args) -> {
+ String name = args.get("name").asText();
+ return ToolResponse.success()
+ .addTextContent("Hello, " + name + "!")
+ .build();
+});
+```
+
+## Transport Configuration
+
+### Stdio Transport
+
+For local subprocess communication:
+
+```java
+import io.mcp.server.transport.StdioServerTransport;
+
+StdioServerTransport transport = new StdioServerTransport();
+server.start(transport).block();
+```
+
+### HTTP Transport (Servlet)
+
+For HTTP-based servers:
+
+```java
+import io.mcp.server.transport.ServletServerTransport;
+import jakarta.servlet.http.HttpServlet;
+
+public class McpServlet extends HttpServlet {
+ private final McpServer server;
+ private final ServletServerTransport transport;
+
+ public McpServlet() {
+ this.server = createMcpServer();
+ this.transport = new ServletServerTransport();
+ }
+
+ @Override
+ protected void doPost(HttpServletRequest req, HttpServletResponse resp) {
+ transport.handleRequest(server, req, resp).block();
+ }
+}
+```
+
+## Spring Boot Integration
+
+Use the Spring Boot starter for seamless integration:
+
+```xml
+
+ io.modelcontextprotocol.sdk
+ mcp-spring-boot-starter
+ 0.14.1
+
+```
+
+Configure the server with Spring:
+
+```java
+import org.springframework.context.annotation.Configuration;
+import io.mcp.spring.McpServerConfigurer;
+
+@Configuration
+public class McpConfiguration {
+
+ @Bean
+ public McpServerConfigurer mcpServerConfigurer() {
+ return server -> server
+ .serverInfo("spring-server", "1.0.0")
+ .capabilities(cap -> cap
+ .tools(true)
+ .resources(true)
+ .prompts(true));
+ }
+}
+```
+
+Register handlers as Spring beans:
+
+```java
+import org.springframework.stereotype.Component;
+import io.mcp.spring.ToolHandler;
+
+@Component
+public class SearchToolHandler implements ToolHandler {
+
+ @Override
+ public String getName() {
+ return "search";
+ }
+
+ @Override
+ public Tool getTool() {
+ return Tool.builder()
+ .name("search")
+ .description("Search for information")
+ .inputSchema(JsonSchema.object()
+ .property("query", JsonSchema.string().required(true)))
+ .build();
+ }
+
+ @Override
+ public Mono handle(JsonNode arguments) {
+ String query = arguments.get("query").asText();
+ return Mono.just(ToolResponse.success()
+ .addTextContent("Search results for: " + query)
+ .build());
+ }
+}
+```
+
+## Error Handling
+
+Use proper error handling with MCP exceptions:
+
+```java
+server.addToolHandler("risky", (args) -> {
+ return Mono.fromCallable(() -> {
+ try {
+ String result = riskyOperation(args);
+ return ToolResponse.success()
+ .addTextContent(result)
+ .build();
+ } catch (ValidationException e) {
+ return ToolResponse.error()
+ .message("Invalid input: " + e.getMessage())
+ .build();
+ } catch (Exception e) {
+ log.error("Unexpected error", e);
+ return ToolResponse.error()
+ .message("Internal error occurred")
+ .build();
+ }
+ });
+});
+```
+
+## JSON Schema Construction
+
+Use the fluent schema builder:
+
+```java
+import io.mcp.json.JsonSchema;
+
+JsonSchema schema = JsonSchema.object()
+ .property("name", JsonSchema.string()
+ .description("User's name")
+ .minLength(1)
+ .maxLength(100)
+ .required(true))
+ .property("age", JsonSchema.integer()
+ .description("User's age")
+ .minimum(0)
+ .maximum(150))
+ .property("email", JsonSchema.string()
+ .description("Email address")
+ .format("email")
+ .required(true))
+ .property("tags", JsonSchema.array()
+ .items(JsonSchema.string())
+ .uniqueItems(true))
+ .additionalProperties(false)
+ .build();
+```
+
+## Logging and Observability
+
+Use SLF4J for logging:
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+private static final Logger log = LoggerFactory.getLogger(MyMcpServer.class);
+
+server.addToolHandler("process", (args) -> {
+ log.info("Tool called: process, args: {}", args);
+
+ return Mono.fromCallable(() -> {
+ String result = process(args);
+ log.debug("Processing completed successfully");
+ return ToolResponse.success()
+ .addTextContent(result)
+ .build();
+ }).doOnError(error -> {
+ log.error("Processing failed", error);
+ });
+});
+```
+
+Propagate context with Reactor:
+
+```java
+import reactor.util.context.Context;
+
+server.addToolHandler("traced", (args) -> {
+ return Mono.deferContextual(ctx -> {
+ String traceId = ctx.get("traceId");
+ log.info("Processing with traceId: {}", traceId);
+
+ return Mono.just(ToolResponse.success()
+ .addTextContent("Processed")
+ .build());
+ });
+});
+```
+
+## Testing
+
+Write tests using the synchronous API:
+
+```java
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.Assertions.assertThat;
+
+class McpServerTest {
+
+ @Test
+ void testToolHandler() {
+ McpServer server = createTestServer();
+ McpSyncServer syncServer = server.toSyncServer();
+
+ JsonNode args = objectMapper.createObjectNode()
+ .put("query", "test");
+
+ ToolResponse response = syncServer.callTool("search", args);
+
+ assertThat(response.isError()).isFalse();
+ assertThat(response.getContent()).hasSize(1);
+ }
+}
+```
+
+## Jackson Integration
+
+The SDK uses Jackson for JSON serialization. Customize as needed:
+
+```java
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+
+ObjectMapper mapper = new ObjectMapper();
+mapper.registerModule(new JavaTimeModule());
+
+// Use custom mapper with server
+McpServer server = McpServerBuilder.builder()
+ .objectMapper(mapper)
+ .build();
+```
+
+## Content Types
+
+Support multiple content types in responses:
+
+```java
+import io.mcp.server.content.Content;
+
+server.addToolHandler("multi", (args) -> {
+ return Mono.just(ToolResponse.success()
+ .addTextContent("Plain text response")
+ .addImageContent(imageBytes, "image/png")
+ .addResourceContent("resource://data", "application/json", jsonData)
+ .build());
+});
+```
+
+## Server Lifecycle
+
+Properly manage server lifecycle:
+
+```java
+import reactor.core.Disposable;
+
+Disposable serverDisposable = server.start(transport).subscribe();
+
+// Graceful shutdown
+Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+ log.info("Shutting down MCP server");
+ serverDisposable.dispose();
+ server.stop().block();
+}));
+```
+
+## Common Patterns
+
+### Request Validation
+
+```java
+server.addToolHandler("validate", (args) -> {
+ if (!args.has("required_field")) {
+ return Mono.just(ToolResponse.error()
+ .message("Missing required_field")
+ .build());
+ }
+
+ return processRequest(args);
+});
+```
+
+### Async Operations
+
+```java
+server.addToolHandler("async", (args) -> {
+ return Mono.fromCallable(() -> callExternalApi(args))
+ .timeout(Duration.ofSeconds(30))
+ .onErrorResume(TimeoutException.class, e ->
+ Mono.just(ToolResponse.error()
+ .message("Operation timed out")
+ .build()))
+ .subscribeOn(Schedulers.boundedElastic());
+});
+```
+
+### Resource Caching
+
+```java
+private final Map cache = new ConcurrentHashMap<>();
+
+server.addResourceReadHandler((uri) -> {
+ return Mono.fromCallable(() ->
+ cache.computeIfAbsent(uri, this::loadResource))
+ .map(content -> ResourceContent.text(content, uri));
+});
+```
+
+## Best Practices
+
+1. **Use Reactive Streams** for async operations and backpressure
+2. **Leverage Spring Boot** starter for enterprise applications
+3. **Implement proper error handling** with specific error messages
+4. **Use SLF4J** for logging, not System.out
+5. **Validate inputs** in tool and prompt handlers
+6. **Support graceful shutdown** with proper resource cleanup
+7. **Use bounded elastic scheduler** for blocking operations
+8. **Propagate context** for observability in reactive chains
+9. **Test with synchronous API** for simplicity
+10. **Follow Java naming conventions** (camelCase for methods, PascalCase for classes)
diff --git a/prompts/java-mcp-server-generator.prompt.md b/prompts/java-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..0d2b68d
--- /dev/null
+++ b/prompts/java-mcp-server-generator.prompt.md
@@ -0,0 +1,756 @@
+---
+description: 'Generate a complete Model Context Protocol server project in Java using the official MCP Java SDK with reactive streams and optional Spring Boot integration.'
+mode: agent
+---
+
+# Java MCP Server Generator
+
+Generate a complete, production-ready MCP server in Java using the official Java SDK with Maven or Gradle.
+
+## Project Generation
+
+When asked to create a Java MCP server, generate a complete project with this structure:
+
+```
+my-mcp-server/
+├── pom.xml (or build.gradle.kts)
+├── src/
+│ ├── main/
+│ │ ├── java/
+│ │ │ └── com/example/mcp/
+│ │ │ ├── McpServerApplication.java
+│ │ │ ├── config/
+│ │ │ │ └── ServerConfiguration.java
+│ │ │ ├── tools/
+│ │ │ │ ├── ToolDefinitions.java
+│ │ │ │ └── ToolHandlers.java
+│ │ │ ├── resources/
+│ │ │ │ ├── ResourceDefinitions.java
+│ │ │ │ └── ResourceHandlers.java
+│ │ │ └── prompts/
+│ │ │ ├── PromptDefinitions.java
+│ │ │ └── PromptHandlers.java
+│ │ └── resources/
+│ │ └── application.properties (if using Spring)
+│ └── test/
+│ └── java/
+│ └── com/example/mcp/
+│ └── McpServerTest.java
+└── README.md
+```
+
+## Maven pom.xml Template
+
+```xml
+
+
+ 4.0.0
+
+ com.example
+ my-mcp-server
+ 1.0.0
+ jar
+
+ My MCP Server
+ Model Context Protocol server implementation
+
+
+ 17
+ 17
+ 17
+ UTF-8
+ 0.14.1
+ 2.0.9
+ 1.4.11
+ 5.10.0
+
+
+
+
+
+ io.modelcontextprotocol.sdk
+ mcp
+ ${mcp.version}
+
+
+
+
+ org.slf4j
+ slf4j-api
+ ${slf4j.version}
+
+
+ ch.qos.logback
+ logback-classic
+ ${logback.version}
+
+
+
+
+ org.junit.jupiter
+ junit-jupiter
+ ${junit.version}
+ test
+
+
+ io.projectreactor
+ reactor-test
+ test
+
+
+
+
+
+
+ org.apache.maven.plugins
+ maven-compiler-plugin
+ 3.11.0
+
+
+ org.apache.maven.plugins
+ maven-surefire-plugin
+ 3.1.2
+
+
+ org.apache.maven.plugins
+ maven-shade-plugin
+ 3.5.0
+
+
+ package
+
+ shade
+
+
+
+
+ com.example.mcp.McpServerApplication
+
+
+
+
+
+
+
+
+
+```
+
+## Gradle build.gradle.kts Template
+
+```kotlin
+plugins {
+ id("java")
+ id("application")
+}
+
+group = "com.example"
+version = "1.0.0"
+
+java {
+ sourceCompatibility = JavaVersion.VERSION_17
+ targetCompatibility = JavaVersion.VERSION_17
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ // MCP Java SDK
+ implementation("io.modelcontextprotocol.sdk:mcp:0.14.1")
+
+ // Logging
+ implementation("org.slf4j:slf4j-api:2.0.9")
+ implementation("ch.qos.logback:logback-classic:1.4.11")
+
+ // Testing
+ testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
+ testImplementation("io.projectreactor:reactor-test:3.5.0")
+}
+
+application {
+ mainClass.set("com.example.mcp.McpServerApplication")
+}
+
+tasks.test {
+ useJUnitPlatform()
+}
+```
+
+## McpServerApplication.java Template
+
+```java
+package com.example.mcp;
+
+import com.example.mcp.tools.ToolHandlers;
+import com.example.mcp.resources.ResourceHandlers;
+import com.example.mcp.prompts.PromptHandlers;
+import io.mcp.server.McpServer;
+import io.mcp.server.McpServerBuilder;
+import io.mcp.server.transport.StdioServerTransport;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.Disposable;
+
+public class McpServerApplication {
+
+ private static final Logger log = LoggerFactory.getLogger(McpServerApplication.class);
+
+ public static void main(String[] args) {
+ log.info("Starting MCP Server...");
+
+ try {
+ McpServer server = createServer();
+ StdioServerTransport transport = new StdioServerTransport();
+
+ // Start server
+ Disposable serverDisposable = server.start(transport).subscribe();
+
+ // Graceful shutdown
+ Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+ log.info("Shutting down MCP server");
+ serverDisposable.dispose();
+ server.stop().block();
+ }));
+
+ log.info("MCP Server started successfully");
+
+ // Keep running
+ Thread.currentThread().join();
+
+ } catch (Exception e) {
+ log.error("Failed to start MCP server", e);
+ System.exit(1);
+ }
+ }
+
+ private static McpServer createServer() {
+ McpServer server = McpServerBuilder.builder()
+ .serverInfo("my-mcp-server", "1.0.0")
+ .capabilities(capabilities -> capabilities
+ .tools(true)
+ .resources(true)
+ .prompts(true))
+ .build();
+
+ // Register handlers
+ ToolHandlers.register(server);
+ ResourceHandlers.register(server);
+ PromptHandlers.register(server);
+
+ return server;
+ }
+}
+```
+
+## ToolDefinitions.java Template
+
+```java
+package com.example.mcp.tools;
+
+import io.mcp.json.JsonSchema;
+import io.mcp.server.tool.Tool;
+
+import java.util.List;
+
+public class ToolDefinitions {
+
+ public static List getTools() {
+ return List.of(
+ createGreetTool(),
+ createCalculateTool()
+ );
+ }
+
+ private static Tool createGreetTool() {
+ return Tool.builder()
+ .name("greet")
+ .description("Generate a greeting message")
+ .inputSchema(JsonSchema.object()
+ .property("name", JsonSchema.string()
+ .description("Name to greet")
+ .required(true)))
+ .build();
+ }
+
+ private static Tool createCalculateTool() {
+ return Tool.builder()
+ .name("calculate")
+ .description("Perform mathematical calculations")
+ .inputSchema(JsonSchema.object()
+ .property("operation", JsonSchema.string()
+ .description("Operation to perform")
+ .enumValues(List.of("add", "subtract", "multiply", "divide"))
+ .required(true))
+ .property("a", JsonSchema.number()
+ .description("First operand")
+ .required(true))
+ .property("b", JsonSchema.number()
+ .description("Second operand")
+ .required(true)))
+ .build();
+ }
+}
+```
+
+## ToolHandlers.java Template
+
+```java
+package com.example.mcp.tools;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import io.mcp.server.McpServer;
+import io.mcp.server.tool.ToolResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+public class ToolHandlers {
+
+ private static final Logger log = LoggerFactory.getLogger(ToolHandlers.class);
+
+ public static void register(McpServer server) {
+ // Register tool list handler
+ server.addToolListHandler(() -> {
+ log.debug("Listing available tools");
+ return Mono.just(ToolDefinitions.getTools());
+ });
+
+ // Register greet handler
+ server.addToolHandler("greet", ToolHandlers::handleGreet);
+
+ // Register calculate handler
+ server.addToolHandler("calculate", ToolHandlers::handleCalculate);
+ }
+
+ private static Mono handleGreet(JsonNode arguments) {
+ log.info("Greet tool called");
+
+ if (!arguments.has("name")) {
+ return Mono.just(ToolResponse.error()
+ .message("Missing 'name' parameter")
+ .build());
+ }
+
+ String name = arguments.get("name").asText();
+ String greeting = "Hello, " + name + "! Welcome to MCP.";
+
+ log.debug("Generated greeting for: {}", name);
+
+ return Mono.just(ToolResponse.success()
+ .addTextContent(greeting)
+ .build());
+ }
+
+ private static Mono handleCalculate(JsonNode arguments) {
+ log.info("Calculate tool called");
+
+ if (!arguments.has("operation") || !arguments.has("a") || !arguments.has("b")) {
+ return Mono.just(ToolResponse.error()
+ .message("Missing required parameters")
+ .build());
+ }
+
+ String operation = arguments.get("operation").asText();
+ double a = arguments.get("a").asDouble();
+ double b = arguments.get("b").asDouble();
+
+ double result;
+ switch (operation) {
+ case "add":
+ result = a + b;
+ break;
+ case "subtract":
+ result = a - b;
+ break;
+ case "multiply":
+ result = a * b;
+ break;
+ case "divide":
+ if (b == 0) {
+ return Mono.just(ToolResponse.error()
+ .message("Division by zero")
+ .build());
+ }
+ result = a / b;
+ break;
+ default:
+ return Mono.just(ToolResponse.error()
+ .message("Unknown operation: " + operation)
+ .build());
+ }
+
+ log.debug("Calculation: {} {} {} = {}", a, operation, b, result);
+
+ return Mono.just(ToolResponse.success()
+ .addTextContent("Result: " + result)
+ .build());
+ }
+}
+```
+
+## ResourceDefinitions.java Template
+
+```java
+package com.example.mcp.resources;
+
+import io.mcp.server.resource.Resource;
+
+import java.util.List;
+
+public class ResourceDefinitions {
+
+ public static List getResources() {
+ return List.of(
+ Resource.builder()
+ .name("Example Data")
+ .uri("resource://data/example")
+ .description("Example resource data")
+ .mimeType("application/json")
+ .build(),
+ Resource.builder()
+ .name("Configuration")
+ .uri("resource://config")
+ .description("Server configuration")
+ .mimeType("application/json")
+ .build()
+ );
+ }
+}
+```
+
+## ResourceHandlers.java Template
+
+```java
+package com.example.mcp.resources;
+
+import io.mcp.server.McpServer;
+import io.mcp.server.resource.ResourceContent;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class ResourceHandlers {
+
+ private static final Logger log = LoggerFactory.getLogger(ResourceHandlers.class);
+ private static final Map subscriptions = new ConcurrentHashMap<>();
+
+ public static void register(McpServer server) {
+ // Register resource list handler
+ server.addResourceListHandler(() -> {
+ log.debug("Listing available resources");
+ return Mono.just(ResourceDefinitions.getResources());
+ });
+
+ // Register resource read handler
+ server.addResourceReadHandler(ResourceHandlers::handleRead);
+
+ // Register resource subscribe handler
+ server.addResourceSubscribeHandler(ResourceHandlers::handleSubscribe);
+
+ // Register resource unsubscribe handler
+ server.addResourceUnsubscribeHandler(ResourceHandlers::handleUnsubscribe);
+ }
+
+ private static Mono handleRead(String uri) {
+ log.info("Reading resource: {}", uri);
+
+ switch (uri) {
+ case "resource://data/example":
+ String jsonData = String.format(
+ "{\"message\":\"Example resource data\",\"timestamp\":\"%s\"}",
+ Instant.now()
+ );
+ return Mono.just(ResourceContent.text(jsonData, uri, "application/json"));
+
+ case "resource://config":
+ String config = "{\"serverName\":\"my-mcp-server\",\"version\":\"1.0.0\"}";
+ return Mono.just(ResourceContent.text(config, uri, "application/json"));
+
+ default:
+ log.warn("Unknown resource requested: {}", uri);
+ return Mono.error(new IllegalArgumentException("Unknown resource URI: " + uri));
+ }
+ }
+
+ private static Mono handleSubscribe(String uri) {
+ log.info("Client subscribed to resource: {}", uri);
+ subscriptions.put(uri, true);
+ return Mono.empty();
+ }
+
+ private static Mono handleUnsubscribe(String uri) {
+ log.info("Client unsubscribed from resource: {}", uri);
+ subscriptions.remove(uri);
+ return Mono.empty();
+ }
+}
+```
+
+## PromptDefinitions.java Template
+
+```java
+package com.example.mcp.prompts;
+
+import io.mcp.server.prompt.Prompt;
+import io.mcp.server.prompt.PromptArgument;
+
+import java.util.List;
+
+public class PromptDefinitions {
+
+ public static List getPrompts() {
+ return List.of(
+ Prompt.builder()
+ .name("code-review")
+ .description("Generate a code review prompt")
+ .argument(PromptArgument.builder()
+ .name("language")
+ .description("Programming language")
+ .required(true)
+ .build())
+ .argument(PromptArgument.builder()
+ .name("focus")
+ .description("Review focus area")
+ .required(false)
+ .build())
+ .build()
+ );
+ }
+}
+```
+
+## PromptHandlers.java Template
+
+```java
+package com.example.mcp.prompts;
+
+import io.mcp.server.McpServer;
+import io.mcp.server.prompt.PromptMessage;
+import io.mcp.server.prompt.PromptResult;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+import java.util.Map;
+
+public class PromptHandlers {
+
+ private static final Logger log = LoggerFactory.getLogger(PromptHandlers.class);
+
+ public static void register(McpServer server) {
+ // Register prompt list handler
+ server.addPromptListHandler(() -> {
+ log.debug("Listing available prompts");
+ return Mono.just(PromptDefinitions.getPrompts());
+ });
+
+ // Register prompt get handler
+ server.addPromptGetHandler(PromptHandlers::handleCodeReview);
+ }
+
+ private static Mono handleCodeReview(String name, Map arguments) {
+ log.info("Getting prompt: {}", name);
+
+ if (!name.equals("code-review")) {
+ return Mono.error(new IllegalArgumentException("Unknown prompt: " + name));
+ }
+
+ String language = arguments.getOrDefault("language", "Java");
+ String focus = arguments.getOrDefault("focus", "general quality");
+
+ String description = "Code review for " + language + " with focus on " + focus;
+
+ List messages = List.of(
+ PromptMessage.user("Please review this " + language + " code with focus on " + focus + "."),
+ PromptMessage.assistant("I'll review the code focusing on " + focus + ". Please share the code."),
+ PromptMessage.user("Here's the code to review: [paste code here]")
+ );
+
+ log.debug("Generated code review prompt for {} ({})", language, focus);
+
+ return Mono.just(PromptResult.builder()
+ .description(description)
+ .messages(messages)
+ .build());
+ }
+}
+```
+
+## McpServerTest.java Template
+
+```java
+package com.example.mcp;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import io.mcp.server.McpServer;
+import io.mcp.server.McpSyncServer;
+import io.mcp.server.tool.ToolResponse;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class McpServerTest {
+
+ private McpSyncServer syncServer;
+ private ObjectMapper objectMapper;
+
+ @BeforeEach
+ void setUp() {
+ McpServer server = createTestServer();
+ syncServer = server.toSyncServer();
+ objectMapper = new ObjectMapper();
+ }
+
+ private McpServer createTestServer() {
+ // Same setup as main application
+ McpServer server = McpServerBuilder.builder()
+ .serverInfo("test-server", "1.0.0")
+ .capabilities(cap -> cap.tools(true))
+ .build();
+
+ // Register handlers
+ ToolHandlers.register(server);
+
+ return server;
+ }
+
+ @Test
+ void testGreetTool() {
+ ObjectNode args = objectMapper.createObjectNode();
+ args.put("name", "Java");
+
+ ToolResponse response = syncServer.callTool("greet", args);
+
+ assertFalse(response.isError());
+ assertEquals(1, response.getContent().size());
+ assertTrue(response.getContent().get(0).getText().contains("Java"));
+ }
+
+ @Test
+ void testCalculateTool() {
+ ObjectNode args = objectMapper.createObjectNode();
+ args.put("operation", "add");
+ args.put("a", 5);
+ args.put("b", 3);
+
+ ToolResponse response = syncServer.callTool("calculate", args);
+
+ assertFalse(response.isError());
+ assertTrue(response.getContent().get(0).getText().contains("8"));
+ }
+
+ @Test
+ void testDivideByZero() {
+ ObjectNode args = objectMapper.createObjectNode();
+ args.put("operation", "divide");
+ args.put("a", 10);
+ args.put("b", 0);
+
+ ToolResponse response = syncServer.callTool("calculate", args);
+
+ assertTrue(response.isError());
+ }
+}
+```
+
+## README.md Template
+
+```markdown
+# My MCP Server
+
+A Model Context Protocol server built with Java and the official MCP Java SDK.
+
+## Features
+
+- ✅ Tools: greet, calculate
+- ✅ Resources: example data, configuration
+- ✅ Prompts: code-review
+- ✅ Reactive Streams with Project Reactor
+- ✅ Structured logging with SLF4J
+- ✅ Full test coverage
+
+## Requirements
+
+- Java 17 or later
+- Maven 3.6+ or Gradle 7+
+
+## Build
+
+### Maven
+```bash
+mvn clean package
+```
+
+### Gradle
+```bash
+./gradlew build
+```
+
+## Run
+
+### Maven
+```bash
+java -jar target/my-mcp-server-1.0.0.jar
+```
+
+### Gradle
+```bash
+./gradlew run
+```
+
+## Testing
+
+### Maven
+```bash
+mvn test
+```
+
+### Gradle
+```bash
+./gradlew test
+```
+
+## Integration with Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "my-mcp-server": {
+ "command": "java",
+ "args": ["-jar", "/path/to/my-mcp-server-1.0.0.jar"]
+ }
+ }
+}
+```
+
+## License
+
+MIT
+```
+
+## Generation Instructions
+
+1. **Ask for project name and package**
+2. **Choose build tool** (Maven or Gradle)
+3. **Generate all files** with proper package structure
+4. **Use Reactive Streams** for async handlers
+5. **Include comprehensive logging** with SLF4J
+6. **Add tests** for all handlers
+7. **Follow Java conventions** (camelCase, PascalCase)
+8. **Include error handling** with proper responses
+9. **Document public APIs** with Javadoc
+10. **Provide both sync and async** examples
From 51b18a7577ec6e9d8b4e27cdc8fede2359183c7b Mon Sep 17 00:00:00 2001
From: Troy Simeon Taylor <44444967+troystaylor@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:12:10 -0400
Subject: [PATCH 8/8] Add Ruby MCP Server Development collection (#330)
- Add Ruby MCP server best practices instruction
- Add Ruby MCP server project generator prompt
- Add Ruby MCP expert chat mode
- Add Ruby MCP development collection manifest
- Update category READMEs
Features:
- Server setup with official mcp gem
- Tool/prompt/resource handlers with classes
- Rails controller integration
- Stdio and HTTP transport support
- Input/output schemas with validation
- Tool annotations for behavior hints
- Structured content in responses
- Exception reporting and instrumentation
- Minitest test examples
Co-authored-by: Aaron Powell
---
README.chatmodes.md | 1 +
README.collections.md | 1 +
README.instructions.md | 1 +
README.prompts.md | 1 +
chatmodes/ruby-mcp-expert.chatmode.md | 346 +++++++++
.../ruby-mcp-development.collection.yml | 35 +
collections/ruby-mcp-development.md | 41 ++
instructions/ruby-mcp-server.instructions.md | 629 +++++++++++++++++
prompts/ruby-mcp-server-generator.prompt.md | 660 ++++++++++++++++++
9 files changed, 1715 insertions(+)
create mode 100644 chatmodes/ruby-mcp-expert.chatmode.md
create mode 100644 collections/ruby-mcp-development.collection.yml
create mode 100644 collections/ruby-mcp-development.md
create mode 100644 instructions/ruby-mcp-server.instructions.md
create mode 100644 prompts/ruby-mcp-server-generator.prompt.md
diff --git a/README.chatmodes.md b/README.chatmodes.md
index 77dae5e..5a1738b 100644
--- a/README.chatmodes.md
+++ b/README.chatmodes.md
@@ -70,6 +70,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
| [Python MCP Server Expert](chatmodes/python-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fpython-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fpython-mcp-expert.chatmode.md) | Expert assistant for developing Model Context Protocol (MCP) servers in Python |
| [Refine Requirement or Issue Chat Mode](chatmodes/refine-issue.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frefine-issue.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frefine-issue.chatmode.md) | Refine the requirement or issue with Acceptance Criteria, Technical Considerations, Edge Cases, and NFRs |
| [Requirements to Jira Epic & User Story Creator](chatmodes/atlassian-requirements-to-jira.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fatlassian-requirements-to-jira.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fatlassian-requirements-to-jira.chatmode.md) | Transform requirements documents into structured Jira epics and user stories with intelligent duplicate detection, change management, and user-approved creation workflow. |
+| [Ruby MCP Expert](chatmodes/ruby-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fruby-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fruby-mcp-expert.chatmode.md) | Expert assistance for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration. |
| [Rust Beast Mode](chatmodes/rust-gpt-4.1-beast-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frust-gpt-4.1-beast-mode.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Frust-gpt-4.1-beast-mode.chatmode.md) | Rust GPT-4.1 Coding Beast Mode for VS Code |
| [Semantic Kernel .NET mode instructions](chatmodes/semantic-kernel-dotnet.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsemantic-kernel-dotnet.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsemantic-kernel-dotnet.chatmode.md) | Create, update, refactor, explain or work with code using the .NET version of Semantic Kernel. |
| [Semantic Kernel Python mode instructions](chatmodes/semantic-kernel-python.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsemantic-kernel-python.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fsemantic-kernel-python.chatmode.md) | Create, update, refactor, explain or work with code using the Python version of Semantic Kernel. |
diff --git a/README.collections.md b/README.collections.md
index 60fc4e5..fad0283 100644
--- a/README.collections.md
+++ b/README.collections.md
@@ -31,6 +31,7 @@ Curated collections of related prompts, instructions, and chat modes organized a
| [Power Platform MCP Connector Development](collections/power-platform-mcp-connector-development.md) | Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio | 4 items | power-platform, mcp, copilot-studio, custom-connector, json-rpc |
| [Project Planning & Management](collections/project-planning.md) | Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization for development teams. | 17 items | planning, project-management, epic, feature, implementation, task, architecture, technical-spike |
| [Python MCP Server Development](collections/python-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | python, mcp, model-context-protocol, fastmcp, server-development |
+| [Ruby MCP Server Development](collections/ruby-mcp-development.md) | 'Complete toolkit for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration support.' | 3 items | ruby, mcp, model-context-protocol, server-development, sdk, rails, gem |
| [Security & Code Quality](collections/security-best-practices.md) | Security frameworks, accessibility guidelines, performance optimization, and code quality best practices for building secure, maintainable, and high-performance applications. | 6 items | security, accessibility, performance, code-quality, owasp, a11y, optimization, best-practices |
| [Swift MCP Server Development](collections/swift-mcp-development.md) | 'Comprehensive collection for building Model Context Protocol servers in Swift using the official MCP Swift SDK with modern concurrency features.' | 3 items | swift, mcp, model-context-protocol, server-development, sdk, ios, macos, concurrency, actor, async-await |
| [Tasks by microsoft/edge-ai](collections/edge-ai-tasks.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 3 items | architecture, planning, research, tasks, implementation |
diff --git a/README.instructions.md b/README.instructions.md
index c772e96..633fe87 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -97,6 +97,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Quarkus](instructions/quarkus.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus.instructions.md) | Quarkus development standards and instructions |
| [Quarkus MCP Server](instructions/quarkus-mcp-server-sse.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus-mcp-server-sse.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus-mcp-server-sse.instructions.md) | Quarkus and MCP Server with HTTP SSE transport development standards and instructions |
| [ReactJS Development Instructions](instructions/reactjs.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Freactjs.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Freactjs.instructions.md) | ReactJS development standards and best practices |
+| [Ruby MCP Server Development Guidelines](instructions/ruby-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Ruby using the official MCP Ruby SDK gem. |
| [Ruby on Rails](instructions/ruby-on-rails.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-on-rails.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-on-rails.instructions.md) | Ruby on Rails coding conventions and guidelines |
| [Rust Coding Conventions and Best Practices](instructions/rust.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust.instructions.md) | Rust programming language coding conventions and best practices |
| [Secure Coding and OWASP Guidelines](instructions/security-and-owasp.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md) | Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices. |
diff --git a/README.prompts.md b/README.prompts.md
index a20c912..df47979 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -98,6 +98,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Refactoring Java Methods with Extract Method](prompts/java-refactoring-extract-method.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-refactoring-extract-method.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-refactoring-extract-method.prompt.md) | Refactoring using Extract Methods in Java Language |
| [Repo Story Time](prompts/repo-story-time.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frepo-story-time.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frepo-story-time.prompt.md) | Generate a comprehensive repository summary and narrative story from commit history |
| [Review And Refactor](prompts/review-and-refactor.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freview-and-refactor.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freview-and-refactor.prompt.md) | Review and refactor code in your project according to defined instructions |
+| [Ruby MCP Server Generator](prompts/ruby-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fruby-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fruby-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Ruby using the official MCP Ruby SDK gem. |
| [Shuffle JSON Data](prompts/shuffle-json-data.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshuffle-json-data.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshuffle-json-data.prompt.md) | Shuffle repetitive JSON objects safely by validating schema consistency before randomising entries. |
| [Spring Boot Best Practices](prompts/java-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) | Get best practices for developing applications with Spring Boot. |
| [Spring Boot with Kotlin Best Practices](prompts/kotlin-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md) | Get best practices for developing applications with Spring Boot and Kotlin. |
diff --git a/chatmodes/ruby-mcp-expert.chatmode.md b/chatmodes/ruby-mcp-expert.chatmode.md
new file mode 100644
index 0000000..db3a34d
--- /dev/null
+++ b/chatmodes/ruby-mcp-expert.chatmode.md
@@ -0,0 +1,346 @@
+---
+description: 'Expert assistance for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration.'
+model: GPT-4.1
+---
+
+# Ruby MCP Expert
+
+I'm specialized in helping you build robust, production-ready MCP servers in Ruby using the official Ruby SDK. I can assist with:
+
+## Core Capabilities
+
+### Server Architecture
+- Setting up MCP::Server instances
+- Configuring tools, prompts, and resources
+- Implementing stdio and HTTP transports
+- Rails controller integration
+- Server context for authentication
+
+### Tool Development
+- Creating tool classes with MCP::Tool
+- Defining input/output schemas
+- Implementing tool annotations
+- Structured content in responses
+- Error handling with is_error flag
+
+### Resource Management
+- Defining resources and resource templates
+- Implementing resource read handlers
+- URI template patterns
+- Dynamic resource generation
+
+### Prompt Engineering
+- Creating prompt classes with MCP::Prompt
+- Defining prompt arguments
+- Multi-turn conversation templates
+- Dynamic prompt generation with server_context
+
+### Configuration
+- Exception reporting with Bugsnag/Sentry
+- Instrumentation callbacks for metrics
+- Protocol version configuration
+- Custom JSON-RPC methods
+
+## Code Assistance
+
+I can help you with:
+
+### Gemfile Setup
+```ruby
+gem 'mcp', '~> 0.4.0'
+```
+
+### Server Creation
+```ruby
+server = MCP::Server.new(
+ name: 'my_server',
+ version: '1.0.0',
+ tools: [MyTool],
+ prompts: [MyPrompt],
+ server_context: { user_id: current_user.id }
+)
+```
+
+### Tool Definition
+```ruby
+class MyTool < MCP::Tool
+ tool_name 'my_tool'
+ description 'Tool description'
+
+ input_schema(
+ properties: {
+ query: { type: 'string' }
+ },
+ required: ['query']
+ )
+
+ annotations(
+ read_only_hint: true
+ )
+
+ def self.call(query:, server_context:)
+ MCP::Tool::Response.new([{
+ type: 'text',
+ text: 'Result'
+ }])
+ end
+end
+```
+
+### Stdio Transport
+```ruby
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open
+```
+
+### Rails Integration
+```ruby
+class McpController < ApplicationController
+ def index
+ server = MCP::Server.new(
+ name: 'rails_server',
+ tools: [MyTool],
+ server_context: { user_id: current_user.id }
+ )
+ render json: server.handle_json(request.body.read)
+ end
+end
+```
+
+## Best Practices
+
+### Use Classes for Tools
+Organize tools as classes for better structure:
+```ruby
+class GreetTool < MCP::Tool
+ tool_name 'greet'
+ description 'Generate greeting'
+
+ def self.call(name:, server_context:)
+ MCP::Tool::Response.new([{
+ type: 'text',
+ text: "Hello, #{name}!"
+ }])
+ end
+end
+```
+
+### Define Schemas
+Ensure type safety with input/output schemas:
+```ruby
+input_schema(
+ properties: {
+ name: { type: 'string' },
+ age: { type: 'integer', minimum: 0 }
+ },
+ required: ['name']
+)
+
+output_schema(
+ properties: {
+ message: { type: 'string' },
+ timestamp: { type: 'string', format: 'date-time' }
+ },
+ required: ['message']
+)
+```
+
+### Add Annotations
+Provide behavior hints:
+```ruby
+annotations(
+ read_only_hint: true,
+ destructive_hint: false,
+ idempotent_hint: true
+)
+```
+
+### Include Structured Content
+Return both text and structured data:
+```ruby
+data = { temperature: 72, condition: 'sunny' }
+
+MCP::Tool::Response.new(
+ [{ type: 'text', text: data.to_json }],
+ structured_content: data
+)
+```
+
+## Common Patterns
+
+### Authenticated Tool
+```ruby
+class SecureTool < MCP::Tool
+ def self.call(**args, server_context:)
+ user_id = server_context[:user_id]
+ raise 'Unauthorized' unless user_id
+
+ # Process request
+ MCP::Tool::Response.new([{
+ type: 'text',
+ text: 'Success'
+ }])
+ end
+end
+```
+
+### Error Handling
+```ruby
+def self.call(data:, server_context:)
+ begin
+ result = process(data)
+ MCP::Tool::Response.new([{
+ type: 'text',
+ text: result
+ }])
+ rescue ValidationError => e
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: e.message }],
+ is_error: true
+ )
+ end
+end
+```
+
+### Resource Handler
+```ruby
+server.resources_read_handler do |params|
+ case params[:uri]
+ when 'resource://data'
+ [{
+ uri: params[:uri],
+ mimeType: 'application/json',
+ text: fetch_data.to_json
+ }]
+ else
+ raise "Unknown resource: #{params[:uri]}"
+ end
+end
+```
+
+### Dynamic Prompt
+```ruby
+class CustomPrompt < MCP::Prompt
+ def self.template(args, server_context:)
+ user_id = server_context[:user_id]
+ user = User.find(user_id)
+
+ MCP::Prompt::Result.new(
+ description: "Prompt for #{user.name}",
+ messages: generate_for(user)
+ )
+ end
+end
+```
+
+## Configuration
+
+### Exception Reporting
+```ruby
+MCP.configure do |config|
+ config.exception_reporter = ->(exception, context) {
+ Bugsnag.notify(exception) do |report|
+ report.add_metadata(:mcp, context)
+ end
+ }
+end
+```
+
+### Instrumentation
+```ruby
+MCP.configure do |config|
+ config.instrumentation_callback = ->(data) {
+ StatsD.timing("mcp.#{data[:method]}", data[:duration])
+ }
+end
+```
+
+### Custom Methods
+```ruby
+server.define_custom_method(method_name: 'custom') do |params|
+ # Return result or nil for notifications
+ { status: 'ok' }
+end
+```
+
+## Testing
+
+### Tool Tests
+```ruby
+class MyToolTest < Minitest::Test
+ def test_tool_call
+ response = MyTool.call(
+ query: 'test',
+ server_context: {}
+ )
+
+ refute response.is_error
+ assert_equal 1, response.content.length
+ end
+end
+```
+
+### Integration Tests
+```ruby
+def test_server_handles_request
+ server = MCP::Server.new(
+ name: 'test',
+ tools: [MyTool]
+ )
+
+ request = {
+ jsonrpc: '2.0',
+ id: '1',
+ method: 'tools/call',
+ params: {
+ name: 'my_tool',
+ arguments: { query: 'test' }
+ }
+ }.to_json
+
+ response = JSON.parse(server.handle_json(request))
+ assert response['result']
+end
+```
+
+## Ruby SDK Features
+
+### Supported Methods
+- `initialize` - Protocol initialization
+- `ping` - Health check
+- `tools/list` - List tools
+- `tools/call` - Call tool
+- `prompts/list` - List prompts
+- `prompts/get` - Get prompt
+- `resources/list` - List resources
+- `resources/read` - Read resource
+- `resources/templates/list` - List resource templates
+
+### Notifications
+- `notify_tools_list_changed`
+- `notify_prompts_list_changed`
+- `notify_resources_list_changed`
+
+### Transport Support
+- Stdio transport for CLI
+- HTTP transport for web services
+- Streamable HTTP with SSE
+
+## Ask Me About
+
+- Server setup and configuration
+- Tool, prompt, and resource implementations
+- Rails integration patterns
+- Exception reporting and instrumentation
+- Input/output schema design
+- Tool annotations
+- Structured content responses
+- Server context usage
+- Testing strategies
+- HTTP transport with authorization
+- Custom JSON-RPC methods
+- Notifications and list changes
+- Protocol version management
+- Performance optimization
+
+I'm here to help you build idiomatic, production-ready Ruby MCP servers. What would you like to work on?
diff --git a/collections/ruby-mcp-development.collection.yml b/collections/ruby-mcp-development.collection.yml
new file mode 100644
index 0000000..fbf65b8
--- /dev/null
+++ b/collections/ruby-mcp-development.collection.yml
@@ -0,0 +1,35 @@
+id: ruby-mcp-development
+name: Ruby MCP Server Development
+description: 'Complete toolkit for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration support.'
+tags: [ruby, mcp, model-context-protocol, server-development, sdk, rails, gem]
+items:
+ - path: instructions/ruby-mcp-server.instructions.md
+ kind: instruction
+ - path: prompts/ruby-mcp-server-generator.prompt.md
+ kind: prompt
+ - path: chatmodes/ruby-mcp-expert.chatmode.md
+ kind: chat-mode
+ usage: |
+ recommended
+
+ This chat mode provides expert guidance for building MCP servers in Ruby.
+
+ This chat mode is ideal for:
+ - Creating new MCP server projects with Ruby
+ - Implementing tools, prompts, and resources
+ - Setting up stdio or HTTP transports
+ - Debugging schema definitions and error handling
+ - Learning Ruby MCP best practices with the official SDK
+ - Integrating with Rails applications
+
+ To get the best results, consider:
+ - Using the instruction file to set context for Ruby MCP development
+ - Using the prompt to generate initial project structure
+ - Switching to the expert chat mode for detailed implementation help
+ - Specifying whether you need stdio or Rails integration
+ - Providing details about what tools or functionality you need
+ - Mentioning if you need authentication or server_context usage
+
+display:
+ ordering: manual
+ show_badge: true
diff --git a/collections/ruby-mcp-development.md b/collections/ruby-mcp-development.md
new file mode 100644
index 0000000..4fcaa07
--- /dev/null
+++ b/collections/ruby-mcp-development.md
@@ -0,0 +1,41 @@
+# Ruby MCP Server Development
+
+'Complete toolkit for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration support.'
+
+**Tags:** ruby, mcp, model-context-protocol, server-development, sdk, rails, gem
+
+## Items in this Collection
+
+| Title | Type | Description |
+| ----- | ---- | ----------- |
+| [Ruby MCP Server Development Guidelines](../instructions/ruby-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-mcp-server.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-mcp-server.instructions.md) | Instruction | Best practices and patterns for building Model Context Protocol (MCP) servers in Ruby using the official MCP Ruby SDK gem. |
+| [Ruby MCP Server Generator](../prompts/ruby-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fruby-mcp-server-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fruby-mcp-server-generator.prompt.md) | Prompt | Generate a complete Model Context Protocol server project in Ruby using the official MCP Ruby SDK gem. |
+| [Ruby MCP Expert](../chatmodes/ruby-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fruby-mcp-expert.chatmode.md)
[](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fchatmodes%2Fruby-mcp-expert.chatmode.md) | Chat Mode | Expert assistance for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration. [see usage](#ruby-mcp-expert) |
+
+## Collection Usage
+
+### Ruby MCP Expert
+
+recommended
+
+This chat mode provides expert guidance for building MCP servers in Ruby.
+
+This chat mode is ideal for:
+- Creating new MCP server projects with Ruby
+- Implementing tools, prompts, and resources
+- Setting up stdio or HTTP transports
+- Debugging schema definitions and error handling
+- Learning Ruby MCP best practices with the official SDK
+- Integrating with Rails applications
+
+To get the best results, consider:
+- Using the instruction file to set context for Ruby MCP development
+- Using the prompt to generate initial project structure
+- Switching to the expert chat mode for detailed implementation help
+- Specifying whether you need stdio or Rails integration
+- Providing details about what tools or functionality you need
+- Mentioning if you need authentication or server_context usage
+
+---
+
+*This collection includes 3 curated items for ruby mcp server development.*
\ No newline at end of file
diff --git a/instructions/ruby-mcp-server.instructions.md b/instructions/ruby-mcp-server.instructions.md
new file mode 100644
index 0000000..a6aca89
--- /dev/null
+++ b/instructions/ruby-mcp-server.instructions.md
@@ -0,0 +1,629 @@
+---
+description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Ruby using the official MCP Ruby SDK gem.'
+applyTo: "**/*.rb, **/Gemfile, **/*.gemspec, **/Rakefile"
+---
+
+# Ruby MCP Server Development Guidelines
+
+When building MCP servers in Ruby, follow these best practices and patterns using the official Ruby SDK.
+
+## Installation
+
+Add the MCP gem to your Gemfile:
+
+```ruby
+gem 'mcp'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Server Setup
+
+Create an MCP server instance:
+
+```ruby
+require 'mcp'
+
+server = MCP::Server.new(
+ name: 'my_server',
+ version: '1.0.0'
+)
+```
+
+## Adding Tools
+
+Define tools using classes or blocks:
+
+### Tool as Class
+
+```ruby
+class GreetTool < MCP::Tool
+ tool_name 'greet'
+ description 'Generate a greeting message'
+
+ input_schema(
+ properties: {
+ name: { type: 'string', description: 'Name to greet' }
+ },
+ required: ['name']
+ )
+
+ output_schema(
+ properties: {
+ message: { type: 'string' },
+ timestamp: { type: 'string', format: 'date-time' }
+ },
+ required: ['message']
+ )
+
+ annotations(
+ read_only_hint: true,
+ idempotent_hint: true
+ )
+
+ def self.call(name:, server_context:)
+ MCP::Tool::Response.new([{
+ type: 'text',
+ text: "Hello, #{name}! Welcome to MCP."
+ }], structured_content: {
+ message: "Hello, #{name}!",
+ timestamp: Time.now.iso8601
+ })
+ end
+end
+
+server = MCP::Server.new(
+ name: 'my_server',
+ tools: [GreetTool]
+)
+```
+
+### Tool with Block
+
+```ruby
+server.define_tool(
+ name: 'calculate',
+ description: 'Perform mathematical calculations',
+ input_schema: {
+ properties: {
+ operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
+ a: { type: 'number' },
+ b: { type: 'number' }
+ },
+ required: ['operation', 'a', 'b']
+ },
+ annotations: {
+ read_only_hint: true,
+ idempotent_hint: true
+ }
+) do |args, server_context|
+ operation = args['operation']
+ a = args['a']
+ b = args['b']
+
+ result = case operation
+ when 'add' then a + b
+ when 'subtract' then a - b
+ when 'multiply' then a * b
+ when 'divide'
+ return MCP::Tool::Response.new([{ type: 'text', text: 'Division by zero' }], is_error: true) if b == 0
+ a / b
+ else
+ return MCP::Tool::Response.new([{ type: 'text', text: "Unknown operation: #{operation}" }], is_error: true)
+ end
+
+ MCP::Tool::Response.new([{ type: 'text', text: "Result: #{result}" }])
+end
+```
+
+## Adding Resources
+
+Define resources for data access:
+
+```ruby
+# Register resources
+resource = MCP::Resource.new(
+ uri: 'resource://data/example',
+ name: 'example-data',
+ description: 'Example resource data',
+ mime_type: 'application/json'
+)
+
+server = MCP::Server.new(
+ name: 'my_server',
+ resources: [resource]
+)
+
+# Define read handler
+server.resources_read_handler do |params|
+ case params[:uri]
+ when 'resource://data/example'
+ [{
+ uri: params[:uri],
+ mimeType: 'application/json',
+ text: { message: 'Example data', timestamp: Time.now }.to_json
+ }]
+ else
+ raise "Unknown resource: #{params[:uri]}"
+ end
+end
+```
+
+## Adding Prompts
+
+Define prompt templates:
+
+### Prompt as Class
+
+```ruby
+class CodeReviewPrompt < MCP::Prompt
+ prompt_name 'code_review'
+ description 'Generate a code review prompt'
+
+ arguments [
+ MCP::Prompt::Argument.new(
+ name: 'language',
+ description: 'Programming language',
+ required: true
+ ),
+ MCP::Prompt::Argument.new(
+ name: 'focus',
+ description: 'Review focus area',
+ required: false
+ )
+ ]
+
+ def self.template(args, server_context:)
+ language = args['language'] || 'Ruby'
+ focus = args['focus'] || 'general quality'
+
+ MCP::Prompt::Result.new(
+ description: "Code review for #{language} with focus on #{focus}",
+ messages: [
+ MCP::Prompt::Message.new(
+ role: 'user',
+ content: MCP::Content::Text.new("Please review this #{language} code with focus on #{focus}.")
+ ),
+ MCP::Prompt::Message.new(
+ role: 'assistant',
+ content: MCP::Content::Text.new("I'll review the code focusing on #{focus}. Please share the code.")
+ )
+ ]
+ )
+ end
+end
+
+server = MCP::Server.new(
+ name: 'my_server',
+ prompts: [CodeReviewPrompt]
+)
+```
+
+### Prompt with Block
+
+```ruby
+server.define_prompt(
+ name: 'analyze',
+ description: 'Analyze a topic',
+ arguments: [
+ MCP::Prompt::Argument.new(name: 'topic', description: 'Topic to analyze', required: true),
+ MCP::Prompt::Argument.new(name: 'depth', description: 'Analysis depth', required: false)
+ ]
+) do |args, server_context:|
+ topic = args['topic']
+ depth = args['depth'] || 'basic'
+
+ MCP::Prompt::Result.new(
+ description: "Analysis of #{topic} at #{depth} level",
+ messages: [
+ MCP::Prompt::Message.new(
+ role: 'user',
+ content: MCP::Content::Text.new("Please analyze: #{topic}")
+ ),
+ MCP::Prompt::Message.new(
+ role: 'assistant',
+ content: MCP::Content::Text.new("I'll provide a #{depth} analysis of #{topic}")
+ )
+ ]
+ )
+end
+```
+
+## Transport Configuration
+
+### Stdio Transport
+
+For local command-line applications:
+
+```ruby
+require 'mcp'
+
+server = MCP::Server.new(
+ name: 'my_server',
+ tools: [MyTool]
+)
+
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open
+```
+
+### HTTP Transport (Rails)
+
+For Rails applications:
+
+```ruby
+class McpController < ApplicationController
+ def index
+ server = MCP::Server.new(
+ name: 'rails_server',
+ version: '1.0.0',
+ tools: [SomeTool],
+ prompts: [MyPrompt],
+ server_context: { user_id: current_user.id }
+ )
+
+ render json: server.handle_json(request.body.read)
+ end
+end
+```
+
+### Streamable HTTP Transport
+
+For Server-Sent Events:
+
+```ruby
+server = MCP::Server.new(name: 'my_server')
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+# When tools change, notify clients
+server.define_tool(name: 'new_tool') { |**args| { result: 'ok' } }
+server.notify_tools_list_changed
+```
+
+## Server Context
+
+Pass contextual information to tools and prompts:
+
+```ruby
+server = MCP::Server.new(
+ name: 'my_server',
+ tools: [AuthenticatedTool],
+ server_context: {
+ user_id: current_user.id,
+ request_id: request.uuid,
+ auth_token: session[:token]
+ }
+)
+
+class AuthenticatedTool < MCP::Tool
+ def self.call(query:, server_context:)
+ user_id = server_context[:user_id]
+ # Use user_id for authorization
+
+ MCP::Tool::Response.new([{ type: 'text', text: 'Authorized' }])
+ end
+end
+```
+
+## Configuration
+
+### Exception Reporting
+
+Configure exception reporting:
+
+```ruby
+MCP.configure do |config|
+ config.exception_reporter = ->(exception, server_context) {
+ # Report to your error tracking service
+ Bugsnag.notify(exception) do |report|
+ report.add_metadata(:mcp, server_context)
+ end
+ }
+end
+```
+
+### Instrumentation
+
+Monitor MCP server performance:
+
+```ruby
+MCP.configure do |config|
+ config.instrumentation_callback = ->(data) {
+ # Log instrumentation data
+ Rails.logger.info("MCP: #{data.inspect}")
+
+ # Or send to metrics service
+ StatsD.timing("mcp.#{data[:method]}.duration", data[:duration])
+ StatsD.increment("mcp.#{data[:method]}.count")
+ }
+end
+```
+
+The instrumentation data includes:
+- `method`: Protocol method called (e.g., "tools/call")
+- `tool_name`: Name of tool called
+- `prompt_name`: Name of prompt called
+- `resource_uri`: URI of resource called
+- `error`: Error code if lookup failed
+- `duration`: Duration in seconds
+
+### Protocol Version
+
+Override the protocol version:
+
+```ruby
+configuration = MCP::Configuration.new(protocol_version: '2025-06-18')
+server = MCP::Server.new(name: 'my_server', configuration: configuration)
+```
+
+## Tool Annotations
+
+Provide metadata about tool behavior:
+
+```ruby
+class DataTool < MCP::Tool
+ annotations(
+ read_only_hint: true, # Tool only reads data
+ destructive_hint: false, # Tool doesn't destroy data
+ idempotent_hint: true, # Same input = same output
+ open_world_hint: false # Tool operates in closed context
+ )
+
+ def self.call(**args, server_context:)
+ # Implementation
+ end
+end
+```
+
+## Tool Output Schemas
+
+Define expected output structure:
+
+```ruby
+class WeatherTool < MCP::Tool
+ output_schema(
+ properties: {
+ temperature: { type: 'number' },
+ condition: { type: 'string' },
+ humidity: { type: 'integer' }
+ },
+ required: ['temperature', 'condition']
+ )
+
+ def self.call(location:, server_context:)
+ weather_data = {
+ temperature: 72.5,
+ condition: 'sunny',
+ humidity: 45
+ }
+
+ # Validate against schema
+ output_schema.validate_result(weather_data)
+
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: weather_data.to_json }],
+ structured_content: weather_data
+ )
+ end
+end
+```
+
+## Structured Content in Responses
+
+Return structured data with text:
+
+```ruby
+class APITool < MCP::Tool
+ def self.call(endpoint:, server_context:)
+ api_data = call_api(endpoint)
+
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: api_data.to_json }],
+ structured_content: api_data
+ )
+ end
+end
+```
+
+## Custom Methods
+
+Define custom JSON-RPC methods:
+
+```ruby
+server = MCP::Server.new(name: 'my_server')
+
+# Custom method with result
+server.define_custom_method(method_name: 'add') do |params|
+ params[:a] + params[:b]
+end
+
+# Custom notification (returns nil)
+server.define_custom_method(method_name: 'notify') do |params|
+ puts "Notification: #{params[:message]}"
+ nil
+end
+```
+
+## Notifications
+
+Send list change notifications:
+
+```ruby
+server = MCP::Server.new(name: 'my_server')
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+# Notify when tools change
+server.define_tool(name: 'new_tool') { |**args| { result: 'ok' } }
+server.notify_tools_list_changed
+
+# Notify when prompts change
+server.define_prompt(name: 'new_prompt') { |args, **_| MCP::Prompt::Result.new(...) }
+server.notify_prompts_list_changed
+
+# Notify when resources change
+server.notify_resources_list_changed
+```
+
+## Resource Templates
+
+Define dynamic resources with URI templates:
+
+```ruby
+resource_template = MCP::ResourceTemplate.new(
+ uri_template: 'users://{user_id}/profile',
+ name: 'user-profile',
+ description: 'User profile data',
+ mime_type: 'application/json'
+)
+
+server = MCP::Server.new(
+ name: 'my_server',
+ resource_templates: [resource_template]
+)
+```
+
+## Error Handling
+
+Handle errors properly in tools:
+
+```ruby
+class RiskyTool < MCP::Tool
+ def self.call(data:, server_context:)
+ begin
+ result = risky_operation(data)
+ MCP::Tool::Response.new([{ type: 'text', text: result }])
+ rescue ValidationError => e
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: "Invalid input: #{e.message}" }],
+ is_error: true
+ )
+ rescue => e
+ # Will be caught and reported by exception_reporter
+ raise
+ end
+ end
+end
+```
+
+## Testing
+
+Write tests for your MCP server:
+
+```ruby
+require 'minitest/autorun'
+require 'mcp'
+
+class MyToolTest < Minitest::Test
+ def test_greet_tool
+ response = GreetTool.call(name: 'Ruby', server_context: {})
+
+ assert_equal 1, response.content.length
+ assert_match(/Ruby/, response.content.first[:text])
+ refute response.is_error
+ end
+
+ def test_invalid_input
+ response = CalculateTool.call(operation: 'divide', a: 10, b: 0, server_context: {})
+
+ assert response.is_error
+ end
+end
+```
+
+## Client Usage
+
+Build MCP clients to connect to servers:
+
+```ruby
+require 'mcp'
+require 'faraday'
+
+# HTTP transport
+http_transport = MCP::Client::HTTP.new(
+ url: 'https://api.example.com/mcp',
+ headers: { 'Authorization' => "Bearer #{token}" }
+)
+
+client = MCP::Client.new(transport: http_transport)
+
+# List tools
+tools = client.tools
+tools.each do |tool|
+ puts "Tool: #{tool.name}"
+ puts "Description: #{tool.description}"
+end
+
+# Call a tool
+response = client.call_tool(
+ tool: tools.first,
+ arguments: { message: 'Hello, world!' }
+)
+```
+
+## Best Practices
+
+1. **Use classes for complex tools** - Better organization and testability
+2. **Define input/output schemas** - Ensure type safety and validation
+3. **Add annotations** - Help clients understand tool behavior
+4. **Include structured content** - Provide both text and structured data
+5. **Use server_context** - Pass authentication and request context
+6. **Configure exception reporting** - Monitor errors in production
+7. **Implement instrumentation** - Track performance metrics
+8. **Send notifications** - Keep clients updated on changes
+9. **Validate inputs** - Check parameters before processing
+10. **Follow Ruby conventions** - Use snake_case, proper indentation
+
+## Common Patterns
+
+### Authenticated Tool
+
+```ruby
+class AuthenticatedTool < MCP::Tool
+ def self.call(**args, server_context:)
+ user_id = server_context[:user_id]
+ raise 'Unauthorized' unless user_id
+
+ # Process authenticated request
+ MCP::Tool::Response.new([{ type: 'text', text: 'Success' }])
+ end
+end
+```
+
+### Paginated Resource
+
+```ruby
+server.resources_read_handler do |params|
+ uri = params[:uri]
+ page = params[:page] || 1
+
+ data = fetch_paginated_data(page)
+
+ [{
+ uri: uri,
+ mimeType: 'application/json',
+ text: data.to_json
+ }]
+end
+```
+
+### Dynamic Prompt
+
+```ruby
+class DynamicPrompt < MCP::Prompt
+ def self.template(args, server_context:)
+ user_id = server_context[:user_id]
+ user_data = User.find(user_id)
+
+ MCP::Prompt::Result.new(
+ description: "Personalized prompt for #{user_data.name}",
+ messages: generate_messages_for(user_data)
+ )
+ end
+end
+```
diff --git a/prompts/ruby-mcp-server-generator.prompt.md b/prompts/ruby-mcp-server-generator.prompt.md
new file mode 100644
index 0000000..0dee38d
--- /dev/null
+++ b/prompts/ruby-mcp-server-generator.prompt.md
@@ -0,0 +1,660 @@
+---
+description: 'Generate a complete Model Context Protocol server project in Ruby using the official MCP Ruby SDK gem.'
+mode: agent
+---
+
+# Ruby MCP Server Generator
+
+Generate a complete, production-ready MCP server in Ruby using the official Ruby SDK.
+
+## Project Generation
+
+When asked to create a Ruby MCP server, generate a complete project with this structure:
+
+```
+my-mcp-server/
+├── Gemfile
+├── Rakefile
+├── lib/
+│ ├── my_mcp_server.rb
+│ ├── my_mcp_server/
+│ │ ├── server.rb
+│ │ ├── tools/
+│ │ │ ├── greet_tool.rb
+│ │ │ └── calculate_tool.rb
+│ │ ├── prompts/
+│ │ │ └── code_review_prompt.rb
+│ │ └── resources/
+│ │ └── example_resource.rb
+├── bin/
+│ └── mcp-server
+├── test/
+│ ├── test_helper.rb
+│ └── tools/
+│ ├── greet_tool_test.rb
+│ └── calculate_tool_test.rb
+└── README.md
+```
+
+## Gemfile Template
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'mcp', '~> 0.4.0'
+
+group :development, :test do
+ gem 'minitest', '~> 5.0'
+ gem 'rake', '~> 13.0'
+ gem 'rubocop', '~> 1.50'
+end
+```
+
+## Rakefile Template
+
+```ruby
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+Rake::TestTask.new(:test) do |t|
+ t.libs << 'test'
+ t.libs << 'lib'
+ t.test_files = FileList['test/**/*_test.rb']
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+```
+
+## lib/my_mcp_server.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative 'my_mcp_server/server'
+require_relative 'my_mcp_server/tools/greet_tool'
+require_relative 'my_mcp_server/tools/calculate_tool'
+require_relative 'my_mcp_server/prompts/code_review_prompt'
+require_relative 'my_mcp_server/resources/example_resource'
+
+module MyMcpServer
+ VERSION = '1.0.0'
+end
+```
+
+## lib/my_mcp_server/server.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+module MyMcpServer
+ class Server
+ attr_reader :mcp_server
+
+ def initialize(server_context: {})
+ @mcp_server = MCP::Server.new(
+ name: 'my_mcp_server',
+ version: MyMcpServer::VERSION,
+ tools: [
+ Tools::GreetTool,
+ Tools::CalculateTool
+ ],
+ prompts: [
+ Prompts::CodeReviewPrompt
+ ],
+ resources: [
+ Resources::ExampleResource.resource
+ ],
+ server_context: server_context
+ )
+
+ setup_resource_handler
+ end
+
+ def handle_json(json_string)
+ mcp_server.handle_json(json_string)
+ end
+
+ def start_stdio
+ transport = MCP::Server::Transports::StdioTransport.new(mcp_server)
+ transport.open
+ end
+
+ private
+
+ def setup_resource_handler
+ mcp_server.resources_read_handler do |params|
+ Resources::ExampleResource.read(params[:uri])
+ end
+ end
+ end
+end
+```
+
+## lib/my_mcp_server/tools/greet_tool.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+module MyMcpServer
+ module Tools
+ class GreetTool < MCP::Tool
+ tool_name 'greet'
+ description 'Generate a greeting message'
+
+ input_schema(
+ properties: {
+ name: {
+ type: 'string',
+ description: 'Name to greet'
+ }
+ },
+ required: ['name']
+ )
+
+ output_schema(
+ properties: {
+ message: { type: 'string' },
+ timestamp: { type: 'string', format: 'date-time' }
+ },
+ required: ['message', 'timestamp']
+ )
+
+ annotations(
+ read_only_hint: true,
+ idempotent_hint: true
+ )
+
+ def self.call(name:, server_context:)
+ timestamp = Time.now.iso8601
+ message = "Hello, #{name}! Welcome to MCP."
+
+ structured_data = {
+ message: message,
+ timestamp: timestamp
+ }
+
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: message }],
+ structured_content: structured_data
+ )
+ end
+ end
+ end
+end
+```
+
+## lib/my_mcp_server/tools/calculate_tool.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+module MyMcpServer
+ module Tools
+ class CalculateTool < MCP::Tool
+ tool_name 'calculate'
+ description 'Perform mathematical calculations'
+
+ input_schema(
+ properties: {
+ operation: {
+ type: 'string',
+ description: 'Operation to perform',
+ enum: ['add', 'subtract', 'multiply', 'divide']
+ },
+ a: {
+ type: 'number',
+ description: 'First operand'
+ },
+ b: {
+ type: 'number',
+ description: 'Second operand'
+ }
+ },
+ required: ['operation', 'a', 'b']
+ )
+
+ output_schema(
+ properties: {
+ result: { type: 'number' },
+ operation: { type: 'string' }
+ },
+ required: ['result', 'operation']
+ )
+
+ annotations(
+ read_only_hint: true,
+ idempotent_hint: true
+ )
+
+ def self.call(operation:, a:, b:, server_context:)
+ result = case operation
+ when 'add' then a + b
+ when 'subtract' then a - b
+ when 'multiply' then a * b
+ when 'divide'
+ return error_response('Division by zero') if b.zero?
+ a / b.to_f
+ else
+ return error_response("Unknown operation: #{operation}")
+ end
+
+ structured_data = {
+ result: result,
+ operation: operation
+ }
+
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: "Result: #{result}" }],
+ structured_content: structured_data
+ )
+ end
+
+ def self.error_response(message)
+ MCP::Tool::Response.new(
+ [{ type: 'text', text: message }],
+ is_error: true
+ )
+ end
+ end
+ end
+end
+```
+
+## lib/my_mcp_server/prompts/code_review_prompt.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+module MyMcpServer
+ module Prompts
+ class CodeReviewPrompt < MCP::Prompt
+ prompt_name 'code_review'
+ description 'Generate a code review prompt'
+
+ arguments [
+ MCP::Prompt::Argument.new(
+ name: 'language',
+ description: 'Programming language',
+ required: true
+ ),
+ MCP::Prompt::Argument.new(
+ name: 'focus',
+ description: 'Review focus area (e.g., performance, security)',
+ required: false
+ )
+ ]
+
+ meta(
+ version: '1.0',
+ category: 'development'
+ )
+
+ def self.template(args, server_context:)
+ language = args['language'] || 'Ruby'
+ focus = args['focus'] || 'general quality'
+
+ MCP::Prompt::Result.new(
+ description: "Code review for #{language} with focus on #{focus}",
+ messages: [
+ MCP::Prompt::Message.new(
+ role: 'user',
+ content: MCP::Content::Text.new(
+ "Please review this #{language} code with focus on #{focus}."
+ )
+ ),
+ MCP::Prompt::Message.new(
+ role: 'assistant',
+ content: MCP::Content::Text.new(
+ "I'll review the code focusing on #{focus}. Please share the code."
+ )
+ ),
+ MCP::Prompt::Message.new(
+ role: 'user',
+ content: MCP::Content::Text.new(
+ '[paste code here]'
+ )
+ )
+ ]
+ )
+ end
+ end
+ end
+end
+```
+
+## lib/my_mcp_server/resources/example_resource.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+module MyMcpServer
+ module Resources
+ class ExampleResource
+ RESOURCE_URI = 'resource://data/example'
+
+ def self.resource
+ MCP::Resource.new(
+ uri: RESOURCE_URI,
+ name: 'example-data',
+ description: 'Example resource data',
+ mime_type: 'application/json'
+ )
+ end
+
+ def self.read(uri)
+ return [] unless uri == RESOURCE_URI
+
+ data = {
+ message: 'Example resource data',
+ timestamp: Time.now.iso8601,
+ version: MyMcpServer::VERSION
+ }
+
+ [{
+ uri: uri,
+ mimeType: 'application/json',
+ text: data.to_json
+ }]
+ end
+ end
+ end
+end
+```
+
+## bin/mcp-server Template
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/my_mcp_server'
+
+begin
+ server = MyMcpServer::Server.new
+ server.start_stdio
+rescue Interrupt
+ warn "\nShutting down server..."
+ exit 0
+rescue StandardError => e
+ warn "Error: #{e.message}"
+ warn e.backtrace.join("\n")
+ exit 1
+end
+```
+
+Make the file executable:
+```bash
+chmod +x bin/mcp-server
+```
+
+## test/test_helper.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'my_mcp_server'
+require 'minitest/autorun'
+```
+
+## test/tools/greet_tool_test.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module MyMcpServer
+ module Tools
+ class GreetToolTest < Minitest::Test
+ def test_greet_with_name
+ response = GreetTool.call(
+ name: 'Ruby',
+ server_context: {}
+ )
+
+ refute response.is_error
+ assert_equal 1, response.content.length
+ assert_match(/Ruby/, response.content.first[:text])
+
+ assert response.structured_content
+ assert_equal 'Hello, Ruby! Welcome to MCP.', response.structured_content[:message]
+ end
+
+ def test_output_schema_validation
+ response = GreetTool.call(
+ name: 'Test',
+ server_context: {}
+ )
+
+ assert response.structured_content.key?(:message)
+ assert response.structured_content.key?(:timestamp)
+ end
+ end
+ end
+end
+```
+
+## test/tools/calculate_tool_test.rb Template
+
+```ruby
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module MyMcpServer
+ module Tools
+ class CalculateToolTest < Minitest::Test
+ def test_addition
+ response = CalculateTool.call(
+ operation: 'add',
+ a: 5,
+ b: 3,
+ server_context: {}
+ )
+
+ refute response.is_error
+ assert_equal 8, response.structured_content[:result]
+ end
+
+ def test_subtraction
+ response = CalculateTool.call(
+ operation: 'subtract',
+ a: 10,
+ b: 4,
+ server_context: {}
+ )
+
+ refute response.is_error
+ assert_equal 6, response.structured_content[:result]
+ end
+
+ def test_multiplication
+ response = CalculateTool.call(
+ operation: 'multiply',
+ a: 6,
+ b: 7,
+ server_context: {}
+ )
+
+ refute response.is_error
+ assert_equal 42, response.structured_content[:result]
+ end
+
+ def test_division
+ response = CalculateTool.call(
+ operation: 'divide',
+ a: 15,
+ b: 3,
+ server_context: {}
+ )
+
+ refute response.is_error
+ assert_equal 5.0, response.structured_content[:result]
+ end
+
+ def test_division_by_zero
+ response = CalculateTool.call(
+ operation: 'divide',
+ a: 10,
+ b: 0,
+ server_context: {}
+ )
+
+ assert response.is_error
+ assert_match(/Division by zero/, response.content.first[:text])
+ end
+
+ def test_unknown_operation
+ response = CalculateTool.call(
+ operation: 'modulo',
+ a: 10,
+ b: 3,
+ server_context: {}
+ )
+
+ assert response.is_error
+ assert_match(/Unknown operation/, response.content.first[:text])
+ end
+ end
+ end
+end
+```
+
+## README.md Template
+
+```markdown
+# My MCP Server
+
+A Model Context Protocol server built with Ruby and the official MCP Ruby SDK.
+
+## Features
+
+- ✅ Tools: greet, calculate
+- ✅ Prompts: code_review
+- ✅ Resources: example-data
+- ✅ Input/output schemas
+- ✅ Tool annotations
+- ✅ Structured content
+- ✅ Full test coverage
+
+## Requirements
+
+- Ruby 3.0 or later
+
+## Installation
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Stdio Transport
+
+Run the server:
+
+```bash
+bundle exec bin/mcp-server
+```
+
+Then send JSON-RPC requests:
+
+```bash
+{"jsonrpc":"2.0","id":"1","method":"ping"}
+{"jsonrpc":"2.0","id":"2","method":"tools/list"}
+{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"greet","arguments":{"name":"Ruby"}}}
+```
+
+### Rails Integration
+
+Add to your Rails controller:
+
+```ruby
+class McpController < ApplicationController
+ def index
+ server = MyMcpServer::Server.new(
+ server_context: { user_id: current_user.id }
+ )
+ render json: server.handle_json(request.body.read)
+ end
+end
+```
+
+## Testing
+
+Run tests:
+
+```bash
+bundle exec rake test
+```
+
+Run linter:
+
+```bash
+bundle exec rake rubocop
+```
+
+Run all checks:
+
+```bash
+bundle exec rake
+```
+
+## Integration with Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "my-mcp-server": {
+ "command": "bundle",
+ "args": ["exec", "bin/mcp-server"],
+ "cwd": "/path/to/my-mcp-server"
+ }
+ }
+}
+```
+
+## Project Structure
+
+```
+my-mcp-server/
+├── Gemfile # Dependencies
+├── Rakefile # Build tasks
+├── lib/ # Source code
+│ ├── my_mcp_server.rb # Main entry point
+│ └── my_mcp_server/ # Module namespace
+│ ├── server.rb # Server setup
+│ ├── tools/ # Tool implementations
+│ ├── prompts/ # Prompt templates
+│ └── resources/ # Resource handlers
+├── bin/ # Executables
+│ └── mcp-server # Stdio server
+├── test/ # Test suite
+│ ├── test_helper.rb # Test configuration
+│ └── tools/ # Tool tests
+└── README.md # This file
+```
+
+## License
+
+MIT
+```
+
+## Generation Instructions
+
+1. **Ask for project name and description**
+2. **Generate all files** with proper naming and module structure
+3. **Use classes for tools and prompts** for better organization
+4. **Include input/output schemas** for type safety
+5. **Add tool annotations** for behavior hints
+6. **Include structured content** in responses
+7. **Implement comprehensive tests** for all tools
+8. **Follow Ruby conventions** (snake_case, modules, frozen_string_literal)
+9. **Add proper error handling** with is_error flag
+10. **Provide both stdio and HTTP** usage examples