scipq-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- scipq_mcp-0.1.0/.gitignore +12 -0
- scipq_mcp-0.1.0/CHANGELOG.md +28 -0
- scipq_mcp-0.1.0/LICENSE +21 -0
- scipq_mcp-0.1.0/PKG-INFO +259 -0
- scipq_mcp-0.1.0/README.md +232 -0
- scipq_mcp-0.1.0/docs/design.md +199 -0
- scipq_mcp-0.1.0/pyproject.toml +53 -0
- scipq_mcp-0.1.0/src/scipq_mcp/__init__.py +3 -0
- scipq_mcp-0.1.0/src/scipq_mcp/__main__.py +3 -0
- scipq_mcp-0.1.0/src/scipq_mcp/cli.py +147 -0
- scipq_mcp-0.1.0/src/scipq_mcp/extras.py +551 -0
- scipq_mcp-0.1.0/src/scipq_mcp/queries.py +706 -0
- scipq_mcp-0.1.0/src/scipq_mcp/render.py +514 -0
- scipq_mcp-0.1.0/src/scipq_mcp/scip.py +546 -0
- scipq_mcp-0.1.0/src/scipq_mcp/server.py +350 -0
- scipq_mcp-0.1.0/src/scipq_mcp/service.py +436 -0
- scipq_mcp-0.1.0/src/scipq_mcp/setup.py +244 -0
- scipq_mcp-0.1.0/src/scipq_mcp/symbols.py +408 -0
- scipq_mcp-0.1.0/src/scipq_mcp/templates/maven-compiler-plugin.xml +38 -0
- scipq_mcp-0.1.0/src/scipq_mcp/templates/scip-shards.init.gradle +49 -0
- scipq_mcp-0.1.0/src/scipq_mcp/workspace.py +574 -0
- scipq_mcp-0.1.0/tests/conftest.py +29 -0
- scipq_mcp-0.1.0/tests/fixtures/build-sample.sh +78 -0
- scipq_mcp-0.1.0/tests/fixtures/orphan/Gone.java +10 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/app/src/main/java/com/example/app/Report.java +20 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/app/src/main/java/com/example/app/Service.java +52 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/app/src/main/java/com/example/app/test/TestSupport.java +10 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/app/src/test/java/com/example/app/ServiceTest.java +15 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/app/compileJava/META-INF/scip/app/src/main/java/com/example/app/Report.java.scip +12 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/app/compileJava/META-INF/scip/app/src/main/java/com/example/app/Service.java.scip +34 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/app/compileJava/META-INF/scip/app/src/main/java/com/example/app/test/TestSupport.java.scip +8 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/app/compileTestJava/META-INF/scip/app/src/test/java/com/example/app/ServiceTest.java.scip +14 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Account.java.scip +20 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Entity.java.scip +18 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Gone.java.scip +10 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Group.java.scip +18 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Identifiable.java.scip +5 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Point.java.scip +11 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Session.java.scip +11 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Snapshot.java.scip +19 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Store.java.scip +15 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/SubAccount.java.scip +15 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/build/scip-targetroot/core/compileJava/META-INF/scip/core/src/main/java/com/example/model/Validator.java.scip +6 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Account.java +29 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Entity.java +28 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Group.java +18 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Identifiable.java +7 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Point.java +8 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Session.java +11 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Snapshot.java +11 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Store.java +20 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/SubAccount.java +12 -0
- scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Validator.java +6 -0
- scipq_mcp-0.1.0/tests/test_cli.py +14 -0
- scipq_mcp-0.1.0/tests/test_extras.py +233 -0
- scipq_mcp-0.1.0/tests/test_queries.py +201 -0
- scipq_mcp-0.1.0/tests/test_scip.py +69 -0
- scipq_mcp-0.1.0/tests/test_server.py +62 -0
- scipq_mcp-0.1.0/tests/test_symbols.py +66 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
One section per version published on PyPI. `scripts/release.sh` turns `## Unreleased` into the
|
|
4
|
+
version and date when releasing.
|
|
5
|
+
|
|
6
|
+
## 0.1.0 — 2026-11-22
|
|
7
|
+
|
|
8
|
+
First release.
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- MCP server (stdio) for Java code navigation over the per-file SCIP shards that the
|
|
13
|
+
scip-javac compiler plugin writes, with no index held in memory: each call greps the shards
|
|
14
|
+
and decodes only the matching protobuf messages.
|
|
15
|
+
- Tools: `setup`, `find_symbols`, `references`, `definition`, `source`, `implementations`,
|
|
16
|
+
`supertypes`, `members`, `family`, `overloads`, `outline`, `callers`, `callees`,
|
|
17
|
+
`annotated`, `typed`, `tests`, `index_status` and `batch`. All read-only, all with an optional
|
|
18
|
+
`project_root` (one server for several checkouts or worktrees), lists paginated.
|
|
19
|
+
- Names or exact SCIP symbols; JDK and library symbols resolve through their references.
|
|
20
|
+
`find_symbols` also finds by part of a name (prefix, substring, camel humps, any case), and a
|
|
21
|
+
name that matches nothing suggests the names that contain it.
|
|
22
|
+
- Freshness warnings on every answer (sources edited after their shard, files not compiled
|
|
23
|
+
yet) naming the task to recompile.
|
|
24
|
+
- `setup` tool and prompt: diagnoses a Gradle or Maven build and returns the steps to produce
|
|
25
|
+
the shards. Gradle init script template (`scipq-mcp gradle-init`) and Maven
|
|
26
|
+
compiler-plugin snippet.
|
|
27
|
+
- Idle outside Java projects: no tools are exposed there unless started with `--always`.
|
|
28
|
+
- `scipq-mcp query …` runs any tool from the command line.
|
scipq_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Germán Dressino
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
scipq_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: scipq-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for Java code navigation over the per-file SCIP shards written by scip-javac, with no index held in memory.
|
|
5
|
+
Project-URL: Homepage, https://github.com/gdressino/scipq-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/gdressino/scipq-mcp/issues
|
|
7
|
+
Author: Germán Dressino
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: code-navigation,java,lsp,mcp,model-context-protocol,scip
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Java
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: Software Development
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Requires-Dist: mcp>=1.2
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# scipq-mcp
|
|
29
|
+
|
|
30
|
+
An [MCP](https://modelcontextprotocol.io) server for navigating Java code — find symbols,
|
|
31
|
+
references, definitions, implementations, supertypes, outlines, callers and callees — that
|
|
32
|
+
reads the per-file [SCIP](https://github.com/scip-code/scip) shards `javac` writes at compile
|
|
33
|
+
time, **without loading an index into memory**.
|
|
34
|
+
|
|
35
|
+
Language servers and index-backed tools keep the whole project in the heap: on a 10,000-file
|
|
36
|
+
multi-module project that is gigabytes per checkout, multiplied by every worktree you have
|
|
37
|
+
open. scipq-mcp keeps nothing between calls. Each call:
|
|
38
|
+
|
|
39
|
+
1. greps the shards for the exact bytes the answer must contain (in parallel, PCRE when
|
|
40
|
+
available),
|
|
41
|
+
2. decodes only the matching protobuf messages of those few shards, with a small stdlib-only
|
|
42
|
+
decoder,
|
|
43
|
+
3. answers in compact text: paths relative to the project root, 1-based lines, the line of
|
|
44
|
+
code.
|
|
45
|
+
|
|
46
|
+
On that 10,000-file project: 0.1–0.3 s per query, ~65 MB resident (≈17 MB for scipq-mcp itself,
|
|
47
|
+
the rest is the MCP SDK), one server for any number of checkouts.
|
|
48
|
+
|
|
49
|
+
## Read-only by design
|
|
50
|
+
|
|
51
|
+
scipq-mcp **reads** shards, sources and (in later versions) git metadata. It never compiles,
|
|
52
|
+
never runs tests and never writes to your repository. The index is produced by the build you
|
|
53
|
+
already run; scipq-mcp consumes it. When the index is not enough (stale shards, files that
|
|
54
|
+
never compiled, a checkout that was never built) it says so and tells you what to build,
|
|
55
|
+
without running it.
|
|
56
|
+
|
|
57
|
+
## How the index is produced
|
|
58
|
+
|
|
59
|
+
The [scip-javac](https://github.com/scip-code/scip-java) compiler plugin writes one shard per
|
|
60
|
+
source file while `javac` runs:
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
<root>/build/scip-targetroot/<module>/<task>/META-INF/scip/<source path from the root>.scip
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Gradle compiles incrementally, so after an edit only the shards of what was recompiled are
|
|
67
|
+
rewritten — the index is as fresh as your last build, at no extra cost.
|
|
68
|
+
|
|
69
|
+
### Gradle
|
|
70
|
+
|
|
71
|
+
The package ships an init script that adds the plugin to every `JavaCompile` task:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
scipq-mcp gradle-init > ~/.gradle/init.d/scip-shards.init.gradle
|
|
75
|
+
# edit PROJECTS in that file to limit it to your projects (empty = every build)
|
|
76
|
+
./gradlew compileJava compileTestJava
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Or for a single build: `./gradlew build --init-script scip-shards.init.gradle`. Turn it off for
|
|
80
|
+
one run with `-Pscip=false`. It only affects local builds that load the script (CI does not see
|
|
81
|
+
`~/.gradle/init.d`). It works with Lombok and other annotation processors, and with the Gradle
|
|
82
|
+
build cache (the shards are declared as task outputs).
|
|
83
|
+
|
|
84
|
+
### Maven
|
|
85
|
+
|
|
86
|
+
Add the plugin configuration that `setup` prints (also in
|
|
87
|
+
`src/scipq_mcp/templates/maven-compiler-plugin.xml`) to `maven-compiler-plugin`, and keep any
|
|
88
|
+
other annotation processors (e.g. Lombok) listed in `annotationProcessorPaths`. Shards land in
|
|
89
|
+
`build/scip-targetroot/<artifactId>/<compile|testCompile>/` under the directory that holds
|
|
90
|
+
`.mvn/` (create an empty `.mvn/` at the repository root if there is none).
|
|
91
|
+
|
|
92
|
+
### Other builds
|
|
93
|
+
|
|
94
|
+
Any build that runs `javac` can produce the same layout: put
|
|
95
|
+
`org.scip-code:scip-javac` on the annotation processor path and pass
|
|
96
|
+
`-Xplugin:scip -sourceroot:<project root> -targetroot:<root>/build/scip-targetroot/<module>/<task>`.
|
|
97
|
+
|
|
98
|
+
### First use from an agent
|
|
99
|
+
|
|
100
|
+
An agent that has the server installed but a project without shards gets an answer that says
|
|
101
|
+
so and points to the **`setup`** tool. `setup` inspects the build (Gradle or Maven, the root
|
|
102
|
+
project name, the wrapper, init scripts already in `~/.gradle/init.d` and whether they apply)
|
|
103
|
+
and returns the exact steps with the init script or pom snippet to add. The server
|
|
104
|
+
instructions tell the agent to ask the user before changing the build. In Claude Code, the
|
|
105
|
+
`setup` prompt (`/mcp__scipq__setup`) does the same on demand.
|
|
106
|
+
|
|
107
|
+
## Install
|
|
108
|
+
|
|
109
|
+
Requirements: Python ≥ 3.11, Linux or macOS. GNU grep and GNU find are used when present
|
|
110
|
+
(much faster on large projects); otherwise scipq-mcp falls back to pure Python. On macOS,
|
|
111
|
+
`brew install grep findutils` provides them (`ggrep` is picked up automatically).
|
|
112
|
+
|
|
113
|
+
```sh
|
|
114
|
+
uvx scipq-mcp --help # run without installing
|
|
115
|
+
pipx install scipq-mcp # or install it
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
> Not on PyPI yet. Until then: `uvx --from git+https://github.com/gdressino/scipq-mcp scipq-mcp`.
|
|
119
|
+
|
|
120
|
+
### Claude Code
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
claude mcp add scipq -- uvx scipq-mcp
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Other MCP clients
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"mcpServers": {
|
|
131
|
+
"scipq": { "command": "uvx", "args": ["scipq-mcp"] }
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The server serves the project it is started in (any directory inside it). Every tool also
|
|
137
|
+
takes `project_root`, so one server can answer for several checkouts or git worktrees.
|
|
138
|
+
|
|
139
|
+
Installed for every project (user scope), it stays out of the way where it does not apply:
|
|
140
|
+
when the directory it starts in is not a Java project (no Gradle or Maven build files, no
|
|
141
|
+
shards, no `.java` sources), it exposes **no tools** and a one-line instruction, so it costs
|
|
142
|
+
no context. A Java project that was never compiled does get the tools (`setup` explains what
|
|
143
|
+
to do). Start it with `--always` to expose the tools anyway, e.g. to query other checkouts
|
|
144
|
+
through `project_root`.
|
|
145
|
+
|
|
146
|
+
Server options: `--root DIR` (default project), `--shards-dir` (default
|
|
147
|
+
`build/scip-targetroot`), `--freshness full|results|off` (see below), `--always`.
|
|
148
|
+
|
|
149
|
+
## Tools
|
|
150
|
+
|
|
151
|
+
| Tool | What it answers | Like |
|
|
152
|
+
|---|---|---|
|
|
153
|
+
| `setup` | how this project produces shards, whether they are fresh, the steps to enable them | — |
|
|
154
|
+
| `find_symbols(name, match)` | definitions by name or part of it (exact, prefix, contains, camel humps; case-insensitive) | workspace/symbol |
|
|
155
|
+
| `references(symbol, exclude_imports, by_name)` | every use, grouped by file, with the line of code and the enclosing method (imports left out for types; large results open with a summary); optionally possible uses by name in strings | findReferences |
|
|
156
|
+
| `definition(symbol)` | location, kind, signature, javadoc, what it overrides or extends | definition + hover |
|
|
157
|
+
| `source(symbol)` | the exact source of a definition, with line numbers | — |
|
|
158
|
+
| `implementations(symbol, direct_only)` | subtypes of a type or overrides of a method, at any depth; anonymous classes included | implementation |
|
|
159
|
+
| `supertypes(symbol)` | supertypes of a type, or the methods a method overrides, direct first | type hierarchy |
|
|
160
|
+
| `members(symbol, inherited)` | own and inherited members of a type, marking overrides and generated ones | — |
|
|
161
|
+
| `family(symbol)` | a method's override family (ancestors, descendants, siblings) and the uses of each | — |
|
|
162
|
+
| `overloads(symbol)` | every overload of a method and the uses of each | — |
|
|
163
|
+
| `outline(file)` | definitions in a file, nested, with signatures; takes a path or a type name | documentSymbol |
|
|
164
|
+
| `callers(symbol, depth, include_overridden)` | incoming calls grouped by enclosing method | incomingCalls |
|
|
165
|
+
| `callees(symbol, include_fields, include_types)` | methods called from a body | outgoingCalls |
|
|
166
|
+
| `annotated(annotation)` | definitions carrying an annotation, with its line (attribute values) | — |
|
|
167
|
+
| `typed(symbol, categories)` | where a type is used: fields, parameters, return types, locals, supertypes, bodies, imports | — |
|
|
168
|
+
| `tests(symbol)` | test classes that use a symbol directly, with a ready `--tests` / `-Dtest` filter | — |
|
|
169
|
+
| `index_status()` | shards per task, stale and uncompiled files, tracked files without a shard, what to recompile | — |
|
|
170
|
+
| `batch(queries)` | several of the above in one call | — |
|
|
171
|
+
|
|
172
|
+
All tools are read-only and take an optional `project_root`. Lists take `offset`/`limit` and
|
|
173
|
+
say `next offset N` when there is more.
|
|
174
|
+
|
|
175
|
+
### Naming symbols
|
|
176
|
+
|
|
177
|
+
Pass a name or an exact SCIP symbol:
|
|
178
|
+
|
|
179
|
+
| Input | Means |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `Account` | a type (or member) named `Account` |
|
|
182
|
+
| `Account#setState`, `Account.setState` | member `setState` of `Account` |
|
|
183
|
+
| `com.example.model.Account` | qualified; `/`, `.` and `#` are all accepted as separators |
|
|
184
|
+
| `setState()` | methods only, any overload |
|
|
185
|
+
| `setState(+1)` | the second overload (SCIP numbers overloads `()`, `(+1)`, `(+2)`…) |
|
|
186
|
+
| `Account#<init>` | constructors |
|
|
187
|
+
| `com/example/model/Account#setState().` | the exact symbol, as printed by `find_symbols` |
|
|
188
|
+
| `PersistenceManager#evict` | JDK and library symbols, found among the references |
|
|
189
|
+
|
|
190
|
+
A name that matches one symbol is resolved, and the answer starts with
|
|
191
|
+
`-- Account#setState → com/example/model/Account#setState().`. An ambiguous name returns the
|
|
192
|
+
candidates with their signatures instead.
|
|
193
|
+
|
|
194
|
+
## Freshness
|
|
195
|
+
|
|
196
|
+
What scipq-mcp sees is the **last compilation**. Every answer ends with a warning when:
|
|
197
|
+
|
|
198
|
+
- a source was edited after its shard was written (its results may be off), naming those that
|
|
199
|
+
appear in the answer;
|
|
200
|
+
- a `.java` file was created after the last compilation of its module and has no shard yet.
|
|
201
|
+
|
|
202
|
+
`--freshness full` (default) checks every shard against its source in parallel with the query
|
|
203
|
+
(~0.1 s on 10,000 files, mostly hidden behind the query); `results` checks only the files in
|
|
204
|
+
the answer; `off` disables it.
|
|
205
|
+
|
|
206
|
+
## Semantics and limits
|
|
207
|
+
|
|
208
|
+
- Only compiled code is visible. Shards of deleted sources are ignored.
|
|
209
|
+
- Occurrences only distinguish definitions from references: scip-javac does not record
|
|
210
|
+
read/write access.
|
|
211
|
+
- Symbols from the JDK or dependencies have references but no definition.
|
|
212
|
+
- `implementations` reports every level: scip-javac records the whole chain of supertypes on
|
|
213
|
+
each type and method. A result is *direct* unless it also implements another result.
|
|
214
|
+
- Callers: uses inside lambdas and anonymous classes count for the enclosing method; field
|
|
215
|
+
initializers for the field; initializer blocks (static or instance) for the class.
|
|
216
|
+
- Lombok: generated members are located at the node that generates them (the field, or a
|
|
217
|
+
class-level `@Getter`/`@Setter`) and marked *generated*; the references inside generated
|
|
218
|
+
bodies are left out.
|
|
219
|
+
- `references(by_name=true)` lists, separately, lines where the name (or its bean property
|
|
220
|
+
name) appears inside string literals or other files: map keys, query strings, templates. The
|
|
221
|
+
index cannot see those; check them by hand.
|
|
222
|
+
|
|
223
|
+
## Command line
|
|
224
|
+
|
|
225
|
+
Besides `serve` (the default) and `gradle-init`, `scipq-mcp query` runs any tool from the shell,
|
|
226
|
+
for debugging or scripts:
|
|
227
|
+
|
|
228
|
+
```sh
|
|
229
|
+
scipq-mcp query --root ~/src/project refs 'Account#setState'
|
|
230
|
+
scipq-mcp query impl Entity --direct
|
|
231
|
+
scipq-mcp query callers 'Entity#setState()' --depth 2
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## Development
|
|
235
|
+
|
|
236
|
+
```sh
|
|
237
|
+
uv venv && uv pip install -e . pytest
|
|
238
|
+
.venv/bin/python -m pytest
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
`tests/fixtures/sample` is a small two-module Java project; its shards are checked in, so the
|
|
242
|
+
tests need no JDK. To regenerate them (JDK 17+): `tests/fixtures/build-sample.sh`.
|
|
243
|
+
|
|
244
|
+
Design notes and the roadmap: [docs/design.md](docs/design.md).
|
|
245
|
+
|
|
246
|
+
### Releasing
|
|
247
|
+
|
|
248
|
+
Releases are published by GitHub Actions with
|
|
249
|
+
[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/): no API token exists in
|
|
250
|
+
the repository, its secrets, or anyone's machine.
|
|
251
|
+
|
|
252
|
+
1. Describe the changes under `## Unreleased` in `CHANGELOG.md` and commit.
|
|
253
|
+
2. `scripts/release.sh [VERSION]` — sets the version, dates the changelog, runs the tests,
|
|
254
|
+
commits and tags `vVERSION`.
|
|
255
|
+
3. `git push origin main vVERSION` — the `release` workflow tests, builds and publishes.
|
|
256
|
+
|
|
257
|
+
## License
|
|
258
|
+
|
|
259
|
+
MIT
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# scipq-mcp
|
|
2
|
+
|
|
3
|
+
An [MCP](https://modelcontextprotocol.io) server for navigating Java code — find symbols,
|
|
4
|
+
references, definitions, implementations, supertypes, outlines, callers and callees — that
|
|
5
|
+
reads the per-file [SCIP](https://github.com/scip-code/scip) shards `javac` writes at compile
|
|
6
|
+
time, **without loading an index into memory**.
|
|
7
|
+
|
|
8
|
+
Language servers and index-backed tools keep the whole project in the heap: on a 10,000-file
|
|
9
|
+
multi-module project that is gigabytes per checkout, multiplied by every worktree you have
|
|
10
|
+
open. scipq-mcp keeps nothing between calls. Each call:
|
|
11
|
+
|
|
12
|
+
1. greps the shards for the exact bytes the answer must contain (in parallel, PCRE when
|
|
13
|
+
available),
|
|
14
|
+
2. decodes only the matching protobuf messages of those few shards, with a small stdlib-only
|
|
15
|
+
decoder,
|
|
16
|
+
3. answers in compact text: paths relative to the project root, 1-based lines, the line of
|
|
17
|
+
code.
|
|
18
|
+
|
|
19
|
+
On that 10,000-file project: 0.1–0.3 s per query, ~65 MB resident (≈17 MB for scipq-mcp itself,
|
|
20
|
+
the rest is the MCP SDK), one server for any number of checkouts.
|
|
21
|
+
|
|
22
|
+
## Read-only by design
|
|
23
|
+
|
|
24
|
+
scipq-mcp **reads** shards, sources and (in later versions) git metadata. It never compiles,
|
|
25
|
+
never runs tests and never writes to your repository. The index is produced by the build you
|
|
26
|
+
already run; scipq-mcp consumes it. When the index is not enough (stale shards, files that
|
|
27
|
+
never compiled, a checkout that was never built) it says so and tells you what to build,
|
|
28
|
+
without running it.
|
|
29
|
+
|
|
30
|
+
## How the index is produced
|
|
31
|
+
|
|
32
|
+
The [scip-javac](https://github.com/scip-code/scip-java) compiler plugin writes one shard per
|
|
33
|
+
source file while `javac` runs:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
<root>/build/scip-targetroot/<module>/<task>/META-INF/scip/<source path from the root>.scip
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Gradle compiles incrementally, so after an edit only the shards of what was recompiled are
|
|
40
|
+
rewritten — the index is as fresh as your last build, at no extra cost.
|
|
41
|
+
|
|
42
|
+
### Gradle
|
|
43
|
+
|
|
44
|
+
The package ships an init script that adds the plugin to every `JavaCompile` task:
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
scipq-mcp gradle-init > ~/.gradle/init.d/scip-shards.init.gradle
|
|
48
|
+
# edit PROJECTS in that file to limit it to your projects (empty = every build)
|
|
49
|
+
./gradlew compileJava compileTestJava
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Or for a single build: `./gradlew build --init-script scip-shards.init.gradle`. Turn it off for
|
|
53
|
+
one run with `-Pscip=false`. It only affects local builds that load the script (CI does not see
|
|
54
|
+
`~/.gradle/init.d`). It works with Lombok and other annotation processors, and with the Gradle
|
|
55
|
+
build cache (the shards are declared as task outputs).
|
|
56
|
+
|
|
57
|
+
### Maven
|
|
58
|
+
|
|
59
|
+
Add the plugin configuration that `setup` prints (also in
|
|
60
|
+
`src/scipq_mcp/templates/maven-compiler-plugin.xml`) to `maven-compiler-plugin`, and keep any
|
|
61
|
+
other annotation processors (e.g. Lombok) listed in `annotationProcessorPaths`. Shards land in
|
|
62
|
+
`build/scip-targetroot/<artifactId>/<compile|testCompile>/` under the directory that holds
|
|
63
|
+
`.mvn/` (create an empty `.mvn/` at the repository root if there is none).
|
|
64
|
+
|
|
65
|
+
### Other builds
|
|
66
|
+
|
|
67
|
+
Any build that runs `javac` can produce the same layout: put
|
|
68
|
+
`org.scip-code:scip-javac` on the annotation processor path and pass
|
|
69
|
+
`-Xplugin:scip -sourceroot:<project root> -targetroot:<root>/build/scip-targetroot/<module>/<task>`.
|
|
70
|
+
|
|
71
|
+
### First use from an agent
|
|
72
|
+
|
|
73
|
+
An agent that has the server installed but a project without shards gets an answer that says
|
|
74
|
+
so and points to the **`setup`** tool. `setup` inspects the build (Gradle or Maven, the root
|
|
75
|
+
project name, the wrapper, init scripts already in `~/.gradle/init.d` and whether they apply)
|
|
76
|
+
and returns the exact steps with the init script or pom snippet to add. The server
|
|
77
|
+
instructions tell the agent to ask the user before changing the build. In Claude Code, the
|
|
78
|
+
`setup` prompt (`/mcp__scipq__setup`) does the same on demand.
|
|
79
|
+
|
|
80
|
+
## Install
|
|
81
|
+
|
|
82
|
+
Requirements: Python ≥ 3.11, Linux or macOS. GNU grep and GNU find are used when present
|
|
83
|
+
(much faster on large projects); otherwise scipq-mcp falls back to pure Python. On macOS,
|
|
84
|
+
`brew install grep findutils` provides them (`ggrep` is picked up automatically).
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
uvx scipq-mcp --help # run without installing
|
|
88
|
+
pipx install scipq-mcp # or install it
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
> Not on PyPI yet. Until then: `uvx --from git+https://github.com/gdressino/scipq-mcp scipq-mcp`.
|
|
92
|
+
|
|
93
|
+
### Claude Code
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
claude mcp add scipq -- uvx scipq-mcp
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Other MCP clients
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"mcpServers": {
|
|
104
|
+
"scipq": { "command": "uvx", "args": ["scipq-mcp"] }
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The server serves the project it is started in (any directory inside it). Every tool also
|
|
110
|
+
takes `project_root`, so one server can answer for several checkouts or git worktrees.
|
|
111
|
+
|
|
112
|
+
Installed for every project (user scope), it stays out of the way where it does not apply:
|
|
113
|
+
when the directory it starts in is not a Java project (no Gradle or Maven build files, no
|
|
114
|
+
shards, no `.java` sources), it exposes **no tools** and a one-line instruction, so it costs
|
|
115
|
+
no context. A Java project that was never compiled does get the tools (`setup` explains what
|
|
116
|
+
to do). Start it with `--always` to expose the tools anyway, e.g. to query other checkouts
|
|
117
|
+
through `project_root`.
|
|
118
|
+
|
|
119
|
+
Server options: `--root DIR` (default project), `--shards-dir` (default
|
|
120
|
+
`build/scip-targetroot`), `--freshness full|results|off` (see below), `--always`.
|
|
121
|
+
|
|
122
|
+
## Tools
|
|
123
|
+
|
|
124
|
+
| Tool | What it answers | Like |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| `setup` | how this project produces shards, whether they are fresh, the steps to enable them | — |
|
|
127
|
+
| `find_symbols(name, match)` | definitions by name or part of it (exact, prefix, contains, camel humps; case-insensitive) | workspace/symbol |
|
|
128
|
+
| `references(symbol, exclude_imports, by_name)` | every use, grouped by file, with the line of code and the enclosing method (imports left out for types; large results open with a summary); optionally possible uses by name in strings | findReferences |
|
|
129
|
+
| `definition(symbol)` | location, kind, signature, javadoc, what it overrides or extends | definition + hover |
|
|
130
|
+
| `source(symbol)` | the exact source of a definition, with line numbers | — |
|
|
131
|
+
| `implementations(symbol, direct_only)` | subtypes of a type or overrides of a method, at any depth; anonymous classes included | implementation |
|
|
132
|
+
| `supertypes(symbol)` | supertypes of a type, or the methods a method overrides, direct first | type hierarchy |
|
|
133
|
+
| `members(symbol, inherited)` | own and inherited members of a type, marking overrides and generated ones | — |
|
|
134
|
+
| `family(symbol)` | a method's override family (ancestors, descendants, siblings) and the uses of each | — |
|
|
135
|
+
| `overloads(symbol)` | every overload of a method and the uses of each | — |
|
|
136
|
+
| `outline(file)` | definitions in a file, nested, with signatures; takes a path or a type name | documentSymbol |
|
|
137
|
+
| `callers(symbol, depth, include_overridden)` | incoming calls grouped by enclosing method | incomingCalls |
|
|
138
|
+
| `callees(symbol, include_fields, include_types)` | methods called from a body | outgoingCalls |
|
|
139
|
+
| `annotated(annotation)` | definitions carrying an annotation, with its line (attribute values) | — |
|
|
140
|
+
| `typed(symbol, categories)` | where a type is used: fields, parameters, return types, locals, supertypes, bodies, imports | — |
|
|
141
|
+
| `tests(symbol)` | test classes that use a symbol directly, with a ready `--tests` / `-Dtest` filter | — |
|
|
142
|
+
| `index_status()` | shards per task, stale and uncompiled files, tracked files without a shard, what to recompile | — |
|
|
143
|
+
| `batch(queries)` | several of the above in one call | — |
|
|
144
|
+
|
|
145
|
+
All tools are read-only and take an optional `project_root`. Lists take `offset`/`limit` and
|
|
146
|
+
say `next offset N` when there is more.
|
|
147
|
+
|
|
148
|
+
### Naming symbols
|
|
149
|
+
|
|
150
|
+
Pass a name or an exact SCIP symbol:
|
|
151
|
+
|
|
152
|
+
| Input | Means |
|
|
153
|
+
|---|---|
|
|
154
|
+
| `Account` | a type (or member) named `Account` |
|
|
155
|
+
| `Account#setState`, `Account.setState` | member `setState` of `Account` |
|
|
156
|
+
| `com.example.model.Account` | qualified; `/`, `.` and `#` are all accepted as separators |
|
|
157
|
+
| `setState()` | methods only, any overload |
|
|
158
|
+
| `setState(+1)` | the second overload (SCIP numbers overloads `()`, `(+1)`, `(+2)`…) |
|
|
159
|
+
| `Account#<init>` | constructors |
|
|
160
|
+
| `com/example/model/Account#setState().` | the exact symbol, as printed by `find_symbols` |
|
|
161
|
+
| `PersistenceManager#evict` | JDK and library symbols, found among the references |
|
|
162
|
+
|
|
163
|
+
A name that matches one symbol is resolved, and the answer starts with
|
|
164
|
+
`-- Account#setState → com/example/model/Account#setState().`. An ambiguous name returns the
|
|
165
|
+
candidates with their signatures instead.
|
|
166
|
+
|
|
167
|
+
## Freshness
|
|
168
|
+
|
|
169
|
+
What scipq-mcp sees is the **last compilation**. Every answer ends with a warning when:
|
|
170
|
+
|
|
171
|
+
- a source was edited after its shard was written (its results may be off), naming those that
|
|
172
|
+
appear in the answer;
|
|
173
|
+
- a `.java` file was created after the last compilation of its module and has no shard yet.
|
|
174
|
+
|
|
175
|
+
`--freshness full` (default) checks every shard against its source in parallel with the query
|
|
176
|
+
(~0.1 s on 10,000 files, mostly hidden behind the query); `results` checks only the files in
|
|
177
|
+
the answer; `off` disables it.
|
|
178
|
+
|
|
179
|
+
## Semantics and limits
|
|
180
|
+
|
|
181
|
+
- Only compiled code is visible. Shards of deleted sources are ignored.
|
|
182
|
+
- Occurrences only distinguish definitions from references: scip-javac does not record
|
|
183
|
+
read/write access.
|
|
184
|
+
- Symbols from the JDK or dependencies have references but no definition.
|
|
185
|
+
- `implementations` reports every level: scip-javac records the whole chain of supertypes on
|
|
186
|
+
each type and method. A result is *direct* unless it also implements another result.
|
|
187
|
+
- Callers: uses inside lambdas and anonymous classes count for the enclosing method; field
|
|
188
|
+
initializers for the field; initializer blocks (static or instance) for the class.
|
|
189
|
+
- Lombok: generated members are located at the node that generates them (the field, or a
|
|
190
|
+
class-level `@Getter`/`@Setter`) and marked *generated*; the references inside generated
|
|
191
|
+
bodies are left out.
|
|
192
|
+
- `references(by_name=true)` lists, separately, lines where the name (or its bean property
|
|
193
|
+
name) appears inside string literals or other files: map keys, query strings, templates. The
|
|
194
|
+
index cannot see those; check them by hand.
|
|
195
|
+
|
|
196
|
+
## Command line
|
|
197
|
+
|
|
198
|
+
Besides `serve` (the default) and `gradle-init`, `scipq-mcp query` runs any tool from the shell,
|
|
199
|
+
for debugging or scripts:
|
|
200
|
+
|
|
201
|
+
```sh
|
|
202
|
+
scipq-mcp query --root ~/src/project refs 'Account#setState'
|
|
203
|
+
scipq-mcp query impl Entity --direct
|
|
204
|
+
scipq-mcp query callers 'Entity#setState()' --depth 2
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Development
|
|
208
|
+
|
|
209
|
+
```sh
|
|
210
|
+
uv venv && uv pip install -e . pytest
|
|
211
|
+
.venv/bin/python -m pytest
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`tests/fixtures/sample` is a small two-module Java project; its shards are checked in, so the
|
|
215
|
+
tests need no JDK. To regenerate them (JDK 17+): `tests/fixtures/build-sample.sh`.
|
|
216
|
+
|
|
217
|
+
Design notes and the roadmap: [docs/design.md](docs/design.md).
|
|
218
|
+
|
|
219
|
+
### Releasing
|
|
220
|
+
|
|
221
|
+
Releases are published by GitHub Actions with
|
|
222
|
+
[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/): no API token exists in
|
|
223
|
+
the repository, its secrets, or anyone's machine.
|
|
224
|
+
|
|
225
|
+
1. Describe the changes under `## Unreleased` in `CHANGELOG.md` and commit.
|
|
226
|
+
2. `scripts/release.sh [VERSION]` — sets the version, dates the changelog, runs the tests,
|
|
227
|
+
commits and tags `vVERSION`.
|
|
228
|
+
3. `git push origin main vVERSION` — the `release` workflow tests, builds and publishes.
|
|
229
|
+
|
|
230
|
+
## License
|
|
231
|
+
|
|
232
|
+
MIT
|