Metadata-Version: 2.5
Name: qorechain-mcp
Version: 0.1.0
Summary: MCP server with read access to QoreChain: blocks, transactions, accounts, validators, hybrid ML-DSA-87 signature status, simulation and unsigned transfers.
Project-URL: Homepage, https://github.com/qorechain/qorechain-mcp
Project-URL: Source, https://github.com/qorechain/qorechain-mcp/tree/main/python
Project-URL: Issues, https://github.com/qorechain/qorechain-mcp/issues
Author: QoreChain Association
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,blockchain,mcp,ml-dsa,model-context-protocol,qorechain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: dilithium-py==1.4.0
Requires-Dist: mcp==2.3.0
Provides-Extra: dev
Requires-Dist: build==1.6.1; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.17.0; extra == 'dev'
Requires-Dist: twine==7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# qorechain-mcp (Python)

<!-- mcp-name: io.github.qorechain/qorechain-mcp -->

MCP server with read access to [QoreChain](https://www.qorechain.io): blocks, transactions, accounts, validators, staking tiers, the status of the hybrid secp256k1 + ML-DSA-87 (FIPS 204) signature, EVM contract reads, simulation and fee estimates, and unsigned transfers for the user's own wallet to sign. It never signs, never holds keys and never broadcasts.

This is the Python distribution of the same server as the npm package `@qorechain/mcp`: same tool names, input and output schemas, outputs and error codes. Both are tested against the same recorded chain answers.

```bash
uvx qorechain-mcp                      # stdio
uvx qorechain-mcp --network mainnet    # mainnet for calls that name no network
```

MCP client configuration:

```json
{ "mcpServers": { "qorechain": { "command": "uvx", "args": ["qorechain-mcp"] } } }
```

Requires Python 3.10 or later. The Python package serves stdio; for Streamable HTTP with API keys and rate limits, use `npx -y @qorechain/mcp serve` or the container image `ghcr.io/qorechain/qorechain-mcp`.

## Tools

`get_chain_info`, `get_block`, `get_transaction`, `get_address_info`, `get_pq_status`, `get_validators`, `get_staking_tiers`, `search`, `read_contract` (eth_call only), `estimate_fee`, `simulate_tx`, `prepare_transfer` (unsigned), and `get_token_holders` and `request_faucet`, which answer `NOT_AVAILABLE_ON_CHAIN`. Every tool takes an optional `network`: `testnet` (default) or `mainnet`. Full reference: <https://github.com/qorechain/qorechain-mcp/blob/main/docs/tools.md>.

Errors are tool results with `isError: true` and a JSON body `{"error": {"code", "message", "details?"}}`, with the codes `NOT_FOUND`, `INVALID_INPUT`, `UPSTREAM_UNAVAILABLE`, `NOT_AVAILABLE_ON_CHAIN`, `RATE_LIMITED`, `UNAUTHORIZED`, `INTERNAL_ERROR`. Input that looks like a recovery phrase or private key is refused.

## Library use

```python
import anyio
from qorechain_mcp import Context, run_tool

async def main():
    out = await run_tool("get_chain_info", {"network": "mainnet"}, Context())
    print(out["latest_block"])

anyio.run(main)
```

## Dependencies

| Package | License |
|---|---|
| `mcp` 2.3.0 (official MCP Python SDK) and its dependencies | MIT, with BSD and Apache-2.0 dependencies |
| `dilithium-py` 1.4.0 (ML-DSA-87 verification, pure Python) | MIT |

keccak-256, RIPEMD-160, bech32 and the protobuf subset are implemented in the package. The BIP-39 English word list (used only to refuse recovery phrases) comes from the BIP-39 specification.

## Development

```bash
pip install -e ".[dev]"
pytest              # golden outputs shared with the TypeScript server
ruff check src tests
python -m build && twine check --strict dist/*
```

`src/qorechain_mcp/tools.json` is generated from the TypeScript server (`node scripts/gen-tools-spec.mjs` in the repository root); do not edit it by hand.

Apache-2.0. Copyright 2026 QoreChain Association.
