ariadne mcp-server

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.

Related MCP server: octopilot-mcp

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   │
                    └─────────────┘

1. Agent calls tool — Passes project path to ariadne

2. Run git diff — ariadne executes git diff --unified=0 against base branch

3. Analyze with sazanami — Build call graph and find affected tests

4. 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):

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:

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:

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.