# mcp-scaffold

> Scaffold FastMCP tool implementations with database integration, error handling, and test session support. Generates production-ready MCP tools.

- Author: Ali jawwad
- Repository: jawwad-ali/hackathonII-Backend
- Version: 20260127220531
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/jawwad-ali/hackathonII-Backend
- Web: https://mule.run/skillshub/@@jawwad-ali/hackathonII-Backend~mcp-scaffold:20260127220531

---

---
name: mcp-scaffold
description: Scaffold FastMCP tool implementations with database integration, error handling, and test session support. Generates production-ready MCP tools.
---

# 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