# 1. Install
pip install -e ".[dev]"

# 2. Create a project
mcp-scaffold new-project my-server

# 3. Enter the project and run its tests
cd my-server
python -m pytest tests/ -v

# 4. Add a tool
mcp-scaffold new-tool get-user-info --project-dir .

# 5. Validate the project structure
mcp-scaffold validate .

git clone https://github.com/j3camp/mcp-starter-kit.git
cd mcp-starter-kit
pip install -e ".[dev]"

pip install -e .

mcp-scaffold new-project my-service
mcp-scaffold new-project my-service --output-dir /projects
mcp-scaffold new-project my-service --dry-run
mcp-scaffold new-project my-service --force

mcp-scaffold new-tool get-user-info
mcp-scaffold new-tool get-user-info --project-dir ./my-service
mcp-scaffold new-tool get-user-info --dry-run
mcp-scaffold new-tool get-user-info --force

mcp-scaffold inspect my_module.tools:get_user_info
mcp-scaffold inspect my_module.tools:get_user_info --base-path .

Function:    get_user_info
Tool name:   get-user-info
Description: Return public information for a user.
Mode:        sync
Returns:     UserInfo
Parameters:
  user_id: str — required

mcp-scaffold generate my_module.tools:get_user_info --project-dir ./my-service
mcp-scaffold generate my_module.tools:get_user_info --project-dir ./my-service --dry-run

mcp-scaffold validate .
mcp-scaffold validate ./my-service

# Generate the project
mcp-scaffold new-project hello-mcp --output-dir /tmp

# Inspect the generated layout
ls /tmp/hello-mcp/src/hello_mcp/

# Run the generated tests (no installation required)
cd /tmp/hello-mcp
python -m pytest tests/ -v

# Start the server
python -m hello_mcp

def create_server() -> fastmcp.FastMCP:
    """Create and configure the MCP server."""
    mcp = fastmcp.FastMCP("mcp-server")
    adapter = FastMCPAdapter(mcp)
    adapter.register_tool(name="echo", description="...", handler=echo)
    return mcp

mcp-scaffold new-tool search-products --project-dir /tmp/hello-mcp

src/hello_mcp/application/tools/search_products.py
src/hello_mcp/application/tools/search_products_registration.py
tests/test_search_products.py

from hello_mcp.application.tools.search_products_registration import register_search_products

def create_server() -> fastmcp.FastMCP:
    mcp = fastmcp.FastMCP("mcp-server")
    adapter = FastMCPAdapter(mcp)
    register_search_products(adapter)
    return mcp

# my_service/tools.py
from pydantic import BaseModel

class UserInfo(BaseModel):
    user_id: str
    display_name: str
    active: bool

def get_user_info(user_id: str) -> UserInfo:
    """Return public information for a user."""
    raise NotImplementedError

mcp-scaffold inspect my_service.tools:get_user_info --base-path .

Function:    get_user_info
Tool name:   get-user-info
Description: Return public information for a user.
Mode:        sync
Returns:     UserInfo
Parameters:
  user_id: str — required

mcp-scaffold generate my_service.tools:get_user_info \
  --project-dir ./my-server --base-path .

Python function
  -> discovery         validate callable is public and annotated
  -> metadata          extract name, docstring, parameters, return type
  -> type mapping      validate each annotation
  -> normalization     produce ToolMetadata
  -> rendering model   plan files to create
  -> generated files   write to disk (skipped in --dry-run)

<project-name>/
├── pyproject.toml               # build config, pytest, ruff, mypy
├── README.md
├── .gitignore
├── src/
│   └── <pkg>/
│       ├── __init__.py
│       ├── __main__.py          # entry point
│       ├── server.py            # composition root (create_server)
│       ├── domain/
│       │   ├── __init__.py
│       │   └── ports.py         # MCPServerPort protocol
│       ├── application/
│       │   ├── __init__.py
│       │   └── tools/
│       │       ├── __init__.py
│       │       └── example_tool.py
│       └── infrastructure/
│           ├── __init__.py
│           └── mcp_adapter.py   # FastMCP adapter
├── tests/
│   ├── __init__.py
│   ├── test_example_tool.py
│   └── test_server.py
└── scripts/
    ├── run.sh / run.bat
    ├── test.sh / test.bat
    ├── lint.sh / lint.bat
    └── typecheck.sh / typecheck.bat

application/domain
    MCPServerPort  <-- Protocol owned by the inner layer
                       (no fastmcp import)

infrastructure
    FastMCPAdapter  --> implements MCPServerPort
                        (only file that imports fastmcp)

import fastmcp
from <pkg>.infrastructure.mcp_adapter import FastMCPAdapter

def create_server() -> fastmcp.FastMCP:
    mcp = fastmcp.FastMCP("name")
    adapter = FastMCPAdapter(mcp)
    adapter.register_tool(...)
    return mcp

graph TD
    CLI["CLI (Typer)"]
    App["Application Services"]
    Domain["Domain Models + Ports"]
    Infra["Infrastructure Adapters"]

    CLI --> App
    App --> Domain
    Infra --> Domain
    CLI --> Infra

graph LR
    CLI --> InspectSvc["inspect_service"]
    CLI --> GenerateSvc["generate_service"]
    CLI --> ValidateSvc["validate_service"]
    InspectSvc --> Models["domain/models.py"]
    InspectSvc --> TypeMapper["infrastructure/type_mapper.py"]
    GenerateSvc --> Models
    GenerateSvc --> Renderer["infrastructure/renderer.py"]
    FastMCPAdapter["infrastructure/fastmcp_adapter.py"] --> Ports["domain/ports.py"]

flowchart TD
    A["mcp-scaffold new-project my-server"] --> B["generate_project()"]
    B --> C["Renderer.stage() all files"]
    C --> D{"dry_run?"}
    D -- yes --> E["Return GenerationPlan (no writes)"]
    D -- no --> F["Conflict check"]
    F --> G{"conflict?"}
    G -- "yes, no --force" --> H["RenderConflictError (exit 3)"]
    G -- "no or --force" --> I["Write files to disk"]
    I --> J["Return GenerationPlan"]

flowchart TD
    A["mcp-scaffold new-tool get-user"] --> B["generate_tool()"]
    B --> C["_detect_package()"]
    C --> D["Stage tool stub"]
    D --> E["Stage registration helper"]
    E --> F["Stage test stub"]
    F --> G["Renderer.commit()"]

sequenceDiagram
    participant Client
    participant FastMCP
    participant Adapter as FastMCPAdapter
    participant Tool as Tool Function

    Client->>FastMCP: call tool "echo"
    FastMCP->>Tool: invoke handler
    Tool-->>FastMCP: return result
    FastMCP-->>Client: tool result

sequenceDiagram
    participant User
    participant CLI
    participant InspectSvc as inspect_service
    participant TypeMapper as type_mapper
    participant GenerateSvc as generate_service
    participant Renderer

    User->>CLI: mcp-scaffold generate module:fn
    CLI->>InspectSvc: inspect_from_string(spec)
    InspectSvc->>TypeMapper: map_type(annotation)
    TypeMapper-->>InspectSvc: mapped type string
    InspectSvc-->>CLI: ToolMetadata
    CLI->>GenerateSvc: generate_from_metadata(metadata)
    GenerateSvc->>Renderer: stage files
    Renderer-->>GenerateSvc: GenerationPlan
    GenerateSvc-->>CLI: GenerationPlan
    CLI-->>User: files created

flowchart LR
    CLI["cli/main.py"] --> GenSvc["generate_service.py"]
    CLI --> InspSvc["inspect_service.py"]
    CLI --> ValSvc["validate_service.py"]
    GenSvc --> Renderer["renderer.py"]
    InspSvc --> TypeMapper["type_mapper.py"]

python -m pytest tests/ -v
python -m ruff check .
python -m mypy src tests
mcp-scaffold validate .

cd test-server
python -m pytest tests/ -v   # should pass with no installation