MatRouter
MatRouter is an agent-native routing and aggregation substrate for materials
data. It turns an explicit data need into executable routes across heterogeneous
sources, then assembles returned records, structures, properties, artifacts,
provenance, and execution outcomes into one EvidenceBundle.
The Agent (LLM + MCP + Skill) chooses source and record scope and owns planning, retries, scientific interpretation, and prose. MatRouter owns capability truth, source-qualified execution, normalization, provenance, and bundle integrity. It preserves the context needed for downstream reasoning without turning retrieval into a scientific verdict.
Install
MatRouter requires Python 3.11 or newer.
# Python dependency
uv add --prerelease=allow matrouter
# Standalone MCP command
uv tool install --prerelease=allow matrouter
From a checkout:
git clone https://github.com/MatRouter/matrouter.git
cd matrouter
uv sync
uv run matrouter
Python
from matrouter import create_router
with create_router() as router:
print(router.get_evidence_capability_document())
EvidenceBundle is the core output and the sole record of what was requested,
attempted, returned, or missing. The single MCP surface also exposes explicit
methods for exact-input structure matching, frame-safe phase-diagram
calculation/plotting, and rendering acquired band-structure or DOS artifacts.
Retrieval never renders implicitly. Method results retain their exact inputs,
parameters, provenance, and limitations; they are not general scientific
verdicts.
Agent plugin
Codex and Claude Code can install the bundled plugin; other MCP hosts can run
matrouter as a local stdio server and use the portable Skill when supported.
See the user guide
for the current installation and configuration procedure.
The sole distributable Skill source is
plugins/matrouter/skills/matrouter/.
Scope
MatRouter does not mirror upstream databases, infer missing values, impose a fixed research workflow, embed scientific assessment rules, or decide scientific truth. OPTIMADE remains complementary: OPTIMADE standardizes provider-side common records; MatRouter orchestrates native and OPTIMADE sources on the Agent side and preserves their source-specific context in a common bundle.
Documentation
- User guide: installation, configuration, MCP, sources, and usage.
- Development guide: architecture, contracts, and maintenance.
- Verification report: current tested surface and limits.
- Plugin guide: agent-host installation.
Contact
- Quansheng Wu quansheng.wu@iphy.ac.cn, wuquansheng@gmail.com
- Tiannian Zhu (朱天念) tnzhu@iphy.ac.cn
License
MatRouter is licensed under Apache-2.0; see LICENSE and NOTICE. Retrieved data remains subject to each upstream provider's terms, licenses, attribution requirements, and access restrictions.
2 maintainers
Metadata
2 maintainers
Release files for matrouter 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| matrouter-0.11.0.tar.gz | 711.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrouter-0.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / matrouter-0.11.0.tar.gz
| Download URL | matrouter-0.11.0.tar.gz |
|---|---|
| Size | 711.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
537be5b7bf3ab10eac033f1c89ad94e51600d2a9cab9924fa41c06c27b00fbcc
|
|
BLAKE2b-256 checksum How to use checksums |
0e4ab17f6d22136c7195365d90bc953823f77c7ba26dfa0c4f7de90b2ebbcc92
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logRelease files / matrouter-0.11.0-py3-none-any.whl
| Download URL | matrouter-0.11.0-py3-none-any.whl |
|---|---|
| Size | 306.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c63b6addf3d5dfaa2c33659e5dffbd30679ba70302c8eb57cc281786a6778b9
|
|
BLAKE2b-256 checksum How to use checksums |
392076830fde10c86d4e79012128f5750bb524c6690e46db18c4823e1258bb70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logSecurity for matrouter 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for matrouter-0.11.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
