Chuk Lazarus

Mechanistic interpretability MCP server wrapping chuk-lazarus.

Load any model, extract activations, train probes, steer generation, and ablate components -- all via MCP tools that Claude (or any MCP client) can call autonomously.

Quick Start

# Clone and install
git clone https://github.com/chuk-ai/chuk-mcp-lazarus.git
cd chuk-mcp-lazarus
uv sync

# Run the smoke test (53 tests on SmolLM2-135M, ~3 seconds)
uv run python examples/smoke_test.py

# Run the full 15-step language transition demo
uv run python examples/language_transition_demo.py

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "lazarus": {
      "command": "uv",
      "args": ["run", "chuk-mcp-lazarus", "stdio"],
      "cwd": "/path/to/chuk-mcp-lazarus"
    }
  }
}

Tools (64)

Resources (4)

Supported Models

Works with any model chuk-lazarus supports:

• Gemma -- Gemma 3 (270M--27B), TranslateGemma 4B/12B
• Llama -- Llama 2/3, Mistral, SmolLM2
• Qwen -- Qwen 2/3
• Granite -- IBM Granite 3.x/4.x (hybrid Mamba-2/Transformer)
• Jamba -- AI21 Jamba (hybrid Mamba-Transformer MoE)
• Mamba -- Pure SSM models
• StarCoder2 -- Code generation
• GPT-2 -- GPT-2 and compatible

Default demo target: TranslateGemma 4B (34 layers, fits on Apple Silicon). Smoke tests use SmolLM2-135M for speed.

Demos

The Demo: Language Transition Probing

The flagship experiment follows a 15-step workflow:

1. Load model -- load_model("google/gemma-3-4b-it")
2. Inspect architecture -- get_model_info() reveals 34 layers
3. Tokenize -- see how the prompt breaks into tokens
4. Generate text -- see baseline model output
5. Sanity-check activations -- verify activations are non-trivial
6. Compare at early layer -- language representations are distinct
7. Compare at late layer -- representations converge
8. Logit lens -- see how predictions evolve through layers
9. Track token -- watch a specific token's probability rise across layers
10. Scan probes across layers -- find where language identity becomes decodable
11. Evaluate best probe -- confirm on held-out data
12. Compute steering vector -- French-to-German direction
13. Steer generation -- redirect a French translation to German
14. Alpha sweep -- iterate with different steering strengths
15. Causal tracing -- prove which layers are necessary for the prediction

Run it: uv run python examples/language_transition_demo.py

The Demo: Model Comparison

Compare a base model against its fine-tuned variant. First see actual output differences with compare_generations, then find where fine-tuning changed weights, activations, and attention patterns. Designed for Gemma 3 4B vs TranslateGemma 4B using low-resource languages (Icelandic, Swahili, Estonian, Marathi) where TranslateGemma shows 25-30% improvement

Run it: uv run python examples/comparison_demo.py

Architecture

See ARCHITECTURE.md for the 10 design principles.

Key points:

• Async-native -- all tools are async def, CPU-bound work wrapped in asyncio.to_thread
• Pydantic-native -- every data structure is a typed BaseModel
• Model-agnostic -- works with 9+ model families
• Error envelopes -- tools never raise; always return structured errors
• JSON-safe boundary -- MLX arrays converted at the tool return

Project Structure

src/chuk_mcp_lazarus/
├── server.py            # ChukMCPServer instance
├── main.py              # Entry point (stdio / http)
├── model_state.py       # ModelState singleton
├── probe_store.py       # ProbeRegistry singleton
├── steering_store.py    # SteeringVectorRegistry singleton
├── comparison_state.py  # ComparisonState singleton (2nd model)
├── experiment_store.py  # ExperimentStore singleton
├── subspace_registry.py # SubspaceRegistry singleton
├── dark_table_registry.py # DarkTableRegistry singleton
├── resources.py         # MCP resources (4 resources)
├── errors.py            # Error types + envelope helper (17 error types)
├── _bootstrap.py        # Optional dependency stubs
├── _serialize.py        # MLX/NumPy -> JSON-safe
├── _generate.py         # Shared text generation
├── _compare.py          # Shared comparison kernels
├── _extraction.py       # Shared activation extraction
├── _residual_helpers.py # Shared residual-stream helpers
└── tools/
    ├── model/               # load_model, get_model_info
    ├── generation/          # generate_text, predict_next_token, tokenize,
    │                        #   logit_lens, track_token, track_race, embedding_neighbors
    ├── activation/          # extract_activations, compare_activations
    ├── attention/           # attention_pattern, attention_heads
    ├── residual/            # residual_decomposition, layer_clustering,
    │                        #   logit_attribution, head_attribution, top_neurons
    ├── neuron/              # discover_neurons, analyze_neuron, neuron_trace
    ├── probe/               # train_probe, evaluate_probe, scan_probe_across_layers,
    │                        #   probe_at_inference, list_probes
    ├── steering/            # compute_steering_vector, steer_and_generate,
    │                        #   list_steering_vectors, extract_direction
    ├── causal/              # trace_token, full_causal_trace,
    │                        #   ablate_layers, patch_activations
    ├── comparison/          # load_comparison_model, compare_weights,
    │                        #   compare_representations, compare_attention,
    │                        #   compare_generations, unload_comparison_model
    ├── attribution/         # attribution_sweep
    ├── intervention/        # component_intervention
    ├── experiment/          # create_experiment, add_experiment_result,
    │                        #   get_experiment, list_experiments
    └── geometry/            # Geometry tools (per-tool subpackage, 18+ tools)
        ├── _helpers.py          # Shared enums, math, direction extraction
        ├── _injection_helpers.py # Shared injection/generation helpers
        └── (one .py per tool)

Development

# Install with dev dependencies
uv sync --extra dev

# Run smoke tests
uv run python examples/smoke_test.py

# Run with a different model
uv run python examples/smoke_test.py --model TinyLlama/TinyLlama-1.1B-Chat-v1.0

# HTTP mode for development
uv run chuk-mcp-lazarus http --port 8765

Requirements

• Python >= 3.11
• Apple Silicon Mac (for MLX)
• chuk-lazarus >= 0.4
• chuk-mcp-server >= 0.25

License

Apache 2.0