TestAtlas
This server provides read-only MCP access to a TestAtlas test-map database for querying and understanding a .NET test-automation solution.
Get summary statistics: projects, classes, methods, class kinds, endpoints, binding coverage, and edge tallies.
Assess change impact: find scenarios affected by a class, method, step definition, or HTTP endpoint.
Search step definitions and scenarios using full-text search.
Resolve a Gherkin step phrase against existing step definitions to check whether it already binds, is ambiguous, or needs reuse suggestions.
Inspect detailed scenario metadata: feature, tags, kind, examples, file location, and ordered steps.
Inspect detailed step definitions: keyword, expression kind, parameters, C# class/method/signature, location, and usage count.
Explore the reusable step catalog with placeholders and allowed values for composing new scenarios.
List HTTP endpoints with verb, route, and scenario blast radius.
List scenario tags with counts to keep tagging consistent.
Query the implied project dependency graph, including dependencies and dependents.
Provides a queryable semantic map of .NET test-automation solutions, indexing projects, Gherkin features, step definitions, and dependencies into a SQLite database. Enables AI agents to resolve steps, assess impact, search scenarios, and explore project dependencies to promote reuse and avoid duplication.
The problem
Large test-automation solutions are hard to navigate — for humans and for AI agents. Asked to automate a new story, an agent can't see which steps already exist, where similar code lives, or what conventions the solution follows — so it duplicates steps and misplaces code. TestAtlas indexes the solution once into a single SQLite map and answers those questions precisely: deterministically, offline, without a model or a network call.
Related MCP server: Slnmap
See it in action
Index the bundled 8-project sample once — testatlas index samples/SampleShop/SampleShop.sln — then
ask it questions from the terminal. Every number below is real output from that run:
$ testatlas stats sampleshop.db
TestAtlas map: sampleshop.db (schema v5)
totals: 8 project(s), 15 class(es), 36 method(s), 14 step definition(s)
class kinds:
api_client 7
page_object 4
step_class 4
gherkin: 4 feature(s), 5 scenario(s), 16 step(s)
bound steps: 16 · unbound: 0 · ambiguous: 0
endpoints: 3 (3 call site(s))…or let your agent ask them over MCP. Here an agent checks whether a step it is about to write
already exists — resolve_step answers with the definitions that would bind it, or the closest
near-misses to reuse instead:
// agent → testatlas: resolve_step { "text": "I add the product to my cart" }
{
"status": "none", // nothing binds this exact text — don't invent it from scratch:
"suggestions": [ // these existing steps are the closest, ranked by shared terms
{ "expression": "product (.*) is added to the cart with quantity (.*)",
"keyword": "When", "location": "SampleShop.Tests.Api/Steps/CatalogApiSteps.cs:34" },
{ "expression": "the cart is not empty",
"keyword": "Then", "location": "SampleShop.Tests.Api/Steps/CatalogApiSteps.cs:43" }
// …8 more
]
}Live sample outputs, committed from that same solution:
HTML report (features, scenarios, bindings, class kinds, endpoints) ·
dependency map (the eight projects in layers — click one to see what it uses, what uses it, and which tests a change can reach).
(GitHub serves .html as source, so the links route through htmlpreview.github.io — or download from docs/ and open locally.)
What you get
TestAtlas statically analyses the solution and emits codemap.db — projects and their dependency
edges, Gherkin features/scenarios/steps, step definitions and their bindings (bound / unbound /
ambiguous), page objects, API clients, helpers, test classes, and the call/usage edges connecting
them — then turns that map into answers:
Capability | What you get | |
🧩 | Reuse-first authoring |
|
💥 | Impact | Blast radius — the scenarios affected by changing a class, method, step, or endpoint |
🔍 | Search | FTS5 over step definitions + scenarios — "does a step for this already exist?" |
🔌 | MCP | All of it served to an AI agent over stdio — precise answers in a few hundred tokens, no context stuffing |
📊 | Report & map | Self-contained HTML drill-down of the whole map + a layered, searchable project-dependency graph |
📈 | Stats | Entity counts, class-kind breakdown, binding coverage, diagnostics |
All of it offline, deterministic, and reproducible — same input, same map, every time.
🚀 Quick start
Requires the .NET SDK 8.0+. On a corporate machine where
dotnet tool installfails with 401, see docs/troubleshooting.md.
1 — Install the CLI (and the MCP server, if you'll connect an agent):
dotnet tool install --global TestAtlas.Cli
dotnet tool install --global TestAtlas.Mcp2 — Index your solution. This produces the map (./codemap.db) that every query, report, and
MCP answer reads — nothing works without it:
testatlas index path/to/YourSolution.slnNo need to build or restore the solution first — indexing is a syntax-only pass, so an unrestored
checkout maps fine. Point index at a folder (or nothing) and it auto-discovers a single
.sln/.csproj there.
3 — Query it:
testatlas stats
testatlas search "login"
testatlas report # writes codemap.html
testatlas map # writes codemap-map.html…and to serve it to your AI agent, continue to MCP setup.
git clone https://github.com/Karzone/TestAtlas.git
cd TestAtlas
dotnet build TestAtlas.sln
dotnet run --project src/CodeMap.Cli -- index path/to/YourSolution.sln🔌 Use it from an AI agent (MCP)
TestAtlas ships an MCP server — testatlas-mcp — that serves the map to any MCP-aware client
(Visual Studio / VS Code Copilot, Claude Code, and others) over stdio JSON-RPC. The agent asks a
precise question and gets an exact, structured answer straight from the .db — instead of
stuffing source files into its context window.
Prerequisites: both tools installed and a map built — steps 1–2 of the Quick start. Then register the server:
Visual Studio / VS Code (GitHub Copilot agent mode) — add to your .mcp.json
(%USERPROFILE%\.mcp.json or <SolutionDir>\.mcp.json):
{
"servers": {
"testatlas": {
"type": "stdio",
"command": "testatlas-mcp",
"args": ["C:\\path\\to\\codemap.db"]
}
}
}Pass the map path explicitly (as above, or via a TESTATLAS_DB env var) — most agents launch
the server from their own working directory, not your solution folder, so relying on auto-discovery
leaves the server with no map: it starts and lists its tools, but every call answers with an error
saying how to supply one (releases before 0.1.11 exited with code 2 instead). In Visual Studio you can also use Tools picker → + → Add
custom MCP server to write this entry for you. On the .NET 10 SDK you can skip the install and
use "command": "dnx", "args": ["TestAtlas.Mcp", "--yes", "C:\\path\\to\\codemap.db"] — dnx
fetches and runs the server on demand.
Claude Code — as a plugin (server, a skill that says when to use which tool, /testatlas:index,
/testatlas:report, and a session-start check that tells Claude when the map is missing or stale):
claude plugin marketplace add Karzone/TestAtlas
claude plugin install testatlas@testatlasThe plugin starts testatlas-mcp with no arguments, so it serves the codemap.db at the root of
whatever project the session is opened in — build it with /testatlas:index; from 0.1.12 the server
picks the map up on the next call, with nothing to reconnect. Both tools must be on
the PATH (dotnet tool install --global TestAtlas.Cli, then the same for TestAtlas.Mcp). The plugin lives in
claude-plugin/.
Claude Code — one server, no plugin:
claude mcp add testatlas -- testatlas-mcp path/to/codemap.db
claude mcp list # the testatlas row should read: ✔ ConnectedBy default the server is registered for the current project (--scope local). Add
--scope user to make it available in every project on your machine, or --scope project to
share the registration with your team via a committed .mcp.json.
MCP clients load serversat session start — if you register mid-session, restart your agent
session before the testatlas tools appear. To confirm it's actually being used (and not
silently ignored), run the checks in
docs/troubleshooting.md.
Tools exposed:
resolve_step— resolve a Gherkin phrase to the existing step definition(s) that would bind it (regex/cucumber, keyword-agnostic).exact/ambiguous/none(+ near-match suggestions ranked by shared terms). Reuse-first authoring: don't write a step that already exists.step_catalog— the reusable step vocabulary with extracted placeholders and allowed values (cucumber{type}, regex(a|b)enums). Compose scenarios from what exists.impact— blast radius of a change: the scenarios affected by a given class, method, step definition, or endpoint.search_steps— full-text search over step definitions (expression text + method + class name).search_scenarios— full-text search over scenarios (feature + scenario name + step text + tags).get_scenario— full detail of scenario(s) by name: feature, tags, kind, example-row count, and the ordered steps.get_step_definition— full detail of step definition(s) by expression: keyword, params, C# class/method/signature, and the scenarios that use it.list_tags— the tag taxonomy with per-tag scenario counts, most-used first — tag new scenarios consistently.list_endpoints— the HTTP endpoints the suite calls, each with verb, route, and scenario blast radius (highest-reach first).project_dependencies— the implied project dependency graph (depends-on / depended-on-by), e.g. "what depends on the Party project?".stats— summary counts: projects, classes, methods, class-kind breakdown, endpoints, and edge tallies.
Retrieval runs locally against the SQLite file — deterministic, offline, and a few hundred tokens
per answer. Protocol details in specs/codemap-mcp.md; registration from
source and every failure mode in docs/troubleshooting.md.
📖 Commands
Command | What it does |
| Analyse a |
| Entity counts per project, unbound/ambiguous steps, diagnostics. |
| FTS5 full-text search over step definitions and scenarios. |
| Blast radius: scenarios affected by changing an entity. |
| Write a self-contained HTML drill-down of the map. |
| Write a self-contained project dependency graph (HTML). |
| Check a file is a supported TestAtlas map. |
index --output <file> · --config <file> · --include <glob> (repeatable) · --exclude <glob> (repeatable) · --verbose · --quiet
search --steps (step definitions only) · --scenarios (scenarios only)
Exit codes 0 ok · 1 completed with warnings · 2 fatal · 3 bad arguments
Run testatlas --help for the full usage text.
# Index the solution (no build needed — the pass is syntax-only)
testatlas index YourSolution.sln --output atlas.db
# Before writing a new step — does one already exist?
testatlas search atlas.db "add a product to the cart" --steps
# About to change a shared client — what will it hit?
testatlas impact atlas.db --class ProductsApiClient
# Share human-readable snapshots
testatlas report atlas.db --html atlas.html
testatlas map atlas.db --html atlas-map.htmlsamples/SampleShop is a self-contained 8-project solution mixing API
tests and UI tests, so the map has plenty of connected nodes — real HttpClient API clients, real
Selenium IWebDriver page objects, and Reqnroll suites driving both:
┌─▶ Api.Catalog ──┐
Tests.Api ────────────┼─▶ Api.Cart ──┤
Tests.E2E ──┬─────────┴─▶ Api.Identity ──┼─▶ Core (ApiClientBase : HttpClient)
└─▶ Ui.Pages ─────────────────┘ (PageBase : IWebDriver)
Tests.Ui ────▶ Ui.Pages ──────────────────▶ CoreReproduce the committed sample outputs yourself:
testatlas index samples/SampleShop/SampleShop.sln --output sampleshop.db
testatlas report sampleshop.db --html docs/sample-report.html
testatlas map sampleshop.db --html docs/sample-map.html🔄 Keeping the map fresh
Answers are deterministic — but only as fresh as the map, so re-index on change, not on a timer. A full re-index is a single static pass (seconds), and its cost scales with solution size, not with how much changed:
Locally —
python scripts/check-map-age.pytells you when your map drifted; a version-controlledpost-mergegit hook can warn automatically after every pull.In CI (team model) — re-index on every merge to main and publish the
.dbto a shared feed (never commit it — it's a build artifact). Then teammates and agents only needTestAtlas.Mcplocally: download the shared map and pointTESTATLAS_DBat it — no localTestAtlas.Clior indexing required. (Index locally only to include your own uncommitted branch work.)
Details — the staleness checker, the git hook, and copy-paste CI recipes (GitHub Actions + Azure DevOps with a Universal feed) — in docs/keeping-the-map-fresh.md.
🧹 Uninstall
Two separate things — remove them in this order, so the editor isn't launching a server whose binary just vanished:
Remove the MCP registration — delete the
testatlasblock from your.mcp.json(<SolutionDir>\.mcp.jsonor%USERPROFILE%\.mcp.json), then restart Visual Studio / VS Code. (Or just toggle it off in the agent's tools/wrench picker to keep it for later.)Uninstall the tools — they're .NET global tools, not editor add-ins:
dotnet tool uninstall --global TestAtlas.Mcp dotnet tool uninstall --global TestAtlas.Cli dotnet tool list --global # confirm they're gone(Optional) delete the
codemap.dbmap file — it's just data, nothing else references it.
🎯 Design tenets
Zero config — a useful map on an unseen solution, no config file required.
Solution agnostic — heuristic, overridable detection; no company-specific assumptions.
Deterministic & offline — same input ⇒ byte-equivalent logical content; no network, no AI.
Graceful degradation — solutions without Gherkin still yield a useful map.
Public schema as contract — a versioned SQLite schema, so downstream consumers keep working even if a third party swaps in their own indexer.
The project folders use the indexer's working name (CodeMap); the shipped tools and
packages are TestAtlas. Full specs: specs/codemap-indexer.md ·
specs/codemap-mcp.md. Repo layout: CONTRIBUTING.md.
🗺 Roadmap
Indexer CLI — C# indexer + documented, versioned SQLite schema
HTML visualization — self-contained report + project map generated from the db
MCP server —
testatlas-mcpexposes the map to AI agents over stdio JSON-RPC (11 tools)Second-language indexer — same schema, contract-tested
Deliberately not planned (see design tenets): LLM-assisted analysis inside the indexer, network calls at index/query time, running or generating tests, and semantic (compilation-based) analysis that would require a restored build. Releases and per-version notes live on the releases page; current distribution channels in docs/DISTRIBUTION.md.
📄 License
MIT © 2026 Karthik Kalaiyarasu
Available Tools
11 toolsget_scenarioA
Full detail of scenario(s) whose name contains the given text: feature, tags, kind, example-row count, file:line, and the ordered steps (keyword + text + doc-string/data-table flags). Use to read an existing scenario before writing a similar one.
Inputs: name (required), limit.
get_step_definitionA
Full detail of step definition(s) whose expression contains the given text: keyword, expression kind, method parameters, C# class/method/signature, file:line, and the scenarios that currently use it (usage count). Use to inspect a step before reusing or changing it.
Inputs: query (required), limit.
impactA
Blast radius of a change: the test scenarios affected by changing a class, method, step definition, or endpoint. Returns the affected scenarios (feature + the connecting step text), plus step-definition and feature counts.
Inputs: value (required), target (required).
list_endpointsA
The HTTP endpoints/operations the suite calls, each with verb, route (real path when known), and its scenario blast radius. Highest-reach first.
Inputs: limit.
list_tagsA
The tag taxonomy across the suite — every scenario tag (e.g. @smoke, @regression, ticket ids) with the number of scenarios carrying it, most-used first. Use to tag new scenarios consistently with what already exists.
Inputs: limit.
project_dependenciesA
The project dependency graph the suite implies: for each project, which projects it depends on and which depend on it, derived from cross-project binds_to/uses_type/inherits edges (edge counts as weight). Answers e.g. "what depends on the Party project?". Optional 'project' name filter.
Inputs: limit, project.
resolve_stepA
Resolve a Gherkin step phrase to the EXISTING step definition(s) that would bind it — the same way the runner does (regex/cucumber expression, keyword-agnostic). Use this BEFORE writing a new step so an agent reuses what already exists instead of authoring a duplicate. status is 'exact' (one binding — reuse it), 'ambiguous' (several match — a conflict to resolve), or 'none' (nothing binds — returns existing step definitions ranked by shared terms, to adapt rather than duplicate). Each match returns the expression, the C# class/method, the method parameters, the argument values captured from the phrase, and file:line.
Inputs: text (required), keyword.
search_scenariosA
Find the tests for a topic: full-text search over scenarios (feature name + scenario name + step text + tags). Returns matching scenarios with feature and file:line. Use this instead of grepping .feature files when asked to find, list or count tests.
Inputs: query (required).
search_stepsA
Full-text search over step definitions (expression text + method + class name). Returns matching step definitions. Use this instead of grepping binding classes.
Inputs: query (required).
statsA
Summary of the test map: project/class/method counts, class-kind breakdown, endpoints, and edge tallies.
Inputs: no named parameters.
step_catalogA
The reusable step vocabulary: step definitions with their placeholders and (best-effort) allowed values pulled from the expression — cucumber {int}/{string}/{word}, regex alternations like (Auto|Allianz) as enum values, other groups as free parameters. Use to compose new scenarios from steps and values that already exist. Optional keyword/query filters.
Inputs: limit, query, keyword.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct targets (endpoints, tags, scenarios, dependencies), and descriptions explicitly differentiate the step-related tools. However, four tools touch step definitions (search_steps, get_step_definition, step_catalog, resolve_step), and an agent could plausibly confuse search_steps with step_catalog or get_step_definition without reading carefully.
Most names follow a verb_noun pattern (list_endpoints, list_tags, search_steps, get_scenario, resolve_step), but several are bare nouns (stats, impact, step_catalog, project_dependencies). The convention is readable but not uniform across the set.
11 tools is well within the sweet spot and each tool maps to a distinct query type over the test suite. No tool feels redundant or padded for the scope of analyzing a BDD test map.
The surface covers discovery (endpoints, tags, stats), search (steps, scenarios), inspection (scenario, step definition, catalog), and analysis (impact, dependencies) — strong coverage for a read-only analysis server. Minor gaps exist, e.g. no direct feature/file listing or bulk export, but core workflows are reachable.
Maintenance
Related MCP Connectors
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceCodeMap is a Roslyn-powered MCP server that lets AI agents navigate C# codebases by symbol, call graph, and architectural fact, instead of brute-force reading thousands of lines of source code. One tool call. Precise answer. No context flood.24-
- AlicenseNot gradedqualityBmaintenanceA semantic map of your .NET solution for AI coding agents. Analyzes a solution with Roslyn into a queryable code graph exposing 11 read-only tools (find_symbol, impact_analysis, find_implementations, etc.) over MCP. 100% local, no telemetry, MIT licensed.25MIT
- AlicenseAqualityCmaintenanceExtracts deterministic architecture maps from codebases for AI agents, enabling queries about blast radius, routes, security findings, and production readiness without sending code anywhere.6MIT
- AlicenseNot gradedqualityBmaintenanceGives AI coding agents real .NET tooling: Roslyn code navigation and refactoring, build/test with affected-test selection, git, and parallel orchestration as a dependency graph.MIT