# 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 a privacy-first, zero-tracking tool that qualifies EVM addresses and reconstructs their asset and movement history. On request, it translates that history into the accounting or tax language of a user-selected jurisdiction. Each translated item links both to its on-chain evidence and to the regulatory or accounting source used.

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, Cursor, Windsurf, etc.) to the Alter MCP server, append this block to their MCP configuration file (e.g. `claude_desktop_config.json` or `.mcp.json`):

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

**CRITICAL NOTE FOR CLAUDE DESKTOP:** 
Claude Desktop requires 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 is a product goal, 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!