How do I install Ariadne?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Ariadne need an API key?

No required environment variable is listed on this record.

What transport does Ariadne use?

Ariadne runs locally over stdio.

When was Ariadne last checked?

Last checked 2026-11-09. Returns only the unit tests affected by your current Kotlin/Android code changes.

Ariadne MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

docker run -i --rm ghcr.io/mikhailhal/ariadne:0.4.0

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.mikhailhal-ariadne -- docker run -i --rm ghcr.io/mikhailhal/ariadne:0.4.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.mikhailhal-ariadne": {4      "command": "docker",5      "args": [6        "run",7        "-i",8        "--rm",9        "ghcr.io/mikhailhal/ariadne:0.4.0"10      ]11    }12  }13}

claude_desktop_config.json

Local · ociPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.4.0
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

ariadne is an MCP (Model Context Protocol) server that provides AI agents with the ability to identify affected tests. Powered by sazanami, it analyzes code changes and returns only the tests that need to be run.

[!IMPORTANT]

⚠️ MUST READ: Speed over Completeness

ariadne is built for the agent inner loop — edit, verify, commit — where fast feedback matters more than exhaustive selection. Static analysis cannot trace every execution path: reflection, DI frameworks, and data-flow indirection (e.g., Flux/MVI dispatch) can hide dependencies from any affected-test-selection tool, not just ariadne.

Always keep a final line of defense in CI. Run the full test suite (or a conservative selection) before merging. ariadne narrows what an agent runs while iterating; it is not a replacement for CI.

When ariadne detects changes it cannot analyze (build scripts, resources, unscanned source sets), it says so explicitly in the tool response instead of silently reporting "no affected tests".

Features

MCP Integration — Works with Claude Code, Claude Desktop, and other MCP-compatible clients
Automatic Git Diff — No need to pass diff manually; ariadne runs git diff internally
Powered by sazanami — Uses Kotlin Analysis API for accurate static analysis

Installation

Homebrew (recommended)

brew install mikhailhal/tap/ariadne

Then register it with your MCP client — for Claude Code:

claude mcp add ariadne -- ariadne

Or add to your MCP client configuration manually (e.g., Claude Desktop):

{
  "mcpServers": {
    "ariadne": {
      "command": "ariadne"
    }
  }
}

Docker

docker run -i --rm -v /path/to/project:/workspace ghcr.io/mikhailhal/ariadne

Mount the project you want analyzed and pass /workspace as project_path. The image is also listed in the official MCP Registry as io.github.MikhailHal/ariadne.

Manual (release JAR)

Download ariadne-<version>-all.jar from Releases (requires JDK 21+) and configure your client with "command": "java", "args": ["-jar", "/path/to/ariadne-<version>-all.jar"].

Build from Source

git clone --recursive https://github.com/MikhailHal/ariadne.git
cd ariadne
./gradlew shadowJar   # fat JAR: build/libs/ariadne-<version>-all.jar

Usage

Once configured, AI agents can use the get_affected_tests tool:

Tool: `get_affected_tests`

Parameters:

project_path (required) — Path to the Kotlin project
scope (optional, deep | shallow, default deep) — how far back to look:
- deep — all changes since base_branch (committed and uncommitted). Safest; the whole branch is covered so nothing you already committed slips through unverified. May select more tests.
- shallow — uncommitted changes only (diff against HEAD). Fastest, for the tight edit loop. Verifying already-committed work is left to the caller. base_branch is ignored.
base_branch (optional, deep scope only) — Branch to compare against. When omitted, ariadne uses the repository's default branch (origin/HEAD). If that is not set (e.g. a repo with no remote), it returns an error asking you to pass base_branch explicitly rather than guessing.

Returns:

List of affected test FQNs (fully qualified names), sorted
If the diff contains changes outside the analyzed Kotlin sources (build scripts, resources, unscanned source sets), a note is appended recommending a full test run for those changes
Analysis is bounded by a 120s timeout; on timeout an explicit error is returned

Example

Agent request:

{
  "name": "get_affected_tests",
  "arguments": {
    "project_path": "/path/to/your/kotlin/project"
  }
}

Response:

com.example.UserServiceTest.testCreateUser
com.example.UserRepositoryTest.testSave

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  MCP Client │ ──▶ │   ariadne   │ ──▶ │  sazanami   │
│  (Agent)    │     │ (MCP Server)│     │  (Analysis) │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  git diff   │
                    └─────────────┘

Agent calls tool — Passes project path to ariadne
Run git diff — ariadne executes git diff --unified=0 against base branch
Analyze with sazanami — Build call graph and find affected tests
Return results — List of test FQNs returned to agent

Real-World Validation: Now in Android

Measured against Now in Android (Google's reference Android app — 34 modules, ~268 Kotlin files):

Metric	Result
Recall audit — 19 target functions across all layers	18/18 valid targets detected (the 19th had no exercising unit test; correctly not selected)
End-to-end response time	~4s (module discovery + call-graph build + BFS)
Module discovery	34 modules via `settings.gradle.kts`, incl. nested modules and type-safe accessor dependencies
Source sets	`main`, `debug`, `prod`, `benchmark`, `testDemo`, … discovered per module (`androidTest*` excluded by design)

Verified patterns include repositories behind project interfaces, a library-interface override (androidx.datastore.Serializer), operator fun invoke use cases, @Composable functions, extension mappers, ViewModel property-initializer chains, and callable references. Two representative results:

Changing core:common's asResult() selects 14 tests across three modules, including ViewModel tests reachable only through val uiState = ...stateIn(...)
Changing the mapper PopulatedNewsResource.asExternalModel() selects 14 tests, including 11 repository tests reachable only through .map(Type::mapper) chains

Test-class selection rate

Every unit-test class in Now in Android was measured by changing a function in the class it tests and checking whether that test class was selected:

Test style	Selected
Plain unit tests (construct the object, call it)	13 / 13 valid targets
Robolectric / Compose screenshot tests	12 / 12
Framework-dispatched callbacks (lint `Detector`)	0 / 2 — see below

Robolectric turned out not to be a barrier: those tests call the composable themselves (setContent { NiaTheme { ... } }), so the call exists in the source. What decides coverage is not the test runner but whether the test's own code contains the call.

What ariadne cannot see

The rule of thumb: if the framework calls your code instead of your test calling it, ariadne cannot connect them. These are limits of static analysis, not bugs — plan your CI safety net around them:

Pattern	Status
Framework-invoked callbacks — Fragment/Activity lifecycle (`launchFragmentInContainer`), lint `Detector` methods, `Application.onCreate`	Not traced: no call written in the test
Reflection / DI-container wiring	Not traced
UDF dispatch (Flux/MVI)	`dispatch → collect` is never an edge, but wiring in `init` (or a `start()` the test calls) is covered conservatively via constructor chains. Subscriptions started by DI/lifecycle are not covered (sazanami#38)
`stateIn` / `shareIn` chains (`map`, `onEach`, `flatMapLatest`, `combine`)	Covered — verified with exact selection
Instrumented tests (`androidTest*`)	Out of scope by design
Build scripts, resources, unscanned source sets	Not analyzed — reported explicitly in the tool response
Same-name top-level extensions in one package	Over-selected (receiver types are not part of top-level FQNs) — safe direction
KMP source sets (`commonMain`, `expect`/`actual`)	Enumerated, but resolution quality unverified (#1)

Full audit notes: sazanami#29, sazanami#38.

Requirements

JDK 21 or later
Git — For diff detection

Limitations

Module discovery is convention-based: it parses settings.gradle(.kts) includes, enumerates src/<sourceSet>/{kotlin,java} layouts, and reads project(":x") / type-safe accessor dependencies from build files. Dynamic includes, projectDir remapping, custom srcDirs, and dependencies injected by convention plugins are not detected — see #1
Full graph rebuild on each request (no caching yet); analysis is capped at 120s
See What ariadne cannot see for analysis-level gaps

License

Copyright 2025 ariadne contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

See LICENSE for the full text.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Ariadne?

Does Ariadne need an API key?

What transport does Ariadne use?

When was Ariadne last checked?

Documentation

⚠️ MUST READ: Speed over Completeness

Features

Installation

Homebrew (recommended)

Docker

Manual (release JAR)

Build from Source

Usage

Tool: get_affected_tests

Example

How It Works

Real-World Validation: Now in Android

Test-class selection rate

What ariadne cannot see

Requirements

Limitations

License

Tool: `get_affected_tests`