mcp-builder

MCP Builder

Overview

The Model Context Protocol (MCP) is the standard for connecting AI assistants to external tools, data, and prompts. Building a quality MCP server requires understanding the protocol's three capability types and implementing them with proper error handling and transport support.

Core principle: MCP servers are AI interfaces, not REST APIs. Design for machine consumption and LLM context efficiency.

Iron Law:

SCHEMA FIRST. Every Tool, Resource, and Prompt must have complete JSON Schema before implementation.

When to Use

• Creating a new MCP server from scratch
• Adding new Tools, Resources, or Prompts to an existing server
• Implementing new transport modes (stdio ↔ SSE)
• Testing MCP server capabilities
• Debugging MCP communication issues

MCP Architecture Overview

MCP Client (Claude, Cursor, etc.)
        ↕  stdio / SSE
MCP Server
  ├── Tools      → Functions the AI can call (side effects allowed)
  ├── Resources  → Data the AI can read (read-only, URI-addressed)
  └── Prompts    → Reusable prompt templates

NestJS MCP Server Structure

apps/mcp-server/src/
├── main.ts              # Transport setup (stdio vs SSE)
├── app.module.ts        # Root module
├── mcp/
│   ├── mcp.module.ts    # MCP module
│   ├── mcp.service.ts   # MCP server registration
│   ├── tools/           # Tool handlers
│   ├── resources/       # Resource handlers
│   └── prompts/         # Prompt handlers
└── rules/
    ├── rules.module.ts
    └── rules.service.ts # Business logic (pure)

Designing MCP Capabilities

Tools (AI can call these)

Tools perform actions and return results. They CAN have side effects.

// Tool Schema (define first)
const searchRulesTool = {
  name: 'search_rules',
  description: 'Search AI coding rules by keyword or topic. Returns matching rules with their content.',
  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Search term to find relevant rules',
        minLength: 1,
        maxLength: 200,
      },
      limit: {
        type: 'number',
        description: 'Maximum results to return (default: 10)',
        minimum: 1,
        maximum: 50,
        default: 10,
      },
    },
    required: ['query'],
  },
};