Exceptions

The public exception hierarchy. PydocsMCPError is the root (re-exported from the package root); the MCP-facing errors below are raised by the nine task-shaped tool handlers (get_overview, search_codebase, get_symbol, get_context, get_references, get_why, grep, glob, read_file).

exception pydocs_mcp.exceptions.PydocsMCPError

Bases: Exception

Base class for all exceptions raised by pydocs-mcp.

Subclasses MAY also inherit from the relevant standard-library builtin (ValueError, RuntimeError, …) via multiple inheritance — see UnitOfWorkNotEnteredError and PipelineLoadError for examples. The PydocsMCPError lineage is the catch-any-pydocs-mcp-failure handle; the builtin lineage preserves existing isinstance checks at older call sites.

Typed exception hierarchy for MCP tool handlers (sub-PR #6 §5.1).

Handlers raise these instead of returning error strings. FastMCP maps them to JSON-RPC error responses; see spec §5.3 for the code mapping.

exception pydocs_mcp.application.mcp_errors.MCPToolError

Bases: PydocsMCPError

Base — every handler-raised error inherits from this.

exception pydocs_mcp.application.mcp_errors.InvalidArgumentError

Bases: MCPToolError

Semantic validation failure — input parsed but domain-invalid.

Pydantic ValidationError covers schema-level failures; this is for post-parse checks (e.g., show="inherits" on a non-class target).

exception pydocs_mcp.application.mcp_errors.NotFoundError

Bases: MCPToolError

Specified target doesn’t exist in the index.

Raised by lookup for unknown packages/modules/symbols. NOT raised by search — an empty search returns success with an empty-result string.

exception pydocs_mcp.application.mcp_errors.ServiceUnavailableError

Bases: MCPToolError

Backend raised an unexpected error (SQLite, pipeline) or a required optional service is missing (e.g. tree_svc is None but show="tree" was requested).