MatRouter

English | 简体中文

MatRouter is an agent-native materials evidence substrate. It routes explicit EvidenceRequirement objects to source-qualified executable operations and deterministically decides whether returned evidence is admissible for a ClaimSpec. It does not treat retrievable data, a ready route, or a successful source call as support for a scientific claim.

The Agent control plane—LLM, Skills, and MCP tool use—interprets natural language, decomposes evidence needs, chooses source breadth and order, retries, iterates, stops, and writes the narrative. The Python evidence plane owns typed requests, capability truth, route readiness, qualified source identity, SourceOutcome, canonical observations and provenance, scientific qualification, trace, lineage, artifact integrity, and ClaimSupportMap. Agents may change a plan; they may not upgrade an incomplete, incomparable, or conflicted MatRouter disposition to supported.

MatRouter's scientific model separates availability → execution → admissibility. FastMCP is one transport for the Python core, and the Agent Skill is a control-plane recipe.

Status

This checkout is the direct-v2 cutover. The public architecture is the two-plane surface described above; old workflow schemas and end-to-end task tools are migration inputs, not supported fallback APIs. A v2 contract or MCP tool is public only when its typed module and contract tests are present. Schemas remain versioned and may change before a stable release. Stateful MCP composition starts with begin_evidence_run; its returned process-local ID isolates the attempt ledger, and a later attempt invalidates older bundles for the same requirements. Each stateful call holds a run-wide lease, so an active run cannot be replaced mid-operation. Executed malformed payloads remain failed SourceOutcome attempts and never become evidence.

Quick Start

MatRouter requires Python 3.11 or newer.

Add MatRouter to a Python project:

uv add --prerelease=allow matrouter

Use the package directly:

from matrouter import create_router

with create_router() as router:
    print(router.explain_sources())

Create a claim specification, collect the explicitly declared evidence requirements through the Agent control plane, and let deterministic Python qualification produce the claim-support map:

from matrouter.claim_support import make_claim_support_request, qualify_claim_support

request = make_claim_support_request(bundle, (claim_spec,))
support_map = qualify_claim_support(request)
print(support_map.entries[0].disposition)

The four finite templates are retained as versioned Python policy packs, Skill recipes, and benchmark specifications. They deterministically expand into mandatory EvidenceRequirement objects; they do not choose a complete source sequence or report preset. EvidenceBundle is the sole evidence truth, and ClaimSupportMap exposes only the four scientific dispositions supported, conflicted, incomparable, and incomplete. Availability statuses such as unsupported remain outside that scientific algebra.

OPTIMADE and MatRouter are complementary: OPTIMADE standardizes provider-side common-record interoperability, while MatRouter provides agent-side evidence capability routing and scientific admissibility across native and OPTIMADE sources. Aggregate providers are discovery scopes; executable evidence routes retain the exact provider/database child identity. MatRouter does not replace OPTIMADE.

Install the same package as an MCP runtime:

uv tool install --prerelease=allow matrouter

Or install from a source checkout:

git clone https://github.com/MatRouter/matrouter.git
cd matrouter
uv sync

Agent hosts can then run MatRouter as a local MCP stdio server:

matrouter

When running from a source checkout instead of the installed tool, use uv run matrouter.

For Codex and Claude Code, prefer the installable plugin path in the user guide. For OpenCode or other hosts, configure MCP with command: "matrouter" or command: ["matrouter"] and install the portable skill if the host supports skills.

Most starter workflows can use public sources without MatRouter-specific credentials. Materials Project, MaterialsGalaxy structure/property routes, and MPDS require API keys supplied through the process environment or the agent host's secret storage. Do not commit keys to the repository or shared MCP client configuration.

Documentation

• User setup, data-source configuration, MCP client examples, workflows, and troubleshooting: user guide
• Development guide, architecture notes, configuration contract, testing, and release workflow: development guide
• Validation report: test report

Agent Skill

The public MatRouter skill source lives in skills/matrouter/. It is for agents that have, or are being configured to have, MatRouter MCP access. It is the non-normative control-plane recipe for creating claim specifications, decomposing evidence needs, choosing routes, handling retries and gaps, and narrating deterministic MatRouter qualification without changing its disposition.

For Codex auto-discovery, install it by copying skills/matrouter/ to .agents/skills/matrouter/ in a repo or to $HOME/.agents/skills/matrouter/ for personal use.

For human-facing MCP client setup, use the user guide. After setup, a useful prompt is:

Use MatRouter to find the band structure of diamond and generate a plot.

Contact

Authors:

• Quansheng Wu quansheng.wu@iphy.ac.cn
• Tiannian Zhu (朱天念) tnzhu@iphy.ac.cn

Maintainer:

• Quansheng Wu wuquansheng@gmail.com

License

MatRouter source code is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

MatRouter does not grant rights to third-party database content. Data retrieved through MatRouter remains subject to the terms, licenses, API policies, attribution requirements, and access restrictions of the respective upstream data providers.