# MCP Builder

> MCP server development: build, create, and test Model Context Protocol servers in TypeScript or Python. Tool design, input/output schemas, Zod/Pydantic validation, evaluations, stdio/HTTP transport, @modelcontextprotocol/sdk, FastMCP.

- **Type:** Skill
- **Install:** `agentstack add skill-poorgramer-zack-copilot-cli-things-mcp-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Poorgramer-Zack](https://agentstack.voostack.com/s/poorgramer-zack)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Poorgramer-Zack](https://github.com/Poorgramer-Zack)
- **Source:** https://github.com/Poorgramer-Zack/copilot-cli-things/tree/main/plugins/mcp-builder/skills/mcp-builder

## Install

```sh
agentstack add skill-poorgramer-zack-copilot-cli-things-mcp-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Server Development Guide

Build MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools.

**Deliverables:** working MCP server with well-designed tools, clear tool descriptions/input schemas/annotations, evaluation suite, and setup documentation.

---

## Phase 1: Deep Research and Planning

### 1.1 Understand Modern MCP Design

**API Coverage vs. Workflow Tools:**
Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage — it gives agents flexibility to compose operations.

**Tool Naming and Discoverability:**
- Use `snake_case` with service prefix: `{service}_{action}_{resource}`
- Examples: `slack_send_message`, `github_create_issue`
- Be action-oriented: start with verbs (get, list, search, create, update, delete)

**Context Management:**
Design tools that return focused, relevant data. Support pagination and filtering to avoid overwhelming responses.

**Actionable Error Messages:**
Error messages should guide agents toward solutions with specific suggestions and next steps.

### 1.2 Study MCP Protocol

Start with the sitemap: `https://modelcontextprotocol.io/sitemap.xml`
Fetch specific pages with `.md` suffix (e.g., `https://modelcontextprotocol.io/specification/draft.md`).

Key pages: specification overview, transport mechanisms (streamable HTTP, stdio), tool/resource/prompt definitions.

### 1.3 Choose Framework

**Recommended stack:**
- **Language**: TypeScript (strong SDK support, good AI code generation, static typing)
- **Transport**: Streamable HTTP for remote servers (stateless JSON), stdio for local servers

**Framework documentation:**
- 📋 [MCP Best Practices](./references/mcp-best-practices.md) — Core guidelines (load first)
- ⚡ [TypeScript Guide](./references/node-mcp-server.md) — TypeScript patterns with `@modelcontextprotocol/sdk`
- 🐍 [Python Guide](./references/python-mcp-server.md) — Python patterns with FastMCP

**SDK README (fetch via web):**
- TypeScript: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
- Python: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`

### 1.4 Plan Implementation

Review the target service's API documentation to identify key endpoints, authentication requirements, and data models. Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.

---

## Phase 2: Implementation

### 2.1 Project Setup

See language-specific guides for project structure, dependencies, and configuration:
- ⚡ [TypeScript Guide](./references/node-mcp-server.md) — package.json, tsconfig.json, project layout
- 🐍 [Python Guide](./references/python-mcp-server.md) — Module organization, FastMCP initialization

### 2.2 Core Infrastructure

Create shared utilities:
- API client with authentication (env vars for secrets, never hardcode)
- Error handling helpers with actionable messages
- Response formatting (JSON for programmatic, Markdown for human-readable)
- Pagination support with `limit`, `offset`, `has_more`, `next_offset`

### 2.3 Implement Tools

For each tool, define:

**Input Schema:**
- Use Zod (TypeScript) or Pydantic (Python) for runtime validation
- Include constraints, clear descriptions, and examples

**Output Schema:**
- Define `outputSchema` where possible for structured data
- Use `structuredContent` in tool responses (TypeScript SDK)

**Annotations:**
```
readOnlyHint: true/false      — Does not modify environment
destructiveHint: true/false   — May perform destructive updates
idempotentHint: true/false    — Repeated calls have no additional effect
openWorldHint: true/false     — Interacts with external entities
```

**Implementation patterns:**
- Async/await for all I/O operations
- Proper error handling with actionable messages
- Support pagination where applicable
- Return both text content and structured data

### 2.4 Server Naming

- **Python**: `{service}_mcp` (e.g., `slack_mcp`)
- **Node/TypeScript**: `{service}-mcp-server` (e.g., `slack-mcp-server`)

---

## Phase 3: Review and Test

### 3.1 Code Quality

Review for:
- No duplicated code (DRY principle)
- Consistent error handling across all tools
- Full type coverage (TypeScript strict mode, Python type hints)
- Clear, comprehensive tool descriptions

### 3.2 Build and Test

**TypeScript:**
```bash
npm run build          # Verify compilation
npx @modelcontextprotocol/inspector  # Test with MCP Inspector
```

**Python:**
```bash
python -m py_compile your_server.py  # Verify syntax
# Test with MCP Inspector
```

**Manual testing with Copilot CLI:**
Configure the server in `.github/mcp.json` and test with `copilot --debug`.

See 📋 [MCP Best Practices](./references/mcp-best-practices.md) for quality checklists.

---

## Phase 4: Create Evaluations

After implementing the MCP server, create evaluations to measure tool effectiveness.

Load ✅ [Evaluation Guide](./references/evaluation-guide.md) for complete guidelines.

### 4.1 Purpose

Evaluations test whether LLMs can effectively use your MCP server to answer realistic, complex questions using only the tools provided. Quality is measured by how well tools enable task completion, not just API coverage.

### 4.2 Create 10 Evaluation Questions

Follow the evaluation guide's process:
1. **Tool Inspection** — List available tools and understand capabilities
2. **Content Exploration** — Use READ-ONLY operations to explore available data
3. **Question Generation** — Create 10 complex, realistic questions
4. **Answer Verification** — Solve each question yourself to verify answers

### 4.3 Requirements

Each question must be:
- **Independent** — Not dependent on other questions
- **Read-only** — Only non-destructive operations required
- **Complex** — Requiring multiple tool calls and deep exploration
- **Realistic** — Based on real use cases humans would care about
- **Verifiable** — Single, clear answer verifiable by string comparison
- **Stable** — Answer will not change over time

### 4.4 Output Format

```xml

  
    Your question here
    Single verifiable answer
  
  

```

### 4.5 Running Evaluations

Use the provided evaluation harness in `scripts/`:

```bash
pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_key

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  evaluation.xml
```

See `scripts/README.md` and [Evaluation Guide](./references/evaluation-guide.md) for detailed instructions.

---

## Quick Reference

### Transport Options

| Criterion | stdio | Streamable HTTP |
|-----------|-------|-----------------|
| **Deployment** | Local | Remote |
| **Clients** | Single | Multiple |
| **Complexity** | Low | Medium |
| **Real-time** | No | Yes |

### Security Considerations

- **OAuth 2.1** for production authentication
- **Environment variables** for API keys — never in code
- **Input validation** via Zod/Pydantic schemas
- **DNS rebinding protection** for local HTTP servers (bind to `127.0.0.1`)
- Sanitize file paths, validate URLs, prevent command injection

---

## Reference Files

Load these resources as needed during development:

| Resource | When to Load | Content |
|----------|-------------|---------|
| 📋 [Best Practices](./references/mcp-best-practices.md) | Phase 1-3 | Naming, responses, pagination, security, error handling |
| ⚡ [TypeScript Guide](./references/node-mcp-server.md) | Phase 2 | Project setup, Zod schemas, `registerTool`, complete examples |
| 🐍 [Python Guide](./references/python-mcp-server.md) | Phase 2 | FastMCP setup, Pydantic models, `@mcp.tool`, complete examples |
| ✅ [Evaluation Guide](./references/evaluation-guide.md) | Phase 4 | Question/answer guidelines, running evaluations |
| 📄 [Example Evaluation](./examples/example-evaluation.xml) | Phase 4 | Sample evaluation XML |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Poorgramer-Zack](https://github.com/Poorgramer-Zack)
- **Source:** [Poorgramer-Zack/copilot-cli-things](https://github.com/Poorgramer-Zack/copilot-cli-things)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-poorgramer-zack-copilot-cli-things-mcp-builder
- Seller: https://agentstack.voostack.com/s/poorgramer-zack
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.