内容
# alphaassay-tools
Open-source client tooling for the AlphaAssay validation service: an offline
certificate verifier (Python) and a stdio-to-remote MCP proxy (Node), plus
runnable examples and the registry manifest for the hosted server.
| Component | Language | Path | What it does |
|---|---|---|---|
| `alphaassay_verify` | Python ≥3.10 | [`alphaassay_verify/`](alphaassay_verify) | Verifies certificates offline: Ed25519 signatures, canonical serialisation, signed key/revocation history. No network access. |
| MCP proxy | Node ≥18 | [`server/`](server) | Bridges a local stdio MCP client to the remote streamable-HTTP endpoint. |
| Examples | — | [`examples/`](examples) | Known-answer request/response pairs you can run against the free demo endpoint. |
| `server.json` | — | [`server.json`](server.json) | Secondary artifact: the manifest the MCP registry reads to describe the hosted server. Not needed to use the code above. |
The validation engine itself is a hosted service and is not part of this
repository.
## Install
Python verifier, from source:
```bash
pip install .
# or, for development
pip install -e ".[dev]"
```
Node proxy:
```bash
npm install
```
## Usage
### Verify a certificate offline
Full platform trust needs three local inputs: the certificate with its
signature, a signed version-2 revocation/key-history bundle, and at least one
externally obtained SHA-256 root fingerprint. The verifier performs no network
or database access.
```bash
python -m alphaassay_verify verify \
--certificate cert.json \
--trust-bundle trust-bundle.json \
--root-fingerprint <64-hex-digest>
```
Signature-only evidence, when you deliberately do not want to establish full
platform trust:
```bash
python -m alphaassay_verify signature-only \
--certificate cert.json \
--public-key key.pem
```
Exit code `0` means verified; a non-zero exit code and a machine-readable
reason mean it is not. See [`SPEC.md`](SPEC.md) for the canonical byte format
and the trust rules the implementation follows.
### Run the MCP proxy
```bash
node server/index.mjs
```
The proxy speaks stdio to your MCP client and forwards to the remote endpoint.
The tool list it exposes is in [`server/tools.json`](server/tools.json).
### Run the examples
Each example is a request payload, the expected response, and a shell script
that posts it to the free demo endpoint:
```bash
cd examples && ./golden_lookahead.sh
```
The expected responses are checked in, so they double as fixtures for
integration tests in your own code.
## Tests
```bash
python -m pytest tests/ # verifier: unit tests and canonical vectors
npm test # proxy: contract and behaviour tests
```
Test vectors live in [`tests/canonical_vectors.json`](tests/canonical_vectors.json)
and [`tests/fixtures/`](tests/fixtures); they are the same vectors the
implementation is developed against.
## Contributing
Issues and pull requests are welcome. Please:
- keep changes focused and include tests for behaviour changes;
- run `python -m pytest tests/` and `npm test` before opening a PR;
- for the verifier, do not add network or database access — offline operation
is a design constraint, not an implementation detail;
- report security issues privately as described in [`SECURITY.md`](SECURITY.md)
rather than in a public issue.
## License
Apache-2.0. See [`LICENSE`](LICENSE).
