Lincoln-cn/JCodeIndexer
GitHub: Lincoln-cn/JCodeIndexer
通过在 AST 级别索引 Java 代码并以 MCP Server 暴露查询接口，帮助 AI 编程助手高效理解陌生项目结构并大幅节省 token 消耗。
Stars: 1 | Forks: 0
# Java 代码索引器
[中文](README.zh-CN.md) | English
## 为什么需要
如今，AI 编程助手在探索一个陌生的 Java 项目时：
| 任务 | 不使用 Java Code Indexer | 使用 Java Code Indexer |
|------|--------------------------|----------------------|
| 查找 `UserService` 的定义位置 | 跨 100 多个文件执行 `grep`（约 1.5 万 token） | `find_symbol("UserService")`（约 200 token） |
| 了解 `saveOrder()` 的所有调用者 | 逐一阅读文件（约 8 千 token） | `get_call_graph("saveOrder", "callers")`（约 500 token） |
| 在 YAML/properties 中查找配置值 | 使用 `find` + `cat` 检索多个配置文件（约 5 千 token） | `search_config("spring.datasource.url")`（约 200 token） |
| 定位所有依赖 | 打开 pom.xml + 传递依赖（约 3 千 token） | `find_dependencies("spring-boot-starter")`（约 300 token） |
## 安装
需要 **Java 21+**（JRE 或 JDK）。Docker 和 Native Image 选项自带运行时。
**选项 1：下载 JAR（推荐）**
```
# 从 GitHub Releases 下载
curl -LO https://github.com/sodlinken/java-code-indexer/releases/latest/download/java-code-indexer-latest.jar
```
**选项 2：从源码构建**（需要 Java 21+ 和 Maven 3.8+）
```
git clone https://github.com/sodlinken/java-code-indexer.git
cd java-code-indexer
mvn package -q -DskipTests
# 输出：target/java-code-indexer-*-shaded.jar
```
**选项 3：Native Image (GraalVM)**
```
native-image -jar target/java-code-indexer-*-shaded.jar \
-o jindexer --no-fallback
```
**选项 4：Docker**
```
docker pull ghcr.io/sodlinken/java-code-indexer:latest
```
## 快速开始
```
# 1. 索引你的 Java 项目
java -jar jindexer.jar --project-root /path/to/your/java-project --index
# 2. 启动 MCP 服务器 (stdio，适用于 Claude Code / Qwen Code / Cursor)
java -jar jindexer.jar --project-root /path/to/your/java-project
```
就是这样。你的 AI 助手现在可以直接查询你的代码库结构，而无需阅读文件。
## CLI 参考
```
java -jar jindexer.jar [options]
Options:
--project-root Java project root directory (default: current dir)
--data-dir Index data directory (default: .jindexer)
--init Initialize database schema only
--index Run indexer (extract symbols/references/calls)
--help, -h Show help
No flags → start MCP server over stdio.
```
## MCP 工具
作为 MCP 服务器运行时，Java Code Indexer 会暴露以下工具：
| 工具 | 描述 |
|------|-------------|
| `find_symbol` | 按名称查找符号（类/方法/字段），支持 `*` 通配符 |
| `find_references` | 查找某个符号的所有引用位置 |
| `get_call_graph` | 方法调用关系图——调用者、被调用者或两者 |
| `search_code` | 搜索符号名称和代码内容 |
| `get_file_info` | 文件详情：符号、代码块、调用关系 |
| `search_config` | 搜索配置文件（YAML / Properties / .env） |
| `find_dependencies` | 搜索项目依赖（Maven / Gradle） |
| `semantic_search` | 语义搜索（需要 Embedding 配置，尚未激活） |
| `list_projects` | 列出已索引的项目（仅限多项目模式） |
## 配置
在你的项目根目录下创建 `.jindexer/config.yaml`（可选）：
```
project_root: /path/to/project
data_dir: .jindexer
threads: 4
embedding:
enabled: false
```
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `INDEXER_EMBEDDING_ENABLED` | 启用 Embedding API | `false` |
| `INDEXER_EMBEDDING_BASE_URL` | Embedding API endpoint | — |
| `INDEXER_EMBEDDING_MODEL` | Embedding 模型名称 | — |
| `INDEXER_THREADS` | 索引线程数 | `4` |
| `INDEXER_LOG_LEVEL` | 日志级别 | `INFO` |
优先级：CLI flags → 环境变量 → 配置文件 → 默认值。
## AI 助手集成
### Qwen Code / Claude Desktop / Cursor
添加到你的 MCP 配置中：
```
{
"mcpServers": {
"java-code-indexer": {
"command": "/path/to/jdk-21/bin/java",
"args": ["-jar", "/path/to/jindexer.jar", "--project-root", "/path/to/project"]
}
}
}
```
## 工作原理
```
┌──────────────┐ MCP (stdio) ┌──────────────────────┐
│ AI Assistant │ ◄─────────────────► │ Java Code Indexer │
│ (Qwen/Claude)│ JSON-RPC │ │
└──────────────┘ │ ┌────────────────┐ │
│ │ JavaParser AST │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ SQLite (WAL) │ │
│ │ symbols │ │
│ │ references │ │
│ │ call_graphs │ │
│ │ configs │ │
│ │ dependencies │ │
│ └────────────────┘ │
└──────────────────────┘
```
### 索引策略
1. 通过文件系统遍历访问 Java 源码文件
2. 通过 SHA-1 内容哈希跳过未更改的文件（增量索引）
3. JavaParser AST 提取符号、引用和调用关系
4. POM/Gradle 解析器提取依赖信息
5. 配置解析器提取 YAML/Properties/.env 条目
6. 将所有数据 upsert 到内嵌的 SQLite 中（WAL 模式）
### 数据库 Schema
五个核心表：
- **`symbols`** — 类、方法、字段及其位置和签名
- **`references`** — 跨代码库的符号使用位置
- **`calls`** — 方法调用关系（caller → callee）
- **`chunks`** — 类/方法粒度的代码切片
- **`file_hashes`** — 用于增量索引的 SHA-1 哈希值
## 架构
```
src/main/java/com/sodlinken/jindexer/
├── cli/ # CLI entry point
├── mcp/ # MCP server (JSON-RPC over stdio)
├── config/ # YAML config loader
├── storage/ # SQLite schema & StorageService
├── indexer/ # Incremental indexing engine
├── parser/ # Java, POM, Gradle, Config parsers
├── chunker/ # Code chunking (class/method slices)
├── search/ # Structured search provider
├── model/ # Data models (Symbol, Call, Chunk, etc.)
└── util/ # SHA-1 hashing utility
```
## 分发
产物输出到 `release//` 目录。
### 一键构建
```
# 构建 Fat JAR + Native Image
./script/release.sh
# 指定版本号
./script/release.sh -v 1.0.0
# 跳过 Native Image
./script/release.sh -v 1.0.0 --skip-native
```
### Fat JAR
构建产物位于 `release//java-code-indexer-.jar`，需 Java 21+。
```
java -jar release/1.0.0/java-code-indexer-1.0.0.jar --project-root /path/to/project
```
### Native Image (GraalVM)
构建产物位于 `release//jindexer`，无需 JVM，启动即时。
```
./release/1.0.0/jindexer --project-root /path/to/project --index
```
### Docker
```
# 本地构建并运行
docker build -t java-code-indexer .
docker run --rm -v /path/to/project:/project java-code-indexer --project-root /project --index
# 推送到私有 registry
DOCKER_REGISTRY=your-registry.com ./script/release.sh --push-docker
```
## 开发
```
# 克隆并构建
git clone https://github.com/sodlinken/java-code-indexer.git
cd java-code-indexer
mvn package -q -DskipTests
# 索引该项目本身
java -jar target/java-code-indexer-*-shaded.jar \
--project-root . --index
# 启动 MCP 服务器
java -jar target/java-code-indexer-*-shaded.jar --project-root .
```
## 它不是什么
- 不是代码执行沙箱
- 不是测试运行器或 linter
- 不能替代 LSP/IDE 功能
- 不是 AI 生成的摘要（符号提取是确定性的）
## License
[Apache License 2.0](LICENSE)
标签：AI辅助编程, JS文件枚举, MCP, SOC Prime, SQLite, 云安全监控, 代码索引, 域名枚举, 开发工具, 请求拦截, 静态分析