Metadata-Version: 2.4
Name: matrouter
Version: 0.2.1
Summary: Local-first MCP server for agentic materials data routing.
Author-email: Quansheng Wu <quansheng.wu@iphy.ac.cn>, Tiannian Zhu <tnzhu@iphy.ac.cn>
Maintainer-email: Quansheng Wu <quansheng.wu@iphy.ac.cn>, Quansheng Wu <wuquansheng@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/MatRouter/matrouter
Project-URL: Repository, https://github.com/MatRouter/matrouter
Project-URL: Issues, https://github.com/MatRouter/matrouter/issues
Keywords: materials-science,mcp,optimade,materials-project,aflow,c2db,mpds,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: matplotlib>=3.11.0
Requires-Dist: materialsgalaxy-api>=0.1.2
Requires-Dist: mp-api>=0.46.4
Requires-Dist: pymatgen>=2026.5.4
Dynamic: license-file

# MatRouter

<p align="center">
  <img src="https://raw.githubusercontent.com/MatRouter/matrouter/main/logo.png" alt="MatRouter logo" width="220">
</p>

[English](https://github.com/MatRouter/matrouter/blob/main/README.md) | [简体中文](https://github.com/MatRouter/matrouter/blob/main/README.zh-CN.md)

MatRouter is a local-first MCP server for agentic materials research. It gives AI agents structured access to materials databases through normalized tools, provenance-aware responses, and lightweight analysis utilities.

## Status

`v0.2.1` is an offline-tested local release focused on provenance-preserving materials retrieval, evidence workflows, and resilient upstream integrations.

## Quick Start

MatRouter requires Python 3.11 or newer.

Install the published package:

```bash
uv tool install matrouter
```

Or install from a source checkout:

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

Optional bootstrap check before wiring an agent host:

```bash
matrouter --explain-sources
```

Agent hosts should run MatRouter as a local MCP stdio server:

```bash
matrouter
```

When running from a source checkout instead of the installed tool, prefix the same commands with `uv run`, for example `uv run matrouter --explain-sources`.

For Codex and Claude Code, prefer the installable plugin path in the [user guide](https://github.com/MatRouter/matrouter/blob/main/docs/usage.md). 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 detail routes, and MPDS require API keys. Keep real keys in a private env file such as `~/.config/matrouter/env`, or in process environment variables; do not commit them to the repository or shared MCP client configuration.

## Documentation

- User setup, data-source configuration, MCP client examples, prompts, FAQ, and troubleshooting: [user guide](https://github.com/MatRouter/matrouter/blob/main/docs/usage.md)
- Development guide, architecture notes, configuration contract, testing, and release workflow: [development guide](https://github.com/MatRouter/matrouter/blob/main/docs/development.md)
- Validation report: [test report](https://github.com/MatRouter/matrouter/blob/main/docs/test-report.md)

## Agent Skill

The public MatRouter skill source lives in [`skills/matrouter/`](https://github.com/MatRouter/matrouter/tree/main/skills/matrouter). It is for agents that have, or are being configured to have, MatRouter MCP access. It provides materials-research guidance: source selection, provenance handling, screening, comparison, report packages, conservative evidence interpretation, and MCP initialization when availability is blocked.

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:

```text
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](https://github.com/MatRouter/matrouter/blob/main/LICENSE) and [NOTICE](https://github.com/MatRouter/matrouter/blob/main/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.
