MCP Server¶

The MCP surface is pinned at nine task-shaped tools — get_overview, search_codebase, get_symbol, get_context, get_references, get_why, grep, glob and read_file — registered by run() (frozen contract: docs/tool-contracts.md). The tools themselves are closures inside the server module; each validates the matching pydantic input model below and delegates to the ToolRouter (the three filesystem tools delegate to the FileToolsService, which walks the indexer’s discovery scope). run serves a single project (db_path) or several — a workspace directory or explicit db_paths for read-only multi-repo serving — and accepts gpu=True to run query-time embedding on CUDA.

pydocs_mcp.server.run(db_path=None, config_path=None, *, gpu=False, workspace=None, db_paths=None, descriptions_path=None)[source]¶

Start the MCP server over one project (db_path) or several — a workspace dir or explicit db_paths (read-only multi-repo). descriptions_path is the --descriptions override document (highest-precedence description source, ADR 0006).

Parameters:

db_path (Path | None)
config_path (Path | None)
gpu (bool)
workspace (Path | None)
db_paths (list[Path] | None)
descriptions_path (Path | None)

Return type:

None

Tool input schemas¶

class pydocs_mcp.application.mcp_inputs.OverviewInput(*, package='', project='')[source]¶

Bases: BaseModel

get_overview — orientation card scope (spec §D1/§D17).

Parameters:

package (str)
project (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.SearchInput(*, query, kind='any', package='', scope='all', project='', limit=<factory>)[source]¶

Bases: BaseModel

Input for the search_codebase MCP tool.

Parameters:

query (Annotated[str, MinLen(min_length=1), MaxLen(max_length=30000)])
kind (Literal['docs', 'api', 'any', 'decision'])
package (str)
scope (Literal['project', 'deps', 'all'])
project (str)
limit (Annotated[int, Ge(ge=1)])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.SymbolInput(*, target, depth='summary', project='')[source]¶

Bases: BaseModel

get_symbol — known dotted path (spec §D1). depth=’source’ is the §D7 recovery contract.

Parameters:

target (Annotated[str, MinLen(min_length=1)])
depth (Literal['summary', 'tree', 'source'])
project (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.ContextInput(*, targets, project='')[source]¶

Bases: BaseModel

get_context — batched targets under one shared budget (spec §D1).

Parameters:

targets (Annotated[list[str], MinLen(min_length=1), MaxLen(max_length=20)])
project (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.ReferencesInput(*, target, direction='callers', project='', limit=<factory>)[source]¶

Bases: BaseModel

get_references — graph traversal incl. ranked transitive impact (spec §D1).

Parameters:

target (Annotated[str, MinLen(min_length=1)])
direction (Literal['callers', 'callees', 'inherits', 'impact', 'governed_by'])
project (str)
limit (Annotated[int, Ge(ge=1)])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.WhyInput(*, query='', targets=None, project='')[source]¶

Bases: BaseModel

get_why — decision search / per-target governing decisions / dashboard (spec §D11).

Parameters:

query (str)
targets (Annotated[list[str] | None, MinLen(min_length=1), MaxLen(max_length=20)])
project (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.GrepInput(*, pattern, path='', glob='', output_mode='files_with_matches', case_insensitive=False, line_numbers=True, after_context=None, before_context=None, context=None, head_limit=None, multiline=False, scope='project', project='')[source]¶

Bases: BaseModel

grep — exact-string / regex text search over source files (§3.7).

Parameters:

pattern (Annotated[str, MinLen(min_length=1)])
path (str)
glob (str)
output_mode (Literal['content', 'files_with_matches', 'count'])
case_insensitive (bool)
line_numbers (bool)
after_context (Annotated[int | None, Ge(ge=0)])
before_context (Annotated[int | None, Ge(ge=0)])
context (Annotated[int | None, Ge(ge=0)])
head_limit (Annotated[int | None, Ge(ge=1)])
multiline (bool)
scope (Literal['project', 'deps', 'all'])
project (str)

model_config = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.GlobInput(*, pattern, path='', head_limit=None, project='')[source]¶

Bases: BaseModel

glob — find files by name pattern, mtime-descending (§3.8).

Parameters:

pattern (Annotated[str, MinLen(min_length=1)])
path (str)
head_limit (Annotated[int | None, Ge(ge=1)])
project (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pydocs_mcp.application.mcp_inputs.ReadFileInput(*, file_path, offset=None, limit=None, project='')[source]¶

Bases: BaseModel

read_file — line-numbered file content within the corpus boundary (§3.9).

Parameters:

file_path (Annotated[str, MinLen(min_length=1)])
offset (Annotated[int | None, Ge(ge=1)])
limit (Annotated[int | None, Ge(ge=1)])
project (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LookupInput is no longer a tool schema: it survives as the internal request contract that get_symbol / get_references build when delegating to the lookup router (see application/tool_router.py).