Metadata-Version: 2.4
Name: verdictswarm-mcp
Version: 0.2.0
Summary: Every tool has an answer — your agent needs a decision. MCP server for the VerdictSwarm pre-trade check: a machine-readable avoid/caution/clear before your agent trades, plus intended-size exit feasibility and holder-cluster attribution on Solana.
Author-email: Sentien Labs <dev@sentienlabs.com>
License-Expression: MIT
Project-URL: Homepage, https://vswarm.io
Project-URL: Documentation, https://github.com/sentien-labs/verdictswarm-mcp#readme
Project-URL: Repository, https://github.com/sentien-labs/verdictswarm-mcp
Project-URL: Issues, https://github.com/sentien-labs/verdictswarm-mcp/issues
Project-URL: Changelog, https://github.com/sentien-labs/verdictswarm-mcp/blob/main/CHANGELOG.md
Keywords: mcp,crypto,token-scanner,rug-pull,risk-analysis,solana,ethereum,defi,ai-agents,verdictswarm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2,>=1.25.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# VerdictSwarm MCP Server

[![PyPI](https://img.shields.io/pypi/v/verdictswarm-mcp)](https://pypi.org/project/verdictswarm-mcp/)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://github.com/sentien-labs/verdictswarm-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)

VerdictSwarm is a pre-trade security layer for agents that touch crypto. This MCP server exposes the Verdict API v2 as a small set of read-only tools for token checks, size-aware exit screening, and live pricing discovery.

## Quick start

No account setup is required. If `VS_API_KEY` is absent, the server mints a free key on the first API-backed tool call and saves it in the platform user config directory.

```bash
uvx verdictswarm-mcp
```

Then ask your MCP client: “Check `DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263` on Solana at fast level.”

To supply an existing free or credits-backed key:

```bash
VS_API_KEY=vs1_your_key uvx verdictswarm-mcp
```

### Claude Desktop, Cursor, Windsurf, and OpenClaw

Use this server entry (the `env` block is optional):

```json
{
  "mcpServers": {
    "verdictswarm": {
      "command": "uvx",
      "args": ["verdictswarm-mcp"],
      "env": {
        "VS_API_KEY": "vs1_your_key"
      }
    }
  }
}
```

Without `VS_API_KEY`, the self-provisioned key is stored at:

- macOS: `~/Library/Application Support/VerdictSwarm/config.json`
- Linux: `${XDG_CONFIG_HOME:-~/.config}/verdictswarm/config.json`
- Windows: `%APPDATA%\VerdictSwarm\config.json`

The file is created with user-only permissions where the operating system supports them. Set `VS_CONFIG_DIR` to override the directory.

## Tools

| Tool | Description |
|---|---|
| `check_token(address, chain="solana", level="fast")` | Calls `POST /v2/verdict` and returns action, score, summary, and the five strongest signals. Levels are `triage`, `fast`, and `deep`. |
| `exit_sim(address, size_usd, side)` | Requests `include:["exit_sim"]` and returns the fresh Solana exit-simulation block. Side is `buy` or `sell`. |
| `get_pricing()` | Reads live pricing, levels, limits, and supported chains from `GET /v2/verdict/info`. |

The 0.1.x tools `scan_token`, `get_quick_score`, `check_rug_risk`, `get_token_report`, and `verify_payment` remain callable for migration safety, but return a deprecation response and make no legacy pay-lane request.

## Free quota and x402 overflow

Free keys have per-level daily limits advertised by the API. If a limit is exhausted, the tool response says when the quota resets and preserves the complete x402 challenge. To continue immediately, set `VS_API_KEY` to a credits-backed key or use the returned x402 payment instructions.

The MCP client sends these attribution headers on API requests:

- `X-VS-Integration: mcp`
- `X-VS-SDK-Version: 0.2.0`

## Configuration

| Environment variable | Default | Description |
|---|---|---|
| `VS_API_KEY` | unset | Optional free or credits-backed v2 API key. |
| `VS_API_URL` | `https://api.vswarm.io` | VerdictSwarm API base URL. |
| `VS_TIMEOUT` | `120` | HTTP request timeout in seconds. |
| `VS_CONFIG_DIR` | platform user config dir | Directory for the self-provisioned key. |
| `VS_TRANSPORT` | `stdio` | MCP transport. Use `streamable-http` for HTTP. |
| `HOST` | `0.0.0.0` | HTTP bind host. |
| `PORT` | `8000` | HTTP bind port. |

For HTTP transport:

```bash
VS_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uvx verdictswarm-mcp
```

## Programmatic client

```python
import asyncio
from verdictswarm_mcp import VerdictSwarmApiClient

async def main():
    client = VerdictSwarmApiClient()
    verdict = await client.check_token("TOKEN_ADDRESS", "solana", "fast")
    print(verdict["verdict"]["action"], verdict["verdict"]["score"])

asyncio.run(main())
```

## Development

```bash
git clone https://github.com/sentien-labs/verdictswarm-mcp.git
cd verdictswarm-mcp
uv sync --extra dev
uv run --extra dev python -m pytest -q
```

The server supports Python 3.10–3.13 and both stdio and HTTP transports.

## Links

- [VerdictSwarm](https://vswarm.io)
- [API documentation](https://api.vswarm.io/docs)
- [GitHub repository](https://github.com/sentien-labs/verdictswarm-mcp)
- [Security policy](SECURITY.md)

MIT licensed. See [LICENSE](LICENSE).
