mcp-scaffold

# MCP Tool Scaffolder ## Purpose Generate FastMCP tool implementations following project conventions with proper error handling, logging, JSON serialization, and test session support. ## Core Rules 1. **Context7 First**: Query FastMCP patterns before generation (if available, else use project patterns) 2. **Tool Decorator**: Use `@mcp.tool()` with descriptive docstrings for LLM 3. **Test Support**: Include `_test_session` parameter for pytest integration 4. **JSON Returns**: Always return `json.dumps()` with success/error structure 5. **Error Handling**: Try-catch with logger.error and fallback response ## Workflow 1. **Identify Operation**: Understand CRUD operation (create/read/update/delete/search) 2. **Read Existing Tools**: Check `src/mcp_server/tools/` for patterns 3. **Generate Tool**: ```python import json import logging from typing import Optional from sqlmodel import Session, select from ..database import engine from ..models import Todo, TodoStatus logger = logging.getLogger(__name__) @mcp.tool() def operation_name( required_param: str, optional_param: str | None = None, _test_session: Optional[Session] = None ) -> str: """ Clear description of what this tool does for the LLM. Args: required_param: Description optional_param: Description """ session = _test_session or Session(engine) try: # Database operation result = session.exec(select(Todo).where(...)).first() if not result: return json.dumps({ "success": False, "error": "Resource not found" }) session.commit() return json.dumps({ "success": True, "data": { "id": result.id, "title": result.title } }) except Exception as e: logger.error(f"Error in operation_name: {e}") if not _test_session: session.rollback() return json.dumps({ "success": False, "error": str(e) }) finally: if not _test_session: session.close() ``` 4. **Register in server.py**: Add import and ensure tool is loaded ## Tool Patterns ### Create Operations - Validate required fields - Set defaults (status=ACTIVE, timestamps) - Return created entity with ID ### Read Operations - Support filtering (status, date ranges) - Implement pagination (offset, limit) - Return list or single entity ### Update Operations - Check entity exists (404 if not) - Only update provided fields - Refresh and return updated entity ### Delete Operations - Check entity exists - Soft delete preferred (status=ARCHIVED) - Return success confirmation ### Search Operations - Support multiple filters (title, description, status) - Case-insensitive search with ILIKE - Return matched count + results ## Output Format - Complete tool file with imports - Proper type hints and docstrings - Error handling and logging - Test session support - JSON response structure ## Quality Checks - ✓ Docstring explains tool purpose for LLM - ✓ _test_session parameter present - ✓ Try-except with logger.error - ✓ Returns JSON with success/error structure - ✓ Session closed in finally block (if not test) - ✓ Proper SQLModel query patterns ## Example Usage User: "Scaffold update_todo MCP tool" Action: Read existing tools → Generate update_todo.py with validation, error handling, test support → Return complete implementation