1# Node/TypeScript MCP Server Implementation Guide
2 
3## Overview
4 
5This document provides Node/TypeScript-specific best practices and examples for implementing MCP servers using the MCP TypeScript SDK. It covers project structure, server setup, tool registration patterns, input validation with Zod, error handling, and complete working examples.
6 
7---
8 
9## Quick Reference
10 
11### Key Imports
12```typescript
13import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
14import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
15import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
16import express from "express";
17import { z } from "zod";
18```
19 
20### Server Initialization
21```typescript
22const server = new McpServer({
23  name: "service-mcp-server",
24  version: "1.0.0"
25});
26```
27 
28### Tool Registration Pattern
29```typescript
30server.registerTool(
31  "tool_name",
32  {
33    title: "Tool Display Name",
34    description: "What the tool does",
35    inputSchema: { param: z.string() },
36    outputSchema: { result: z.string() }
37  },
38  async ({ param }) => {
39    const output = { result: `Processed: ${param}` };
40    return {
41      content: [{ type: "text", text: JSON.stringify(output) }],
42      structuredContent: output // Modern pattern for structured data
43    };
44  }
45);
46```
47 
48---
49 
50## MCP TypeScript SDK
51 
52The official MCP TypeScript SDK provides:
53- `McpServer` class for server initialization
54- `registerTool` method for tool registration
55- Zod schema integration for runtime input validation
56- Type-safe tool handler implementations
57 
58**IMPORTANT - Use Modern APIs Only:**
59- **DO use**: `server.registerTool()`, `server.registerResource()`, `server.registerPrompt()`
60- **DO NOT use**: Old deprecated APIs such as `server.tool()`, `server.setRequestHandler(ListToolsRequestSchema, ...)`, or manual handler registration
61- The `register*` methods provide better type safety, automatic schema handling, and are the recommended approach
62 
63See the MCP SDK documentation in the references for complete details.
64 
65## Server Naming Convention
66 
67Node/TypeScript MCP servers must follow this naming pattern:
68- **Format**: `{service}-mcp-server` (lowercase with hyphens)
69- **Examples**: `github-mcp-server`, `jira-mcp-server`, `stripe-mcp-server`
70 
71The name should be:
72- General (not tied to specific features)
73- Descriptive of the service/API being integrated
74- Easy to infer from the task description
75- Without version numbers or dates
76 
77## Project Structure
78 
79Create the following structure for Node/TypeScript MCP servers:
80 
81```
82{service}-mcp-server/
83├── package.json
84├── tsconfig.json
85├── README.md
86├── src/
87│   ├── index.ts          # Main entry point with McpServer initialization
88│   ├── types.ts          # TypeScript type definitions and interfaces
89│   ├── tools/            # Tool implementations (one file per domain)
90│   ├── services/         # API clients and shared utilities
91│   ├── schemas/          # Zod validation schemas
92│   └── constants.ts      # Shared constants (API_URL, CHARACTER_LIMIT, etc.)
93└── dist/                 # Built JavaScript files (entry point: dist/index.js)
94```
95 
96## Tool Implementation
97 
98### Tool Naming
99 
100Use snake_case for tool names (e.g., "search_users", "create_project", "get_channel_info") with clear, action-oriented names.
101 
102**Avoid Naming Conflicts**: Include the service context to prevent overlaps:
103- Use "slack_send_message" instead of just "send_message"
104- Use "github_create_issue" instead of just "create_issue"
105- Use "asana_list_tasks" instead of just "list_tasks"
106 
107### Tool Structure
108 
109Tools are registered using the `registerTool` method with the following requirements:
110- Use Zod schemas for runtime input validation and type safety
111- The `description` field must be explicitly provided - JSDoc comments are NOT automatically extracted
112- Explicitly provide `title`, `description`, `inputSchema`, and `annotations`
113- The `inputSchema` must be a Zod schema object (not a JSON schema)
114- Type all parameters and return values explicitly
115 
116```typescript
117import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
118import { z } from "zod";
119 
120const server = new McpServer({
121  name: "example-mcp",
122  version: "1.0.0"
123});
124 
125// Zod schema for input validation
126const UserSearchInputSchema = z.object({
127  query: z.string()
128    .min(2, "Query must be at least 2 characters")
129    .max(200, "Query must not exceed 200 characters")
130    .describe("Search string to match against names/emails"),
131  limit: z.number()
132    .int()
133    .min(1)
134    .max(100)
135    .default(20)
136    .describe("Maximum results to return"),
137  offset: z.number()
138    .int()
139    .min(0)
140    .default(0)
141    .describe("Number of results to skip for pagination"),
142  response_format: z.nativeEnum(ResponseFormat)
143    .default(ResponseFormat.MARKDOWN)
144    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
145}).strict();
146 
147// Type definition from Zod schema
148type UserSearchInput = z.infer<typeof UserSearchInputSchema>;
149 
150server.registerTool(
151  "example_search_users",
152  {
153    title: "Search Example Users",
154    description: `Search for users in the Example system by name, email, or team.
155 
156This tool searches across all user profiles in the Example platform, supporting partial matches and various search filters. It does NOT create or modify users, only searches existing ones.
157 
158Args:
159  - query (string): Search string to match against names/emails
160  - limit (number): Maximum results to return, between 1-100 (default: 20)
161  - offset (number): Number of results to skip for pagination (default: 0)
162  - response_format ('markdown' | 'json'): Output format (default: 'markdown')
163 
164Returns:
165  For JSON format: Structured data with schema:
166  {
167    "total": number,           // Total number of matches found
168    "count": number,           // Number of results in this response
169    "offset": number,          // Current pagination offset
170    "users": [
171      {
172        "id": string,          // User ID (e.g., "U123456789")
173        "name": string,        // Full name (e.g., "John Doe")
174        "email": string,       // Email address
175        "team": string,        // Team name (optional)
176        "active": boolean      // Whether user is active
177      }
178    ],
179    "has_more": boolean,       // Whether more results are available
180    "next_offset": number      // Offset for next page (if has_more is true)
181  }
182 
183Examples:
184  - Use when: "Find all marketing team members" -> params with query="team:marketing"
185  - Use when: "Search for John's account" -> params with query="john"
186  - Don't use when: You need to create a user (use example_create_user instead)
187 
188Error Handling:
189  - Returns "Error: Rate limit exceeded" if too many requests (429 status)
190  - Returns "No users found matching '<query>'" if search returns empty`,
191    inputSchema: UserSearchInputSchema,
192    annotations: {
193      readOnlyHint: true,
194      destructiveHint: false,
195      idempotentHint: true,
196      openWorldHint: true
197    }
198  },
199  async (params: UserSearchInput) => {
200    try {
201      // Input validation is handled by Zod schema
202      // Make API request using validated parameters
203      const data = await makeApiRequest<any>(
204        "users/search",
205        "GET",
206        undefined,
207        {
208          q: params.query,
209          limit: params.limit,
210          offset: params.offset
211        }
212      );
213 
214      const users = data.users || [];
215      const total = data.total || 0;
216 
217      if (!users.length) {
218        return {
219          content: [{
220            type: "text",
221            text: `No users found matching '${params.query}'`
222          }]
223        };
224      }
225 
226      // Prepare structured output
227      const output = {
228        total,
229        count: users.length,
230        offset: params.offset,
231        users: users.map((user: any) => ({
232          id: user.id,
233          name: user.name,
234          email: user.email,
235          ...(user.team ? { team: user.team } : {}),
236          active: user.active ?? true
237        })),
238        has_more: total > params.offset + users.length,
239        ...(total > params.offset + users.length ? {
240          next_offset: params.offset + users.length
241        } : {})
242      };
243 
244      // Format text representation based on requested format
245      let textContent: string;
246      if (params.response_format === ResponseFormat.MARKDOWN) {
247        const lines = [`# User Search Results: '${params.query}'`, "",
248          `Found ${total} users (showing ${users.length})`, ""];
249        for (const user of users) {
250          lines.push(`## ${user.name} (${user.id})`);
251          lines.push(`- **Email**: ${user.email}`);
252          if (user.team) lines.push(`- **Team**: ${user.team}`);
253          lines.push("");
254        }
255        textContent = lines.join("\n");
256      } else {
257        textContent = JSON.stringify(output, null, 2);
258      }
259 
260      return {
261        content: [{ type: "text", text: textContent }],
262        structuredContent: output // Modern pattern for structured data
263      };
264    } catch (error) {
265      return {
266        content: [{
267          type: "text",
268          text: handleApiError(error)
269        }]
270      };
271    }
272  }
273);
274```
275 
276## Zod Schemas for Input Validation
277 
278Zod provides runtime type validation:
279 
280```typescript
281import { z } from "zod";
282 
283// Basic schema with validation
284const CreateUserSchema = z.object({
285  name: z.string()
286    .min(1, "Name is required")
287    .max(100, "Name must not exceed 100 characters"),
288  email: z.string()
289    .email("Invalid email format"),
290  age: z.number()
291    .int("Age must be a whole number")
292    .min(0, "Age cannot be negative")
293    .max(150, "Age cannot be greater than 150")
294}).strict();  // Use .strict() to forbid extra fields
295 
296// Enums
297enum ResponseFormat {
298  MARKDOWN = "markdown",
299  JSON = "json"
300}
301 
302const SearchSchema = z.object({
303  response_format: z.nativeEnum(ResponseFormat)
304    .default(ResponseFormat.MARKDOWN)
305    .describe("Output format")
306});
307 
308// Optional fields with defaults
309const PaginationSchema = z.object({
310  limit: z.number()
311    .int()
312    .min(1)
313    .max(100)
314    .default(20)
315    .describe("Maximum results to return"),
316  offset: z.number()
317    .int()
318    .min(0)
319    .default(0)
320    .describe("Number of results to skip")
321});
322```
323 
324## Response Format Options
325 
326Support multiple output formats for flexibility:
327 
328```typescript
329enum ResponseFormat {
330  MARKDOWN = "markdown",
331  JSON = "json"
332}
333 
334const inputSchema = z.object({
335  query: z.string(),
336  response_format: z.nativeEnum(ResponseFormat)
337    .default(ResponseFormat.MARKDOWN)
338    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
339});
340```
341 
342**Markdown format**:
343- Use headers, lists, and formatting for clarity
344- Convert timestamps to human-readable format
345- Show display names with IDs in parentheses
346- Omit verbose metadata
347- Group related information logically
348 
349**JSON format**:
350- Return complete, structured data suitable for programmatic processing
351- Include all available fields and metadata
352- Use consistent field names and types
353 
354## Pagination Implementation
355 
356For tools that list resources:
357 
358```typescript
359const ListSchema = z.object({
360  limit: z.number().int().min(1).max(100).default(20),
361  offset: z.number().int().min(0).default(0)
362});
363 
364async function listItems(params: z.infer<typeof ListSchema>) {
365  const data = await apiRequest(params.limit, params.offset);
366 
367  const response = {
368    total: data.total,
369    count: data.items.length,
370    offset: params.offset,
371    items: data.items,
372    has_more: data.total > params.offset + data.items.length,
373    next_offset: data.total > params.offset + data.items.length
374      ? params.offset + data.items.length
375      : undefined
376  };
377 
378  return JSON.stringify(response, null, 2);
379}
380```
381 
382## Character Limits and Truncation
383 
384Add a CHARACTER_LIMIT constant to prevent overwhelming responses:
385 
386```typescript
387// At module level in constants.ts
388export const CHARACTER_LIMIT = 25000;  // Maximum response size in characters
389 
390async function searchTool(params: SearchInput) {
391  let result = generateResponse(data);
392 
393  // Check character limit and truncate if needed
394  if (result.length > CHARACTER_LIMIT) {
395    const truncatedData = data.slice(0, Math.max(1, data.length / 2));
396    response.data = truncatedData;
397    response.truncated = true;
398    response.truncation_message =
399      `Response truncated from ${data.length} to ${truncatedData.length} items. ` +
400      `Use 'offset' parameter or add filters to see more results.`;
401    result = JSON.stringify(response, null, 2);
402  }
403 
404  return result;
405}
406```
407 
408## Error Handling
409 
410Provide clear, actionable error messages:
411 
412```typescript
413import axios, { AxiosError } from "axios";
414 
415function handleApiError(error: unknown): string {
416  if (error instanceof AxiosError) {
417    if (error.response) {
418      switch (error.response.status) {
419        case 404:
420          return "Error: Resource not found. Please check the ID is correct.";
421        case 403:
422          return "Error: Permission denied. You don't have access to this resource.";
423        case 429:
424          return "Error: Rate limit exceeded. Please wait before making more requests.";
425        default:
426          return `Error: API request failed with status ${error.response.status}`;
427      }
428    } else if (error.code === "ECONNABORTED") {
429      return "Error: Request timed out. Please try again.";
430    }
431  }
432  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
433}
434```
435 
436## Shared Utilities
437 
438Extract common functionality into reusable functions:
439 
440```typescript
441// Shared API request function
442async function makeApiRequest<T>(
443  endpoint: string,
444  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
445  data?: any,
446  params?: any
447): Promise<T> {
448  try {
449    const response = await axios({
450      method,
451      url: `${API_BASE_URL}/${endpoint}`,
452      data,
453      params,
454      timeout: 30000,
455      headers: {
456        "Content-Type": "application/json",
457        "Accept": "application/json"
458      }
459    });
460    return response.data;
461  } catch (error) {
462    throw error;
463  }
464}
465```
466 
467## Async/Await Best Practices
468 
469Always use async/await for network requests and I/O operations:
470 
471```typescript
472// Good: Async network request
473async function fetchData(resourceId: string): Promise<ResourceData> {
474  const response = await axios.get(`${API_URL}/resource/${resourceId}`);
475  return response.data;
476}
477 
478// Bad: Promise chains
479function fetchData(resourceId: string): Promise<ResourceData> {
480  return axios.get(`${API_URL}/resource/${resourceId}`)
481    .then(response => response.data);  // Harder to read and maintain
482}
483```
484 
485## TypeScript Best Practices
486 
4871. **Use Strict TypeScript**: Enable strict mode in tsconfig.json
4882. **Define Interfaces**: Create clear interface definitions for all data structures
4893. **Avoid `any`**: Use proper types or `unknown` instead of `any`
4904. **Zod for Runtime Validation**: Use Zod schemas to validate external data
4915. **Type Guards**: Create type guard functions for complex type checking
4926. **Error Handling**: Always use try-catch with proper error type checking
4937. **Null Safety**: Use optional chaining (`?.`) and nullish coalescing (`??`)
494 
495```typescript
496// Good: Type-safe with Zod and interfaces
497interface UserResponse {
498  id: string;
499  name: string;
500  email: string;
501  team?: string;
502  active: boolean;
503}
504 
505const UserSchema = z.object({
506  id: z.string(),
507  name: z.string(),
508  email: z.string().email(),
509  team: z.string().optional(),
510  active: z.boolean()
511});
512 
513type User = z.infer<typeof UserSchema>;
514 
515async function getUser(id: string): Promise<User> {
516  const data = await apiCall(`/users/${id}`);
517  return UserSchema.parse(data);  // Runtime validation
518}
519 
520// Bad: Using any
521async function getUser(id: string): Promise<any> {
522  return await apiCall(`/users/${id}`);  // No type safety
523}
524```
525 
526## Package Configuration
527 
528### package.json
529 
530```json
531{
532  "name": "{service}-mcp-server",
533  "version": "1.0.0",
534  "description": "MCP server for {Service} API integration",
535  "type": "module",
536  "main": "dist/index.js",
537  "scripts": {
538    "start": "node dist/index.js",
539    "dev": "tsx watch src/index.ts",
540    "build": "tsc",
541    "clean": "rm -rf dist"
542  },
543  "engines": {
544    "node": ">=18"
545  },
546  "dependencies": {
547    "@modelcontextprotocol/sdk": "^1.6.1",
548    "axios": "^1.7.9",
549    "zod": "^3.23.8"
550  },
551  "devDependencies": {
552    "@types/node": "^22.10.0",
553    "tsx": "^4.19.2",
554    "typescript": "^5.7.2"
555  }
556}
557```
558 
559### tsconfig.json
560 
561```json
562{
563  "compilerOptions": {
564    "target": "ES2022",
565    "module": "Node16",
566    "moduleResolution": "Node16",
567    "lib": ["ES2022"],
568    "outDir": "./dist",
569    "rootDir": "./src",
570    "strict": true,
571    "esModuleInterop": true,
572    "skipLibCheck": true,
573    "forceConsistentCasingInFileNames": true,
574    "declaration": true,
575    "declarationMap": true,
576    "sourceMap": true,
577    "allowSyntheticDefaultImports": true
578  },
579  "include": ["src/**/*"],
580  "exclude": ["node_modules", "dist"]
581}
582```
583 
584## Complete Example
585 
586```typescript
587#!/usr/bin/env node
588/**
589 * MCP Server for Example Service.
590 *
591 * This server provides tools to interact with Example API, including user search,
592 * project management, and data export capabilities.
593 */
594 
595import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
596import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
597import { z } from "zod";
598import axios, { AxiosError } from "axios";
599 
600// Constants
601const API_BASE_URL = "https://api.example.com/v1";
602const CHARACTER_LIMIT = 25000;
603 
604// Enums
605enum ResponseFormat {
606  MARKDOWN = "markdown",
607  JSON = "json"
608}
609 
610// Zod schemas
611const UserSearchInputSchema = z.object({
612  query: z.string()
613    .min(2, "Query must be at least 2 characters")
614    .max(200, "Query must not exceed 200 characters")
615    .describe("Search string to match against names/emails"),
616  limit: z.number()
617    .int()
618    .min(1)
619    .max(100)
620    .default(20)
621    .describe("Maximum results to return"),
622  offset: z.number()
623    .int()
624    .min(0)
625    .default(0)
626    .describe("Number of results to skip for pagination"),
627  response_format: z.nativeEnum(ResponseFormat)
628    .default(ResponseFormat.MARKDOWN)
629    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
630}).strict();
631 
632type UserSearchInput = z.infer<typeof UserSearchInputSchema>;
633 
634// Shared utility functions
635async function makeApiRequest<T>(
636  endpoint: string,
637  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
638  data?: any,
639  params?: any
640): Promise<T> {
641  try {
642    const response = await axios({
643      method,
644      url: `${API_BASE_URL}/${endpoint}`,
645      data,
646      params,
647      timeout: 30000,
648      headers: {
649        "Content-Type": "application/json",
650        "Accept": "application/json"
651      }
652    });
653    return response.data;
654  } catch (error) {
655    throw error;
656  }
657}
658 
659function handleApiError(error: unknown): string {
660  if (error instanceof AxiosError) {
661    if (error.response) {
662      switch (error.response.status) {
663        case 404:
664          return "Error: Resource not found. Please check the ID is correct.";
665        case 403:
666          return "Error: Permission denied. You don't have access to this resource.";
667        case 429:
668          return "Error: Rate limit exceeded. Please wait before making more requests.";
669        default:
670          return `Error: API request failed with status ${error.response.status}`;
671      }
672    } else if (error.code === "ECONNABORTED") {
673      return "Error: Request timed out. Please try again.";
674    }
675  }
676  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
677}
678 
679// Create MCP server instance
680const server = new McpServer({
681  name: "example-mcp",
682  version: "1.0.0"
683});
684 
685// Register tools
686server.registerTool(
687  "example_search_users",
688  {
689    title: "Search Example Users",
690    description: `[Full description as shown above]`,
691    inputSchema: UserSearchInputSchema,
692    annotations: {
693      readOnlyHint: true,
694      destructiveHint: false,
695      idempotentHint: true,
696      openWorldHint: true
697    }
698  },
699  async (params: UserSearchInput) => {
700    // Implementation as shown above
701  }
702);
703 
704// Main function
705// For stdio (local):
706async function runStdio() {
707  if (!process.env.EXAMPLE_API_KEY) {
708    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
709    process.exit(1);
710  }
711 
712  const transport = new StdioServerTransport();
713  await server.connect(transport);
714  console.error("MCP server running via stdio");
715}
716 
717// For streamable HTTP (remote):
718async function runHTTP() {
719  if (!process.env.EXAMPLE_API_KEY) {
720    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
721    process.exit(1);
722  }
723 
724  const app = express();
725  app.use(express.json());
726 
727  app.post('/mcp', async (req, res) => {
728    const transport = new StreamableHTTPServerTransport({
729      sessionIdGenerator: undefined,
730      enableJsonResponse: true
731    });
732    res.on('close', () => transport.close());
733    await server.connect(transport);
734    await transport.handleRequest(req, res, req.body);
735  });
736 
737  const port = parseInt(process.env.PORT || '3000');
738  app.listen(port, () => {
739    console.error(`MCP server running on http://localhost:${port}/mcp`);
740  });
741}
742 
743// Choose transport based on environment
744const transport = process.env.TRANSPORT || 'stdio';
745if (transport === 'http') {
746  runHTTP().catch(error => {
747    console.error("Server error:", error);
748    process.exit(1);
749  });
750} else {
751  runStdio().catch(error => {
752    console.error("Server error:", error);
753    process.exit(1);
754  });
755}
756```
757 
758---
759 
760## Advanced MCP Features
761 
762### Resource Registration
763 
764Expose data as resources for efficient, URI-based access:
765 
766```typescript
767import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";
768 
769// Register a resource with URI template
770server.registerResource(
771  {
772    uri: "file://documents/{name}",
773    name: "Document Resource",
774    description: "Access documents by name",
775    mimeType: "text/plain"
776  },
777  async (uri: string) => {
778    // Extract parameter from URI
779    const match = uri.match(/^file:\/\/documents\/(.+)$/);
780    if (!match) {
781      throw new Error("Invalid URI format");
782    }
783 
784    const documentName = match[1];
785    const content = await loadDocument(documentName);
786 
787    return {
788      contents: [{
789        uri,
790        mimeType: "text/plain",
791        text: content
792      }]
793    };
794  }
795);
796 
797// List available resources dynamically
798server.registerResourceList(async () => {
799  const documents = await getAvailableDocuments();
800  return {
801    resources: documents.map(doc => ({
802      uri: `file://documents/${doc.name}`,
803      name: doc.name,
804      mimeType: "text/plain",
805      description: doc.description
806    }))
807  };
808});
809```
810 
811**When to use Resources vs Tools:**
812- **Resources**: For data access with simple URI-based parameters
813- **Tools**: For complex operations requiring validation and business logic
814- **Resources**: When data is relatively static or template-based
815- **Tools**: When operations have side effects or complex workflows
816 
817### Transport Options
818 
819The TypeScript SDK supports two main transport mechanisms:
820 
821#### Streamable HTTP (Recommended for Remote Servers)
822 
823```typescript
824import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
825import express from "express";
826 
827const app = express();
828app.use(express.json());
829 
830app.post('/mcp', async (req, res) => {
831  // Create new transport for each request (stateless, prevents request ID collisions)
832  const transport = new StreamableHTTPServerTransport({
833    sessionIdGenerator: undefined,
834    enableJsonResponse: true
835  });
836 
837  res.on('close', () => transport.close());
838 
839  await server.connect(transport);
840  await transport.handleRequest(req, res, req.body);
841});
842 
843app.listen(3000);
844```
845 
846#### stdio (For Local Integrations)
847 
848```typescript
849import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
850 
851const transport = new StdioServerTransport();
852await server.connect(transport);
853```
854 
855**Transport selection:**
856- **Streamable HTTP**: Web services, remote access, multiple clients
857- **stdio**: Command-line tools, local development, subprocess integration
858 
859### Notification Support
860 
861Notify clients when server state changes:
862 
863```typescript
864// Notify when tools list changes
865server.notification({
866  method: "notifications/tools/list_changed"
867});
868 
869// Notify when resources change
870server.notification({
871  method: "notifications/resources/list_changed"
872});
873```
874 
875Use notifications sparingly - only when server capabilities genuinely change.
876 
877---
878 
879## Code Best Practices
880 
881### Code Composability and Reusability
882 
883Your implementation MUST prioritize composability and code reuse:
884 
8851. **Extract Common Functionality**:
886   - Create reusable helper functions for operations used across multiple tools
887   - Build shared API clients for HTTP requests instead of duplicating code
888   - Centralize error handling logic in utility functions
889   - Extract business logic into dedicated functions that can be composed
890   - Extract shared markdown or JSON field selection & formatting functionality
891 
8922. **Avoid Duplication**:
893   - NEVER copy-paste similar code between tools
894   - If you find yourself writing similar logic twice, extract it into a function
895   - Common operations like pagination, filtering, field selection, and formatting should be shared
896   - Authentication/authorization logic should be centralized
897 
898## Building and Running
899 
900Always build your TypeScript code before running:
901 
902```bash
903# Build the project
904npm run build
905 
906# Run the server
907npm start
908 
909# Development with auto-reload
910npm run dev
911```
912 
913Always ensure `npm run build` completes successfully before considering the implementation complete.
914 
915## Quality Checklist
916 
917Before finalizing your Node/TypeScript MCP server implementation, ensure:
918 
919### Strategic Design
920- [ ] Tools enable complete workflows, not just API endpoint wrappers
921- [ ] Tool names reflect natural task subdivisions
922- [ ] Response formats optimize for agent context efficiency
923- [ ] Human-readable identifiers used where appropriate
924- [ ] Error messages guide agents toward correct usage
925 
926### Implementation Quality
927- [ ] FOCUSED IMPLEMENTATION: Most important and valuable tools implemented
928- [ ] All tools registered using `registerTool` with complete configuration
929- [ ] All tools include `title`, `description`, `inputSchema`, and `annotations`
930- [ ] Annotations correctly set (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
931- [ ] All tools use Zod schemas for runtime input validation with `.strict()` enforcement
932- [ ] All Zod schemas have proper constraints and descriptive error messages
933- [ ] All tools have comprehensive descriptions with explicit input/output types
934- [ ] Descriptions include return value examples and complete schema documentation
935- [ ] Error messages are clear, actionable, and educational
936 
937### TypeScript Quality
938- [ ] TypeScript interfaces are defined for all data structures
939- [ ] Strict TypeScript is enabled in tsconfig.json
940- [ ] No use of `any` type - use `unknown` or proper types instead
941- [ ] All async functions have explicit Promise<T> return types
942- [ ] Error handling uses proper type guards (e.g., `axios.isAxiosError`, `z.ZodError`)
943 
944### Advanced Features (where applicable)
945- [ ] Resources registered for appropriate data endpoints
946- [ ] Appropriate transport configured (stdio or streamable HTTP)
947- [ ] Notifications implemented for dynamic server capabilities
948- [ ] Type-safe with SDK interfaces
949 
950### Project Configuration
951- [ ] Package.json includes all necessary dependencies
952- [ ] Build script produces working JavaScript in dist/ directory
953- [ ] Main entry point is properly configured as dist/index.js
954- [ ] Server name follows format: `{service}-mcp-server`
955- [ ] tsconfig.json properly configured with strict mode
956 
957### Code Quality
958- [ ] Pagination is properly implemented where applicable
959- [ ] Large responses check CHARACTER_LIMIT constant and truncate with clear messages
960- [ ] Filtering options are provided for potentially large result sets
961- [ ] All network operations handle timeouts and connection errors gracefully
962- [ ] Common functionality is extracted into reusable functions
963- [ ] Return types are consistent across similar operations
964 
965### Testing and Build
966- [ ] `npm run build` completes successfully without errors
967- [ ] dist/index.js created and executable
968- [ ] Server runs: `node dist/index.js --help`
969- [ ] All imports resolve correctly
970- [ ] Sample tool calls work as expected