Gradle-mcp searching_dependency_sources

install

source · Clone the upstream repo

git clone https://github.com/rnett/gradle-mcp

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/rnett/gradle-mcp "$T" && mkdir -p ~/.claude/skills && cp -r "$T/src/main/skills/searching_dependency_sources" ~/.claude/skills/rnett-gradle-mcp-searching-dependency-sources && rm -rf "$T"

manifest: src/main/skills/searching_dependency_sources/SKILL.md

source content

Authoritative Dependency Source & API Exploration

Explores, navigates, and analyzes the internal logic, APIs, and symbol implementations of external libraries and plugins with absolute precision using high-performance, indexed searching.

Constitution

ALWAYS use
```
search_dependency_sources
```
as the primary discovery tool for external library and plugin code.
ALWAYS prefer reading source code over interactive REPL exploration for understanding unfamiliar library APIs.
ALWAYS provide absolute paths for
```
projectRoot
```
.
ALWAYS use the
```
{group}/{artifact}
```
prefix for reading specific files (e.g.,
```
path="org.mongodb/mongodb-driver-sync/org/mongodb/client/MongoClient.kt"
```
). The
```
dependency
```
parameter should only be used to filter the search scope for performance when searching across libraries, not as the primary way to specify a path.
NEVER use
```
gradleSource: true
```
in this skill; use
```
researching_gradle_internals
```
for Gradle's internal implementation.
NEVER use generic shell tools like
```
grep
```
or
```
find
```
to locate dependency sources; they reside in remote caches whose paths are not predictable in advance.
MAY use shell tools like
```
rg
```
or
```
ast-grep
```
to operate on a sources root path explicitly returned by
```
read_dependency_sources
```
or
```
search_dependency_sources
```
in the
```
Sources root: <path>
```
header line. Dependency directories inside the sources root are symlinks; always pass
```
--follow
```
to
```
rg
```
(e.g.,
```
rg --follow <pattern> <sources-root>
```
).
ALWAYS escape Lucene special characters (
```
:
```
,
```
=
```
,
```
+
```
,
```
-
```
,
```
*
```
,
```
/
```
) in
```
FULL_TEXT
```
searches using a backslash (e.g.,
```
\:
```
) or double quotes.
ALWAYS use
```
read_dependency_sources
```
once a specific file path has been identified via search.
ALWAYS use
```
fresh: true
```
if a search returns a
```
SearchResponse
```
with an
```
error
```
indicating a missing index; the tool will return an error message rather than throwing an exception if the index is not found.
BE AWARE that indexing and extraction failures (e.g.,
```
ZipException
```
) are still propagated and will cause the tool to fail with a descriptive error.
NOTE that the
```
dependency
```
filter targets ONLY the specific library version matched, NOT its transitive dependencies.
BE AWARE that buildscript (plugin) dependencies are excluded from
```
search_dependency_sources
```
and
```
read_dependency_sources
```
by default to reduce noise.
ALWAYS use
```
sourceSetPath=":buildscript"
```
(root project) or
```
sourceSetPath=":app:buildscript"
```
(subproject) to search or read plugin source code. This targets the virtual
```
buildscript
```
source set which aggregates all classpath plugins.

Directives

Identify Search Mode Authoritatively:
- DECLARATION: Best for classes, methods, or interfaces. Matches against the simple name (tokenized for CamelCase) and the full path (exact literal). All declaration searches are case-sensitive. Do NOT include keywords like
```
class
```
  ,
```
interface
```
  , or
```
fun
```
  . Supports exact names, exact FQNs, glob wildcards (e.g.,
```
*
```
  ,
```
**
```
  ), and regular expressions. Partial package paths require wildcards (e.g., use
```
*.MyClass
```
  to find
```
com.example.MyClass
```
  ). You can target specific fields using
```
name:
```
  (discovery) or
```
fqn:
```
  (precision) prefixes.
- FULL_TEXT: Best for literal strings, constants, and complex code patterns using Lucene. Case-insensitive.
- GLOB: Best for finding specific files (XML, properties, etc.) by name or extension. Case-insensitive.
Invoke Precisely: ALWAYS set
```
searchType
```
explicitly if the intent is not a general full-text search. This improves result accuracy and reduces noise.
Scope Surgically: Use
```
projectPath
```
,
```
configurationPath
```
, or
```
sourceSetPath
```
to narrow the search and improve performance if the target library's context is known. To search a plugin, use
```
sourceSetPath=":buildscript"
```
.
ALWAYS scope with a project, configuration, or source set (or use
```
gradleSource: true
```
) — unscoped search is no longer supported.
Target Libraries Directly: Use the
```
dependency
```
parameter to filter searches to a single library. It supports
```
group:name:version:variant
```
,
```
group:name:version
```
,
```
group:name
```
, or just
```
group
```
. This bypasses project-level index merging and provides instantaneous results from the global extracted source cache.
Troubleshoot Targeted Searches: If a targeted search using the
```
dependency
```
parameter fails or returns no matches, use
```
inspect_dependencies
```
first to verify the exact coordinates (group, name, version, variant) of the dependency as resolved by Gradle.
Refresh Indices: Use
```
fresh: true
```
if project dependencies have recently changed to ensure the index is up-to-date.
Use Returned Sources Root: Every response from
```
read_dependency_sources
```
and
```
search_dependency_sources
```
includes a
```
Sources root: <absolute-path>
```
header. Use this path with
```
rg
```
,
```
ast-grep
```
, or other shell tools for operations not covered by the MCP tools (e.g., regex-heavy searches). Because dependency directories are symlinks, always pass
```
--follow
```
to
```
rg
```
:
```
rg --follow <pattern> <sources-root>
```
.
Explore Packages Authoritatively: Use
```
read_dependency_sources
```
with a dot-separated package path (e.g.,
```
org.gradle.api
```
) to list its direct symbols and sub-packages. This is backed by the symbol index and is more reliable than directory-based exploration for Kotlin projects.
Analyze Implementation: Use
```
read_dependency_sources
```
to retrieve the implementation logic. If the file is large, use
```
pagination
```
to read specific sections. You can target plugins by passing
```
sourceSetPath=":buildscript"
```
.
Trace Symbols Authoritatively: When encountering an unknown symbol, use
```
DECLARATION
```
search to jump directly to its definition in the library. This is the only reliable way to understand exact behavior and available methods.

When to Use

Decision rule: If the question is "what does this API look like or how does it work?" — use this skill. If you need to run code to see what it does at runtime — use
interacting_with_project_runtime
(REPL). Read before you run.

API & Symbol Discovery: When you need to find the implementation, signature, or documentation of a class, interface, or method imported from a library.
Library Usage Research: When understanding how to use a library's API by reading its internal implementation or looking for usage patterns in its source.
Internal Logic Auditing: When researching how a dependency handles specific operations, edge cases, or performance-critical logic.
Resource File Location: When searching for configuration files (XML, JSON, properties), specific named files (e.g.,
```
build.gradle
```
), or metadata (AndroidManifest.xml) packaged within library jars.
Constant & Literal Research: When searching for specific constant values, error strings, or literal keys within external code.

Workflows

1. Tracing a Symbol from Project Code

Identify the symbol name (e.g.,
```
JsonConfiguration
```
) or fully qualified name from an import.

Call

search_dependency_sources(query="<SymbolName>", searchType="DECLARATION", projectPath=":")

Identify the correct file path from the results.

Call

read_dependency_sources(path="<path>", projectPath=":")

to analyze the implementation.

2. Discovering API Usage through Source

Search for a known entry point (e.g., a constructor or main class) using
```
DECLARATION
```
or
```
FULL_TEXT
```
.
Once the file is found, use
```
read_dependency_sources
```
to read its source.
Look for internal calls, helper methods, or factory patterns to understand the library's preferred usage.

3. Searching for Constants or Error Codes

Identify the constant name or a snippet of an error message.

Call

search_dependency_sources(query="\"<text>\"", projectPath=":")

(defaults to

FULL_TEXT

Review matches to find where the value is defined or used.

Targeted Search for a Single Library

Identify the dependency coordinates (e.g., from
```
inspect_dependencies
```
or project files).

Call

search_dependency_sources(query="<query>", dependency="<group:artifact>", projectPath=":")

The results will be scoped ONLY to that library, ensuring maximum speed and relevance.

Path Syntax and Targeted Searching

When reading specific dependency source files, it is STRONGLY RECOMMENDED to use the full path syntax including the

{group}/{artifact}

prefix (e.g.,

path = "org.mongodb/mongodb-driver-sync/org/mongodb/client/MongoClient.kt"

). The

dependency

parameter should be reserved for filtering the scope of

search_dependency_sources

for performance, rather than as a way to shorten paths. This explicitly avoids Windows file system issues with colons.

Examples

Search for a specific class definition within a targeted library

{
  "query": "MongoClient",
  "searchType": "DECLARATION",
  "dependency": "org.mongodb:mongodb-driver-sync",
  "projectPath": ":"
}

// Reasoning: Using the 'dependency' parameter to target only the 'mongodb-driver-sync' library for a fast, focused search.

Read sources from a specific dependency

{
  "path": "org.jetbrains.kotlinx/kotlinx-coroutines-core/kotlinx/coroutines/Job.kt",
  "projectPath": ":"
}

// Reasoning: Reading 'Job.kt' using the recommended

{group}/{artifact}

syntax.

Search for a specific class definition

{
  "query": "JsonConfiguration",
  "searchType": "DECLARATION",
  "projectPath": ":"
}

// Reasoning: Using DECLARATION search to find a class named 'JsonConfiguration' across both name and FQN fields, scoped to the root project.

Search with field-specific precision

{
  "query": "fqn:kotlinx.serialization.json.*",
  "searchType": "DECLARATION",
  "projectPath": ":"
}

// Reasoning: Using the 'fqn:' prefix with a wildcard to find all declarations within a specific package literal.

Search with name-specific discovery (CamelCase)

{
  "query": "name:Configuration",
  "searchType": "DECLARATION",
  "projectPath": ":"
}

// Reasoning: Using the 'name:' prefix to find classes like 'JsonConfiguration' via CamelCase tokenization.

Trace a method signature using wildcards

{
  "query": "encodeTo*",
  "searchType": "DECLARATION",
  "projectPath": ":"
}

// Reasoning: Finding all definitions starting with 'encodeTo' across both name and FQN fields.

Use regular expressions for complex matching

{
  "query": "fqn:/.*\.internal\..*/",
  "searchType": "DECLARATION",
  "projectPath": ":"
}

// Reasoning: Using a regular expression on the 'fqn' field to find all internal declarations.

Search for a constant value assignment

{
  "query": "DEFAULT_TIMEOUT_MS \\: 5000",
  "projectPath": ":"
}

// Reasoning: Using FULL_TEXT (default) with escaped colon to find a specific constant assignment.

Locate a specific file by its exact name

{
  "query": "**/AndroidManifest.xml",
  "searchType": "GLOB",
  "projectPath": ":"
}

// Reasoning: Using GLOB search to find a specific file by name across the dependency graph.

Read a specific dependency source file

{
  "path": "kotlinx/serialization/json/Json.kt",
  "projectPath": ":"
}

// Reasoning: Reading the implementation of a known class path identified from previous search results, scoped to the root project.

Explore a package via its FQN

{
  "path": "org.gradle.api",
  "projectPath": ":"
}

// Reasoning: Listing the direct symbols and sub-packages of 'org.gradle.api' using index-backed exploration, scoped to the root project.

Resources

Lucene Query Syntax: Refer to the tool description for
```
search_dependency_sources
```
for details on complex queries and escaping.
Troubleshooting Targeted Searches: If
```
dependency
```
filter fails, run
```
inspect_dependencies
```
to confirm the exact coordinates.