Jeffallan/claude-skills / skills/mcp-developer
mcp-developer
VerifiedUse when building, debugging, or extending MCP servers or clients that connect AI systems with external tools and data sources. Invoke to implement tool handlers, configure resource providers, set up stdio/HTTP/SSE transport layers, validate schemas with Zod or Pydantic, debug protocol compliance issues, or scaffold complete MCP server/client projects using TypeScript or Python SDKs.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
| references/protocol.md | markdown | 4.9 KB |
| references/python-sdk.md | markdown | 9.6 KB |
| references/resources.md | markdown | 11.9 KB |
| references/tools.md | markdown | 10.2 KB |
| references/typescript-sdk.md | markdown | 7.8 KB |
references/tools.md
View on GitHub# MCP Tools Reference
## Tool Definition
Tools are functions that AI assistants can invoke to perform actions or retrieve data.
```typescript
{
"name": "tool_name",
"description": "Clear description of what the tool does",
"inputSchema": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "What this parameter is for"
}
},
"required": ["param1"]
}
}
```
## Input Schema Patterns
### Simple String Parameter
```typescript
{
"name": "search_docs",
"description": "Search documentation for a query",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query",
"minLength": 1
}
},
"required": ["query"]
}
}
```
### Enum Values
```typescript
{
"name": "get_weather",
"description": "Get weather information",
"inputSchema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"units": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius",
"description": "Temperature units"
}
},
"required": ["location"]
}
}
```
### Nested Objects
```typescript
{
"name": "create_task",
"description": "Create a new task",
"inputSchema": {
"type": "object",
"properties": {
"title": { "type": "string", "minLength": 1 },
"metadata": {
"type": "object",
"properties": {
"priority": { "type": "string", "enum": ["low", "medium", "high"] },
"tags": { "type": "array", "items": { "type": "string" } }
}
}
},
"required": ["title"]
}
}
```
### Array Parameters
```typescript
{
"name": "batch_process",
"description": "Process multiple items",
"inputSchema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"action": { "type": "string", "enum": ["update", "delete"] }
},
"required": ["id", "action"]
},
"minItems": 1,
"maxItems": 100
}
},
"required": ["items"]
}
}
```
### Union Types (anyOf)
```typescript
{
"name": "search",
"description": "Search by ID or query",
"inputSchema": {
"type": "object",
"properties": {
"search": {
"anyOf": [
{ "type": "string", "description": "Search query" },
{ "type": "number", "description": "Item ID" }
]
}
},
"required": ["search"]
}
}
```
## Tool Response Formats
### Text Response
```typescript
{
"content": [
{
"type": "text",
"text": "Operation completed successfully"
}
]
}
```
### Multiple Content Blocks
```typescript
{
"content": [
{
"type": "text",
"text": "Found 3 results:"
},
{
"type": "text",
"text": "1. First result\n2. Second result\n3. Third result"
}
]
}
```
### Image Content
```typescript
{
"content": [
{
"type": "image",
"data": "base64-encoded-image-data",
"mimeType": "image/png"
}
]
}
```
### Resource Reference
```typescript
{
"content": [
{
"type": "resource",
"resource": {
"uri": "file:///data/results.json",
"mimeType": "application/json",
"text": "{\"results\": [...]}"
}
}
]
}
```
## Tool Implementation Patterns
### Database Query Tool
```typescript
// TypeScript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "query_database") {
const { table, filter, limit } = request.params.arguments as {
table: string;
filter?: Record<string, any>;
limit?: number;
};
// Validate table name (prevent SQL injection)
if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
throw new McpError(ErrorCode.InvalidParams, "Invalid table name");
}
const results = await db.query(table, filter, limit || 10);
return {
content: [
{
type: "text",
text: JSON.stringify(results, null, 2),
},
],
};
}
});
```
```python
# Python
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "query_database":
args = QueryArgs(**arguments) # Pydantic validation
# Validate table name
if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', args.table):
raise ValueError("Invalid table name")
results = await db.query(args.table, args.filter, args.limit)
return [
TextContent(type="text", text=json.dumps(results, indent=2))
]
```
### File System Tool
```typescript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "read_file") {
const { path } = request.params.arguments as { path: string };
// Security: validate path is within allowed directory
const safePath = resolvePath(ALLOWED_DIR, path);
if (!safePath.startsWith(ALLOWED_DIR)) {
throw new McpError(ErrorCode.InvalidParams, "Access denied");
}
const content = await fs.readFile(safePath, "utf-8");
return {
content: [{ type: "text", text: content }],
};
}
});
```
### HTTP API Tool
```python
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "fetch_api":
args = FetchArgs(**arguments)
async with httpx.AsyncClient() as client:
try:
response = await client.get(
args.url,
timeout=30.0,
headers={"User-Agent": "MCP Server"}
)
response.raise_for_status()
return [
TextContent(
type="text",
text=response.text
)
]
except httpx.HTTPError as e:
raise McpError(INTERNAL_ERROR, f"HTTP request failed: {e}")
```
### Async Background Task
```typescript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "start_job") {
const { jobType, params } = request.params.arguments as {
jobType: string;
params: Record<string, any>;
};
// Start job asynchronously
const jobId = await jobQueue.enqueue(jobType, params);
return {
content: [
{
type: "text",
text: `Job started with ID: ${jobId}`,
},
],
};
}
if (request.params.name === "check_job") {
const { jobId } = request.params.arguments as { jobId: string };
const status = await jobQueue.getStatus(jobId);
return {
content: [
{
type: "text",
text: JSON.stringify(status, null, 2),
},
],
};
}
});
```
## Best Practices
### 1. Descriptive Names and Descriptions
```typescript
// Good
{
"name": "search_knowledge_base",
"description": "Search the knowledge base using semantic search. Returns top 5 relevant documents with excerpts.",
"inputSchema": { ... }
}
// Bad
{
"name": "search",
"description": "Search",
"inputSchema": { ... }
}
```
### 2. Input Validation
```python
class SearchArgs(BaseModel):
query: str = Field(..., min_length=1, max_length=500)
max_results: int = Field(default=5, ge=1, le=50)
filters: dict[str, str] = Field(default_factory=dict)
@field_validator("query")
@classmethod
def validate_query(cls, v: str) -> str:
# Sanitize query
return v.strip()
```
### 3. Error Handling
```typescript
try {
const result = await executeOperation(params);
return { content: [{ type: "text", text: result }] };
} catch (error) {
if (error instanceof ValidationError) {
throw new McpError(ErrorCode.InvalidParams, error.message);
}
if (error instanceof NotFoundError) {
return {
content: [{ type: "text", text: "Resource not found" }],
isError: true,
};
}
throw new McpError(ErrorCode.InternalError, `Operation failed: ${error.message}`);
}
```
### 4. Rate Limiting
```python
from asyncio import Lock
from datetime import datetime, timedelta
rate_limiter = {}
rate_limit_lock = Lock()
async def check_rate_limit(tool_name: str, limit: int = 10) -> None:
async with rate_limit_lock:
now = datetime.now()
if tool_name not in rate_limiter:
rate_limiter[tool_name] = []
# Remove old entries
rate_limiter[tool_name] = [
t for t in rate_limiter[tool_name]
if now - t < timedelta(minutes=1)
]
if len(rate_limiter[tool_name]) >= limit:
raise McpError(-32004, "Rate limit exceeded")
rate_limiter[tool_name].append(now)
```
### 5. Idempotency
```typescript
// For operations that should be idempotent, use unique IDs
{
"name": "create_record",
"inputSchema": {
"type": "object",
"properties": {
"idempotency_key": {
"type": "string",
"description": "Unique key to prevent duplicate operations"
},
"data": { "type": "object" }
},
"required": ["idempotency_key", "data"]
}
}
```
### 6. Timeouts
```python
import asyncio
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "long_operation":
try:
result = await asyncio.wait_for(
execute_operation(arguments),
timeout=30.0 # 30 second timeout
)
return [TextContent(type="text", text=str(result))]
except asyncio.TimeoutError:
raise McpError(INTERNAL_ERROR, "Operation timed out")
```
### 7. Logging
```typescript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const startTime = Date.now();
console.error(`[${new Date().toISOString()}] Tool call: ${request.params.name}`);
try {
const result = await executeTool(request.params.name, request.params.arguments);
const duration = Date.now() - startTime;
console.error(`[${new Date().toISOString()}] Tool completed in ${duration}ms`);
return result;
} catch (error) {
console.error(`[${new Date().toISOString()}] Tool failed:`, error);
throw error;
}
});
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |