Averray MCP server

Polkadot Agent Platform

This repository contains a greenfield implementation of an agent-first treasury and job runtime:

• Foundry contracts for account, escrow, policy, strategy registry, and reputation
• A shared service layer exposed through HTTP and directory-safe MCP discovery
• Discovery and indexing scaffolds for later hosted deployment

Launch posture and trust documents:

• Production readiness checklist
• Threat model
• No token statement
• Week-12 bootstrap gate
• Product-proof gate
• Arbitration migration
• Dispute reason-code registry
• Service token operator pack

The mcp-server workspace currently uses a JavaScript runtime source tree. There is no parallel TypeScript build step to maintain.

Development setup

After cloning, install the git hooks once so staged commits are scanned for accidentally-staged .env files and private-key-shaped strings:

./scripts/install-hooks.sh

Run the full test matrix locally:

npm test               # backend + frontend + forge
npm run typecheck:indexer

CI runs the same four jobs on every push to main and every PR via .github/workflows/ci.yml.

Multi-agent branch start

Before any agent starts new work, create its branch through the guarded helper:

./scripts/ops/start-agent-branch.sh codex/your-task-name

The helper fetches origin, switches local main to the latest origin/main, fast-forwards only, then creates the new branch. This keeps each agent from starting work on a stale local main.

Local deployment flow

1. Start a local Anvil chain:

./scripts/start_anvil.sh

1. In another terminal, deploy and configure the contract suite:

./scripts/deploy_contracts.sh

1. Export the addresses returned by the deploy script and write a server env file:

export AGENT_ACCOUNT_ADDRESS=0x...
export ESCROW_CORE_ADDRESS=0x...
export REPUTATION_SBT_ADDRESS=0x...
export DISCOVERY_REGISTRY_ADDRESS=0x...
export TREASURY_POLICY_ADDRESS=0x...
export MOCK_DOT_ADDRESS=0x...
./scripts/write_server_env.sh

1. Start the service:

cd mcp-server
set -a
source .env.local
set +a
npm run start:http

The HTTP adapter will use live on-chain reads and signed writes whenever the env file contains a valid RPC URL, signer key, and deployed contract addresses.

The live API now also exposes a push-only SSE stream at /events behind the app proxy as /api/events.

If you want durable sessions and verifier results, also set:

REDIS_URL=redis://...
REDIS_NAMESPACE=agent-platform

Without REDIS_URL, the service falls back to in-memory state for local development.

Pimlico / ERC-4337 gas sponsorship

The hosted API can now expose a minimal Pimlico-backed gas sponsorship surface when these env vars are set:

PIMLICO_BUNDLER_URL=https://...
PIMLICO_PAYMASTER_URL=https://...
PIMLICO_ENTRY_POINT=0x...
PIMLICO_SPONSORSHIP_POLICY_ID=...
PIMLICO_CHAIN_ID=...

Once configured, the HTTP server exposes:

• GET /gas/health
• GET /gas/capabilities
• POST /gas/quote
• POST /gas/sponsor

These endpoints are intended for ERC-4337 user operation quoting and sponsorship. They do not replace the current direct signer flow yet; they add the hosted gas-management path so the platform can evolve toward smart-account execution.

To verify Redis-backed resumability across separate runtimes:

cd mcp-server
set -a
source .env.local
export REDIS_URL=redis://...
set +a
npm run check:redis

That check creates a session in one runtime, verifies it, then loads the same session/result through a second runtime to prove persistence.

End-to-end local demo

With Anvil running and mcp-server/.env.local populated, run:

Shortened. The full README is on GitHub.