chuk-mcp-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 (55 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)
├── dark_table_registry.py # DarkTableRegistry singleton (precomputed coordinates)
├── 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
└── tools/
    ├── model_tools.py       # load_model, get_model_info
    ├── generation_tools.py    # generate_text, predict_next_token, tokenize, logit_lens, track_token, track_race, embedding_neighbors
    ├── activation_tools.py    # extract_activations, compare_activations
    ├── attention_tools.py     # attention_pattern, attention_heads
    ├── probe_tools.py         # train_probe, evaluate_probe, scan_probe_across_layers, probe_at_inference, list_probes
    ├── steering_tools.py      # compute_steering_vector, steer_and_generate, list_steering_vectors
    ├── ablation_tools.py      # ablate_layers, patch_activations
    ├── causal_tools.py        # trace_token, full_causal_trace
    ├── residual_tools.py      # residual_decomposition, layer_clustering, logit_attribution, head_attribution, top_neurons
    ├── attribution_tools.py   # attribution_sweep (batch logit attribution with prompt summaries)
    ├── intervention_tools.py  # component_intervention (zero/scale attention, FFN, heads)
    ├── neuron_tools.py        # discover_neurons, analyze_neuron, neuron_trace
    ├── direction_tools.py     # extract_direction
    ├── experiment_tools.py    # create_experiment, add_experiment_result, get_experiment, list_experiments
    ├── comparison_tools.py    # load_comparison_model, compare_weights, compare_representations, compare_attention, compare_generations, unload_comparison_model
    └── geometry/              # Geometry tools (per-tool subpackage)
        ├── _helpers.py            # Shared enums, math, direction extraction
        ├── token_space.py         # token_space
        ├── direction_angles.py    # direction_angles
        ├── subspace_decomposition.py  # subspace_decomposition
        ├── residual_trajectory.py # residual_trajectory
        ├── feature_dimensionality.py  # feature_dimensionality
        ├── decode_residual.py     # decode_residual
        ├── computation_map.py     # computation_map
        ├── inject_residual.py     # inject_residual
        ├── residual_match.py      # residual_match
        ├── compute_subspace.py    # compute_subspace, list_subspaces
        ├── residual_atlas.py      # residual_atlas
        ├── weight_geometry.py     # weight_geometry
        ├── residual_map.py        # residual_map
        ├── branch_and_collapse.py # branch_and_collapse
        ├── subspace_surgery.py    # subspace_surgery
        └── build_dark_table.py    # build_dark_table, list_dark_tables

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