ADR-0004: Lenient mypy Configuration for MVP

Status

Accepted

Context

The mail-mcp project uses mypy for static type checking as part of CI. However, several type errors arise from:

  1. elasticsearch-py type stubs: The official Elasticsearch Python client has known issues with type stubs, particularly around **kwargs patterns used in search and other API methods. See: https://github.com/elastic/elasticsearch-py/issues/2270

  2. Dynamic dict construction: Building Elasticsearch queries requires dynamic dict construction that doesn’t always satisfy strict typing.

  3. MVP development phase: The project is in active development where rapid iteration is more valuable than strict type safety.

Running mypy with default settings produces ~50 errors, primarily from the Elasticsearch client integration, not from actual bugs in the codebase.

Decision

Configure mypy with lenient settings that:

  • Disable specific error codes that primarily affect library integrations:

    • arg-type - Elasticsearch **kwargs patterns

    • return-value - ObjectApiResponse vs dict return types

    • dict-item - Dynamic query construction

    • attr-defined - Accessing response attributes

    • operator - Counter/stats operations

    • assignment - Config field type narrowing (pydantic-settings)

    • union-attr - Email payload decode (bytes vs Message union types)

  • Disable warn_return_any since elasticsearch-py returns Any from many methods

  • Keep other mypy checks enabled to catch genuine type errors

Consequences

Positive

  • CI passes without false positives from library type issues

  • Development velocity maintained during MVP phase

  • Real type errors (undefined names, import errors) still caught

Negative

  • Some genuine type errors in Elasticsearch-related code may be missed

  • Technical debt: configuration should be tightened as codebase matures

Future Work

When the project stabilizes:

  1. Revisit disabled error codes and enable them selectively

  2. Add type annotations to key functions

  3. Consider per-module mypy overrides for stricter checking in non-Elasticsearch code

  4. Monitor elasticsearch-py for improved type stub support