uv sync

cp .env.example .env

uv run fastmcp run src/mcp_server/server.py:mcp

uv run fastmcp run src/mcp_server/server.py:mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8000

uv run mcp-server

uv run pytest

async def test_echo(client):
    result = await client.call_tool("echo", {"message": "hello"})
    assert result.data.result == "hello"

uv run ruff check .     # lint
uv run ruff format .    # format

mcp-server-template/
├── src/
│   └── mcp_server/
│       ├── server.py            # assembly only: create_server() + mcp
│       ├── config.py            # pydantic-settings (MCP_* env vars)
│       ├── tools/               # register_tools(mcp)
│       ├── resources/           # register_resources(mcp)
│       ├── prompts/             # register_prompts(mcp)
│       ├── services/            # business logic, MCP-agnostic
│       └── schemas/             # pydantic models
├── tests/
├── .env.example
├── Dockerfile
├── pyproject.toml
└── README.md

tool/resource/prompt  ->  service  ->  schema
   (MCP surface)         (logic)      (data)

from fastmcp import FastMCP

from mcp_server.services.my_service import do_the_work


def register_my_feature_tool(mcp: FastMCP) -> None:
    @mcp.tool
    def my_feature(query: str, limit: int = 10) -> list[str]:
        """One-line description the model will read.

        Args:
            query: What to look for.
            limit: Maximum number of results.
        """
        return do_the_work(query, limit=limit)

from mcp_server.tools.my_feature import register_my_feature_tool


def register_tools(mcp: FastMCP) -> None:
    register_my_feature_tool(mcp)

# src/mcp_server/resources/my_resource.py
from fastmcp import FastMCP


def register_my_resource(mcp: FastMCP) -> None:
    @mcp.resource("data://items", mime_type="application/json")
    def items() -> list[dict[str, str]]:
        """Static resource: fixed URI."""
        return [{"id": "1", "name": "example"}]

    @mcp.resource("data://items/{item_id}")
    def item(item_id: str) -> dict[str, str]:
        """Resource template: the URI carries a parameter."""
        return {"id": item_id, "name": "example"}

# src/mcp_server/prompts/my_prompt.py
from fastmcp import FastMCP


def register_my_prompt(mcp: FastMCP) -> None:
    @mcp.prompt
    def review_code(code: str, language: str = "python") -> str:
        """Ask the model to review a snippet."""
        return f"Review this {language} code and list concrete issues:\n\n{code}"

rm src/mcp_server/tools/echo.py \
   src/mcp_server/resources/server_info.py \
   src/mcp_server/prompts/summarize.py \
   src/mcp_server/services/echo_service.py \
   src/mcp_server/schemas/echo.py \
   tests/test_tools_echo.py \
   tests/test_services_echo.py \
   tests/test_resources_and_prompts.py

docker build -t mcp-server-template .
docker run --rm -p 8000:8000 mcp-server-template

claude mcp add my-server -- uv run --directory /absolute/path/to/mcp-server-template   fastmcp run src/mcp_server/server.py:mcp

[mcp_servers.my-server]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/mcp-server-template",
        "fastmcp", "run", "src/mcp_server/server.py:mcp"]

[mcp_servers.my-server.env]
MCP_SERVER_NAME = "my-server"

codex mcp add my-server -- uv run --directory /absolute/path/to/mcp-server-template   fastmcp run src/mcp_server/server.py:mcp

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-server-template",
        "fastmcp",
        "run",
        "src/mcp_server/server.py:mcp"
      ],
      "env": {
        "MCP_SERVER_NAME": "my-server"
      }
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

[mcp_servers.my-server]
url = "http://localhost:8000/mcp"