From 24bbea858537d25665f14ffaf7854bec98618e59 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 00:27:55 +0000 Subject: [PATCH] chore: publish from main --- docs/README.skills.md | 2 +- .../typescript-mcp-server-generator/SKILL.md | 57 +++++++++++++------ .../typescript-mcp-server-generator/SKILL.md | 57 +++++++++++++------ 3 files changed, 81 insertions(+), 35 deletions(-) diff --git a/docs/README.skills.md b/docs/README.skills.md index c4c73a5c..d9cbd9c4 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -397,7 +397,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [tldr-prompt](../skills/tldr-prompt/SKILL.md)
`gh skills install github/awesome-copilot tldr-prompt` | Create tldr summaries for GitHub Copilot files (prompts, agents, instructions, collections), MCP servers, or documentation from URLs and queries. | None | | [tm7-threat-model](../skills/tm7-threat-model/SKILL.md)
`gh skills install github/awesome-copilot tm7-threat-model` | Creates valid Microsoft Threat Modeling Tool (.tm7) files compatible with the Microsoft Threat Modeling Tool v7.3+. Use this skill whenever asked to create, generate, or modify a .tm7 threat model file, or when performing STRIDE threat modeling that should output a .tm7 file that opens cleanly in the Microsoft Threat Modeling Tool. | `assets/example-minimal.tm7` | | [transloadit-media-processing](../skills/transloadit-media-processing/SKILL.md)
`gh skills install github/awesome-copilot transloadit-media-processing` | Process media files (video, audio, images, documents) using Transloadit. Use when asked to encode video to HLS/MP4, generate thumbnails, resize or watermark images, extract audio, concatenate clips, add subtitles, OCR documents, or run any media processing pipeline. Covers 86+ processing robots for file transformation at scale. | None | -| [typescript-mcp-server-generator](../skills/typescript-mcp-server-generator/SKILL.md)
`gh skills install github/awesome-copilot typescript-mcp-server-generator` | Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration | None | +| [typescript-mcp-server-generator](../skills/typescript-mcp-server-generator/SKILL.md)
`gh skills install github/awesome-copilot typescript-mcp-server-generator` | Generate a complete MCP server project in TypeScript using the MCP TypeScript SDK v2 (@modelcontextprotocol/server) with tools, resources, and proper configuration | None | | [typespec-api-operations](../skills/typespec-api-operations/SKILL.md)
`gh skills install github/awesome-copilot typespec-api-operations` | Add GET, POST, PATCH, and DELETE operations to a TypeSpec API plugin with proper routing, parameters, and adaptive cards | None | | [typespec-create-agent](../skills/typespec-create-agent/SKILL.md)
`gh skills install github/awesome-copilot typespec-create-agent` | Generate a complete TypeSpec declarative agent with instructions, capabilities, and conversation starters for Microsoft 365 Copilot | None | | [typespec-create-api-plugin](../skills/typespec-create-api-plugin/SKILL.md)
`gh skills install github/awesome-copilot typespec-create-api-plugin` | Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot | None | diff --git a/plugins/typescript-mcp-development/skills/typescript-mcp-server-generator/SKILL.md b/plugins/typescript-mcp-development/skills/typescript-mcp-server-generator/SKILL.md index 9495356c..d7a98d27 100644 --- a/plugins/typescript-mcp-development/skills/typescript-mcp-server-generator/SKILL.md +++ b/plugins/typescript-mcp-development/skills/typescript-mcp-server-generator/SKILL.md @@ -1,18 +1,22 @@ --- name: typescript-mcp-server-generator -description: 'Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration' +description: 'Generate a complete MCP server project in TypeScript using the MCP TypeScript SDK v2 (@modelcontextprotocol/server) with tools, resources, and proper configuration' --- # Generate TypeScript MCP Server -Create a complete Model Context Protocol (MCP) server in TypeScript with the following specifications: +Create a complete Model Context Protocol (MCP) server in TypeScript using the **MCP TypeScript SDK v2** 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 +2. **NPM Packages**: The v1 monolithic `@modelcontextprotocol/sdk` package is retired. Use the focused v2 packages: + - `@modelcontextprotocol/server` — server implementation (stdio transport via the `@modelcontextprotocol/server/stdio` subpath) + - `@modelcontextprotocol/node` — Node HTTP transport (`NodeStreamableHTTPServerTransport`), or a framework adapter: `@modelcontextprotocol/express`, `@modelcontextprotocol/hono`, `@modelcontextprotocol/fastify` — each adapter requires its peer framework to be installed alongside it (e.g. `@modelcontextprotocol/express` + `express`) + - `@modelcontextprotocol/core` — shared protocol schemas (import `*Schema` constants from here, not from `sdk/types.js`) + - `zod@^4.2` — v2 requires Zod 4.2+; do not use zod@3 +3. **Runtime**: Node.js 20+ (v2 minimum); ESM-first with `"type": "module"` (a CommonJS build is also shipped, so `require()` works if needed) +4. **Server Type**: Choose between HTTP (Streamable HTTP transport) or stdio-based server. SSE and WebSocket transports were removed in v2 — do not generate them. 5. **Tools**: Create at least one useful tool with proper schema validation 6. **Error Handling**: Include comprehensive error handling and validation @@ -20,30 +24,42 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol ### Project Setup - Initialize with `npm init` and create package.json -- Install dependencies: `@modelcontextprotocol/sdk`, `zod@3`, and transport-specific packages +- Install dependencies: `@modelcontextprotocol/server`, `zod@^4.2`, and the transport package — `@modelcontextprotocol/node` for plain Node HTTP, or a framework adapter together with its peer framework (e.g. `npm install @modelcontextprotocol/express express`) - 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 +- Use `McpServer` class from `@modelcontextprotocol/server` 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 +- Choose the appropriate transport: + - HTTP (Node): `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node` + - HTTP (Web Standard runtimes): `WebStandardStreamableHTTPServerTransport` from `@modelcontextprotocol/server` + - stdio: `StdioServerTransport` from `@modelcontextprotocol/server/stdio` +- For HTTP: prefer a framework adapter (`@modelcontextprotocol/express`, etc.) with proper middleware and error handling +- Note that v2 uses Web Standard `Headers`/`Request` types; read headers with `ctx.http?.req?.headers.get('x-custom')` ### Tool Implementation -- Use `registerTool()` method with descriptive names -- Define schemas using zod for input and output validation +- Use `registerTool()` with a config object — v1 variadic `.tool()` signatures are gone: + ```typescript + server.registerTool('greet', { + description: 'Greet user', + inputSchema: z.object({ name: z.string() }) + }, async ({ name }, ctx) => { + return { content: [{ type: 'text', text: `Hello, ${name}!` }] }; + }); + ``` +- Schemas must be full Zod objects (`z.object({...})`) — raw shape objects (`{ name: z.string() }`) are deprecated - Provide clear `title` and `description` fields - Return both `content` and `structuredContent` in results -- Implement proper error handling with try-catch blocks +- The handler's second parameter is a structured `ctx` object (replaces v1 `extra`): `ctx.mcpReq.signal`, `ctx.mcpReq.id`, `ctx.mcpReq.send(...)`, `ctx.mcpReq.notify(...)` +- Implement proper error handling with try-catch blocks; use the v2 error hierarchy (`ProtocolError`, `SdkError`, `SdkHttpError` with `.status`) instead of v1 `McpError`/`StreamableHTTPError` - 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 +- Add prompts using `registerPrompt()` with argument schemas (same config-object style as `registerTool()`) +- Consider adding completion support for better UX; note the v2 `completable()` wrapper order: `completable(z.string(), callback).optional()` (optional applied outside) ### Code Quality - Use TypeScript for type safety @@ -58,7 +74,7 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol - External API integrations - File system operations (read, search, analyze) - Database queries -- Text analysis or summarization (with sampling) +- Text analysis or summarization (LLM-assisted via the multi-round `input_required` pattern) - System information retrieval ## Configuration Options @@ -67,12 +83,19 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol - CORS setup for browser clients - Session management (stateless vs stateful) - DNS rebinding protection for local servers + - Strict `Content-Type` handling: v2 rejects non-`application/json` POST bodies - **For stdio Servers**: - Proper stdin/stdout handling - Environment-based configuration - Process lifecycle management +## Migrating an Existing v1 Server +- Run the official codemod first: `npx @modelcontextprotocol/codemod@latest v1-to-v2 .` +- Then search for `@mcp-codemod-error` markers for the parts requiring manual judgment (transport choice, header reads, error classification) +- Swap `McpError + ErrorCode` checks for the new error classes; HTTP status now lives on `error.status`, not `error.code` +- `Server.createMessage()`, `listRoots()`, `sendLoggingMessage()` and the `roots`/`sampling`/`logging` capability fields are deprecated in v2 — avoid them in new code + ## Testing Guidance - Explain how to run the server (`npm start` or `npx tsx server.ts`) - Provide MCP Inspector command: `npx @modelcontextprotocol/inspector` @@ -81,7 +104,7 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol - Add troubleshooting tips for common issues ## Additional Features to Consider -- Sampling support for LLM-powered tools +- LLM-powered tools using the multi-round `input_required` pattern (the v2 replacement for the deprecated sampling subsystem) - User input elicitation for interactive workflows - Dynamic tool registration with enable/disable capabilities - Notification debouncing for bulk updates diff --git a/skills/typescript-mcp-server-generator/SKILL.md b/skills/typescript-mcp-server-generator/SKILL.md index 9495356c..d7a98d27 100644 --- a/skills/typescript-mcp-server-generator/SKILL.md +++ b/skills/typescript-mcp-server-generator/SKILL.md @@ -1,18 +1,22 @@ --- name: typescript-mcp-server-generator -description: 'Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration' +description: 'Generate a complete MCP server project in TypeScript using the MCP TypeScript SDK v2 (@modelcontextprotocol/server) with tools, resources, and proper configuration' --- # Generate TypeScript MCP Server -Create a complete Model Context Protocol (MCP) server in TypeScript with the following specifications: +Create a complete Model Context Protocol (MCP) server in TypeScript using the **MCP TypeScript SDK v2** 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 +2. **NPM Packages**: The v1 monolithic `@modelcontextprotocol/sdk` package is retired. Use the focused v2 packages: + - `@modelcontextprotocol/server` — server implementation (stdio transport via the `@modelcontextprotocol/server/stdio` subpath) + - `@modelcontextprotocol/node` — Node HTTP transport (`NodeStreamableHTTPServerTransport`), or a framework adapter: `@modelcontextprotocol/express`, `@modelcontextprotocol/hono`, `@modelcontextprotocol/fastify` — each adapter requires its peer framework to be installed alongside it (e.g. `@modelcontextprotocol/express` + `express`) + - `@modelcontextprotocol/core` — shared protocol schemas (import `*Schema` constants from here, not from `sdk/types.js`) + - `zod@^4.2` — v2 requires Zod 4.2+; do not use zod@3 +3. **Runtime**: Node.js 20+ (v2 minimum); ESM-first with `"type": "module"` (a CommonJS build is also shipped, so `require()` works if needed) +4. **Server Type**: Choose between HTTP (Streamable HTTP transport) or stdio-based server. SSE and WebSocket transports were removed in v2 — do not generate them. 5. **Tools**: Create at least one useful tool with proper schema validation 6. **Error Handling**: Include comprehensive error handling and validation @@ -20,30 +24,42 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol ### Project Setup - Initialize with `npm init` and create package.json -- Install dependencies: `@modelcontextprotocol/sdk`, `zod@3`, and transport-specific packages +- Install dependencies: `@modelcontextprotocol/server`, `zod@^4.2`, and the transport package — `@modelcontextprotocol/node` for plain Node HTTP, or a framework adapter together with its peer framework (e.g. `npm install @modelcontextprotocol/express express`) - 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 +- Use `McpServer` class from `@modelcontextprotocol/server` 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 +- Choose the appropriate transport: + - HTTP (Node): `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node` + - HTTP (Web Standard runtimes): `WebStandardStreamableHTTPServerTransport` from `@modelcontextprotocol/server` + - stdio: `StdioServerTransport` from `@modelcontextprotocol/server/stdio` +- For HTTP: prefer a framework adapter (`@modelcontextprotocol/express`, etc.) with proper middleware and error handling +- Note that v2 uses Web Standard `Headers`/`Request` types; read headers with `ctx.http?.req?.headers.get('x-custom')` ### Tool Implementation -- Use `registerTool()` method with descriptive names -- Define schemas using zod for input and output validation +- Use `registerTool()` with a config object — v1 variadic `.tool()` signatures are gone: + ```typescript + server.registerTool('greet', { + description: 'Greet user', + inputSchema: z.object({ name: z.string() }) + }, async ({ name }, ctx) => { + return { content: [{ type: 'text', text: `Hello, ${name}!` }] }; + }); + ``` +- Schemas must be full Zod objects (`z.object({...})`) — raw shape objects (`{ name: z.string() }`) are deprecated - Provide clear `title` and `description` fields - Return both `content` and `structuredContent` in results -- Implement proper error handling with try-catch blocks +- The handler's second parameter is a structured `ctx` object (replaces v1 `extra`): `ctx.mcpReq.signal`, `ctx.mcpReq.id`, `ctx.mcpReq.send(...)`, `ctx.mcpReq.notify(...)` +- Implement proper error handling with try-catch blocks; use the v2 error hierarchy (`ProtocolError`, `SdkError`, `SdkHttpError` with `.status`) instead of v1 `McpError`/`StreamableHTTPError` - 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 +- Add prompts using `registerPrompt()` with argument schemas (same config-object style as `registerTool()`) +- Consider adding completion support for better UX; note the v2 `completable()` wrapper order: `completable(z.string(), callback).optional()` (optional applied outside) ### Code Quality - Use TypeScript for type safety @@ -58,7 +74,7 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol - External API integrations - File system operations (read, search, analyze) - Database queries -- Text analysis or summarization (with sampling) +- Text analysis or summarization (LLM-assisted via the multi-round `input_required` pattern) - System information retrieval ## Configuration Options @@ -67,12 +83,19 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol - CORS setup for browser clients - Session management (stateless vs stateful) - DNS rebinding protection for local servers + - Strict `Content-Type` handling: v2 rejects non-`application/json` POST bodies - **For stdio Servers**: - Proper stdin/stdout handling - Environment-based configuration - Process lifecycle management +## Migrating an Existing v1 Server +- Run the official codemod first: `npx @modelcontextprotocol/codemod@latest v1-to-v2 .` +- Then search for `@mcp-codemod-error` markers for the parts requiring manual judgment (transport choice, header reads, error classification) +- Swap `McpError + ErrorCode` checks for the new error classes; HTTP status now lives on `error.status`, not `error.code` +- `Server.createMessage()`, `listRoots()`, `sendLoggingMessage()` and the `roots`/`sampling`/`logging` capability fields are deprecated in v2 — avoid them in new code + ## Testing Guidance - Explain how to run the server (`npm start` or `npx tsx server.ts`) - Provide MCP Inspector command: `npx @modelcontextprotocol/inspector` @@ -81,7 +104,7 @@ Create a complete Model Context Protocol (MCP) server in TypeScript with the fol - Add troubleshooting tips for common issues ## Additional Features to Consider -- Sampling support for LLM-powered tools +- LLM-powered tools using the multi-round `input_required` pattern (the v2 replacement for the deprecated sampling subsystem) - User input elicitation for interactive workflows - Dynamic tool registration with enable/disable capabilities - Notification debouncing for bulk updates