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.
Files changed (59) hide show
  1. scipq_mcp-0.1.0/.gitignore +12 -0
  2. scipq_mcp-0.1.0/CHANGELOG.md +28 -0
  3. scipq_mcp-0.1.0/LICENSE +21 -0
  4. scipq_mcp-0.1.0/PKG-INFO +259 -0
  5. scipq_mcp-0.1.0/README.md +232 -0
  6. scipq_mcp-0.1.0/docs/design.md +199 -0
  7. scipq_mcp-0.1.0/pyproject.toml +53 -0
  8. scipq_mcp-0.1.0/src/scipq_mcp/__init__.py +3 -0
  9. scipq_mcp-0.1.0/src/scipq_mcp/__main__.py +3 -0
  10. scipq_mcp-0.1.0/src/scipq_mcp/cli.py +147 -0
  11. scipq_mcp-0.1.0/src/scipq_mcp/extras.py +551 -0
  12. scipq_mcp-0.1.0/src/scipq_mcp/queries.py +706 -0
  13. scipq_mcp-0.1.0/src/scipq_mcp/render.py +514 -0
  14. scipq_mcp-0.1.0/src/scipq_mcp/scip.py +546 -0
  15. scipq_mcp-0.1.0/src/scipq_mcp/server.py +350 -0
  16. scipq_mcp-0.1.0/src/scipq_mcp/service.py +436 -0
  17. scipq_mcp-0.1.0/src/scipq_mcp/setup.py +244 -0
  18. scipq_mcp-0.1.0/src/scipq_mcp/symbols.py +408 -0
  19. scipq_mcp-0.1.0/src/scipq_mcp/templates/maven-compiler-plugin.xml +38 -0
  20. scipq_mcp-0.1.0/src/scipq_mcp/templates/scip-shards.init.gradle +49 -0
  21. scipq_mcp-0.1.0/src/scipq_mcp/workspace.py +574 -0
  22. scipq_mcp-0.1.0/tests/conftest.py +29 -0
  23. scipq_mcp-0.1.0/tests/fixtures/build-sample.sh +78 -0
  24. scipq_mcp-0.1.0/tests/fixtures/orphan/Gone.java +10 -0
  25. scipq_mcp-0.1.0/tests/fixtures/sample/app/src/main/java/com/example/app/Report.java +20 -0
  26. scipq_mcp-0.1.0/tests/fixtures/sample/app/src/main/java/com/example/app/Service.java +52 -0
  27. scipq_mcp-0.1.0/tests/fixtures/sample/app/src/main/java/com/example/app/test/TestSupport.java +10 -0
  28. scipq_mcp-0.1.0/tests/fixtures/sample/app/src/test/java/com/example/app/ServiceTest.java +15 -0
  29. 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
  30. 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
  31. 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
  32. 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
  33. 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
  34. 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
  35. 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
  36. 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
  37. 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
  38. 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
  39. 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
  40. 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
  41. 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
  42. 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
  43. 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
  44. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Account.java +29 -0
  45. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Entity.java +28 -0
  46. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Group.java +18 -0
  47. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Identifiable.java +7 -0
  48. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Point.java +8 -0
  49. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Session.java +11 -0
  50. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Snapshot.java +11 -0
  51. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Store.java +20 -0
  52. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/SubAccount.java +12 -0
  53. scipq_mcp-0.1.0/tests/fixtures/sample/core/src/main/java/com/example/model/Validator.java +6 -0
  54. scipq_mcp-0.1.0/tests/test_cli.py +14 -0
  55. scipq_mcp-0.1.0/tests/test_extras.py +233 -0
  56. scipq_mcp-0.1.0/tests/test_queries.py +201 -0
  57. scipq_mcp-0.1.0/tests/test_scip.py +69 -0
  58. scipq_mcp-0.1.0/tests/test_server.py +62 -0
  59. scipq_mcp-0.1.0/tests/test_symbols.py +66 -0
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .coverage
10
+ # The test fixtures ship their SCIP shards; the jars used to regenerate them do not.
11
+ !tests/fixtures/sample/build/
12
+ tests/fixtures/.jars/
@@ -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.
@@ -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.
@@ -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