# mcp-py-template

Production-ready **Model Context Protocol (MCP) server** template in Python, built on the official [`mcp`](https://github.com/modelcontextprotocol/python-sdk) SDK (FastMCP). Ships an example **tool**, **resource**, and **prompt**.

## Use this template

```bash
gh repo create my-mcp --template vidyasagarr7/mcp-py-template
```

## Layout

```
src/mcp_py_template/
  server.py    # FastMCP registration + stdio entry point
  core.py      # pure domain logic (testable, no MCP concerns)
  __init__.py
tests/         # pytest specs (core + server)
```

Golden rule: **registration in `server.py`, logic in `core.py`.**

## Develop

```bash
uv sync --extra dev            # create .venv + install deps
uv run mcp-py-template         # run server over stdio
uv run pytest                  # tests + coverage
uv run ruff check .            # lint
uv run mypy                    # strict type-check
```

## Inspect

```bash
uv run mcp dev src/mcp_py_template/server.py   # MCP Inspector (dev UI)
```

## Register a new tool

1. Add pure logic to `src/mcp_py_template/core.py`.
2. Add a unit test in `tests/`.
3. Register it in `server.py` with `@mcp.tool()` (type hints become the schema).

## Connect from a client

```json
{
  "mcpServers": {
    "my-mcp": { "command": "uv", "args": ["run", "mcp-py-template"] }
  }
}
```

## Make it yours (rename checklist)

- `pyproject.toml`: `name`, `description`, `[project.scripts]`, coverage target
- Rename the package dir `src/mcp_py_template/` and update imports
- `server.py`: `FastMCP("mcp-py-template")` name
- Replace the example `add` tool / `greeting` resource / `summarize` prompt with your own

## License

MIT