@varun-ai07/covenant-mcp 2.1.1 → 2.2.0

package/README.md

@@ -1,91 +1,752 @@
 # COVENANT MCP Server
 
-Model Context Protocol Server for the COVENANT Protocol — 25 blockchain tools for AI agent autonomy.
+Model Context Protocol Server for the COVENANT Protocol — 28 blockchain tools for AI agent autonomy on Base Sepolia L2.
 
-[![MCP](https://img.shields.io/badge/MCP-v1.2.3-6366f1?style=for-the-badge)](https://modelcontextprotocol.io)
-[![Tools](https://img.shields.io/badge/Tools-25-10b981?style=for-the-badge)](https://www.npmjs.com/package/@varun-ai07/covenant-mcp)
+[![MCP](https://img.shields.io/badge/MCP-v2.1.1-6366f1?style=for-the-badge)](https://modelcontextprotocol.io)
+[![Tools](https://img.shields.io/badge/Tools-28-10b981?style=for-the-badge)](https://www.npmjs.com/package/@varun-ai07/covenant-mcp)
 [![Base Sepolia](https://img.shields.io/badge/Base-Sepolia%20L2-0052FF?style=for-the-badge)](https://sepolia.basescan.org)
 
+---
+
 ## Quick Start
 
 ```bash
-# Install
-npm install -g @varun-ai07/covenant-mcp
+npx @varun-ai07/covenant-mcp@latest add
+```
 
-# Add to Claude Code
-npx @varun-ai07/covenant-mcp add
+Restart your AI agent platform. 28 tools are now available.
 
-# Or manually add to claude_desktop_config.json:
-{
-  "mcpServers": {
-    "covenant": {
-      "command": "node",
-      "args": ["/path/to/covenant-mcp/dist/index.js"]
-    }
-  }
-}
+---
+
+## How It Works
+
+1. You talk to your AI agent normally — "Register me as an agent", "Create a task", etc.
+2. The AI calls the right tool in the background — you see nothing
+3. The AI reads the tool's output
+4. The AI presents the result in clean, structured text
+
+**Write operations always show the cost and ask for your approval before spending ETH.**
+
+---
+
+## Examples
+
+These are real prompts you can type in your AI agent platform.
+
+### First Time Setup
+
+```
+You: Register me as an agent called "CodeBot" with capabilities python and code-review
+AI: [calls corven_agent register] → shows cost 0.001 ETH → asks "Proceed?"
+You: Yes
+AI: Done. You're registered. TX: 0x...
 ```
 
-## 25 Tools
-
-Each tool uses `action` parameter for routing:
-
-| Tool | Actions | Description |
-|------|---------|-------------|
-| `corven_agent` | register, get, update, deactivate, stake, find | Agent identity |
-| `corven_task` | create, fund, submit, verify, dispute, get, milestone | Task lifecycle |
-| `corven_market` | post, bid, select, cancel, get, list | Open marketplace |
-| `corven_batch` | create, submit, verify, get, check | Parallel tasks |
-| `corven_collective` | create, join, launch, propose, get | Pool resources |
-| `corven_insurance` | join, premium, claim, vote, get | Insurance pool |
-| `corven_dispute` | file, vote, get, claim_reward | Disputes |
-| `corven_attest` | create, verify, batch, get | Attestations |
-| `corven_stream` | create, withdraw, cancel, get | Streaming payments |
-| `corven_wallet` | create, get, limit, recipient, pause | Smart wallet |
-| `corven_multi` | create, submit, verify, get, tokens | ERC-20 payments |
-| `corven_training` | create, enroll, complete, list, get | Training |
-| `corven_grants` | apply, vote, list, get | Grants |
-| `corven_govern` | create, vote, list, get | Governance |
-| `corven_bounty` | post, claim, winner, list, get | Bounties |
-| `corven_message` | send, list, unread | Messaging |
-| `corven_revision` | request, submit, get, check | Revisions |
-| `corven_reputation` | export, import, did | Reputation VCs |
-| `corven_verify` | deep, capability, reputation, result | Verification |
-| `corven_match` | find, match | Worker matching |
-| `corven_router` | multicall, quickstart | Batch multicall |
-| `corven_stats` | stats, leaderboard | Protocol stats |
-| `corven_fiat` | url, providers | Fiat on-ramp |
-| `corven_upload_ipfs` | (upload content) | IPFS upload |
-| `corven_help` | (protocol guide) | Help |
-
-## Example Usage
+### Find Workers
 
-```json
-// Register an agent
-corven_agent({ action: 'register', name: 'CodeBot', capabilities: ['python', 'data-analysis'] })
+```
+You: Find me the best Python developer for data analysis
+AI: [calls corven_match find] → ranks agents by capability, reputation, success rate
+AI: Top match: Agent 0x1234... (reputation 850, 47 tasks completed, 98% success rate)
+```
+
+### Create and Complete a Task
+
+```
+You: I need someone to build a landing page. Budget 0.05 ETH.
+AI: [calls corven_task create] → shows "Will escrow 0.05 ETH. Proceed?"
+You: Yes
+AI: Task #3 created. TX: 0x...
+
+You: The worker submitted the deliverable, approve it
+AI: [calls corven_task verify task 3] → shows "Will release 0.05 ETH to worker. Proceed?"
+You: Yes
+AI: Payment released. TX: 0x...
+```
+
+### Check Protocol Status
+
+```
+You: Show me the protocol stats
+AI: [calls corven_stats stats]
+AI: 12 agents registered, 47 tasks created, 0.8 ETH total volume
+
+You: Who are the top agents?
+AI: [calls corven_stats leaderboard limit 5]
+AI: #1 Agent 0x5678... — reputation 920, 63 tasks, 0.15 ETH staked
+```
+
+### Verify Worker's Code
+
+```
+You: Verify the code submitted for task 3
+AI: [calls corven_verify deep repoUrl="https://github.com/worker/project"]
+AI: Score: 82/100 (PASS). Build passes, 8 tests pass, no security issues. Approved.
+```
+
+### File a Dispute
+
+```
+You: The work submitted for task 5 is not what I asked for. File a dispute.
+AI: [calls corven_file_dispute taskId 5 bond "0.001"] → shows cost → asks "Proceed?"
+You: Yes
+AI: Dispute filed. Bond: 0.001 ETH. Jurors will vote within 48 hours.
+```
+
+---
+
+## Tools
+
+### corven_agent
+
+Manage AI agent identities on COVENANT.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `register` | Create on-chain identity with name, capabilities, and ETH stake | Stake (default 0.001 ETH) |
+| `get` | Look up agent by address — returns reputation, stake, active status | Free |
+| `list` | List all registered agents on the protocol | Free |
+| `find` | Search agents by capability tag (e.g., "python", "data-analysis") | Free |
+| `update` | Update agent profile (name, capabilities, bio) | Gas only |
+| `deactivate` | Withdraw stake and deactivate agent identity | Gas only |
+| `stake` | Check staking info for an agent | Free |
+
+**Prompts:**
+```
+Register me as an agent
+Show me agent 0x1234...abcd
+List all registered agents
+Find agents with the python capability
+```
+
+---
+
+### corven_task
+
+Manage the full task lifecycle — create, submit, verify, dispute.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Post a new task with escrowed payment for a worker | Payment amount (default 0.01 ETH) |
+| `submit` | Worker submits a deliverable (IPFS CID or GitHub URL) | Gas only |
+| `verify` | Client approves work and releases payment to worker | Gas only |
+| `dispute` | File a dispute on a task (paused payment) | Gas only |
+| `get` | Get task details by ID | Free |
+| `list` | List all tasks | Free |
+| `submit_milestone` | Worker submits a specific milestone deliverable | Gas only |
+| `verify_milestone` | Client approves or rejects a specific milestone | Gas only |
+
+**Workflow:** create → submit → verify
+
+**Prompts:**
+```
+Create a task, pay 0.01 ETH to worker 0x1234...
+Show me task number 3
+List all my tasks
+The worker submitted, approve task 3
+Reject task 5, the work is incomplete
+```
+
+---
+
+### corven_market
+
+Open marketplace for competitive task bidding.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `post` | Post an open task for workers to bid on | Payment amount (default 0.05 ETH) |
+| `bid` | Worker submits a bid with price and proposal | Gas only |
+| `select` | Client selects the winning bidder | Gas only |
+| `get` | Get open task details with all bids | Free |
+| `list` | List open tasks | Free |
+| `cancel` | Cancel an open task | Gas only |
+
+**Prompts:**
+```
+Post an open task, max budget 0.05 ETH
+Show me available tasks
+```
+
+---
+
+### corven_batch
+
+Run multiple tasks in parallel via COVENANT batches. Max 50 workers per batch.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Create a batch of parallel tasks (one per worker) | Total of all payments |
+| `submit` | Worker submits deliverable for a batch subtask | Gas only |
+| `verify` | Finalize batch by aggregating all results | Gas only |
+| `get` | Get batch details or total count | Free |
+| `check` | Check if all subtasks in a batch are submitted | Free |
+
+**Workflow:** create → workers execute → check (all submitted?) → verify (aggregate)
+
+**Prompts:**
+```
+Create a batch of 3 tasks: workers 0xaaa, 0xbbb, 0xccc with 0.01 ETH each
+Show batch number 2
+Are all subtasks in batch 1 submitted yet?
+```
+
+---
+
+### corven_collective
+
+Pool resources with other agents to fund expensive tasks together.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Create a new collective with minimum contribution and max members | Gas only |
+| `join` | Join an existing collective by contributing ETH | Contribution amount |
+| `launch` | Launch a task from pooled collective funds | Payment from pool |
+| `propose` | Submit a governance proposal to the collective | Gas only |
+| `get` | Get collective details or total count | Free |
+
+**Workflow:** create → join (others contribute) → launch (use pooled funds)
+
+**Prompts:**
+```
+Create a collective, min 0.01 ETH, max 5 members
+Join collective 3 with 0.02 ETH
+Launch a task from collective 3, pay 0.05 ETH to worker 0x...
+Show collective 3 details
+```
+
+---
+
+### corven_insurance
+
+Protect against task failures with the COVENANT insurance pool.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `join` | Join the insurance pool | Contribution (min 0.01 ETH) |
+| `premium` | Pay premium for a specific task | Premium (~5% of task payment) |
+| `claim` | File an insurance claim for a failed task | Gas only |
+| `vote` | Governance vote on an insurance claim | Gas only |
+| `get` | Get claim details, pool balance, or coverage info | Free |
+
+**Workflow:** join pool → pay premium per task → if task fails → claim → vote → payout
+
+**Prompts:**
+```
+Join the insurance pool with 0.01 ETH
+Check the insurance pool balance
+File an insurance claim for task 5
+```
+
+---
+
+### corven_file_dispute
+
+File a formal dispute on a task. Requires a bond in ETH. Resolved by juror voting.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `taskId` | number | Task to dispute |
+| `bond` | string | ETH bond (min 0.001 ETH, refunded if you win) |
+| `confirm` | boolean | Set true to execute |
+
+**When to use:** You disagree with a task outcome — either as client (work was substandard) or worker (verification was unfair).
+
+**Prompt:**
+```
+File a dispute on task 5 with a 0.001 ETH bond
+```
+
+---
+
+### corven_cast_vote
+
+Cast your vote on a dispute. True = favor worker, False = favor client.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `disputeId` | number | Dispute to vote on |
+| `inFavorOfWorker` | boolean | True for worker, false for client |
+| `confirm` | boolean | Set true to execute |
+
+**Note:** Voting is commit-reveal — your choice is hidden until voting ends.
+
+**Prompt:**
+```
+Vote in favor of the worker on dispute 2
+```
+
+---
+
+### corven_get_dispute
+
+Get dispute details by ID, or total dispute count if no ID provided.
+
+**Prompt:**
+```
+Show me dispute number 3
+How many disputes are there?
+```
+
+---
+
+### corven_claim_reward
+
+Claim your accumulated juror rewards from resolved disputes. No parameters needed.
+
+**Prompt:**
+```
+Claim my juror rewards
+```
+
+---
+
+### corven_attest
+
+ERC-8004 attestation receipts to prove task completion on-chain.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Issue an attestation receipt | Gas only |
+| `verify` | Verify a specific receipt by ID | Free |
+| `batch` | List all receipts for an address | Free |
+| `get` | Get receipt count for an address | Free |
+
+**Receipt Types:** 0=TaskCompleted, 1=AgentVerified, 2=CapabilityProven, 3=ReputationVerified, 4=DisputeResolved, 5=InsuranceClaimed
+
+**Prompts:**
+```
+Create a task completion receipt for agent 0x1234...
+Show all receipts for agent 0x5678...
+```
+
+---
+
+### corven_stream
+
+Pay-per-second streaming payments for ongoing work. Accrues linearly.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Create a streaming payment | Total payment upfront |
+| `withdraw` | Worker withdraws accrued amount | Gas only |
+| `cancel` | Cancel stream and refund remaining | Gas only |
+| `get` | Get stream details and progress | Free |
+
+**Prompts:**
+```
+Create a payment stream of 0.0001 ETH/second to worker 0x... for 1 hour
+How much has stream 1 accrued?
+Cancel stream 2
+```
+
+---
+
+### corven_wallet
+
+Programmable ERC-4337 smart wallet with spending limits and whitelists.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Deploy a new smart wallet | Gas only |
+| `get` | Get wallet details and limits | Free |
+| `limit` | Set daily and per-transaction spending limits | Gas only |
+| `recipient` | Manage recipient whitelist | Gas only |
+| `pause` | Emergency pause/unpause the wallet | Gas only |
+
+**Workflow:** create → limit (set guardrails) → recipient (whitelist targets) → agent executes within limits
+
+**Prompts:**
+```
+Create a smart wallet, daily limit 1 ETH, per-tx limit 0.1 ETH
+Show wallet 0xabcd... details
+Set the daily limit to 0.5 ETH on wallet 0xabcd...
+Pause wallet 0xabcd...
+```
 
-// Create a task
-corven_task({ action: 'create', worker: '0x...', payment: '0.01', descriptionHash: 'Qm...' })
+---
 
-// Submit work
-corven_task({ action: 'submit', taskId: 1, deliverableHash: 'QmDelivered' })
+### corven_multi
+
+ERC-20 token escrow for task payments. Pay with USDC, DAI, USDT instead of ETH.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Create and fund a task with ERC-20 tokens | Token amount |
+| `submit` | Worker submits deliverable hash | Gas only |
+| `verify` | Client verifies and releases ERC-20 payment | Gas only |
+| `get` | Get task details from MultiTokenEscrow | Free |
+| `tokens` | List accepted ERC-20 tokens | Free |
+
+**Workflow:** ERC-20 approve() → create → worker does work → submit → verify
+
+**Prompts:**
+```
+What ERC-20 tokens can I use to pay?
+Create a task paying 100 USDC to worker 0x...
+```
+
+---
+
+### corven_training
+
+Create and sell agent training programs. 2.5% platform fee.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Create a training program | Gas only |
+| `enroll` | Enroll in a training program | Training price |
+| `complete` | Mark training as completed | Gas only |
+| `list` | List available training programs | Free |
+| `get` | Get training program details by ID | Free |
+
+**Workflow:** create → enroll → complete → earn capabilities
+
+**Prompts:**
+```
+Create a training program called "Solidity Security", price 0.01 ETH
+List available training programs
+Enroll in training 2
+```
+
+---
+
+### corven_grants
+
+DAO-funded grants for agent development. Apply, vote, fund.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `apply` | Submit a grant application | Gas only |
+| `vote` | Vote on a grant application | Gas only |
+| `list` | List grant applications | Free |
+| `get` | Get grant details by ID | Free |
+
+**Categories:** ecosystem_growth, research, community, security
+
+**Prompts:**
+```
+Apply for a research grant, 1 ETH, for AI safety research
+Vote yes on grant 3
+Show me all grant applications
+```
+
+---
+
+### corven_govern
+
+Protocol governance. Create proposals, vote, shape the future.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `create` | Create a governance proposal | Gas only |
+| `vote` | Vote on a proposal | Gas only |
+| `list` | List governance proposals | Free |
+| `get` | Get proposal details by ID | Free |
+
+**Types:** parameter_change, feature_addition, treasury_spend, emergency_action
+
+**Note:** Voting weight = agent reputation (0-1000).
+
+**Prompts:**
+```
+Create a proposal to reduce the protocol fee to 0.5%
+Vote in favor of proposal 2
+Show all governance proposals
+```
+
+---
+
+### corven_bounty
+
+Post bounties for specific tasks. Workers claim and compete.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `post` | Post a bounty with reward | Reward amount |
+| `claim` | Submit work to claim a bounty | Gas only |
+| `winner` | Select the winning submission | Gas only |
+| `list` | List available bounties | Free |
+| `get` | Get bounty details by ID | Free |
+
+**Workflow:** post → claim (workers submit) → winner (creator picks)
+
+**Prompts:**
+```
+Post a bounty for a landing page, reward 0.1 ETH
+Show available bounties
+Select the winner for bounty 3
+```
+
+---
+
+### corven_message
+
+Agent-to-agent messaging. Send messages, check inbox.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `send` | Send a message to another agent | Free (in-memory) |
+| `list` | List messages for a task | Free |
+| `unread` | Get unread message count | Free |
+
+**Note:** In-memory MVP. Messages persist for the MCP session lifetime.
+
+**Prompts:**
+```
+Send a message to agent 0x1234... about task 5: "Can you start the data pipeline?"
+Check my messages for task 5
+How many unread messages do I have?
+```
+
+---
+
+### corven_revision
+
+Request revisions on deliverables. Track revision history. Max 3 revisions per task.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `request` | Client requests changes | Free (no ETH) |
+| `submit` | Worker submits revised work | Free (no ETH) |
+| `get` | Get revision history | Free |
+| `check` | Check if revisions are allowed | Free |
+
+**Workflow:** request → submit → check → approve or request again
+
+**Prompts:**
+```
+Request a revision on task 3: "Add error handling to the API layer"
+Submit revised code for task 3
+Show revision history for task 3
+Can I still request revisions on task 2?
+```
+
+---
+
+### corven_reputation
+
+Portable reputation credentials. Export W3C Verifiable Credentials.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `export` | Export reputation as W3C VC JWT | Free |
+| `import` | Verify and parse a reputation VC | Free |
+| `did` | Get DID document for an agent | Free |
+
+**Workflow:** export → share JWT → import (cross-platform trust)
+
+**Prompts:**
+```
+Export my reputation credentials
+Show the DID document for agent 0x5678...
+```
+
+---
+
+### corven_verify
+
+Automatic verification of worker deliverables. Background auto-verifier handles most cases.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `deep` | Run full verification: clone repo + static analysis + score (0-100) | Free |
+| `pending` | Check what tasks need verification (Submitted status) | Free |
+| `status` | Show auto-verifier system status | Free |
+| `capability` | Verify agent has specific capability | Free |
+| `reputation` | Verify agent reputation meets threshold | Free |
+| `result` | Get verification result by evidence hash | Free |
+
+**How it works (automatic):**
+1. Worker submits → Event detected → Repo cloned → 5 checks run → Score 0-100
+2. Score ≥ 70: Auto-approve → Worker paid
+3. Score < 40: Auto-reject → Disputeable
+4. Score 40-69: Flagged for your AI to review
+
+**What it checks:** build status, test coverage, security (eval, innerHTML, SQL injection), secrets (hardcoded keys, .env files), code quality (LOC, TODOs, any types)
+
+**Prompts:**
+```
+Verify the code submitted for task 3
+Show the auto-verifier status
+Are there any tasks waiting for verification?
+```
+
+---
+
+### corven_match
+
+Find the best workers for your task using multi-factor scoring.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `find` | Discover and rank agents by capability match, success rate, price, reputation | Free |
+| `match` | Get a detailed match score for a specific worker | Free |
+
+**Scoring:** capability_match (30%) + success_rate (20%) + price_competitiveness (15%) + reputation (55%)
+
+**Prompts:**
+```
+Find the best Python developer for data analysis
+Match agent 0x1234... against my requirements: python, data-analysis
+```
+
+---
+
+### corven_router
+
+Batch multiple contract calls in one transaction via COVENANTRouter. Up to 10 calls per batch.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `multicall` | Execute 2-10 contract calls atomically | Sum of all call values |
+| `quickstart` | Register as agent AND create a task in one transaction | Stake + payment |
+
+**Prompts:**
+```
+Register me as an agent and create a task in one transaction
+```
+
+---
+
+### corven_stats
+
+Get aggregate COVENANT protocol health metrics.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `stats` | Total agents, tasks created, total volume (ETH), fees collected | Free |
+| `leaderboard` | Top N agents ranked by reputation | Free |
+
+**Prompts:**
+```
+Show me protocol stats
+Who are the top 10 agents?
+```
+
+---
+
+### corven_fiat
+
+Buy crypto with fiat currency to use on COVENANT. Lists on-ramp providers.
+
+| Action | What It Does | Cost |
+|--------|-------------|------|
+| `url` | Get a direct purchase URL for a specific amount | Free |
+| `providers` | List all supported on-ramp providers | Free |
+
+**Providers:** MoonPay (~4.5%), Transak (~3.5%), Stripe Onramp (~1.5%)
+
+**Prompts:**
+```
+How can I buy Base Sepolia ETH?
+Get me a link to buy $50 worth
+```
+
+---
+
+### corven_upload_ipfs
+
+Upload content to IPFS via Pinata. Returns a CID for tasks and deliverables.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `content` | string | Content to upload (text, JSON, or base64) |
+| `name` | string | Filename for the upload (optional) |
+| `type` | string | "text", "json", or "base64" (default "text") |
+
+**Requires:** PINATA_API_KEY and PINATA_SECRET_KEY in environment.
+
+**Prompt:**
+```
+Upload this task description to IPFS: {"task": "build page", "requirements": "responsive"}
+```
+
+---
+
+### corven_help
+
+Complete guide to all 28 COVENANT tools. Returns workflows, tool reference, and format rules.
+
+**Prompt:**
+```
+How does COVENANT work?
+```
+
+---
+
+## Safety Features
+
+Every tool that spends ETH has a **confirmation gate**. Without `confirm: true`, the tool returns a cost summary and asks for your permission.
 
-// Verify and pay
-corven_task({ action: 'verify', taskId: 1, success: true })
 ```
+You: Create a task, pay 0.05 ETH
+AI:   [calls corven_task create] → shows "CONFIRMATION REQUIRED. Cost: 0.05 ETH. Payment locked in escrow."
+AI:   "This will create a task and escrow 0.05 ETH. Should I proceed?"
+You:  "Yes"
+AI:   [calls corven_task create confirm=true] → executes transaction
+AI:   "Done. Task created. TX: 0x..."
+```
+
+**Security layers:**
+- Balance check before every transaction
+- Gas estimation with 20% buffer
+- Spending cap (0.1 ETH per session, configurable via SPENDING_LIMIT env var)
+- Chain validation (Base Sepolia only)
+- Write rate limit (1 per 5 seconds)
+- Confirmation required for all writes
+
+---
 
 ## V5 Contracts (Base Sepolia)
 
-All tools use V5 contract addresses. Config maps V1 tool names to V5 addresses automatically.
+| Contract | Address | Purpose |
+|----------|---------|---------|
+| CovenantIdentity | `0x694a9bD525288A8Faa5b795f861626ae6A10b68c` | Agent registration, stake, reputation |
+| CovenantEscrow | `0xc9C113A766a4311B6Ebd129a2f88f5BCC5a5B9aa` | Task payments, escrow |
+| CovenantSettlement | `0x1FbD8465cF79435Ea1C12AAcA25f83468e268816` | Streaming payments, receipts |
+| CovenantArbitration | `0x84FE876aC91f4e1FA9c7DbeaFf9299500812933D` | Dispute resolution |
+| CovenantAttestation | `0x0F5B060D7Eab7a2c65628CC81174958c19db91bF` | Verifiable credentials |
+| CovenantGovernance | `0xED595Cbe2ffe2B6836A290497Bf9c0A1B2cfc29f` | DAO proposals and voting |
+| TrainingMarketplace | `0xEC62BF280c9A5D0e492952258c38C186F3467C2a` | Agent training programs |
+| GrantProgram | `0xe625F5e90901197c560b7d213D5EA81dC96E3CEE` | DAO-funded grants |
+| InsurancePool | `0x6BA6971b06Acd7000AF12168ba2529Bc20E7802A` | Insurance against task failures |
+| RevisionManager | `0x3A1B5c762Fd0a38e708cC9F835AA144F62056d76` | Work revision tracking |
 
-## Development
+---
+
+## Installation
 
 ```bash
-npm install
-npm run build
-npm start
+npx @varun-ai07/covenant-mcp@latest add
 ```
 
+Or add manually to your platform's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "covenant": {
+      "command": "npx",
+      "args": ["-y", "@varun-ai07/covenant-mcp@latest", "server"]
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PRIVATE_KEY` | Only for writes | — | Wallet private key |
+| `BASE_SEPOLIA_RPC_URL` | No | `https://sepolia.base.org` | RPC endpoint |
+| `SPENDING_LIMIT` | No | `0.1` | Max ETH per session |
+| `MCP_API_KEY` | No | — | HTTP mode authentication |
+| `PINATA_API_KEY` | Only for IPFS | — | Pinata API key |
+| `PINATA_SECRET_KEY` | Only for IPFS | — | Pinata secret key |
+
+---
+
 ## License
 
 MIT