mcp-hello-server: Instructions file for Claude Code

mcp-hello-server — notes for Claude

A minimal MCP server built with Python / FastMCP — a good starting point for a new server or a demo. It exposes two tools: server_info (a health/status check) and greet (a friendly greeting in one of a handful of languages, defaulting to English). Built with uv, FastMCP, pytest, and make; multi-stage Docker on a distroless Chainguard/Wolfi Python base (cgr.dev/chainguard/python) for a near-zero-CVE image. It was scaffolded from the sibling random-mcp-server by stripping every tool down to server_info and adding the greet demo tool.

Layout

• src/mcp_hello_server/greetings.py — greeting data (GREETINGS), language resolution (names, aliases, ISO codes), and the greet() builder.
• src/mcp_hello_server/server.py — the FastMCP server (mcp), its tools (server_info, greet), and the main() console-script entry point (mcp-hello-server).
• tests/ — pytest suite. test_server.py drives the tools through an in-memory FastMCP Client (no network, no subprocess); test_greetings.py unit-tests the resolver/builder; test_bdd.py + tests/features/*.feature are a pytest-bdd layer.

Conventions

• Dependencies / venv: managed by uv. make install runs uv sync (creates .venv). uv.lock is committed and the Dockerfile installs --frozen from it, so run make lock (or uv lock) whenever pyproject.toml deps change.
• Running: make run (stdio, the default MCP transport), make run-http (streamable HTTP on PORT, default 8000), make dev (FastMCP Inspector). The transport is chosen by MCP_TRANSPORT (stdio | http | sse).
• Tests: make test → uv run pytest.
• Adding a tool: give it a title and MCP annotations. Both current tools are pure reads (readOnlyHint: True, openWorldHint: False); a tool that mutates state or reaches the network should flip those and add destructiveHint/idempotentHint, which are only meaningful when readOnlyHint is false.
• Adding a language: add a row to GREETINGS in greetings.py (and, optionally, an alias / ISO code in _ALIASES). server_info reports the supported set automatically.
• Docker: the image defaults to HTTP transport (MCP_TRANSPORT=http, HOST=0.0.0.0, PORT=8000) so it's reachable on a published port. The base is distroless Chainguard/Wolfi Python (cgr.dev/chainguard/python), which already runs as the non-root nonroot user (uid 65532) and has no shell / package manager. The venv is built on the matching -dev image so its interpreter symlink resolves at runtime. make scan should report 0 CRITICAL/HIGH.
• Trivy version is pinned in two places that must move together. The Makefile's TRIVY_VERSION (used as aquasec/trivy:$(TRIVY_VERSION) by make scan) and the version: input on every aquasecurity/trivy-action step (image-scan.yml ×2, publish.yml, publish-dockerhub.yml, scan-scheduled.yml). Bump all of them in the same change. Dependabot covers neither: its docker ecosystem reads the Dockerfile only, so it never sees the Makefile tag, and its github-actions ecosystem bumps the action while the scanner binary inside it stays put — the action's own default lags badly (v0.36.0 still defaults to trivy v0.70.0, which is what CI silently ran until the pin landed). Leaving the Makefile on an unpinned aquasec/trivy is worse than a stale pin: local drifts to whatever :latest resolves to while CI sits on the action default, so a local pass stops predicting the required scan check.
• The scan check also smoke-tests the container: image-scan.yml runs the freshly built image and calls make docker-smoke against it (an MCP initialize that must return this server's name), so an image that builds but crashes at startup fails the PR. make docker-test runs the same check against the published image instead.
• Releasing: make release (BUMP=patch|minor|major, default patch) bumps the version and opens a release/vX.Y.Z PR carrying the bump plus the CHANGELOG.md section, waits for main's required checks, merges it, then tags vX.Y.Z — the tag triggers the GHCR, Docker Hub, and PyPI publish workflows (publish, publish-dockerhub, publish-pypi). It then creates the matching GitHub Release (gh release create) using that version's CHANGELOG.md section as the notes (extracted with awk), so the tag, images, package, and Release stay in sync — the Releases page previously drifted because the tag was pushed without a Release object.
  • Write the new version's CHANGELOG.md entry (Keep a Changelog format, top of the file) before running it — the release notes are only as good as that section, and the run aborts if the section is missing. You may leave that edit uncommitted; it rides along in the release PR. Everything else must be committed first.
  • It must not go back to pushing the bump straight to main. That only ever worked because enforce_admins was off, so the release commit reached main without running unit/bdd and the tag was built from an unchecked commit. Branch protection now enforces admins, so a direct push is refused outright.
  • The target is re-runnable: if a run stops (checks failed, merge declined), re-running resumes the existing release/vX.Y.Z branch and skips straight to whatever step is left, rather than bumping the version a second time. It also won't re-tag or re-create an existing Release.
• Branch protection on main: required checks are unit, bdd, and scan (the Trivy image gate), with enforce_admins on — nothing reaches main without them, including releases. Because scan is required, a newly disclosed fixable CRITICAL/HIGH blocks merges until the bump that clears it lands; that's the intended behavior, and Dependabot's uv ecosystem opens that bump.
• PyPI trusted publishing: publish-pypi.yml uploads to PyPI via OIDC trusted publishing (no stored token), from the pypi GitHub environment. The PyPI Trusted Publisher must stay constrained to the pypi environment (owner mitchallen, repo mcp-hello-server, workflow publish-pypi.yml). If it's ever reconfigured, don't leave the environment field blank — an unconstrained publisher lets any workflow/environment in the repo publish, and PyPI will nag you to constrain it. Version badges (PyPI, Python) are cached proxy images (shields.io + PyPI's own image cache) and can lag a release by hours — that's cosmetic, not drift; see the badge note in README.md.