scaffolding-python-repo

Scaffolding a Python Repo

Overview

Canonical setup for a new Python project (used as the workshop example by vibber.ai). Stack: uv + just + ruff + ty + pydantic-settings, with a src/ layout, CLAUDE.md for AI agents, .env-based configuration, and (when applicable) a FastMCP HTTP server as the entry point.

When to Use

• A new Python repo (Python 3.13+) is being set up
• The user mentions FastMCP, just, uv, ty, pydantic-settings
• An existing empty repo needs these conventions added

Don't use for: repos with established conventions (follow them); non-Python projects; throwaway scripts.

Iron conventions (do not violate)

• uv for everything Python — no pip, no requirements.txt, no setup.py
• All commands go through just recipes that wrap uv run
• Type checker is ty (Astral, pre-1.0) — never mypy or pyright
• Settings field names are UPPER_CASE with no env_prefix
• FastMCP servers default to HTTP transport, but main() branches on settings.TRANSPORT so the same binary can run as stdio when Claude Desktop spawns it (Claude Desktop accepts only stdio + streamable HTTPS — plain HTTP localhost is rejected)
• No pre-commit hooks unless the user explicitly asks
• Default branch is main (rename from master after uv init if needed)
• Default port: 8888 (avoids 8000/3000 collisions)

Folder structure

project-name/
├── Justfile
├── pyproject.toml
├── uv.lock
├── .python-version          # "3.13"
├── .env.example
├── .gitignore
├── README.md
├── CLAUDE.md
├── src/
│   └── package_name/
│       ├── __init__.py      # empty
│       ├── config.py
│       └── server.py        # FastMCP entry, or main module for non-MCP apps
└── tests/
    ├── __init__.py
    └── test_server.py

Setup steps

1. Init via uv (creates src layout, git repo, .python-version, basic pyproject.toml):

   uv init --package --lib --python 3.13 --name <project-name> .
   

2. Replace pyproject.toml with the template below (merge if uv added authors/etc.).

3. Add deps:

   uv add fastmcp pydantic-settings
   uv add --dev ruff ty pytest pytest-asyncio
   

4. Write source files from the templates section. Empty out the hello() function uv generated in __init__.py.

5. Append to .gitignore:

   .env
   .env.local
   .pytest_cache/
   .ruff_cache/
   .ty_cache/
   

6. Rename branch: git branch -m master main

7. Verify: just check must pass before declaring the scaffold done.

8. Commit with a clear initial message.

9. Remind the user about Claude Desktop registration. A scaffolded server can't be tried in Claude Desktop until it's added to claude_desktop_config.json. Don't do this silently — surface it: "Want me to register this server in Claude Desktop now? See connecting-to-claude-desktop." Use the connecting-to-claude-desktop skill if they say yes.

File templates

pyproject.toml

[project]
name = "project-name"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "fastmcp>=3.2.4",
    "pydantic-settings>=2.14.0",
]

[project.scripts]
project-name = "package_name.server:main"

[build-system]
requires = ["uv_build>=0.10.10,<0.11.0"]
build-backend = "uv_build"

[tool.ruff]
line-length = 100
target-version = "py313"
src = ["src", "tests"]

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF"]

[tool.ty.src]
include = ["src", "tests"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

Justfile

set windows-shell := ["powershell.exe", "-ExecutionPolicy", "Bypass", "-Command"]

default:
    @just --list

install:
    @echo '📦 ⬇️  Installing dependencies...'
    uv sync

start:
    @echo '🚀 Starting server...'
    uv run project-name

format args='':
    uv run ruff format {{ args }}

format-check args='':
    uv run ruff format --check {{ args }}

lint args='':
    uv run ruff check --fix {{ args }}

lint-check args='':
    uv run ruff check {{ args }}

typecheck args='':
    uv run ty check {{ args }}

test args='':
    uv run pytest {{ args }}

check: lint-check format-check typecheck test

src/package_name/config.py

from typing import Literal

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )

    APP_NAME: str = Field(default="project-name")
    HOST: str = Field(default="127.0.0.1")
    PORT: int = Field(default=8888)
    TRANSPORT: Literal["http", "stdio"] = Field(default="http")


settings = Settings()

src/package_name/server.py (FastMCP)

from fastmcp import FastMCP

from package_name.config import settings

mcp: FastMCP = FastMCP(settings.APP_NAME)


@mcp.tool
def greet(name: str) -> str:
    """Return a friendly greeting."""
    return f"Hello, {name}!"


@mcp.resource("config://app")
def app_info() -> dict[str, str | int]:
    return {"app_name": settings.APP_NAME, "host": settings.HOST, "port": settings.PORT}


def main() -> None:
    if settings.TRANSPORT == "stdio":
        mcp.run(transport="stdio")
    else:
        mcp.run(transport="http", host=settings.HOST, port=settings.PORT)


if __name__ == "__main__":
    main()

tests/test_server.py

from fastmcp import Client

from package_name.server import mcp


async def test_greet_tool() -> None:
    async with Client(mcp) as client:
        result = await client.call_tool("greet", {"name": "Ford"})
        assert result.data == "Hello, Ford!"

In-memory Client(mcp) is the standard test pattern — no port binding, no network, fast.

.env.example

APP_NAME=project-name
HOST=127.0.0.1
PORT=8888

# Transport: "http" for local dev / MCP Jam / Claude Code (default),
# "stdio" when Claude Desktop spawns the server (set in mcpServers env block).
TRANSPORT=http

CLAUDE.md skeleton

Always cover these sections (tailor content per project):

1. Project Overview — one paragraph
2. Project Structure — file tree
3. Development Commands — table of just recipes; "Always use just; never call python or pip directly"; "Before claiming work complete: run just check"
4. Stack — uv, fastmcp, pydantic-settings, ruff, ty, pytest
5. Environment Configuration — Settings class in config.py, UPPER_CASE fields, .env workflow
6. What's Exposed — tools/resources for MCP servers
7. Testing — in-memory Client(mcp) example
8. Transport Selection — explain settings.TRANSPORT: http (default) for just start / MCP Jam / Claude Code; stdio for Claude Desktop integration
9. Inspecting / Debugging — bunx @mcpjam/inspector@latest → point at http://127.0.0.1:8888/mcp; claude mcp add --transport http <name> http://127.0.0.1:8888/mcp; Claude Desktop snippet (see Optional integrations below)
10. Conventions — list the iron rules above

README.md skeleton

Minimum sections: Requirements (with brew install uv just + bun install commands), Setup, Run, Inspect (MCP Jam), Develop (just recipes), What's exposed, Testing with Claude Code.

Verification

Always run just check (lint-check + format-check + typecheck + test) before declaring done. All four must pass.

Optional integrations

• MCP Jam inspector (HTTP): bunx @mcpjam/inspector@latest → http://127.0.0.1:8888/mcp
• Claude Code (HTTP): claude mcp add --transport http <name> http://127.0.0.1:8888/mcp (then start a fresh session)
• Claude Desktop (stdio): use the connecting-to-claude-desktop skill — it edits claude_desktop_config.json for the right OS, sets TRANSPORT=stdio, and handles the macOS GUI PATH gotcha. (Plain http://localhost URLs are rejected by Claude Desktop; only stdio + streamable HTTPS are accepted.)

Related skills

• For deeper FastMCP work (tool design, OAuth/JWT auth, deployment), Anthropic's mcp-builder skill is the better reference. If the user doesn't have it, prompt them:

  "Install Anthropic's official skills bundle: /plugin marketplace add anthropics/skills"

• For new feature work in the scaffolded repo: superpowers:test-driven-development
• For scoping the project before scaffolding: superpowers:brainstorming

Common mistakes

Mistake	Fix
Calling python or pip directly	Use just <recipe> or uv run ...
Adding requirements.txt, setup.py, setup.cfg	uv + pyproject.toml only
Adding mypy or pyright	Convention is ty
Lowercase Settings fields, or adding env_prefix	UPPER_CASE, no prefix
mcp.run() hardcoded to one transport	Branch on settings.TRANSPORT so HTTP and stdio both work
Trying to register a http://localhost URL with Claude Desktop	Claude Desktop needs stdio or HTTPS — use the TRANSPORT=stdio env block
Skipping just check before commit	All four checks must pass
Adding pre-commit / lefthook unprompted	Only if explicitly requested
Leaving the branch as master	Rename to main
Defaulting port to 8000 or 3000	Use 8888 to avoid collisions