mcp-builder

MCP Server Development Guide

Create MCP servers that enable LLMs to interact with external services through well-designed tools.

High-Level Workflow

Phase 1: Research and Planning

Understand Modern MCP Design:

• Balance comprehensive API coverage with specialized workflow tools
• Use clear, descriptive tool names with consistent prefixes (e.g., github_create_issue)
• Design tools that return focused, relevant data
• Provide actionable error messages

Study MCP Protocol:

• Start with sitemap: https://modelcontextprotocol.io/sitemap.xml
• Key pages: specification, transport mechanisms, tool definitions

Phase 2: Implementation

Recommended Stack:

• Language: TypeScript (best SDK support)
• Transport: Streamable HTTP for remote, stdio for local

Project Structure:

my-mcp-server/
├── src/
│   ├── index.ts      # Server entry point
│   ├── tools/        # Tool implementations
│   └── utils/        # Shared utilities
├── package.json
└── tsconfig.json

Tool Implementation Pattern:

server.registerTool({
  name: "github_create_issue",
  description: "Create a new GitHub issue",
  inputSchema: z.object({
    repo: z.string().describe("Repository name (owner/repo)"),
    title: z.string().describe("Issue title"),
    body: z.string().optional().describe("Issue body")
  }),
  outputSchema: z.object({
    id: z.number(),
    url: z.string()
  }),
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false
  },
  handler: async (input) => {
    // Implementation
    return { id: 123, url: "https://..." };
  }
});

Phase 3: Test

# TypeScript
npm run build
npx @modelcontextprotocol/inspector

# Python
python -m py_compile your_server.py

Phase 4: Create Evaluations

Create 10 complex, realistic questions to test your MCP server:

<evaluation>
  <qa_pair>
    <question>Find all open issues labeled 'bug' in the repo</question>
    <answer>5</answer>
  </qa_pair>
</evaluation>

Tool Design Best Practices

• Use Zod (TS) or Pydantic (Python) for schemas
• Include constraints and examples in field descriptions
• Define outputSchema for structured data
• Support pagination where applicable
• Add tool annotations (readOnly, destructive, idempotent)

Scientific Skill Interleaving

This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:

Graph Theory

• networkx [○] via bicomodule
  • Universal graph hub

Bibliography References

• general: 734 citations in bib.duckdb

Cat# Integration

This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:

Trit: 1 (PLUS)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #4ECDC4

GF(3) Naturality

The skill participates in triads satisfying:

(-1) + (0) + (+1) ≡ 0 (mod 3)

This ensures compositional coherence in the Cat# equipment structure.