mcp-python-starter: Instructions file for Codex

AGENTS.md

This file provides context for AI coding agents working in this repository.

Quick Reference

Task	Command
Install	uv sync --all-extras --dev
Test	uv run pytest -v
Lint	uv run ruff check .
Lint fix	uv run ruff check --fix .
Format	uv run ruff format .
Format check	uv run ruff format --check .
Type check	uv run mypy . --ignore-missing-imports
Run (stdio)	uv run mcp-python-starter
Run (HTTP)	uv run mcp-python-starter --http

Project Overview

MCP Python Starter is a feature-complete Model Context Protocol (MCP) server template in Python using FastMCP. It demonstrates all major MCP features including tools, resources, resource templates, prompts, sampling, progress updates, and dynamic tool loading.

Purpose: Workshop starter template for learning MCP server development.

Technology Stack

• Runtime: Python >=3.11
• MCP SDK: mcp (FastMCP)
• HTTP Server: uvicorn
• CLI: Click
• Package Manager: uv (lockfile: uv.lock - committed to repo)
• Linter/Formatter: Ruff
• Type Checker: mypy or pyright

Project Structure

mcp_starter/
├── __init__.py
└── server.py       # Main server with all MCP features

.vscode/
├── mcp.json            # MCP server configuration for VS Code
├── tasks.json          # Build/run tasks
├── launch.json         # Debug configurations
└── extensions.json     # Recommended extensions

.devcontainer/
└── devcontainer.json   # DevContainer configuration

pyproject.toml          # Package configuration and tool settings

Build & Run Commands

# Install dependencies (uses uv.lock for reproducible installs)
uv sync --all-extras --dev

# Run server (stdio)
uv run mcp-python-starter

# Run server (HTTP)
uv run mcp-python-starter --http

Linting & Formatting

# Lint code
uv run ruff check .

# Fix lint issues
uv run ruff check --fix .

# Format code
uv run ruff format .

# Check formatting (CI mode)
uv run ruff format --check .

# Type checking
uv run mypy . --ignore-missing-imports