# Alter MCP Server - AI Agent Skill Instructions

🤖 **Hello AI Agent!** 
If you are reading this file, you have been tasked with installing, configuring, or using the Alter MCP server.
Alter is an open, privacy-first, zero-tracking multi-chain EVM intelligence tool that qualifies EVM addresses and reconstructs their asset and movement history. Whether you are an AI assistant in an IDE (Cursor, Windsurf), a conversational desktop workspace (Claude Desktop, Claude Cowork), or a web interface (ChatGPT with MCP / custom actions), Alter equips you with structured on-chain verification capabilities without managing individual RPC endpoints. On request, it translates that history into the accounting or tax language of a user-selected jurisdiction, linking facts both to cryptographic proofs and to normative sources.

This file gives you all the context you need to orchestrate Alter autonomously.

## 1. Installation

Alter provides two binaries: `alter-cli` (for humans) and `alter-mcp` (for you).
Depending on the user's OS, install it using the following methods:

**macOS / Linux (via Homebrew):**
```bash
brew install VISIALIS/alter/alter
```

**macOS / Linux (via installer script):**
```bash
curl -fsSL https://www.alter-evm.com/install.sh | bash
```
*(Binaries will be installed to `/usr/local/bin` or `~/.local/bin`)*

**Windows:**
Download the latest `.exe` binaries directly from the GitHub releases page: `https://github.com/VISIALIS/alter/releases`

## 2. MCP Client Configuration

To connect the user's environment (Claude Desktop, Claude Cowork, ChatGPT MCP, Cursor, Windsurf, etc.) to the Alter MCP server, append this block to their MCP configuration file (e.g. `claude_desktop_config.json`, `.mcp.json` or client settings):

```json
{
  "mcpServers": {
    "alter": {
      "command": "alter-mcp",
      "args": []
    }
  }
}
```

**CRITICAL NOTE FOR CLAUDE DESKTOP & COWORK:** 
Claude Desktop and Cowork require absolute paths for the command. If installed via Homebrew on macOS (ARM64), use `/opt/homebrew/bin/alter-mcp`. If installed via the script, find the path (e.g., `/Users/username/.local/bin/alter-mcp`) and use it in the `"command"` field.

## 3. How to use it

Once the MCP server is initialized, you have access to typed, discoverable tools. Each result stays linked to its on-chain proof, and limits are explicit. The main tool families:

- **Address portrait & context:** `address.inspect` (type, roles, capabilities and their on-chain proof source), `address.contexts`, `address.balance`, `address.portfolio`, `address.position`, `address.transfers`, `address.allowances`, `address.approvals`.
- **Classified activity statement:** `address.statement` produces a closed-period audit/control statement with qualified movements, wallet-perspective lines, reconciliation, evidence, confidence, and explicit limits. It is not a final accounting entry, tax calculation, filing, or professional opinion.
- **Token economics:** `address.concentration` (full holder list, not a capped sample), `address.check_kyc_batch`, `address.lending_risk_score`, `address.lending_apy_history`.
- **Transactions:** `transaction.inspect` (classifies every address involved, not only the main one), `transaction.simulate_transfer`.
- **Lending & markets:** `lending.pool_snapshot`, `lending.positions_batch`, `lending.spread` (primary vs secondary market spread), `lending.events`, `orderbook.orders`.
- **Chains & RPC:** `chain.list`, `chain.inspect`, `chain.search`, `chain.rpc`, `chain.rpc_batch` (Alter routes to the RPC endpoints you configure).
- **Analytics & observability:** `analytics.snapshot`, `observability.quality_report`, `observability.anomalies`, `observability.diagnostics`.

Guidance:
- **Always rely on on-chain data:** Alter pulls verifiable data from public RPC nodes. You do not manage RPC URLs or API keys yourself.
- **Proof vs heuristic:** Alter always separates on-chain proof from presentation heuristics — surface that distinction to the user rather than flattening it.
- **Professional translation:** Translate the qualified asset and movement history only for an explicitly requested jurisdiction and supplied context. Do not infer a jurisdiction, regime, or universal treatment from a token contract or transaction hash.
- **Dual proof:** Every translated item must retain links to the on-chain evidence establishing the fact and to the versioned regulatory or accounting source supporting the professional term.
- **Strict boundary:** Alter stops at this sourced translation. Never present its output as a final journal entry, tax-base or tax-due calculation, regime selection, filing, advice, certification, or recommendation.
- **Current coverage:** Structured jurisdictional translation and regulatory-source links are not yet exhaustive. Preserve `unclassified`, `undetermined`, confidence, evidence, and limitation states rather than filling gaps.
- **Multichain by default:** Alter resolves addresses across multiple EVM chains automatically.
- **Proxies & ABIs:** If an address is a proxy (like an ERC-1967), Alter resolves the underlying implementation for you.
- **Not delivered yet:** autonomous purchase/execution in crypto-assets (ADR-0106) is a product goal currently under development, not a shipped capability — never present it as available.

## 4. Issues & Support

If you or the user encounter a bug, a missing feature, or unexpected behavior with Alter:
1. You are encouraged to create an issue on the GitHub repository: `VISIALIS/alter`.
2. **IMPORTANT**: Before submitting a new issue, use your GitHub or web tools to search the existing issues at `https://github.com/VISIALIS/alter/issues` to ensure it hasn't already been reported.

You are fully equipped to assist the user. Good luck!