ssd-ai typescript-mcp-server.instructions.md

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