mcp-server-template

Opinionated template for building read-only MCP servers that coding agents can actually use well: I/O seams with timeouts, offline tests, compact text outputs, least-privilege docs.

Start here → BUILDING.md — the full workflow from idea to published server (~half a day).

What's inside: a working example server (pypi_project fixed-origin HTTP tool behind a stubbed seam + word_stats pure tool), offline test suite, CI workflow, CLAUDE.md conventions, and a README skeleton below.

The network example deliberately does not accept arbitrary URLs. "Read-only" does not make a URL fetcher safe: unrestricted destinations and followed redirects can expose loopback, private-network, or cloud-metadata services. pypi_project constructs only https://pypi.org/... requests, rejects URL/path-shaped input, never follows redirects, caps the decoded response at 2 MiB, and applies a 15-second whole-operation deadline.

README skeleton for your server (replace this whole file)

1. # mcp-<name> + one-line value prop in bold

2. 4-line usage transcript (You: … / Agent: → tool calls / Agent: answer)

3. Tools table (tool → what it returns)

4. Install: claude mcp add <name> -e TOKEN=... -- python -m mcp_<name> + .mcp.json block

5. Token scope / security (least privilege, read-only statement)

6. Design notes (why read-only, why compact text, why timeouts)

7. License + contact line

Use the structure above directly; replace every template name and example before publishing a derived server.

Related MCP server: MCP Server Template

Security and privacy

• The example sends only the supplied package name to PyPI. Do not put secrets or private identifiers in tool arguments.

• PyPI project summaries are uploader-controlled prose, so the example deliberately omits them from agent-visible output. Treat all external text as untrusted data.

• Never log credentials, authorization headers, raw private responses, or user prompts.

• Document which external service receives each argument. Private CI logs and internal URLs are sensitive even when a tool only reads them.

• Keep arbitrary URL fetching out of derived servers unless you implement a destination allowlist and a transport that cannot be bypassed by redirects or DNS rebinding.

Development

python -m pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest
python -m build

MIT — see LICENSE.