AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

Original source
anthropics
License
Apache-2.0
Pinned revision
ca45fc496a3436251f191354091d557da31c15b5

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read anthropics--mcp-builder at revision ca45fc496a3436251f191354091d557da31c15b5, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

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:

  1. 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
  2. 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 registerTool with complete configuration
  • [ ] All tools include title, description, inputSchema, and annotations
  • [ ] 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 any type - use unknown or 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 build completes 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