@musashishao/agent-kit 1.0.0 → 1.1.0

package/.agent/skills/mcp-builder/python-template.md

@@ -0,0 +1,522 @@
+# Python MCP Server Template (FastMCP)
+
+> Copy this template to quickly start a Python MCP server.
+
+## Project Structure
+
+```
+my-mcp-server/
+├── src/
+│   ├── __init__.py
+│   ├── server.py         # Entry point
+│   ├── tools/            # Tool implementations
+│   │   ├── __init__.py
+│   │   └── example.py
+│   ├── resources/        # Resource handlers
+│   │   └── __init__.py
+│   └── utils/            # Utilities
+│       └── __init__.py
+├── tests/
+│   └── test_tools.py
+├── pyproject.toml
+├── requirements.txt
+└── README.md
+```
+
+## Files
+
+### pyproject.toml
+
+```toml
+[project]
+name = "my-mcp-server"
+version = "1.0.0"
+description = "My MCP Server"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=0.3.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+my-mcp-server = "src.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+### requirements.txt
+
+```
+fastmcp>=0.3.0
+httpx>=0.27.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+```
+
+### src/server.py
+
+```python
+#!/usr/bin/env python3
+"""
+My MCP Server - Main entry point
+"""
+
+import os
+import logging
+from fastmcp import FastMCP
+
+# Import tools and resources
+from .tools.example import register_example_tools
+from .resources import register_resources
+
+# Configuration
+SERVER_NAME = "my-mcp-server"
+SERVER_VERSION = "1.0.0"
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(SERVER_NAME)
+
+# Create server instance
+mcp = FastMCP(
+    SERVER_NAME,
+    version=SERVER_VERSION,
+    description="My awesome MCP server"
+)
+
+# Register tools and resources
+register_example_tools(mcp)
+register_resources(mcp)
+
+
+def main():
+    """Entry point for the server."""
+    logger.info(f"Starting {SERVER_NAME} v{SERVER_VERSION}")
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+### src/tools/__init__.py
+
+```python
+"""Tool exports."""
+
+from .example import register_example_tools
+
+__all__ = ["register_example_tools"]
+```
+
+### src/tools/example.py
+
+```python
+"""Example tools for the MCP server."""
+
+import json
+from typing import Optional
+from datetime import datetime
+from fastmcp import FastMCP
+
+
+def register_example_tools(mcp: FastMCP):
+    """Register example tools with the server."""
+
+    @mcp.tool()
+    def greet(
+        name: str,
+        language: str = "en"
+    ) -> str:
+        """Greet a user by name.
+        
+        Args:
+            name: The name of the user to greet
+            language: Language for greeting (en, es, fr)
+        
+        Returns:
+            A greeting message
+        """
+        greetings = {
+            "en": f"Hello, {name}!",
+            "es": f"¡Hola, {name}!",
+            "fr": f"Bonjour, {name}!",
+        }
+        return greetings.get(language, greetings["en"])
+
+    @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
+        """
+        operations = {
+            "add": lambda: a + b,
+            "subtract": lambda: a - b,
+            "multiply": lambda: a * b,
+            "divide": lambda: a / b if b != 0 else None,
+        }
+        
+        if operation not in operations:
+            return {"error": f"Unknown operation: {operation}"}
+        
+        result = operations[operation]()
+        
+        if result is None:
+            return {"error": "Division by zero"}
+        
+        return {
+            "operation": operation,
+            "a": a,
+            "b": b,
+            "result": result
+        }
+
+    @mcp.tool()
+    def get_timestamp() -> dict:
+        """Get current timestamp information.
+        
+        Returns:
+            Current date/time in various formats
+        """
+        now = datetime.now()
+        return {
+            "iso": now.isoformat(),
+            "timestamp": int(now.timestamp()),
+            "formatted": now.strftime("%Y-%m-%d %H:%M:%S"),
+            "date": now.strftime("%Y-%m-%d"),
+            "time": now.strftime("%H:%M:%S"),
+        }
+
+    @mcp.tool()
+    def json_format(
+        data: str,
+        indent: int = 2
+    ) -> str:
+        """Format JSON string with pretty printing.
+        
+        Args:
+            data: JSON string to format
+            indent: Number of spaces for indentation
+        
+        Returns:
+            Formatted JSON string
+        """
+        try:
+            parsed = json.loads(data)
+            return json.dumps(parsed, indent=indent, ensure_ascii=False)
+        except json.JSONDecodeError as e:
+            return f"Error parsing JSON: {e}"
+```
+
+### src/resources/__init__.py
+
+```python
+"""Resource handlers for the MCP server."""
+
+import json
+import os
+from datetime import datetime
+from fastmcp import FastMCP
+
+
+def register_resources(mcp: FastMCP):
+    """Register resources with the server."""
+
+    @mcp.resource("status://server")
+    def get_status() -> str:
+        """Get server status information."""
+        return json.dumps({
+            "status": "running",
+            "timestamp": datetime.now().isoformat(),
+            "pid": os.getpid(),
+            "python_version": os.sys.version,
+        })
+
+    @mcp.resource("config://settings")
+    def get_config() -> str:
+        """Get server configuration."""
+        return json.dumps({
+            "name": "my-mcp-server",
+            "version": "1.0.0",
+            "features": ["tools", "resources", "prompts"],
+            "environment": os.environ.get("ENVIRONMENT", "development"),
+        })
+
+    @mcp.resource("env://variables")
+    def get_safe_env() -> str:
+        """Get safe environment variables (non-sensitive)."""
+        safe_keys = ["PATH", "HOME", "USER", "SHELL", "LANG"]
+        safe_env = {
+            k: os.environ.get(k, "")
+            for k in safe_keys
+            if k in os.environ
+        }
+        return json.dumps(safe_env)
+```
+
+### src/utils/__init__.py
+
+```python
+"""Utility functions for the MCP server."""
+
+import os
+import json
+import hashlib
+from typing import Any, Optional, TypeVar
+from datetime import datetime
+import logging
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def require_env(name: str) -> str:
+    """Get required environment variable or raise error."""
+    value = os.environ.get(name)
+    if not value:
+        raise ValueError(f"Missing required environment variable: {name}")
+    return value
+
+
+def get_env(name: str, default: str = "") -> str:
+    """Get environment variable with default."""
+    return os.environ.get(name, default)
+
+
+def safe_json_parse(data: str, default: T = None) -> T:
+    """Safely parse JSON with fallback."""
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError:
+        return default
+
+
+def generate_id() -> str:
+    """Generate a unique ID."""
+    timestamp = datetime.now().isoformat()
+    return hashlib.sha256(timestamp.encode()).hexdigest()[:12]
+
+
+def truncate(text: str, max_length: int = 100) -> str:
+    """Truncate text with ellipsis."""
+    if len(text) <= max_length:
+        return text
+    return text[:max_length - 3] + "..."
+
+
+def log_tool_call(tool_name: str, args: dict, result: Any) -> None:
+    """Log tool calls for debugging."""
+    logger.info(f"Tool: {tool_name}, Args: {args}, Result type: {type(result).__name__}")
+```
+
+### tests/test_tools.py
+
+```python
+"""Tests for MCP tools."""
+
+import pytest
+from src.tools.example import register_example_tools
+from fastmcp import FastMCP
+
+
+@pytest.fixture
+def mcp():
+    """Create a test MCP server."""
+    server = FastMCP("test-server")
+    register_example_tools(server)
+    return server
+
+
+def test_greet_english():
+    """Test greeting in English."""
+    from src.tools.example import register_example_tools
+    
+    mcp = FastMCP("test")
+    register_example_tools(mcp)
+    
+    # Tools are registered, you would call them through the server
+    # This is a simplified example
+    assert True  # Replace with actual test
+
+
+def test_calculate_add():
+    """Test addition calculation."""
+    # Import the functions directly for unit testing
+    result = {"operation": "add", "a": 2, "b": 3, "result": 5}
+    assert result["result"] == 5
+
+
+def test_calculate_divide_by_zero():
+    """Test division by zero handling."""
+    result = {"error": "Division by zero"}
+    assert "error" in result
+```
+
+## Running the Server
+
+### Development
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Or with uv (faster)
+uv pip install -r requirements.txt
+
+# Run in development mode
+fastmcp dev src/server.py
+
+# Run with hot reload
+fastmcp dev src/server.py --reload
+```
+
+### Production
+
+```bash
+# Install as package
+pip install .
+
+# Run
+my-mcp-server
+
+# Or directly
+python -m src.server
+```
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "python",
+      "args": ["-m", "src.server"],
+      "cwd": "/path/to/my-mcp-server",
+      "env": {
+        "PYTHONPATH": "/path/to/my-mcp-server",
+        "MY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Or using fastmcp:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "fastmcp",
+      "args": ["run", "/path/to/my-mcp-server/src/server.py"]
+    }
+  }
+}
+```
+
+## FastMCP Installation Commands
+
+```bash
+# Install directly to Claude Desktop
+fastmcp install src/server.py --name "My Server"
+
+# Install with environment variables
+fastmcp install src/server.py --name "My Server" \
+  --env MY_API_KEY=secret \
+  --env DATABASE_URL=postgres://...
+```
+
+## Testing
+
+```bash
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=src
+
+# Test with MCP Inspector
+fastmcp dev src/server.py
+# Then open the inspector URL in browser
+```
+
+## Common Patterns
+
+### Async Tool
+
+```python
+@mcp.tool()
+async def fetch_data(url: str) -> dict:
+    """Fetch data from URL."""
+    import httpx
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+        return response.json()
+```
+
+### Tool with Validation
+
+```python
+from pydantic import BaseModel, validator
+
+class UserInput(BaseModel):
+    name: str
+    age: int
+    
+    @validator("age")
+    def validate_age(cls, v):
+        if v < 0 or v > 150:
+            raise ValueError("Age must be between 0 and 150")
+        return v
+
+@mcp.tool()
+def create_user(user: UserInput) -> dict:
+    """Create a new user with validation."""
+    return {"id": generate_id(), **user.dict()}
+```
+
+### Context-aware Tool
+
+```python
+@mcp.tool()
+def get_context_info(ctx) -> dict:
+    """Get information about the current context."""
+    return {
+        "client_id": ctx.client_id if hasattr(ctx, "client_id") else "unknown",
+        "request_id": ctx.request_id if hasattr(ctx, "request_id") else "none",
+    }
+```