mcp-builder

Original source / Raw SKILL.md

---
name: mcp-builder
description: Build MCP (Model Context Protocol) servers in TypeScript or Python. Use when creating custom tools, resources, or prompts that extend AI assistant capabilities via MCP.
compatibility: Requires Node.js 18+ or Python 3.10+
metadata:
  version: "1.0"
---

# MCP Builder

## Decision Tree

```
What are you building?
    ├─ Tool (action the AI can take) → Define tool with input schema
    ├─ Resource (data the AI can read) → Define resource with URI
    └─ Prompt (reusable template) → Define prompt with arguments

What language?
    ├─ TypeScript → See references/typescript-guide.md
    └─ Python → See references/python-guide.md
```

## Quick Start (TypeScript)

```bash
npx @anthropic-ai/create-mcp-server my-server
cd my-server && npm install
```

```typescript
import { McpServer } from '@anthropic-ai/mcp-server';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

server.tool('greet', { name: { type: 'string' } }, async ({ name }) => {
  return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
});

server.run();
```

## Quick Start (Python)

```bash
pip install mcp
```

```python
from mcp.server import Server

server = Server("my-server")

@server.tool("greet")
async def greet(name: str) -> str:
    return f"Hello, {name}!"

server.run()
```

## Configuration

Register in `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/my-server/dist/index.js"]
    }
  }
}
```

## Best Practices

- Return structured data (JSON) not just text
- Include error handling with meaningful messages
- Add input validation on all tool parameters
- Keep tools focused (one action per tool)
- Use descriptive names and descriptions (shown to the AI)

## For detailed guides see:
- [TypeScript MCP guide](references/typescript-guide.md)
- [Python MCP guide](references/python-guide.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/typescript-guide.md

```markdown
# TypeScript MCP Server Guide

## Project Structure

```
my-mcp-server/
├── src/
│   ├── index.ts          # Server setup + tool registration
│   ├── tools/            # One file per tool
│   └── resources/        # One file per resource
├── package.json
└── tsconfig.json
```

## Tool with Validation

```typescript
server.tool(
  'search-files',
  {
    query: { type: 'string', description: 'Search query' },
    path: { type: 'string', description: 'Directory to search', default: '.' },
    maxResults: { type: 'number', description: 'Maximum results', default: 10 },
  },
  async ({ query, path, maxResults }) => {
    if (!query.trim()) {
      return { content: [{ type: 'text', text: 'Error: query cannot be empty' }], isError: true };
    }
    const results = await searchFiles(query, path, maxResults);
    return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
  }
);
```

## Testing

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}}}' | node dist/index.js
```

```

### references/python-guide.md

```markdown
# Python MCP Server Guide

## Project Structure

```
my-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py         # Server setup + tool registration
│   ├── tools/
│   └── resources/
├── pyproject.toml
└── requirements.txt
```

## Tool with Validation

```python
from mcp.server import Server
from mcp.types import TextContent

server = Server("my-server")

@server.tool("search-files")
async def search_files(query: str, path: str = ".", max_results: int = 10) -> list[TextContent]:
    """Search for files matching a query."""
    if not query.strip():
        raise ValueError("Query cannot be empty")
    results = await do_search(query, path, max_results)
    return [TextContent(type="text", text=json.dumps(results, indent=2))]
```

## Configuration

```json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["-m", "src.server"]
    }
  }
}
```

```