drunk-mcp-proxy: Instructions file for Codex

Drunk MCP Proxy - Development Guidelines

This document provides instructions and guidelines for AI agents and developers working on the Drunk MCP Proxy project.

1. Environment & Setup

• Python Version: 3.10+
• Project Type: Python application using setuptools with src/ layout.
• Dependency Management: pyproject.toml.
• Key Libraries: fastmcp, pydantic, fastapi, uvicorn.

Installation

To install the project in editable mode with development dependencies:

pip install -e ".[dev]"

2. Build, Lint & Test Commands

Running Tests

Use pytest to run tests. Always use python -m pytest to ensure the current directory is added to sys.path.

• Run all tests:

  python -m pytest
  

• Run a single test file:

  python -m pytest tests/test_mcp_proxy_provider.py
  

• Run a specific test class:

  python -m pytest tests/test_mcp_proxy_provider.py::TestMcpProxyProviderCreateProxy
  

• Run a single test method:

  python -m pytest tests/test_mcp_proxy_provider.py::TestMcpProxyProviderCreateProxy::test_create_proxy_returns_cached_mcp
  

• Run with coverage:

  python -m pytest --cov=src
  

Linting & Type Checking

• Linting (flake8):

  flake8 src tests
  

• Type Checking (pyright):

  pyright
  

3. Code Style & Conventions

Python Version & Modern Syntax (Critical)

• Python Version: 3.10+ required. Do not write code compatible with Python 3.8 or 3.9.
• Modern Union Types: Always use X | Y syntax, never Union[X, Y] or Optional[X].
  • ✅ GOOD: def get(self) -> str | None:
  • ❌ BAD: def get(self) -> Optional[str]: or def get(self) -> Union[str, None]:
• Modern Generic Types: Use lowercase built-in generics: list[str], dict[str, int], never List[str], Dict[str, int].
• Pattern Matching: Use match/case for complex conditional logic (Python 3.10+ feature).

  match status:
      case 200:
          return "OK"
      case 404:
          return "Not Found"
      case _:
          return "Unknown"
  

• Parenthesized Context Managers: Use for multi-line context managers:

  with (
      open("file1.txt") as f1,
      open("file2.txt") as f2
  ):
      data = f1.read()
      f2.write(data)
  

• F-strings Only: Never use % formatting or str.format(). Always use f-strings:
  • ✅ GOOD: f"User {user.name} logged in"
  • ❌ BAD: "User %s logged in" % user.name or "User {} logged in".format(user.name)