Skip to content

MCP server reference

xpd mcp starts a Model Context Protocol server, so an agent can lint, fix, search and check Python through tools instead of a shell. The server is built on FastMCP 4.2 and gets every rule and result from the xpd binary, so it matches the installed version. This page and the pages below list what the server registers, as the site's build read it from the running server. xpd mcp lists the server's flags.

Terminal window
claude mcp add xpd -- uvx xpd mcp

The server is named xpd, and xpd 0.41.5 lists 21 tools, 10 resources, 2 resource templates and 5 prompts.

Tool What it does May change files
find Find up to five symbols, three rules and three recipes, ranked within each kind. No
api Read a public dotted name's parameters, summary, own class members and rule links. No
check Lint Python files for slow or wrong habits with pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly, Apache Hamilton and Python itself. No
fix Write xpd's fixes into the files, then lint what is left. Yes
graph Read the dataflow of step code or Apache Hamilton modules without running them: which step or node reads which, and what does not connect. No
profile Profile a data file (csv, parquet, feather, json or xlsx): each column's dtype, nulls, distinct values and memory. No
refit Fit a clone of the saved Pipeline on raw training rows and compare held out outputs and validation scores. Yes
equiv Run two scripts with the project's Python, each in its own process, and check that they leave an equal result (DataFrames and Series with pandas.testing, anything else with numpy.testing). Yes
query Find AST patterns or syntax kinds and preview replacements without changing files. No
rewrite Preview a structural rewrite, ask for confirmation, then apply it to project files. Yes
outline Read symbols, signatures, imports, members and source ranges without execution. No
new Create a project, rule, empty case template or shared utility without prompts. Yes
test Check valid and invalid examples using xpd's scanner and compare snapshots. Yes
discovery_gate Read Python files and check direct imported calls in the chosen symbols' modules. No
show_issues Show what check finds as a sortable, searchable table, in hosts that render MCP Apps. No
show_dataflow Show what graph reads as a flowchart of steps or nodes and a table of its problems, in hosts that render MCP Apps. No
show_columns Show what profile reads as a table of columns, in hosts that render MCP Apps. No
rules List xpd's rules and package checks, without their documentation. No
rule Read one rule: why it matters, what it reports, and its before and after examples. No
contract Read the contract that a training script saved beside its model: the data file and target, the split, the input columns, the steps of the Pipeline, the validation scores, and the model file with the versions that wrote it and the project files it imports when it loads. No
gates Judge a pipeline run from raw rows to a saved model. No

The resources page lists the resources and templates, and the prompts page lists the prompts.

With --code-mode, the server lists these 3 tools in place of the ones above.

Tool Arguments Description
search query, tags?, detail?, limit? Search for available tools by query. Returns matching tools ranked by relevance.
get_schema tools, detail? Get parameter schemas for specific tools. Use after searching to get the detail needed to call a tool.
execute code Chain await call_tool(...) calls in one Python block; prefer returning the final answer from a single block. Use return to produce output. Only call_tool(tool_name: str, params: dict) -> Any is available in scope.

The server gives the agent these instructions when it connects.

xpd lints Python for slow or wrong habits with pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly and Apache Hamilton, reads the dataflow of step code and Hamilton modules, profiles data files, and checks that a refactor keeps its result. Every path is relative to the project root.
- Before choosing a library, call `find` with the task, then `api` with a returned name. Call `api` with `Class.method` to read a method's parameters with their defaults before you call it.
- After choosing and writing code, call `discovery_gate` on its files before `equiv`.
- After you write or change Python, call `check`. Fix every error. Fix a warning unless you can say why the code is right. `fix` writes xpd's fixes, and asks the user before unsafe ones.
- Use `query` to find code patterns and preview replacements, and `rewrite` to apply them after confirmation. Use `outline` to browse project symbols, imports and members in supported languages.
- Use `new` to create a local rule project, rule, empty case template or shared utility.
- To learn why a rule fires and see its before and after code, call `rule`. `rules` lists and filters all of them.
- After you add, move or rename a step or a Hamilton node, call `graph`, and reuse columns that exist instead of computing their formulas again.
- Before you choose methods for a data file, call `profile`.
- After you refactor data logic, call `equiv` on the old and new script. The refactor is done when it says `equivalent: true`.
- To build a model from a data file, follow the `build_pipeline` prompt. The run is done when `gates` returns `passed: true` for the results of `profile`, `check`, `graph`, `equiv`, `refit` and `contract`. With code mode on, one `execute` call chains them.
- The show_ tools draw the same results as tables and charts in hosts that render apps.
- skill://xpd/SKILL.md, skill://python-best-practices/SKILL.md and skill://python-review/SKILL.md hold the style a linter cannot check.

A tool checks that each path is inside the project root, runs the xpd binary there and returns the binary's JSON as a typed result. find and api run in the server's working folder, because they read no project file. discovery_gate parses the files in Python, contract reads a JSON file, and gates only judges the results it is given.

sequenceDiagram
    participant Agent
    participant Server as xpd mcp
    participant Binary as xpd binary
    Agent->>Server: check(paths=["samples/bad.py"])
    Server->>Server: check that the path is inside the project root
    Server->>Binary: xpd check --format json -- samples/bad.py
    Binary-->>Server: {"fixed": 0, "fixable": 0, "issues": [...]}
    Server-->>Agent: the same JSON, as a typed result

The project root is --root or XPD_MCP_ROOT when one is set. A client that starts the server in a plugin's folder sets PLUGIN_ROOT, and then the root is the first root of the client that is a folder on the machine. Otherwise it is the server's working folder.

A tool that cannot finish returns a tool error with a message, and the agent sees it as the result of the call. A path outside the project root fails before xpd runs. When the binary exits with a code that carries no result, the error names the command and its message, such as xpd api -- no.such.name exited with 2: xpd: no entry named no.such.name. Issues, problems in a dataflow and failed gates are results, not errors.

A client can run check, fix, query, rewrite, outline, new, test, profile, refit and equiv as background tasks, so it gets a task at once and fetches the result when the tool is done. Each of them reports progress and logs the xpd command it runs.