Provides read-only tools for querying CMake project build models via the CMake File API and compile_commands.json, including targets, sources, compile flags, include directories, defines, language standards, dependencies, artifacts, install rules, cache variables, toolchains, and exact compiler invocations across multiple build directories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cmake-build-model how is src/main.cpp compiled in the release build?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets AI assistants query the build model of CMake
projects — targets, sources, compile flags, include directories, defines, language standards, dependencies,
artifacts, install rules, cache variables and toolchains — using the
CMake File API, plus the exact compiler
invocations from compile_commands.json.
It is workspace-aware: it discovers multiple CMake projects under one or more roots and multiple build
directories per project (e.g. build-debug, build-release, preset build trees, multi-config generators),
and can answer questions like "how is this file compiled?" across all of them at once.
The server is read-only: it never runs CMake and never writes into build directories. It only reads what a previous CMake configure run left behind.
Each build directory must already contain a File API reply with at least the codemodel object. Create the
query files before configuring (or re-configure after creating them):
mkdir -p build/.cmake/api/v1/query
touch build/.cmake/api/v1/query/{codemodel-v2,cache-v2,cmakeFiles-v1,toolchains-v1}
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ONcodemodel-v2 is required; cache-v2, cmakeFiles-v1 and toolchains-v1 enable the cache, inputs /
staleness and toolchain tools.
Replies requested by other clients (e.g. VS Code CMake Tools or CLion) are used as well, so build directories managed by an IDE usually work as-is.
CMAKE_EXPORT_COMPILE_COMMANDS=ON (Makefile and Ninja generators) writes compile_commands.json, which
find_file_targets and get_compile_commands read. Without it, everything else still works.
Related MCP server: CodeAtlas MCP Server
Discovery. Each workspace root is scanned for top-level CMakeLists.txt files (source projects) and for
CMakeCache.txt files (build directories). A build directory is linked to its project through
CMAKE_HOME_DIRECTORY, and the binaryDir of configure presets in CMakePresets.json /
CMakeUserPresets.json is resolved, so build trees outside the roots are found too.
Reply. The newest .cmake/api/v1/reply/index-*.json is read; objects are loaded lazily and cached until
the reply index changes, so re-configuring outside the server is picked up automatically.
Compile commands. <buildDir>/compile_commands.json is loaded (and re-loaded when it changes) and
indexed by source file. Entries are attributed to targets and configurations through their object file
path (CMakeFiles/<target>.dir/[<config>/]...).
Staleness. Using the cmakeFiles object, the server reports when a CMakeLists.txt or included
.cmake file has been modified since the last configure.
Tool | Purpose |
| Source projects and build directories in the workspace, with generator, build type, File API status (codemodel present, stale, modified inputs) and |
| Add an existing build directory that lives outside the workspace roots. |
| Configure and build presets of a source directory, with resolved binary directories. |
| CMake version, generator, configurations, |
| Targets filtered by type, name (substring / glob / |
| Everything about one target: definition site, artifacts, dependencies, compile groups (flags, defines, includes, standard, PCH), link/archive fragments, install destinations, sources, optional backtraces. |
| Direct or transitive dependencies or dependents of a target. |
| Which targets compile a file (in every build directory and configuration), with the File API compile settings and the matching |
| Exact entries of |
| Cache entries with type, value, help string; filterable. |
| Compilers per language with implicit include/link directories. |
| Files CMake read during configure, glob dependencies, and inputs modified since then. |
Most tools accept a buildDir argument: an absolute path, a path relative to a workspace root, or a source
directory that has exactly one build directory. It can be omitted when the workspace has a single build
directory. Multi-config generators (Visual Studio, Xcode, Ninja Multi-Config) are supported through the
configuration argument.
Example find_file_targets result:
{
"file": "/src/app/tools/main.cpp",
"matches": [
{
"buildDir": "/src/app/build",
"target": "app_cli",
"targetType": "EXECUTABLE",
"matchedBy": "source",
"compileGroup": {
"language": "CXX",
"languageStandard": "20",
"compileFlags": ["-std=gnu++20", "-Wall"],
"defines": ["CORE_VERSION=3"],
"includes": [{ "path": "/src/app/include" }]
},
"compileCommands": [
{
"file": "/src/app/tools/main.cpp",
"directory": "/src/app/build/tools",
"output": "tools/CMakeFiles/app_cli.dir/main.cpp.o",
"arguments": ["/usr/bin/c++", "-DCORE_VERSION=3", "-I/src/app/include", "-std=gnu++20", "-Wall",
"-o", "CMakeFiles/app_cli.dir/main.cpp.o", "-c", "/src/app/tools/main.cpp"],
"command": "/usr/bin/c++ -DCORE_VERSION=3 -I/src/app/include -std=gnu++20 -Wall -o CMakeFiles/app_cli.dir/main.cpp.o -c /src/app/tools/main.cpp"
}
]
}
]
}Node.js 18+
Build directories produced by CMake 3.14+ (3.20+ for toolchains; newer versions add fields such as
languageStandard). CMake itself does not need to be installed where the server runs.
git clone https://github.com/pkp124/cmake-build-model-mcp.git
cd cmake-build-model-mcp
npm install # also builds dist/The server speaks MCP over stdio.
cmake-build-model-mcp [options] [root...]
--root <dir> Workspace root to scan (repeatable; also CMAKE_MCP_ROOTS).
Without roots, the client's MCP roots are used, else the current directory.
--build-dir <dir> Additional build directory outside the roots (repeatable).
--max-depth <n> Maximum scan depth below each root (default: 6)..cursor/mcp.json){
"mcpServers": {
"cmake-build-model": {
"command": "node",
"args": ["/path/to/cmake-build-model-mcp/dist/index.js", "--root", "${workspaceFolder}"]
}
}
}{
"mcpServers": {
"cmake-build-model": {
"command": "node",
"args": ["/path/to/cmake-build-model-mcp/dist/index.js", "/path/to/workspace"]
}
}
}claude mcp add cmake-build-model -- node /path/to/cmake-build-model-mcp/dist/index.js "$PWD".vscode/mcp.json)VS Code provides MCP roots, so no --root is needed:
{
"servers": {
"cmake-build-model": {
"type": "stdio",
"command": "node",
"args": ["/path/to/cmake-build-model-mcp/dist/index.js"]
}
}
}Top-level projects are detected as CMakeLists.txt files with no CMakeLists.txt in an ancestor
directory below the root; nested independent projects are picked up once they have a build directory.
INTERFACE libraries only appear in the codemodel when they have sources (a CMake File API rule).
compile_commands.json is not produced by the Visual Studio and Xcode generators; for those, use the
File API compile groups returned by get_target / find_file_targets.
Directories starting with ., node_modules, CMakeFiles and _deps are not scanned.
npm run build # compile TypeScript to dist/
npm test # build + unit and end-to-end tests (needs cmake and a C/C++ compiler; ninja optional)The end-to-end tests copy test/fixtures/workspace (two independent projects, one with presets) into a
temporary directory, configure several build directories with File API queries (the test harness runs CMake,
the server never does), including a Ninja Multi-Config one when ninja is available, and drive the compiled
server over stdio with the MCP SDK client.
MIT
Finds which targets (in which build directories and configurations) compile a given source file, and returns the effective language, standard, flags, defines and include directories from the File API together with the exact compiler command(s) from the build directory's compile_commands.json. For headers not listed as sources, returns targets whose include directories contain the file. Searches all known build directories unless buildDir is given.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the file (absolute or relative to a workspace root). | |
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| configuration | No | Build configuration (e.g. Debug, Release) for multi-config generators. Defaults to the first one. | |
| includeBacktraces | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuine context beyond them: it reads from the File API plus compile_commands.json, defaults to scanning all build directories, and covers the header-not-a-source case. It omits failure behavior for unknown files and any mention of result size or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, purpose front-loaded, with the return payload detailed second and the header/buildDir caveats last. Dense but nearly every clause carries information; the header clause in particular earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of naming what comes back, and read-only safety is covered by annotations. It stops short of describing the shape of the result (per-target vs per-command grouping) or behavior when no targets match.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the schema already documents most parameters. The description largely restates schema semantics (buildDir omission, default configuration) rather than adding new meaning such as path resolution edge cases or includeBacktraces effects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb+resource ('Finds which targets ... compile a given source file') and enumerates the returned artifacts (language, standard, flags, defines, include dirs, compiler commands). It is clearly distinguishable from siblings like get_compile_commands (raw commands) and list_targets (all targets) because it performs a file-to-target mapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains search scope ('Searches all known build directories unless buildDir is given') and the header special case, which implies when it applies. However, it never names an alternative tool or states when NOT to use it, so routing between it and get_compile_commands remains inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns CMake cache entries (name, type, value, help string), optionally filtered by name. Advanced entries are hidden unless includeAdvanced is set or a filter is given.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Name filter: substring, glob or /regex/. | |
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| includeAdvanced | No | Include entries marked as advanced. | |
| includeInternal | No | Include INTERNAL and STATIC entries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds genuinely non-obvious behavior: advanced entries are suppressed by default and revealed either by includeAdvanced or by supplying a filter. That conditional visibility rule is behavior an agent could not derive from the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the return shape front-loaded and the visibility caveat immediately after. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description names the returned fields, and the default-visibility rule fills the main behavioral gap. Minor omission: no mention of ordering, size, or what happens when buildDir resolution fails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that `filter` has a side effect of exposing advanced entries, which is a semantic interaction between two parameters not stated in either schema entry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Returns) and resource (CMake cache entries), and enumerates the returned fields (name, type, value, help string). No sibling tool deals with cache variables, so the purpose is unambiguous without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage through 'optionally filtered by name' and the advanced-entry rule, but never states when to reach for this tool versus siblings like get_cmake_inputs or list_presets. No exclusions or prerequisites are given, so the agent must infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the files CMake read during configuration (CMakeLists.txt, included .cmake modules, configure_file inputs, etc.) and glob-dependent file lists.
| Name | Required | Description | Default |
|---|---|---|---|
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| includeExternal | No | Include files outside the source and build trees. | |
| includeCMakeModules | No | Include modules shipped with CMake itself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully enumerates the kinds of files returned (glob-dependent lists, configure_file inputs), which adds value given there is no output schema, but it says nothing about ordering, volume, or how defaults affect results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-formed sentence that front-loads the resource and follows with examples. No filler, though the parenthetical enumeration is slightly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with full schema coverage and no output schema, the description adequately conveys the returned content categories. It could be stronger by noting that CMake-shipped modules are excluded by default, which would clarify a potentially confusing example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The mention of 'included .cmake modules' loosely maps to includeCMakeModules and 'glob-dependent file lists' hints at external files, but no additional syntax or default behavior is explained beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (lists) and resource (files CMake read during configuration), with concrete examples like CMakeLists.txt, .cmake modules, and configure_file inputs. It is distinguishable from siblings like get_cache_variables or get_compile_commands, though it does not explicitly name a contrasting tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never says when to reach for this tool versus alternatives such as get_compile_commands or get_cache_variables, nor does it mention prerequisites like requiring a configured build directory. Usage is only inferable from the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the exact compiler invocations from compile_commands.json in a build directory, filtered by file, path pattern, target and/or configuration. When file is given without buildDir, every build directory of the workspace that compiles the file is searched. Each entry has the working directory, the argument list, the original command string (when the database uses command) and the output file.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Exact source file path (absolute or relative to a workspace root). | |
| limit | No | Maximum number of entries per build directory. | |
| filter | No | Source path filter: substring, glob or /regex/. | |
| target | No | Only commands compiling objects of this target. | |
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| configuration | No | Only commands of this configuration (multi-config generators; ignored otherwise). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the workspace-wide fallback search when buildDir is omitted, and the shape of each returned entry (working directory, argument list, original command string, output file). It does not mention limits or pagination semantics beyond the default, but the added disclosure is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action and filtering axes, with no filler. The return-shape sentence is slightly dense but earns its place given there is no output schema. Minor tweak would be to break the last, list-heavy sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and six optional parameters, the description compensates by describing the returned entries and the fallback search behavior. The one lingering gap is pagination/ordering semantics around `limit` (capped at 50 by default), which is only implied by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and the schema already documents all six parameters. The description still adds value by clarifying cross-parameter behavior – that omitting buildDir while supplying file widens the search to all workspace build directories – which is not stated in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Reads the exact compiler invocations from compile_commands.json') and states the filtering axes, which cleanly separates it from siblings like get_cache_variables, list_targets, and get_target. An agent can identify the tool's job without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage condition – when you need exact compiler invocations – and explains the important cross-parameter case (file given without buildDir searches every build directory of the workspace). It does not name explicit alternatives or when-not-to-use this tool, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
High-level overview of a configured build directory: CMake version, generator, configurations, the project() hierarchy and target names grouped by type.
| Name | Required | Description | Default |
|---|---|---|---|
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| configuration | No | Build configuration (e.g. Debug, Release) for multi-config generators. Defaults to the first one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe local read. The description adds the content inventory of the summary, but says nothing about cost, size, or the fact that it may auto-select a build directory when buildDir is omitted (that detail lives only in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that lists the payload contents without filler. Every clause earns its place; nothing is repeated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates what the summary returns, and the read-only annotation covers the safety profile. Adequate for a zero-required-parameter read tool, though it omits any hint about relative cost versus the finer-grained sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented there (including the single-build-directory fallback and the multi-config default). The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb-and-resource pair (high-level overview / build directory) and enumerates the contents (CMake version, generator, configurations, project() hierarchy, target names by type), which implicitly separates it from list_targets and get_cache_variables. It does not explicitly name a sibling to contrast against, keeping it at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"High-level overview" implies this is the orientation/entry-point tool before drilling into specific data, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. "use list_targets for per-target detail"). Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details of one target: artifacts, where it is defined, dependencies, link/archive command fragments, install destinations, and per compile group the language standard, flags, defines and include directories, plus its source files.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target name or File API target id. | |
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| maxSources | No | Maximum number of sources to list. | |
| configuration | No | Build configuration (e.g. Debug, Release) for multi-config generators. Defaults to the first one. | |
| includeSources | No | Include the list of source files. | |
| includeBacktraces | No | Include CMake backtraces (file:line of the command) for sources, defines, includes, etc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful scope limitation that it returns exactly one target's details, but is silent on behavior driven by the tool's own parameters, e.g. that source listing is capped/paginated or that backtraces are off by default.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence beginning with the resource ('Full details of one target'), followed by a compact enumeration of return fields. No filler, though the enumeration runs long enough that the tail is easy to skim past.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return values and does so concretely (artifacts, definitions, dependencies, link/archive fragments, install destinations, compile-group settings, sources). Combined with 100% parameter coverage, the agent has enough to call it, though the absence of any usage routing leaves a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents target, buildDir, maxSources, configuration, includeSources and includeBacktraces in detail. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Full details of one target') and enumerates the returned content domains (artifacts, dependencies, flags, source files), so the agent knows exactly what class of information this returns. It does not, however, distinguish itself from siblings like get_target_dependencies or get_project_summary, which overlap in surface area.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains no when-to-use or when-not-to-use guidance and names no alternative. An agent must infer that this is the broad 'single target' call versus list_targets (enumeration) or get_target_dependencies (dependency-only view).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the targets a target depends on (dependencies) or the targets depending on it (dependents), directly or transitively, including an adjacency list for the transitive graph.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target name or id. | |
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| direction | No | dependencies | |
| transitive | No | ||
| configuration | No | Build configuration (e.g. Debug, Release) for multi-config generators. Defaults to the first one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds real behavioral context: the result includes an adjacency list representing the transitive graph, not just a flat list. It doesn't discuss pagination or size limits, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence with zero filler, front-loading the return content and clarifying the two directions in parenthetical examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description usefully sketches the returned shape (adjacency list). Remaining gaps around configuration selection and build-dir resolution are already documented in schema field descriptions, so the definition is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60% and the bare enum for direction has no schema description; the description supplies the meaning of both values (dependencies vs dependents) and clarifies the transitive-graph output. It adds meaning beyond the schema, though it doesn't touch buildDir/configuration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource (returns targets a target depends on / depending on it) and names the two modes, which distinguishes it from siblings like get_target and list_targets. The graph-traversal framing makes it unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the direction parameter but the description never states when to choose this tool over get_target or list_targets, nor any prerequisite such as needing a resolved build directory. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the compilers used per language (path, id, version, target) including implicit include and link directories.
| Name | Required | Description | Default |
|---|---|---|---|
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read-only profile is covered. The description adds useful content detail — that results are per language and include implicit include and link directories — but says nothing about behavior such as failure modes, missing-config handling, or scope beyond what is structured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core result and then lists the returned fields and extras. Nothing is redundant and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the return fields (path, id, version, target, implicit include/link dirs), which is exactly what an agent needs. Combined with 100% schema coverage for the single parameter, only a minor gap remains around usage conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the buildDir parameter, its absolut/relative resolution rules, and the omission fallback are fully documented in the schema. The description adds no parameter meaning on top of that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: returns compilers used per language, with the returned fields enumerated (path, id, version, target). It is clearly distinct from siblings like get_compile_commands or get_cache_variables, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to use this tool versus siblings such as get_compile_commands, which overlaps in the compiler/tooling space. No prerequisites, exclusions, or alternative-routing guidance are provided; usage is only implied by the tool's subject matter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the configure and build presets from CMakePresets.json / CMakeUserPresets.json of a source directory, with resolved binary directories.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceDir | Yes | Source directory containing the presets file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without the description. The description adds useful context by naming the two files consulted and noting that binary directories are resolved, but says nothing about behavior when the file is absent or about the returned preset fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence covering source files, scope, and the resolved-binary-directory detail with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool whose annotations cover safety and whose lone parameter is fully documented in the schema, the description is essentially sufficient. Only minor gaps remain: no mention of error behavior when no presets exist and no note on ordering or which preset set (configure vs build) is returned first.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is a single sourceDir parameter, so the schema already documents it fully. The description's phrase 'of a source directory' restates rather than extends the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (Lists) plus resource (configure and build presets) and the exact source files read (CMakePresets.json / CMakeUserPresets.json), including the extra detail that binary directories are resolved. It is distinguishable from every sibling, though the differentiation is implicit rather than stated since no sibling touches presets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to reach for this tool versus alternatives like list_projects or get_project_summary, nor any prerequisite or failure condition (e.g., what happens when no presets file exists). Usage is only inferable from the purpose sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists top-level CMake source projects and build directories found under the workspace roots, including which source directory each build directory belongs to, its generator/build type and whether a File API reply is available and up to date.
| Name | Required | Description | Default |
|---|---|---|---|
| rescan | No | Re-scan the workspace roots for new projects and build directories. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, local read operation. The description adds useful behavioral detail: it enumerates the fields returned per build directory (generator, build type, File API reply freshness), which helps set expectations. However, it doesn't mention performance/rescanning cost or caching behavior, which would be valuable given the rescan parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and then elaborates on the data returned. It is appropriately concise with no filler, though it could be slightly clearer with a shorter opening clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a simple input schema, the description does a fair job of describing return contents. However, it lacks guidance on usage context, alternative tools, and any prerequisites (e.g., whether the workspace must be configured). For a listing tool among many project-graph siblings, this is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single parameter 'rescan' is fully documented in the schema. No parameters are required, so the tool can be called with no arguments. The description doesn't repeat parameter details, which is appropriate when the schema is complete; baseline would be 3-4, and given the parameter is simple and well-described, a 4 is reasonable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (lists) and resource (top-level CMake source projects and build directories) with detail about what each entry contains (source→build mapping, generator/build type, File API reply status). It is clear what the tool returns. However, it doesn't explicitly differentiate itself from siblings like get_project_summary or list_targets, which also operate on the project graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_project_summary or list_targets. The description only explains what it lists, not the conditions under which an agent should call it or what preconditions exist (e.g., whether a prior scan is required).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists build targets with type, project, defining directory, artifacts and languages.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name filter: substring, glob (`*`, `?`) or regex wrapped in slashes, e.g. `/^test_/`. | |
| type | No | Only include these target types. | |
| project | No | Only targets belonging to this project() name. | |
| buildDir | No | Build directory (absolute, or relative to a workspace root). A source directory with a single build directory is also accepted. May be omitted when the workspace has exactly one build directory. | |
| directory | No | Only targets defined in this source directory (or below). | |
| configuration | No | Build configuration (e.g. Debug, Release) for multi-config generators. Defaults to the first one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description's useful addition is disclosing what the listing contains (type, project, source directory, artifacts, languages), which compensates for the absent output schema. It says nothing about pagination, cost, or filter combination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or repetition. It is efficient, though arguably terse for a six-parameter tool with no usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description partially covers return shape by naming the listed attributes, and the read-only annotation covers safety. However, for a six-param tool with a buildDir/configuration selection burden, missing guidance on filter interplay and sibling routing leaves clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each of the six parameters is fully documented in the schema, so the baseline is 3. The description's mention of "type", "project" and "directory" reads as returned fields rather than filter semantics, adding no meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Lists build targets") and enumerates the attributes returned (type, project, defining directory, artifacts, languages). It is distinguishable from get_target (singular/detailed) and find_file_targets, though it never names or contrasts those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this versus get_target, find_file_targets, or list_projects, and no prerequisites stated. The agent must infer usage purely from the name and returned-field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds an existing CMake build directory (one containing CMakeCache.txt) that lies outside the workspace roots, e.g. /tmp/build-foo, so the other tools can query it.
| Name | Required | Description | Default |
|---|---|---|---|
| buildDir | Yes | Path to the build directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds a genuine precondition beyond the name: the directory must contain CMakeCache.txt and must be outside the workspace roots. It does not say whether registration persists across sessions, whether it is idempotent, or what happens if the path is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that leads with the action and then qualifies the resource. It earns its length, though the three stacked qualifiers make it slightly dense rather than maximally scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter registration tool with no output schema, the description covers the action, the required precondition, and the downstream benefit. Remaining gaps (persistence, failure behavior, idempotency) are minor given the annotations already establish the safe read-only profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single parameter, so the baseline is 3. The description adds the /tmp/build-foo example and the CMakeCache.txt validity constraint, which supplements the bare 'Path to the build directory' schema text without introducing syntax the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (adds/registers) and resource (an existing CMake build directory), plus the distinguishing scope constraint that it lies outside workspace roots. The trailing clause 'so the other tools can query it' clarifies its role relative to the sibling query tools. An agent can identify this without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear condition for use: a build directory that lies outside the workspace roots, with a concrete example (/tmp/build-foo). It implies the directory would otherwise be invisible to the other tools, but does not name any explicit alternative or exclusion, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_file_targetsget_cache_variablesget_cmake_inputsget_compile_commandsget_project_summaryget_targetget_target_dependenciesget_toolchainslist_presetslist_projectslist_targetsregister_build_dirScored across 12 tools
Tools are mostly distinct, but find_file_targets and get_compile_commands overlap in returning compiler commands for a file, and get_target includes dependency information that get_target_dependencies also provides. Descriptions mitigate confusion, but the boundaries are not perfectly clean.
Consistent snake_case verb_noun pattern throughout (list_, get_, find_, register_), with no mixed conventions or vague verbs.
12 tools is well-scoped for a CMake build model inspector; each tool covers a distinct aspect such as projects, targets, dependencies, cache, toolchains, and inputs without redundancy.
The core inspection surface is comprehensive, covering projects, targets, dependencies, compile commands, cache variables, toolchains, and CMake inputs. Minor gaps include no tool to unregister a build directory or retrieve full preset details beyond resolved binary directories.
Read-only AI project discovery, verification, comparison, shortlisting, and stack planning.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
