mcp-builder
Scannednpx machina-cli add skill vudovn/antigravity-kit/mcp-builder --openclawFiles (1)
SKILL.md
3.2 KB
MCP Builder
Principles for building MCP servers.
1. MCP Overview
What is MCP?
Model Context Protocol - standard for connecting AI systems with external tools and data sources.
Core Concepts
| Concept | Purpose |
|---|---|
| Tools | Functions AI can call |
| Resources | Data AI can read |
| Prompts | Pre-defined prompt templates |
2. Server Architecture
Project Structure
my-mcp-server/
├── src/
│ └── index.ts # Main entry
├── package.json
└── tsconfig.json
Transport Types
| Type | Use |
|---|---|
| Stdio | Local, CLI-based |
| SSE | Web-based, streaming |
| WebSocket | Real-time, bidirectional |
3. Tool Design Principles
Good Tool Design
| Principle | Description |
|---|---|
| Clear name | Action-oriented (get_weather, create_user) |
| Single purpose | One thing well |
| Validated input | Schema with types and descriptions |
| Structured output | Predictable response format |
Input Schema Design
| Field | Required? |
|---|---|
| Type | Yes - object |
| Properties | Define each param |
| Required | List mandatory params |
| Description | Human-readable |
4. Resource Patterns
Resource Types
| Type | Use |
|---|---|
| Static | Fixed data (config, docs) |
| Dynamic | Generated on request |
| Template | URI with parameters |
URI Patterns
| Pattern | Example |
|---|---|
| Fixed | docs://readme |
| Parameterized | users://{userId} |
| Collection | files://project/* |
5. Error Handling
Error Types
| Situation | Response |
|---|---|
| Invalid params | Validation error message |
| Not found | Clear "not found" |
| Server error | Generic error, log details |
Best Practices
- Return structured errors
- Don't expose internal details
- Log for debugging
- Provide actionable messages
6. Multimodal Handling
Supported Types
| Type | Encoding |
|---|---|
| Text | Plain text |
| Images | Base64 + MIME type |
| Files | Base64 + MIME type |
7. Security Principles
Input Validation
- Validate all tool inputs
- Sanitize user-provided data
- Limit resource access
API Keys
- Use environment variables
- Don't log secrets
- Validate permissions
8. Configuration
Claude Desktop Config
| Field | Purpose |
|---|---|
| command | Executable to run |
| args | Command arguments |
| env | Environment variables |
9. Testing
Test Categories
| Type | Focus |
|---|---|
| Unit | Tool logic |
| Integration | Full server |
| Contract | Schema validation |
10. Best Practices Checklist
- Clear, action-oriented tool names
- Complete input schemas with descriptions
- Structured JSON output
- Error handling for all cases
- Input validation
- Environment-based configuration
- Logging for debugging
Remember: MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.
Source
git clone https://github.com/vudovn/antigravity-kit/blob/main/.agent/skills/mcp-builder/SKILL.mdView on GitHub Overview
MCP Builder provides practical principles for constructing MCP (Model Context Protocol) servers. It covers tool design, resource patterns, prompts, error handling, security, and testing to create robust AI-tool integrations.
How This Skill Works
It defines core MCP concepts (Tools, Resources, Prompts), outlines a standard project structure, and prescribes transport options (Stdio, SSE, WebSocket). It then enforces consistent input schemas, structured outputs, and defensive error handling across tools.
When to Use It
- You’re designing a new MCP server from scratch and need clear patterns for tools, resources, and prompts.
- You want strict input/output schemas and predictable tool responses.
- You need to support multiple transports (CLI, streaming, real-time).
- You’re aiming to apply resource patterns (Static/Dynamic/Template) consistently.
- You’re auditing security, validation, and logging across the MCP stack.
Quick Start
- Step 1: Define Tools, Resources, and Prompts per MCP core concepts.
- Step 2: Scaffold project (src/index.ts, package.json, tsconfig.json) and pick a transport (Stdio/SSE/WebSocket).
- Step 3: Implement input schemas, structured outputs, and error handling; run unit/integration tests.
Best Practices
- Use clear, action-oriented tool names (e.g., get_weather, create_user).
- Complete input schemas with types and descriptions for every field.
- Return structured outputs in a predictable JSON-like format.
- Validate all inputs, sanitize data, and enforce permission limits.
- Configure via environment variables and avoid logging secrets.
Example Use Cases
- Build a docs viewer with a fixed docs://readme resource and a parameterized docs path.
- Create a weather tool that fetches data via a get_weather action and emits structured responses.
- Implement a user-management tool with create_user and proper input validation.
- Use template URIs (files://project/*) to serve project docs and assets dynamically.
- Support real-time updates by streaming via SSE for long-running queries.
Frequently Asked Questions
Add this skill to your agents
