thrivekit 2.0.0

package/templates/examples/CLAUDE-fastapi.md

@@ -0,0 +1,270 @@
+# CLAUDE.md - FastAPI Project
+
+## Naming Conventions
+- **Files**: `snake_case.py` — e.g., `user_service.py`, `auth_router.py`
+- **Functions/Variables**: `snake_case` — e.g., `get_user_by_id`, `is_valid`
+- **Classes**: `PascalCase` — e.g., `UserService`, `AuthRouter`
+- **Pydantic Models**: `PascalCase` — e.g., `UserCreate`, `UserResponse`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RETRIES`, `DEFAULT_LIMIT`
+- **Database tables**: `snake_case` — e.g., `user_sessions`, `api_keys`
+- **API endpoints**: `kebab-case` — e.g., `/api/user-profile`, `/api/v1/auth`
+
+## Project Overview
+
+This is a FastAPI backend application with async SQLAlchemy and Pydantic.
+
+## Tech Stack
+
+- **Framework**: FastAPI
+- **ORM**: SQLAlchemy 2.0 (async)
+- **Validation**: Pydantic v2
+- **Database**: PostgreSQL
+- **Migrations**: Alembic
+- **Testing**: pytest + httpx
+- **Task Queue**: Celery + Redis (if applicable)
+
+## Project Structure
+
+```
+app/
+├── main.py              # FastAPI app entry point
+├── config.py            # Settings via pydantic-settings
+├── database.py          # Async SQLAlchemy setup
+├── models/              # SQLAlchemy models
+├── schemas/             # Pydantic schemas
+├── routers/             # API route handlers
+├── services/            # Business logic
+├── dependencies.py      # FastAPI dependencies
+└── exceptions.py        # Custom exceptions
+tests/
+├── conftest.py          # Fixtures
+├── test_api/            # API tests
+└── test_services/       # Unit tests
+```
+
+## Commands
+
+```bash
+# Development
+uvicorn app.main:app --reload --port 8000
+
+# Database
+alembic upgrade head                    # Run migrations
+alembic revision --autogenerate -m ""   # Create migration
+
+# Testing
+pytest                                  # Run all tests
+pytest -x                               # Stop on first failure
+pytest --cov=app                        # With coverage
+
+# Linting
+ruff check app/
+ruff format app/
+```
+
+## Code Standards
+
+### API Endpoints
+
+```python
+# Good - explicit status codes, response model, dependencies
+@router.post("/users", status_code=status.HTTP_201_CREATED, response_model=UserResponse)
+async def create_user(
+    user_in: UserCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> UserResponse:
+    """Create a new user."""
+    return await user_service.create(db, user_in)
+
+# Bad - implicit everything
+@router.post("/users")
+async def create_user(user_in: UserCreate, db = Depends(get_db)):
+    return await create(db, user_in)
+```
+
+### Pydantic Schemas
+
+```python
+# Good - explicit validation, examples, field descriptions
+class UserCreate(BaseModel):
+    email: EmailStr = Field(..., description="User's email address")
+    password: str = Field(..., min_length=8, description="Password (min 8 chars)")
+    name: str = Field(..., min_length=1, max_length=100)
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "email": "user@example.com",
+                "password": "securepass123",
+                "name": "John Doe"
+            }
+        }
+    )
+
+# Bad - no validation
+class UserCreate(BaseModel):
+    email: str
+    password: str
+    name: str
+```
+
+### SQLAlchemy Models
+
+```python
+# Good - explicit types, relationships, indexes
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    hashed_password: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column(default=func.now())
+
+    # Relationships
+    posts: Mapped[list["Post"]] = relationship(back_populates="author")
+
+# Bad - old style, no types
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    email = Column(String)
+    password = Column(String)
+```
+
+### Async Database Sessions
+
+```python
+# Good - async context manager
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+# Bad - no cleanup
+async def get_db():
+    return async_session()
+```
+
+### Error Handling
+
+```python
+# Good - custom exceptions with proper HTTP codes
+class NotFoundError(Exception):
+    def __init__(self, resource: str, id: int):
+        self.resource = resource
+        self.id = id
+
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request: Request, exc: NotFoundError):
+    return JSONResponse(
+        status_code=404,
+        content={"detail": f"{exc.resource} with id {exc.id} not found"}
+    )
+
+# Bad - generic exceptions
+raise Exception("User not found")
+```
+
+### Service Layer
+
+```python
+# Good - service handles business logic
+class UserService:
+    async def create(self, db: AsyncSession, user_in: UserCreate) -> User:
+        # Check if exists
+        existing = await self.get_by_email(db, user_in.email)
+        if existing:
+            raise ConflictError("User", "email", user_in.email)
+
+        # Hash password
+        hashed = hash_password(user_in.password)
+
+        # Create user
+        user = User(email=user_in.email, hashed_password=hashed, name=user_in.name)
+        db.add(user)
+        await db.flush()
+        return user
+
+# Bad - logic in router
+@router.post("/users")
+async def create_user(user_in: UserCreate, db: AsyncSession = Depends(get_db)):
+    existing = await db.execute(select(User).where(User.email == user_in.email))
+    if existing.scalar():
+        raise HTTPException(409, "Email exists")
+    hashed = bcrypt.hash(user_in.password)
+    user = User(email=user_in.email, hashed_password=hashed)
+    db.add(user)
+    # ... more logic
+```
+
+## Do NOT
+
+- Use `Any` type - create proper Pydantic models
+- Put business logic in routers - use service layer
+- Use synchronous database calls in async endpoints
+- Hardcode secrets - use `pydantic-settings` with env vars
+- Skip input validation - use Pydantic Field validators
+- Return SQLAlchemy models directly - use response schemas
+- Use `*` imports - explicit imports only
+- Catch generic `Exception` - catch specific exceptions
+
+## Do
+
+- Use async/await consistently
+- Add OpenAPI descriptions to all endpoints
+- Use dependency injection for services
+- Write tests for all endpoints
+- Use Alembic for all schema changes
+- Add proper logging with structlog
+- Use HTTPException for API errors
+- Validate all inputs with Pydantic
+
+## Environment Variables
+
+```bash
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/dbname
+SECRET_KEY=your-secret-key
+REDIS_URL=redis://localhost:6379/0
+DEBUG=false
+```
+
+Always use `pydantic-settings`:
+
+```python
+class Settings(BaseSettings):
+    database_url: PostgresDsn
+    secret_key: str
+    debug: bool = False
+
+    model_config = SettingsConfigDict(env_file=".env")
+
+settings = Settings()
+```
+
+## Testing
+
+```python
+# Good - async test with fixtures
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient, db: AsyncSession):
+    response = await client.post(
+        "/api/users",
+        json={"email": "test@example.com", "password": "testpass123", "name": "Test"}
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "test@example.com"
+    assert "password" not in data  # Never return password
+
+# conftest.py
+@pytest.fixture
+async def client(app: FastAPI) -> AsyncGenerator[AsyncClient, None]:
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+```

package/templates/examples/CLAUDE-fastmcp.md

@@ -0,0 +1,352 @@
+# CLAUDE.md - FastMCP Server
+
+## Naming Conventions
+- **Files**: `snake_case.py` — e.g., `search_tool.py`, `db_resource.py`
+- **Functions/Variables**: `snake_case` — e.g., `search_files`, `is_valid`
+- **Classes**: `PascalCase` — e.g., `SearchResult`, `FileResource`
+- **Tool names**: `snake_case` — e.g., `search_files`, `read_database`
+- **Resource URIs**: `kebab-case` — e.g., `file://project-files`, `db://user-data`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RESULTS`, `DEFAULT_TIMEOUT`
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) server built with FastMCP. It exposes tools, resources, and prompts to LLM clients.
+
+## Tech Stack
+
+- **Framework**: FastMCP 2.0
+- **Protocol**: Model Context Protocol (MCP)
+- **Validation**: Pydantic v2
+- **Async**: anyio
+
+## Project Structure
+
+```
+server/
+├── main.py              # FastMCP app entry point
+├── tools/               # Tool implementations
+│   ├── __init__.py
+│   └── search.py
+├── resources/           # Resource handlers
+│   ├── __init__.py
+│   └── data.py
+├── prompts/             # Prompt templates
+│   ├── __init__.py
+│   └── analysis.py
+├── dependencies.py      # Dependency injection
+└── config.py            # Settings
+tests/
+├── conftest.py
+└── test_tools.py
+```
+
+## Commands
+
+```bash
+# Development
+fastmcp dev server/main.py
+
+# Run server
+python server/main.py
+
+# Testing
+pytest
+
+# Install to Claude Desktop
+fastmcp install server/main.py --name "My Server"
+```
+
+## Code Standards
+
+### Basic Server Setup
+
+```python
+# Good - clear name, proper structure
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+def search(query: str) -> list[dict]:
+    """Search for items matching the query."""
+    return [{"id": 1, "name": "Result"}]
+
+if __name__ == "__main__":
+    mcp.run()
+
+# Bad - no name, no types
+from fastmcp import FastMCP
+mcp = FastMCP()
+
+@mcp.tool
+def search(query):
+    return [{"id": 1}]
+```
+
+### Tools
+
+```python
+from typing import Annotated
+from pydantic import Field
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+
+mcp = FastMCP("My Server")
+
+# Good - typed parameters, validation, docstring, error handling
+@mcp.tool
+async def search_products(
+    query: Annotated[str, Field(min_length=1, description="Search query")],
+    max_results: Annotated[int, Field(ge=1, le=100, description="Max results")] = 10,
+    category: str | None = None,
+) -> list[dict]:
+    """Search the product catalog.
+
+    Returns matching products with id, name, and price.
+    """
+    if not query.strip():
+        raise ToolError("Query cannot be empty")
+
+    results = await fetch_products(query, max_results, category)
+    return results
+
+# Bad - no types, no validation, no docstring
+@mcp.tool
+def search_products(query, max_results=10, **kwargs):
+    return fetch_products(query, max_results)
+```
+
+### Resources
+
+```python
+from fastmcp import FastMCP
+from fastmcp.resources import TextResource, FileResource
+from fastmcp.exceptions import ResourceError
+from pathlib import Path
+
+mcp = FastMCP("My Server")
+
+# Good - static resource with proper URI and MIME type
+config_resource = TextResource(
+    uri="config://app/settings",
+    name="App Settings",
+    text='{"theme": "dark", "version": "1.0"}',
+    mime_type="application/json"
+)
+mcp.add_resource(config_resource)
+
+# Good - dynamic resource with template
+@mcp.resource("users://{user_id}/profile")
+async def get_user_profile(user_id: str) -> dict:
+    """Get user profile by ID."""
+    user = await fetch_user(user_id)
+    if not user:
+        raise ResourceError(f"User {user_id} not found")
+    return user
+
+# Bad - no URI scheme, no error handling
+@mcp.resource("user")
+def get_user(id):
+    return fetch_user(id)
+```
+
+### Prompts
+
+```python
+from fastmcp import FastMCP
+from fastmcp.prompts import PromptMessage
+
+mcp = FastMCP("My Server")
+
+# Good - typed parameters, clear docstring, structured return
+@mcp.prompt
+def analyze_code(
+    code: str,
+    language: str = "python",
+    focus: str = "security"
+) -> list[PromptMessage]:
+    """Analyze code for issues.
+
+    Args:
+        code: The code to analyze
+        language: Programming language
+        focus: Analysis focus (security, performance, style)
+    """
+    return [
+        PromptMessage(
+            role="user",
+            content=f"Analyze this {language} code for {focus} issues:\n\n```{language}\n{code}\n```"
+        )
+    ]
+
+# Bad - no types, returns plain string
+@mcp.prompt
+def analyze(code):
+    return f"Analyze: {code}"
+```
+
+### Dependency Injection
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_context
+
+mcp = FastMCP("My Server")
+
+# Good - hide runtime values from LLM
+def get_api_key() -> str:
+    return os.environ["API_KEY"]
+
+def get_db() -> Database:
+    return Database(os.environ["DATABASE_URL"])
+
+@mcp.tool
+async def fetch_data(
+    query: str,
+    api_key: str = Depends(get_api_key),  # Hidden from schema
+    db: Database = Depends(get_db),        # Hidden from schema
+) -> dict:
+    """Fetch data from external API."""
+    return await db.query(query)
+
+# Bad - exposing secrets in schema
+@mcp.tool
+def fetch_data(query: str, api_key: str) -> dict:
+    return call_api(query, api_key)
+```
+
+### Error Handling
+
+```python
+from fastmcp.exceptions import ToolError, ResourceError
+
+# Good - specific errors with helpful messages
+@mcp.tool
+def divide(a: float, b: float) -> float:
+    """Divide two numbers."""
+    if b == 0:
+        raise ToolError("Cannot divide by zero")
+    return a / b
+
+@mcp.resource("data://{id}")
+def get_data(id: str) -> dict:
+    """Get data by ID."""
+    data = fetch_data(id)
+    if not data:
+        raise ResourceError(f"Data with ID '{id}' not found")
+    return data
+
+# Bad - generic exceptions
+@mcp.tool
+def divide(a, b):
+    return a / b  # ZeroDivisionError not handled
+```
+
+### Async Best Practices
+
+```python
+import anyio
+
+# Good - async for I/O operations
+@mcp.tool
+async def fetch_url(url: str) -> str:
+    """Fetch content from URL."""
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+        return response.text
+
+# Good - wrap CPU-bound sync code
+@mcp.tool
+async def process_image(image_data: bytes) -> bytes:
+    """Process image (CPU-intensive)."""
+    return await anyio.to_thread.run_sync(
+        lambda: heavy_image_processing(image_data)
+    )
+
+# Bad - blocking call in async context
+@mcp.tool
+async def fetch_url(url: str) -> str:
+    return requests.get(url).text  # Blocks event loop!
+```
+
+## Do NOT
+
+- Use `*args` or `**kwargs` in tools - FastMCP needs complete parameter schemas
+- Expose secrets as tool parameters - use `Depends()` for injection
+- Use blocking I/O in async functions - wrap with `anyio.to_thread.run_sync()`
+- Skip type hints - they generate the JSON schema for clients
+- Catch and silence exceptions - use `ToolError`/`ResourceError` with helpful messages
+- Use generic names like `data` or `process` - be specific
+
+## Do
+
+- Add docstrings to all tools, resources, and prompts
+- Use `Annotated` with `Field` for parameter validation and descriptions
+- Use async for all I/O operations
+- Use `Depends()` to inject runtime values (API keys, DB connections)
+- Use specific error types (`ToolError`, `ResourceError`)
+- Add proper MIME types to resources
+- Use URI schemes (`data://`, `config://`, `file://`)
+- Test tools with `mcp.call_tool()` in pytest
+
+## Testing
+
+```python
+import pytest
+from server.main import mcp
+
+@pytest.mark.asyncio
+async def test_search_tool():
+    result = await mcp.call_tool("search_products", {"query": "test"})
+    assert isinstance(result, list)
+
+@pytest.mark.asyncio
+async def test_search_empty_query():
+    with pytest.raises(ToolError, match="cannot be empty"):
+        await mcp.call_tool("search_products", {"query": ""})
+
+@pytest.mark.asyncio
+async def test_user_resource():
+    result = await mcp.read_resource("users://123/profile")
+    assert "name" in result
+```
+
+## Configuration
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    api_key: str
+    database_url: str
+    debug: bool = False
+
+    model_config = {"env_file": ".env"}
+
+settings = Settings()
+
+# Use in server
+mcp = FastMCP(
+    "My Server",
+    debug=settings.debug,
+    mask_error_details=not settings.debug,  # Hide errors in production
+)
+```
+
+## Deployment
+
+```bash
+# FastMCP Cloud (free for personal)
+fastmcp deploy server/main.py
+
+# Install to Claude Desktop
+fastmcp install server/main.py --name "My Server"
+
+# HTTP server
+uvicorn server.main:mcp.http_app --host 0.0.0.0 --port 8000
+```
+
+## Resources
+
+- [FastMCP Docs](https://gofastmcp.com)
+- [MCP Specification](https://modelcontextprotocol.io)