# tezos-mcp

RAG-powered MCP server for Tezos protocol specs, TZIPs, and Octez source code.

## What It Does

Indexes and searches across:
- [Octez Protocol](https://gitlab.com/tezos/tezos) - OCaml protocol implementations (`src/proto_*/lib_protocol/`)
- [Octez Node](https://gitlab.com/tezos/tezos) - Shell architecture, RPC specs, P2P, storage (`src/`, `docs/`)
- [TZIPs](https://gitlab.com/tezos/tzip) - Tezos Improvement Proposals (FA2, metadata, wallet standards)

## Installation

```bash
# From PyPI
pip install tezos-mcp

# From source
pip install -e .

# With Voyage API embeddings (best quality)
pip install -e ".[voyage]"

# With tree-sitter OCaml parsing
pip install -e ".[ocaml]"
```

## Quick Start

```bash
# Build the index (downloads repos + creates embeddings)
tezos-mcp build

# Search
tezos-mcp search "FA2 token standard"

# Check status
tezos-mcp status
```

## Features

### Incremental Indexing

Only re-embeds changed files instead of rebuilding the entire index. Reduces update time from minutes to seconds.

```bash
# Update repos and incrementally re-index (fast!)
tezos-mcp update

# Incremental index (default behavior)
tezos-mcp index

# Force full rebuild
tezos-mcp index --full
```

**How it works:**
1. Tracks file hashes and modification times in a manifest
2. Detects which files changed since last index
3. Only re-embeds the changed content
4. Updates LanceDB incrementally (add/delete operations)

### Configurable Embedding Models

Choose from multiple embedding models based on your quality/speed tradeoff:

```bash
# List available models
tezos-mcp models

# Use a specific model
tezos-mcp index --model codesage/codesage-large
```

| Model | Dims | Quality | Speed | Notes |
|-------|------|---------|-------|-------|
| `all-MiniLM-L6-v2` | 384 | Fair | Fast | Default, good for quick searches |
| `all-mpnet-base-v2` | 768 | Good | Medium | Better quality |
| `codesage/codesage-large` | 1024 | Good | Medium | Code-specialized |
| `voyage:voyage-code-3` | 1024 | Excellent | API | Best quality, requires API key |

Configure in `~/.tezos-mcp/config.yaml`:

```yaml
embedding_model: all-MiniLM-L6-v2
chunk_size: 1000
chunk_overlap: 200
protocol_depth: 3  # Number of past protocols to index
```

### Expert Guidance

Curated knowledge beyond what's in the code:

```bash
# Via MCP tool
tez_expert_guidance("baking")
tez_expert_guidance("governance")
tez_expert_guidance("smart_rollups")
```

Topics include: `baking`, `delegation`, `staking`, `tenderbake`, `governance`, `smart_rollups`, `dal`, `michelson`, `fa2`, `adaptive_issuance`, `slashing`

## CLI Commands

```bash
# Full build pipeline
tezos-mcp build                       # Download + compile + index
tezos-mcp build --full                # Force full rebuild

# Individual steps
tezos-mcp download                    # Clone octez + tzip repos
tezos-mcp compile                     # Parse OCaml/markdown into JSON
tezos-mcp index                       # Build vector embeddings
tezos-mcp index --full                # Force full rebuild
tezos-mcp index --model MODEL         # Use specific embedding model

# Update (git pull + incremental index)
tezos-mcp update
tezos-mcp update --full               # Update + force rebuild

# Search
tezos-mcp search "stake delegation"
tezos-mcp search "tenderbake consensus" --protocol paris
tezos-mcp search "FA2 transfer" --limit 10

# Lookup
tezos-mcp constant max_operations_ttl
tezos-mcp function apply_operation

# Info
tezos-mcp status                      # Index status, manifest info
tezos-mcp models                      # List embedding models
tezos-mcp serve                       # Start MCP server
```

## MCP Tools

When running as an MCP server:

| Tool | Purpose |
|------|---------|
| `tez_search` | Semantic search across all indexed content |
| `tez_search_tzip` | Search TZIP standards (FA2, metadata, wallet specs) |
| `tez_search_protocol` | Search protocol specs and OCaml source |
| `tez_search_octez` | Search Octez node docs and source code |
| `tez_grep_constant` | Fast OCaml constant lookup |
| `tez_analyze_function` | Get OCaml function source code |
| `tez_get_current_protocol` | Current mainnet protocol (Tallinn) |
| `tez_list_protocols` | Full amendment history (Athens through Tallinn) |
| `tez_expert_guidance` | Curated guidance on Tezos topics |

## Protocol Amendments

Tezos upgrades through on-chain governance. The index covers the full amendment history:

| Protocol | Date | Notable Features |
|----------|------|------------------|
| Athens | 2019-05 | First amendment |
| Ithaca | 2022-03 | Tenderbake consensus |
| Mumbai | 2023-03 | Smart rollups |
| Paris | 2024-06 | Adaptive issuance, staking |
| Quebec | 2025-02 | Universal baker attestation |
| Tallinn | 2026-01 | 6s block time |

## Project Structure

```
src/tezos_mcp/
├── server.py               # MCP server (FastMCP)
├── cli.py                  # CLI commands (Click)
├── config.py               # Configuration management
├── models.py               # Pydantic input validation
├── protocols.py            # Protocol amendment history
├── logging.py              # Structured logging
├── indexer/
│   ├── downloader.py       # Git clone with sparse checkout
│   ├── compiler.py         # Markdown/RST extraction
│   ├── ocaml_compiler.py   # OCaml parsing (tree-sitter + regex)
│   ├── chunker.py          # Document chunking + chunk IDs
│   ├── embedder.py         # Embeddings + LanceDB + incremental
│   └── manifest.py         # File tracking for incremental updates
└── expert/
    └── guidance.py         # Curated expert knowledge
```

## Data Location

```
~/.tezos-mcp/
├── config.yaml             # Configuration (optional)
├── manifest.json           # Index state tracking
├── repos/
│   ├── tezos/              # Octez protocol + node (sparse checkout)
│   └── tzip/               # TZIP standards (full clone)
├── compiled/               # Extracted JSON specs
│   ├── tzips/
│   └── octez_docs/
└── lancedb/                # Vector index
```

## Expert Guidance Topics

The `tez_expert_guidance` tool provides curated knowledge on:

**Consensus & Baking:**
- `baking` - Block production, endorsing, rights
- `delegation` - Delegating to bakers, rewards
- `staking` - Direct staking (Paris+), frozen deposits
- `tenderbake` - Deterministic finality consensus
- `slashing` - Double-baking/endorsing penalties

**Governance & Standards:**
- `governance` - On-chain amendment process
- `fa2` - FA2 token standard (TZIP-012)
- `michelson` - Smart contract language

**Scaling & Data:**
- `smart_rollups` - L2 scaling (WASM rollups)
- `dal` - Data Availability Layer
- `adaptive_issuance` - Dynamic reward adjustment

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=tezos_mcp

# Lint
ruff check src/
```

## Running as MCP Server

```bash
# Start the server
tezos-mcp serve
```

Add to your Claude Code MCP configuration:

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

## License

MIT