@musashishao/agent-kit 1.0.0 → 1.0.1

package/.agent/skills/mcp-builder/SKILL.md

@@ -1,12 +1,23 @@
 ---
 name: mcp-builder
-description: MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: MCP (Model Context Protocol) server building. Complete guide with TypeScript/Python examples, FastMCP, tool design, deployment patterns.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+skills:
+  - typescript-expert
+  - python-patterns
 ---
 
 # MCP Builder
 
-> Principles for building MCP servers.
+> Build production-ready MCP servers to extend AI capabilities with external tools and data.
+
+## 🔧 Quick Reference
+
+| File | Purpose |
+|------|---------|
+| [typescript-template.md](typescript-template.md) | TypeScript MCP server template |
+| [python-template.md](python-template.md) | FastMCP Python template |
+| [tool-patterns.md](tool-patterns.md) | Tool design patterns & examples |
 
 ---
 
@@ -14,154 +25,628 @@ allowed-tools: Read, Write, Edit, Glob, Grep
 
 ### What is MCP?
 
-Model Context Protocol - standard for connecting AI systems with external tools and data sources.
+Model Context Protocol - the open standard for connecting AI systems with external tools, data sources, and services.
+
+```
+┌─────────────┐     MCP Protocol     ┌─────────────────┐
+│   AI Host   │◄───────────────────►│   MCP Server    │
+│  (Claude)   │   Tools/Resources    │ (Your Service)  │
+└─────────────┘                      └─────────────────┘
+```
 
 ### Core Concepts
 
-| Concept | Purpose |
-|---------|---------|
-| **Tools** | Functions AI can call |
-| **Resources** | Data AI can read |
-| **Prompts** | Pre-defined prompt templates |
+| Concept | Purpose | Example |
+|---------|---------|---------|
+| **Tools** | Functions AI can call | `get_weather`, `create_issue` |
+| **Resources** | Data AI can read | Files, database records, APIs |
+| **Prompts** | Pre-defined templates | Workflow shortcuts |
+
+### Why Build MCP Servers?
+
+| Use Case | Example |
+|----------|---------|
+| **API Integration** | Connect to GitHub, Slack, Notion |
+| **Database Access** | Query PostgreSQL, MongoDB |
+| **File Operations** | Read/write local files |
+| **Custom Tools** | Domain-specific automation |
 
 ---
 
-## 2. Server Architecture
+## 2. TypeScript MCP Server
 
-### Project Structure
+### Quick Start
 
-```
-my-mcp-server/
-├── src/
-│   └── index.ts      # Main entry
-├── package.json
-└── tsconfig.json
+```bash
+# Create project
+mkdir my-mcp-server && cd my-mcp-server
+npm init -y
+npm install @modelcontextprotocol/sdk zod
+npm install -D typescript @types/node tsx
+
+# Create structure
+mkdir src
+touch src/index.ts
 ```
 
-### Transport Types
+### Basic Server Template
+
+```typescript
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// Create server instance
+const server = new McpServer({
+  name: "my-mcp-server",
+  version: "1.0.0",
+});
+
+// Define a tool
+server.tool(
+  "greet",
+  "Greet a user by name",
+  {
+    name: z.string().describe("The user's name"),
+  },
+  async ({ name }) => {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Hello, ${name}! Welcome to MCP.`,
+        },
+      ],
+    };
+  }
+);
+
+// Define a resource
+server.resource(
+  "status",
+  "status://server",
+  async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify({ status: "running", timestamp: new Date().toISOString() }),
+      },
+    ],
+  })
+);
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP Server running on stdio");
+}
+
+main().catch(console.error);
+```
 
-| Type | Use |
-|------|-----|
-| **Stdio** | Local, CLI-based |
-| **SSE** | Web-based, streaming |
-| **WebSocket** | Real-time, bidirectional |
+### Package.json Config
+
+```json
+{
+  "name": "my-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "my-mcp-server": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
 
 ---
 
-## 3. Tool Design Principles
+## 3. Python MCP Server (FastMCP)
 
-### Good Tool Design
+### Quick Start
 
-| 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 |
+```bash
+# Install FastMCP
+pip install fastmcp
 
-### Input Schema Design
+# Or with uv (recommended)
+uv add fastmcp
+```
 
-| Field | Required? |
-|-------|-----------|
-| Type | Yes - object |
-| Properties | Define each param |
-| Required | List mandatory params |
-| Description | Human-readable |
+### Basic Server Template
+
+```python
+# server.py
+from fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("My MCP Server")
+
+# Define a tool
+@mcp.tool()
+def greet(name: str) -> str:
+    """Greet a user by name.
+    
+    Args:
+        name: The user's name
+    
+    Returns:
+        A greeting message
+    """
+    return f"Hello, {name}! Welcome to MCP."
+
+# Define a tool with complex input
+@mcp.tool()
+def calculate(
+    operation: str,
+    a: float,
+    b: float
+) -> dict:
+    """Perform a mathematical calculation.
+    
+    Args:
+        operation: One of 'add', 'subtract', 'multiply', 'divide'
+        a: First number
+        b: Second number
+    
+    Returns:
+        Result of the calculation
+    """
+    ops = {
+        "add": lambda: a + b,
+        "subtract": lambda: a - b,
+        "multiply": lambda: a * b,
+        "divide": lambda: a / b if b != 0 else "Error: Division by zero",
+    }
+    
+    if operation not in ops:
+        return {"error": f"Unknown operation: {operation}"}
+    
+    return {"result": ops[operation](), "operation": operation}
+
+# Define a resource
+@mcp.resource("config://settings")
+def get_settings() -> str:
+    """Get server configuration."""
+    import json
+    return json.dumps({
+        "version": "1.0.0",
+        "features": ["tools", "resources"],
+    })
+
+# Define a prompt template
+@mcp.prompt()
+def code_review(code: str, language: str = "python") -> str:
+    """Generate a code review prompt."""
+    return f"""Please review this {language} code:
+
+```{language}
+{code}
+```
 
----
+Focus on:
+1. Code quality
+2. Potential bugs
+3. Performance
+4. Best practices"""
 
-## 4. Resource Patterns
+if __name__ == "__main__":
+    mcp.run()
+```
 
-### Resource Types
+### Running FastMCP
 
-| Type | Use |
-|------|-----|
-| Static | Fixed data (config, docs) |
-| Dynamic | Generated on request |
-| Template | URI with parameters |
+```bash
+# Development
+fastmcp dev server.py
 
-### URI Patterns
+# Production
+fastmcp run server.py
 
-| Pattern | Example |
-|---------|---------|
-| Fixed | `docs://readme` |
-| Parameterized | `users://{userId}` |
-| Collection | `files://project/*` |
+# Install to Claude Desktop
+fastmcp install server.py --name "My Server"
+```
 
 ---
 
-## 5. Error Handling
+## 4. Tool Design Patterns
+
+### Pattern 1: CRUD Operations
+
+```python
+@mcp.tool()
+def create_task(title: str, description: str = "", priority: str = "medium") -> dict:
+    """Create a new task."""
+    task = {
+        "id": generate_id(),
+        "title": title,
+        "description": description,
+        "priority": priority,
+        "status": "pending",
+        "created_at": datetime.now().isoformat(),
+    }
+    save_task(task)
+    return {"success": True, "task": task}
+
+@mcp.tool()
+def get_task(task_id: str) -> dict:
+    """Get task by ID."""
+    task = load_task(task_id)
+    if not task:
+        return {"error": f"Task {task_id} not found"}
+    return task
+
+@mcp.tool()
+def update_task(task_id: str, status: str = None, priority: str = None) -> dict:
+    """Update task properties."""
+    # Implementation...
+
+@mcp.tool()
+def delete_task(task_id: str) -> dict:
+    """Delete a task."""
+    # Implementation...
+```
+
+### Pattern 2: API Integration
+
+```python
+import httpx
+
+@mcp.tool()
+async def github_create_issue(
+    repo: str,
+    title: str,
+    body: str = "",
+    labels: list[str] = []
+) -> dict:
+    """Create a GitHub issue.
+    
+    Args:
+        repo: Repository in format 'owner/repo'
+        title: Issue title
+        body: Issue body (markdown)
+        labels: List of label names
+    """
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        return {"error": "GITHUB_TOKEN not set"}
+    
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"https://api.github.com/repos/{repo}/issues",
+            headers={
+                "Authorization": f"token {token}",
+                "Accept": "application/vnd.github.v3+json",
+            },
+            json={
+                "title": title,
+                "body": body,
+                "labels": labels,
+            }
+        )
+        
+        if response.status_code == 201:
+            issue = response.json()
+            return {
+                "success": True,
+                "issue_number": issue["number"],
+                "url": issue["html_url"],
+            }
+        else:
+            return {"error": response.text}
+```
 
-### Error Types
+### Pattern 3: Database Query
+
+```python
+import sqlite3
+
+@mcp.tool()
+def query_database(sql: str, params: list = []) -> dict:
+    """Execute a read-only SQL query.
+    
+    Args:
+        sql: SQL SELECT query
+        params: Query parameters (for safety)
+    
+    Returns:
+        Query results as list of dicts
+    """
+    # Validate read-only
+    if not sql.strip().upper().startswith("SELECT"):
+        return {"error": "Only SELECT queries allowed"}
+    
+    conn = sqlite3.connect("database.db")
+    conn.row_factory = sqlite3.Row
+    
+    try:
+        cursor = conn.execute(sql, params)
+        rows = [dict(row) for row in cursor.fetchall()]
+        return {"rows": rows, "count": len(rows)}
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        conn.close()
+```
 
-| Situation | Response |
-|-----------|----------|
-| Invalid params | Validation error message |
-| Not found | Clear "not found" |
-| Server error | Generic error, log details |
+### Pattern 4: File Operations
+
+```python
+from pathlib import Path
+
+@mcp.tool()
+def read_file(path: str) -> dict:
+    """Read a file's contents.
+    
+    Args:
+        path: Relative path to file
+    """
+    file_path = Path(path).resolve()
+    
+    # Security: validate path
+    if not file_path.is_relative_to(ALLOWED_DIR):
+        return {"error": "Access denied"}
+    
+    if not file_path.exists():
+        return {"error": f"File not found: {path}"}
+    
+    return {
+        "content": file_path.read_text(),
+        "size": file_path.stat().st_size,
+        "modified": file_path.stat().st_mtime,
+    }
+
+@mcp.tool()
+def write_file(path: str, content: str) -> dict:
+    """Write content to a file.
+    
+    Args:
+        path: Relative path to file
+        content: Content to write
+    """
+    file_path = Path(path).resolve()
+    
+    if not file_path.is_relative_to(ALLOWED_DIR):
+        return {"error": "Access denied"}
+    
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(content)
+    
+    return {"success": True, "path": str(file_path)}
+```
 
-### Best Practices
+---
 
-- Return structured errors
-- Don't expose internal details
-- Log for debugging
-- Provide actionable messages
+## 5. Claude Desktop Configuration
+
+### Config Location
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+### Config Example
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["/path/to/my-mcp-server/dist/index.js"],
+      "env": {
+        "API_KEY": "your-api-key"
+      }
+    },
+    "python-server": {
+      "command": "python",
+      "args": ["/path/to/server.py"],
+      "env": {
+        "DATABASE_URL": "postgresql://..."
+      }
+    },
+    "fastmcp-server": {
+      "command": "fastmcp",
+      "args": ["run", "/path/to/server.py"]
+    }
+  }
+}
+```
 
 ---
 
-## 6. Multimodal Handling
+## 6. Best Practices
 
-### Supported Types
+### Tool Naming
 
-| Type | Encoding |
-|------|----------|
-| Text | Plain text |
-| Images | Base64 + MIME type |
-| Files | Base64 + MIME type |
+| ❌ Bad | ✅ Good | Why |
+|--------|---------|-----|
+| `do_thing` | `create_user` | Specific action |
+| `process` | `parse_csv` | Clear purpose |
+| `handle_request` | `send_email` | Verb + noun |
+
+### Input Validation
+
+```python
+@mcp.tool()
+def send_email(
+    to: str,
+    subject: str,
+    body: str
+) -> dict:
+    """Send an email."""
+    # Validate email format
+    if not re.match(r"[^@]+@[^@]+\.[^@]+", to):
+        return {"error": "Invalid email format"}
+    
+    # Validate subject length
+    if len(subject) > 200:
+        return {"error": "Subject too long (max 200 chars)"}
+    
+    # ... send email
+```
+
+### Error Handling
+
+```python
+@mcp.tool()
+def risky_operation(param: str) -> dict:
+    """Operation that might fail."""
+    try:
+        result = do_something(param)
+        return {"success": True, "result": result}
+    except ValidationError as e:
+        return {"error": f"Invalid input: {e.message}"}
+    except PermissionError:
+        return {"error": "Permission denied"}
+    except Exception as e:
+        # Log internally, return generic message
+        logging.error(f"Unexpected error: {e}")
+        return {"error": "An unexpected error occurred"}
+```
+
+### Security Checklist
+
+- [ ] Validate all inputs
+- [ ] Use environment variables for secrets
+- [ ] Limit file system access
+- [ ] Sanitize SQL queries (use parameters)
+- [ ] Rate limit expensive operations
+- [ ] Log operations for audit
 
 ---
 
-## 7. Security Principles
+## 7. Deployment Options
 
-### Input Validation
+### Local (Claude Desktop)
+
+```bash
+# Build and configure
+npm run build
+# Add to claude_desktop_config.json
+```
 
-- Validate all tool inputs
-- Sanitize user-provided data
-- Limit resource access
+### NPX Distribution
 
-### API Keys
+```json
+// package.json
+{
+  "name": "@myorg/mcp-server",
+  "bin": {
+    "my-mcp-server": "./dist/index.js"
+  }
+}
+```
 
-- Use environment variables
-- Don't log secrets
-- Validate permissions
+```bash
+# Publish
+npm publish --access public
+
+# Users can run
+npx @myorg/mcp-server
+```
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY dist ./dist
+CMD ["node", "dist/index.js"]
+```
 
 ---
 
-## 8. Configuration
+## 8. Testing
+
+### Unit Test Example
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { greetTool } from "./tools/greet";
+
+describe("greet tool", () => {
+  it("should greet user by name", async () => {
+    const result = await greetTool({ name: "Alice" });
+    expect(result.content[0].text).toContain("Hello, Alice");
+  });
+  
+  it("should handle empty name", async () => {
+    const result = await greetTool({ name: "" });
+    expect(result.content[0].text).toContain("error");
+  });
+});
+```
 
-### Claude Desktop Config
+### Integration Test
 
-| Field | Purpose |
-|-------|---------|
-| command | Executable to run |
-| args | Command arguments |
-| env | Environment variables |
+```bash
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector node dist/index.js
+```
 
 ---
 
-## 9. Testing
+## 9. Common Patterns
+
+### Progress Reporting
+
+```python
+@mcp.tool()
+async def long_running_task(items: list[str]) -> dict:
+    """Process items with progress updates."""
+    results = []
+    
+    for i, item in enumerate(items):
+        # Process item
+        result = await process_item(item)
+        results.append(result)
+        
+        # Report progress via logging
+        progress = (i + 1) / len(items) * 100
+        logging.info(f"Progress: {progress:.0f}%")
+    
+    return {"results": results}
+```
+
+### Caching
 
-### Test Categories
+```python
+from functools import lru_cache
 
-| Type | Focus |
-|------|-------|
-| Unit | Tool logic |
-| Integration | Full server |
-| Contract | Schema validation |
+@lru_cache(maxsize=100)
+def expensive_lookup(key: str) -> dict:
+    """Cached database lookup."""
+    return db.query(key)
+
+@mcp.tool()
+def get_user(user_id: str) -> dict:
+    """Get user with caching."""
+    return expensive_lookup(user_id)
+```
 
 ---
 
-## 10. Best Practices Checklist
+## 10. Checklist
+
+### Before Publishing
 
 - [ ] Clear, action-oriented tool names
 - [ ] Complete input schemas with descriptions
@@ -169,8 +654,9 @@ my-mcp-server/
 - [ ] Error handling for all cases
 - [ ] Input validation
 - [ ] Environment-based configuration
-- [ ] Logging for debugging
+- [ ] README with installation instructions
+- [ ] Tests for critical paths
 
 ---
 
-> **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.
+> **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly. Write tool descriptions as if explaining to a junior developer.