@musashishao/agent-kit 1.0.0 → 1.1.0

package/.agent/skills/mcp-builder/tool-patterns.md

@@ -0,0 +1,642 @@
+# MCP Tool Design Patterns
+
+> Patterns for designing effective, user-friendly MCP tools.
+
+## Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Single Purpose** | One tool does one thing well |
+| **Clear Naming** | Action-oriented: verb_noun |
+| **Validated Input** | Schema with types and descriptions |
+| **Structured Output** | Predictable, parseable responses |
+| **Graceful Errors** | Helpful error messages |
+
+---
+
+## Pattern 1: CRUD Operations
+
+For managing entities (users, tasks, documents):
+
+```python
+# CREATE
+@mcp.tool()
+def create_task(
+    title: str,
+    description: str = "",
+    priority: str = "medium",
+    due_date: str = None
+) -> dict:
+    """Create a new task.
+    
+    Args:
+        title: Task title (required)
+        description: Detailed description
+        priority: One of 'low', 'medium', 'high'
+        due_date: Due date in YYYY-MM-DD format
+    
+    Returns:
+        Created task with ID and timestamps
+    """
+    task = {
+        "id": generate_id(),
+        "title": title,
+        "description": description,
+        "priority": priority,
+        "due_date": due_date,
+        "status": "pending",
+        "created_at": datetime.now().isoformat(),
+    }
+    save_task(task)
+    return {"success": True, "task": task}
+
+
+# READ (single)
+@mcp.tool()
+def get_task(task_id: str) -> dict:
+    """Get a task by ID.
+    
+    Args:
+        task_id: Unique task identifier
+    
+    Returns:
+        Task details or error if not found
+    """
+    task = load_task(task_id)
+    if not task:
+        return {"error": f"Task not found: {task_id}"}
+    return task
+
+
+# READ (list with filters)
+@mcp.tool()
+def list_tasks(
+    status: str = None,
+    priority: str = None,
+    limit: int = 10
+) -> dict:
+    """List tasks with optional filters.
+    
+    Args:
+        status: Filter by status ('pending', 'in_progress', 'done')
+        priority: Filter by priority ('low', 'medium', 'high')
+        limit: Maximum number of tasks to return
+    
+    Returns:
+        List of matching tasks
+    """
+    tasks = load_all_tasks()
+    
+    if status:
+        tasks = [t for t in tasks if t["status"] == status]
+    if priority:
+        tasks = [t for t in tasks if t["priority"] == priority]
+    
+    return {
+        "tasks": tasks[:limit],
+        "total": len(tasks),
+        "showing": min(limit, len(tasks))
+    }
+
+
+# UPDATE
+@mcp.tool()
+def update_task(
+    task_id: str,
+    title: str = None,
+    status: str = None,
+    priority: str = None
+) -> dict:
+    """Update task properties.
+    
+    Args:
+        task_id: Task to update
+        title: New title (optional)
+        status: New status (optional)
+        priority: New priority (optional)
+    
+    Returns:
+        Updated task or error
+    """
+    task = load_task(task_id)
+    if not task:
+        return {"error": f"Task not found: {task_id}"}
+    
+    if title:
+        task["title"] = title
+    if status:
+        task["status"] = status
+    if priority:
+        task["priority"] = priority
+    
+    task["updated_at"] = datetime.now().isoformat()
+    save_task(task)
+    
+    return {"success": True, "task": task}
+
+
+# DELETE
+@mcp.tool()
+def delete_task(task_id: str) -> dict:
+    """Delete a task.
+    
+    Args:
+        task_id: Task to delete
+    
+    Returns:
+        Confirmation or error
+    """
+    task = load_task(task_id)
+    if not task:
+        return {"error": f"Task not found: {task_id}"}
+    
+    remove_task(task_id)
+    return {"success": True, "deleted": task_id}
+```
+
+---
+
+## Pattern 2: API Integration
+
+For connecting to external APIs:
+
+```python
+import httpx
+import os
+
+@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 in markdown
+        labels: List of label names to apply
+    
+    Returns:
+        Created issue details with URL
+    """
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        return {"error": "GITHUB_TOKEN environment variable not set"}
+    
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"https://api.github.com/repos/{repo}/issues",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/vnd.github.v3+json",
+            },
+            json={
+                "title": title,
+                "body": body,
+                "labels": labels,
+            },
+            timeout=30.0,
+        )
+        
+        if response.status_code == 201:
+            issue = response.json()
+            return {
+                "success": True,
+                "issue_number": issue["number"],
+                "url": issue["html_url"],
+                "title": issue["title"],
+            }
+        elif response.status_code == 401:
+            return {"error": "Invalid GitHub token"}
+        elif response.status_code == 404:
+            return {"error": f"Repository not found: {repo}"}
+        else:
+            return {
+                "error": f"GitHub API error: {response.status_code}",
+                "details": response.text[:200]
+            }
+
+
+@mcp.tool()
+async def fetch_url(
+    url: str,
+    method: str = "GET",
+    headers: dict = None
+) -> dict:
+    """Fetch content from a URL.
+    
+    Args:
+        url: URL to fetch
+        method: HTTP method (GET, POST, etc.)
+        headers: Optional headers to include
+    
+    Returns:
+        Response content and metadata
+    """
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.request(
+                method=method,
+                url=url,
+                headers=headers or {},
+                timeout=30.0,
+            )
+            
+            return {
+                "status_code": response.status_code,
+                "content_type": response.headers.get("content-type", "unknown"),
+                "content": response.text[:10000],  # Limit content size
+                "truncated": len(response.text) > 10000,
+            }
+        except httpx.ConnectError:
+            return {"error": f"Failed to connect to {url}"}
+        except httpx.TimeoutException:
+            return {"error": f"Request to {url} timed out"}
+```
+
+---
+
+## Pattern 3: File Operations
+
+For reading/writing files safely:
+
+```python
+from pathlib import Path
+import mimetypes
+
+# Define allowed directory
+ALLOWED_DIR = Path.home() / "mcp-files"
+
+def validate_path(path: str) -> Path:
+    """Validate path is within allowed directory."""
+    resolved = Path(path).resolve()
+    
+    if not resolved.is_relative_to(ALLOWED_DIR):
+        raise ValueError(f"Access denied: {path}")
+    
+    return resolved
+
+
+@mcp.tool()
+def read_file(path: str) -> dict:
+    """Read a file's contents.
+    
+    Args:
+        path: Path relative to allowed directory
+    
+    Returns:
+        File contents and metadata
+    """
+    try:
+        file_path = validate_path(path)
+    except ValueError as e:
+        return {"error": str(e)}
+    
+    if not file_path.exists():
+        return {"error": f"File not found: {path}"}
+    
+    if not file_path.is_file():
+        return {"error": f"Not a file: {path}"}
+    
+    # Check file size
+    size = file_path.stat().st_size
+    if size > 1_000_000:  # 1MB limit
+        return {"error": f"File too large: {size} bytes (max 1MB)"}
+    
+    try:
+        content = file_path.read_text()
+    except UnicodeDecodeError:
+        return {"error": "Cannot read binary file as text"}
+    
+    return {
+        "path": str(file_path),
+        "content": content,
+        "size": size,
+        "mime_type": mimetypes.guess_type(str(file_path))[0],
+    }
+
+
+@mcp.tool()
+def write_file(
+    path: str,
+    content: str,
+    append: bool = False
+) -> dict:
+    """Write content to a file.
+    
+    Args:
+        path: Path relative to allowed directory
+        content: Content to write
+        append: If true, append instead of overwrite
+    
+    Returns:
+        Confirmation with file details
+    """
+    try:
+        file_path = validate_path(path)
+    except ValueError as e:
+        return {"error": str(e)}
+    
+    # Create parent directories
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Write content
+    mode = "a" if append else "w"
+    with open(file_path, mode) as f:
+        f.write(content)
+    
+    return {
+        "success": True,
+        "path": str(file_path),
+        "size": file_path.stat().st_size,
+        "mode": "appended" if append else "written",
+    }
+
+
+@mcp.tool()
+def list_directory(path: str = ".") -> dict:
+    """List contents of a directory.
+    
+    Args:
+        path: Directory path relative to allowed directory
+    
+    Returns:
+        List of files and subdirectories
+    """
+    try:
+        dir_path = validate_path(path)
+    except ValueError as e:
+        return {"error": str(e)}
+    
+    if not dir_path.exists():
+        return {"error": f"Directory not found: {path}"}
+    
+    if not dir_path.is_dir():
+        return {"error": f"Not a directory: {path}"}
+    
+    items = []
+    for item in dir_path.iterdir():
+        items.append({
+            "name": item.name,
+            "type": "directory" if item.is_dir() else "file",
+            "size": item.stat().st_size if item.is_file() else None,
+        })
+    
+    return {
+        "path": str(dir_path),
+        "items": sorted(items, key=lambda x: (x["type"], x["name"])),
+        "count": len(items),
+    }
+```
+
+---
+
+## Pattern 4: Database Queries
+
+For safe database access:
+
+```python
+import sqlite3
+from typing import List, Any
+
+def get_db_connection():
+    """Get database connection."""
+    return sqlite3.connect(os.environ.get("DATABASE_PATH", "data.db"))
+
+
+@mcp.tool()
+def query_database(
+    sql: str,
+    params: List[Any] = []
+) -> dict:
+    """Execute a read-only SQL query.
+    
+    Args:
+        sql: SQL SELECT query
+        params: Query parameters for safe binding
+    
+    Returns:
+        Query results as list of dictionaries
+    """
+    # Validate read-only query
+    normalized = sql.strip().upper()
+    if not normalized.startswith("SELECT"):
+        return {"error": "Only SELECT queries are allowed"}
+    
+    # Check for dangerous patterns
+    dangerous = ["DROP", "DELETE", "UPDATE", "INSERT", "ALTER", "CREATE", "--", ";"]
+    for pattern in dangerous:
+        if pattern in normalized:
+            return {"error": f"Query contains forbidden pattern: {pattern}"}
+    
+    conn = get_db_connection()
+    conn.row_factory = sqlite3.Row
+    
+    try:
+        cursor = conn.execute(sql, params)
+        rows = [dict(row) for row in cursor.fetchall()]
+        
+        return {
+            "success": True,
+            "rows": rows,
+            "count": len(rows),
+            "columns": list(rows[0].keys()) if rows else [],
+        }
+    except sqlite3.Error as e:
+        return {"error": f"Database error: {str(e)}"}
+    finally:
+        conn.close()
+
+
+@mcp.tool()
+def get_table_schema(table: str) -> dict:
+    """Get schema information for a table.
+    
+    Args:
+        table: Table name
+    
+    Returns:
+        Column definitions and indexes
+    """
+    # Validate table name (alphanumeric only)
+    if not table.replace("_", "").isalnum():
+        return {"error": "Invalid table name"}
+    
+    conn = get_db_connection()
+    
+    try:
+        # Get column info
+        cursor = conn.execute(f"PRAGMA table_info({table})")
+        columns = [
+            {
+                "name": row[1],
+                "type": row[2],
+                "nullable": not row[3],
+                "primary_key": bool(row[5]),
+            }
+            for row in cursor.fetchall()
+        ]
+        
+        if not columns:
+            return {"error": f"Table not found: {table}"}
+        
+        return {
+            "table": table,
+            "columns": columns,
+        }
+    finally:
+        conn.close()
+```
+
+---
+
+## Pattern 5: Long-running Operations
+
+For operations that take time:
+
+```python
+import asyncio
+from typing import Callable
+
+@mcp.tool()
+async def process_batch(
+    items: List[str],
+    operation: str = "process"
+) -> dict:
+    """Process a batch of items with progress tracking.
+    
+    Args:
+        items: List of items to process
+        operation: Operation to perform on each item
+    
+    Returns:
+        Results for all items
+    """
+    results = []
+    errors = []
+    
+    for i, item in enumerate(items):
+        try:
+            # Process item
+            result = await process_single_item(item, operation)
+            results.append({"item": item, "result": result})
+            
+            # Log progress for debugging
+            progress = (i + 1) / len(items) * 100
+            logger.info(f"Progress: {progress:.0f}% ({i+1}/{len(items)})")
+            
+        except Exception as e:
+            errors.append({"item": item, "error": str(e)})
+        
+        # Avoid overwhelming the system
+        await asyncio.sleep(0.1)
+    
+    return {
+        "total": len(items),
+        "successful": len(results),
+        "failed": len(errors),
+        "results": results,
+        "errors": errors,
+    }
+
+
+async def process_single_item(item: str, operation: str) -> str:
+    """Process a single item."""
+    await asyncio.sleep(0.5)  # Simulate work
+    return f"Processed {item} with {operation}"
+```
+
+---
+
+## Error Handling Pattern
+
+Consistent error responses:
+
+```python
+from enum import Enum
+from typing import Union
+
+class ErrorCode(Enum):
+    NOT_FOUND = "not_found"
+    INVALID_INPUT = "invalid_input"
+    UNAUTHORIZED = "unauthorized"
+    RATE_LIMITED = "rate_limited"
+    INTERNAL_ERROR = "internal_error"
+
+def error_response(
+    code: ErrorCode,
+    message: str,
+    details: dict = None
+) -> dict:
+    """Create a standardized error response."""
+    response = {
+        "success": False,
+        "error": {
+            "code": code.value,
+            "message": message,
+        }
+    }
+    if details:
+        response["error"]["details"] = details
+    return response
+
+def success_response(data: Union[dict, list]) -> dict:
+    """Create a standardized success response."""
+    return {
+        "success": True,
+        "data": data,
+    }
+
+# Usage
+@mcp.tool()
+def example_tool(id: str) -> dict:
+    """Example with standardized responses."""
+    
+    if not id:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "ID is required"
+        )
+    
+    item = load_item(id)
+    
+    if not item:
+        return error_response(
+            ErrorCode.NOT_FOUND,
+            f"Item not found: {id}"
+        )
+    
+    return success_response(item)
+```
+
+---
+
+## Best Practices Checklist
+
+### Before Publishing Your Tool
+
+- [ ] **Naming**: Verb_noun format (create_task, get_user)
+- [ ] **Description**: Clear, human-readable purpose
+- [ ] **Args**: All parameters have descriptions
+- [ ] **Validation**: Input is validated before processing
+- [ ] **Errors**: All error paths return helpful messages
+- [ ] **Output**: Structured JSON, consistent format
+- [ ] **Security**: Sensitive data not logged
+- [ ] **Limits**: Resource limits in place (file size, query results)
+- [ ] **Testing**: Unit tests for critical paths
+- [ ] **Documentation**: README explains usage
+
+---
+
+## Tool Naming Guidelines
+
+| ❌ Bad | ✅ Good | Why |
+|--------|---------|-----|
+| `do_thing` | `create_user` | Specific action + entity |
+| `process` | `parse_csv_file` | Clear what it does |
+| `handle_data` | `validate_email` | Single purpose |
+| `run` | `execute_query` | Descriptive |
+| `getData` | `get_user_profile` | snake_case, explicit |