reference/node_mcp_server.md · 24000
mport { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const transport = new StdioServerTransport(); await server.connect(transport);
**Transport selection:**
- **Streamable HTTP**: Web services, remote access, multiple clients
- **stdio**: Command-line tools, local development, subprocess integration
### Notification Support
Notify clients when server state changes:
```typescript
// Notify when tools list changes
server.notification({
method: "notifications/tools/list_changed"
});
// Notify when resources change
server.notification({
method: "notifications/resources/list_changed"
});
Use notifications sparingly - only when server capabilities genuinely change.
Code Best Practices
Code Composability and Reusability
Your implementation MUST prioritize composability and code reuse:
-
Extract Common Functionality:
- Create reusable helper functions for operations used across multiple tools
- Build shared API clients for HTTP requests instead of duplicating code
- Centralize error handling logic in utility functions
- Extract business logic into dedicated functions that can be composed
- Extract shared markdown or JSON field selection & formatting functionality
-
Avoid Duplication:
- NEVER copy-paste similar code between tools
- If you find yourself writing similar logic twice, extract it into a function
- Common operations like pagination, filtering, field selection, and formatting should be shared
- Authentication/authorization logic should be centralized
Building and Running
Always build your TypeScript code before running:
# Build the project
npm run build
# Run the server
npm start
# Development with auto-reload
npm run dev
Always ensure npm run build completes successfully before considering the implementation complete.
Quality Checklist
Before finalizing your Node/TypeScript MCP server implementation, ensure:
Strategic Design
- [ ] Tools enable complete workflows, not just API endpoint wrappers
- [ ] Tool names reflect natural task subdivisions
- [ ] Response formats optimize for agent context efficiency
- [ ] Human-readable identifiers used where appropriate
- [ ] Error messages guide agents toward correct usage
Implementation Quality
- [ ] FOCUSED IMPLEMENTATION: Most important and valuable tools implemented
- [ ] All tools registered using
registerToolwith complete configuration - [ ] All tools include
title,description,inputSchema, andannotations - [ ] Annotations correctly set (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
- [ ] All tools use Zod schemas for runtime input validation with
.strict()enforcement - [ ] All Zod schemas have proper constraints and descriptive error messages
- [ ] All tools have comprehensive descriptions with explicit input/output types
- [ ] Descriptions include return value examples and complete schema documentation
- [ ] Error messages are clear, actionable, and educational
TypeScript Quality
- [ ] TypeScript interfaces are defined for all data structures
- [ ] Strict TypeScript is enabled in tsconfig.json
- [ ] No use of
anytype - useunknownor proper types instead - [ ] All async functions have explicit Promise return types
- [ ] Error handling uses proper type guards (e.g.,
axios.isAxiosError,z.ZodError)
Advanced Features (where applicable)
- [ ] Resources registered for appropriate data endpoints
- [ ] Appropriate transport configured (stdio or streamable HTTP)
- [ ] Notifications implemented for dynamic server capabilities
- [ ] Type-safe with SDK interfaces
Project Configuration
- [ ] Package.json includes all necessary dependencies
- [ ] Build script produces working JavaScript in dist/ directory
- [ ] Main entry point is properly configured as dist/index.js
- [ ] Server name follows format:
{service}-mcp-server - [ ] tsconfig.json properly configured with strict mode
Code Quality
- [ ] Pagination is properly implemented where applicable
- [ ] Large responses check CHARACTER_LIMIT constant and truncate with clear messages
- [ ] Filtering options are provided for potentially large result sets
- [ ] All network operations handle timeouts and connection errors gracefully
- [ ] Common functionality is extracted into reusable functions
- [ ] Return types are consistent across similar operations
Testing and Build
- [ ]
npm run buildcompletes successfully without errors - [ ] dist/index.js created and executable
- [ ] Server runs:
node dist/index.js --help - [ ] All imports resolve correctly
- [ ] Sample tool calls work as expected