home / skills / enoch-robinson / agent-skill-collection / mcp-builder

mcp-builder skill

safe

This skill helps you build MCP servers that enable LLMs to interact with external services by providing structured tools, schemas, and testing guidance.

npx playbooks add skill enoch-robinson/agent-skill-collection --skill mcp-builder

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.2 KB

---
name: mcp-builder
description: MCP (Model Context Protocol) 服务器开发指南。当用户需要创建 MCP 服务器、集成外部 API 或服务、让 LLM 与外部系统交互时使用此技能。支持 TypeScript（推荐）和 Python。
---

# MCP Server Development Guide

创建高质量的 MCP 服务器，让 LLM 能够与外部服务交互。

## 概述

MCP (Model Context Protocol) 是一种协议，允许 LLM 通过定义良好的工具与外部服务交互。MCP 服务器的质量取决于它能多好地帮助 LLM 完成实际任务。

## 技术栈推荐

- **语言**: TypeScript（推荐）- SDK 支持好，类型安全
- **传输**: Streamable HTTP（远程服务器）/ stdio（本地服务器）

## 开发流程

### 阶段 1：研究与规划

1. **理解 API**：研究目标服务的 API 文档
2. **工具选择**：优先覆盖常用API 端点
3. **命名规范**：使用清晰的前缀，如 `github_create_issue`

### 阶段 2：实现

#### 项目结构 (TypeScript)
```
my-mcp-server/
├── src/
│   ├── index.ts        # 入口文件
│   ├── tools/          # 工具定义
│   └── utils/          # 工具函数
├── package.json
└── tsconfig.json
```

#### 工具定义要点

```typescript
// 使用 Zod 定义输入 Schema
const inputSchema = z.object({
  query: z.string().describe("搜索关键词"),
  limit: z.number().optional().default(10).describe("返回数量")
});

// 工具注解
{
  readOnlyHint: true,      // 只读操作
  destructiveHint: false,  // 非破坏性
  idempotentHint: true,    // 幂等操作
}
```

### 阶段 3：测试

```bash
# TypeScript 构建
npm run build

# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector
```

### 阶段 4：创建评估

创建 10 个复杂、真实的测试问题验证服务器效果。

## 工具设计原则

1. **清晰命名**：`service_action_target` 格式
2. **完整描述**：包含参数说明和返回类型
3. **错误处理**：提供可操作的错误信息
4. **分页支持**：大数据集支持分页

## 参考资源

- MCP 协议文档：https://modelcontextprotocol.io
- TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
- Python SDK：https://github.com/modelcontextprotocol/python-sdk

Overview

This skill is a practical developer guide for building MCP (Model Context Protocol) servers that let LLMs interact with external APIs and services. It covers recommended tech stacks (TypeScript preferred, Python supported), project structure, tool definition, testing, and evaluation practices. The content focuses on creating clear, robust tools that enable reliable LLM-driven integrations.

How this skill works

The guide walks you through researching target APIs, defining well-typed tools (input schemas, hints, and clear descriptions), and implementing a server that exposes those tools via Streamable HTTP or stdio. It shows how to annotate tool behavior (readOnly, destructive, idempotent), add error handling and pagination, and run validation with MCP Inspector and a set of realistic test prompts. Finally, it recommends building an evaluation suite of complex user scenarios to measure effectiveness.

When to use it

When you need an MCP server to let an LLM call external APIs or services.
When integrating a third-party API into an LLM workflow and you want typed, well-documented tools.
When choosing a stack: prefer TypeScript for SDK support and type safety; use Python when necessary.
When preparing an MCP server for production testing and automated evaluation.
When you need guidance on naming, schema design, and error handling for LLM-accessible tools.

Best practices

Prefer TypeScript for first-class SDK support and static types; Python is supported if preferred.
Design tools with clear names using service_action_target naming convention.
Define strict input schemas (e.g., Zod) and document parameter meanings and return types.
Annotate tool metadata: readOnlyHint, destructiveHint, idempotentHint to guide the LLM.
Implement actionable error messages and standardized pagination for large results.
Create a suite of realistic, complex test prompts (around 10+) and use MCP Inspector for validation.

Example use cases

Expose a GitHub integration: create issues, list PRs, fetch repo metadata with typed tool schemas.
Build a CRM connector that lets the LLM search contacts, update records, and paginate large lists.
Create a payment reconciliation tool where LLM queries transactions and flags anomalies with clear errors.
Implement a support automation server to triage tickets, add comments, and fetch related resources.
Wrap a public API to allow LLM-driven data lookups with rate-limit-aware pagination.

FAQ

Which language should I choose for my MCP server?

Use TypeScript when possible for better SDK support and type safety. Use Python if your team prefers it or for quick prototypes.

How do I validate my MCP server works with LLMs?

Build ~10 realistic, complex prompts that reflect real tasks and run them with the MCP Inspector to verify tool behavior and edge cases.