Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (50 loc) · 2.44 KB

AGENTS.md

File metadata and controls

58 lines (50 loc) · 2.44 KB

Repository Guidelines

Project Structure & Module Organization

  • Documentation: docs/
  • Project description: docs/index.md
  • Internal documentation:
    • Architecture: docs/internal/architecture.md
    • Testing: docs/internal/testing.md
  • Source modules:
    • mcpygen/client.py: MCPClient (stdio, SSE, streamable HTTP)
    • mcpygen/apigen.py: MCP tool wrapper code generation
    • mcpygen/vars.py: variable replacement utilities
    • mcpygen/tool_exec/server.py: ToolServer
    • mcpygen/tool_exec/client.py: ToolRunner, ToolRunnerError, ApprovalRejectedError, ApprovalTimeoutError
    • mcpygen/tool_exec/approval/server.py: ApprovalChannel
    • mcpygen/tool_exec/approval/client.py: ApprovalClient, ApprovalRequest
    • mcpygen/cli.py: CLI entry point (apigen, toolserver)
    • mcpygen/utils.py: shared utilities
  • Tests:
    • tests/unit/: unit tests
    • tests/integration/: integration tests

Directory-specific Guidelines

  • docs/AGENTS.md: documentation authoring
  • tests/AGENTS.md: testing conventions and utilities

Development Commands

uv sync                      # Install/sync dependencies
uv add [--dev] [-U] <dep>    # Add a dependency (--dev for dev-only, -U to upgrade)
uv run <command>             # Run <command> in project's venv
uv run invoke cc             # Run code checks (auto-fixes formatting, mypy errors need manual fix)
uv run invoke test           # Run all tests
uv run invoke ut             # Run unit tests only
uv run invoke it             # Run integration tests only
uv run invoke test --cov     # Run tests with coverage
uv run invoke build-docs     # Build docs
uv run invoke serve-docs     # Serve docs at localhost:8000
uv run pytest -xsv tests/integration/test_[name].py             # Single test file
uv run pytest -xsv tests/integration/test_[name].py::test_name  # Single test
  • invoke cc only checks files under version control. Run git add on new files first.

Docstring Guidelines

  • Use mkdocs-formatter and mkdocs-docstrings skills for docstrings
  • Use Markdown formatting, not reST
  • Do not add module-level docstrings

Coding Guidelines

  • All function parameters and return types must have type hints
  • Modern union syntax: str | None instead of Optional[str]
  • Prefer match/case over isinstance() for type dispatch
  • Package __init__.py files are re-exports only; do not define functions or classes in them

Commit & Pull Request Guidelines

  • Do not include test plan in PR messages