name: mcp-builder
description: Build high-quality Model Context Protocol (MCP) servers to integrate external APIs and services. Use when creating MCP tools, resources, or prompts.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

MCP Builder

Create well-structured Model Context Protocol servers that integrate external APIs and services.

MCP Fundamentals

MCP servers expose three primitives:
1. Tools - Functions the AI can call (with user approval)
2. Resources - Data the AI can read (files, database records, API responses)
3. Prompts - Pre-defined prompt templates

Server Structure

my-mcp-server/
├── src/
│   ├── index.ts          # Main entry point
│   ├── tools/            # Tool implementations
│   ├── resources/        # Resource handlers
│   └── prompts/          # Prompt templates
├── package.json
├── tsconfig.json
└── README.md

Tool Design Principles

Naming

• Use verb_noun format: get_user, create_issue, search_files
• Be specific: get_github_issue not get_issue
• Match the API's terminology

Input Schema

• Use JSON Schema for parameter validation
• Mark required fields explicitly
• Provide clear descriptions for each parameter
• Include examples where helpful

Error Handling

• Return structured error messages
• Include actionable information
• Don't expose internal details

Best Practices

Authentication

• Support environment variables for credentials
• Never hardcode secrets
• Document required auth setup clearly

Rate Limiting

• Implement backoff for API rate limits
• Cache responses where appropriate
• Batch requests when possible

Testing

• Write unit tests for each tool
• Test error paths, not just happy paths
• Mock external APIs in tests

Example Tool Implementation

server.tool(
  "get_weather",
  {
    description: "Get current weather for a location",
    inputSchema: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "City name or coordinates"
        }
      },
      required: ["location"]
    }
  },
  async ({ location }) => {
    const data = await weatherApi.getCurrent(location);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(data, null, 2)
      }]
    };
  }
);

Resources

• MCP Specification
• MCP TypeScript SDK
• MCP Python SDK