# Astray Verify

> Record and replay MCP server contracts in CI.

- **Type:** MCP server
- **Install:** `agentstack add mcp-theastraydev-astray-verify`
- **Verified:** Pending review
- **Seller:** [TheAstrayDev](https://agentstack.voostack.com/s/theastraydev)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TheAstrayDev](https://github.com/TheAstrayDev)
- **Source:** https://github.com/TheAstrayDev/astray-verify

## Install

```sh
agentstack add mcp-theastraydev-astray-verify
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Astray Verify

> Record an MCP server's contract once. Catch breaking changes before your AI clients do.

[](https://github.com/TheAstrayDev/astray-verify/actions/workflows/ci.yml)
[](LICENSE)
[](https://modelcontextprotocol.io/)

An MCP server can still start successfully after a release while an AI client has
quietly lost a tool, received a changed JSON schema, or begun seeing invalid data
on `stdout`. Astray Verify turns the server interface that already works today
into a committed regression test.

It is a tiny, local-first test runner for authors of MCP servers and teams that
maintain them.

## What it does

```text
working MCP server
       │
       ├── astray-verify record
       │       saves the expected tools and schemas
       │
       └── astray-verify test
               fails when a later change breaks that contract
```

In the first release, Astray Verify launches a stdio MCP server, performs the
standard handshake, snapshots `tools/list`, and replays it later. A fixture is
plain JSON, designed to be reviewed and committed with the server source.

## Install

### Linux and macOS

```bash
curl -fsSL https://raw.githubusercontent.com/TheAstrayDev/astray-verify/main/install.sh | sh
```

### Windows PowerShell

```powershell
curl.exe -fsSL https://raw.githubusercontent.com/TheAstrayDev/astray-verify/main/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -
```

The installers download the matching binary from the latest GitHub Release.

### From source

```bash
git clone https://github.com/TheAstrayDev/astray-verify.git
cd astray-verify
cargo install --path .
```

## Quick start

Run these commands inside the repository that contains your MCP server:

```bash
astray-verify init

# Everything after -- is the command that starts your MCP server.
astray-verify record --name filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem ./demo

astray-verify test
```

You will get two files worth committing:

```text
astray.verify.json
fixtures/
  filesystem.mcp.json
```

When an intentional interface change is made, record the fixture again and
review the diff just like any other API change.

## Example

The repository includes a minimal MCP demo server:

```bash
mkdir /tmp/astray-verify-demo && cd /tmp/astray-verify-demo
astray-verify init
astray-verify record --name echo -- \
  python3 /path/to/astray-verify/examples/echo_server.py
astray-verify test
```

Expected result:

```text
PASS  echo
```

## Why not only use the MCP Inspector?

The official MCP Inspector is excellent for exploring and debugging a server
interactively. Astray Verify is for the next step: a small, repeatable check that
runs after every change in local development or CI.

| Inspector | Astray Verify |
| --- | --- |
| Explore and debug now | Preserve what worked for later |
| Interactive | Commit-friendly fixture |
| Individual calls | Regression check in CI |

## Current scope

- Stdio transport
- MCP `initialize` handshake
- `tools/list` contract snapshots
- Strict JSON-RPC stdout validation
- Human-readable failure output

## Roadmap

- [ ] Record and replay `tools/call` fixtures
- [ ] Stable, reviewable JSON diff output
- [ ] GitHub Action
- [ ] Streamable HTTP support
- [ ] Compatibility profiles for major MCP clients

## Contributing

Issues, fixtures from real servers, and focused pull requests are welcome.
Please do not add new transport or client support without a reproducible test
case. The project should stay small, predictable, and useful in CI.

## License

MIT. See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TheAstrayDev](https://github.com/TheAstrayDev)
- **Source:** [TheAstrayDev/astray-verify](https://github.com/TheAstrayDev/astray-verify)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-theastraydev-astray-verify
- Seller: https://agentstack.voostack.com/s/theastraydev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.