# java-memory-index-mcp

**Repository Path**: suveng/java-memory-index-mcp

## Basic Information

- **Project Name**: java-memory-index-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-29
- **Last Updated**: 2025-11-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java MCP Server

一个基于 Model Context Protocol (MCP) 的 Java 项目代码索引和查询服务器，为 LLM 提供深度理解 Java 项目结构的能力。

## 📋 项目简介

Java MCP Server 是一个专为 Java 项目设计的 MCP 服务器，它能够：

- **智能索引**：自动扫描和索引 Java 源代码、字节码和 Maven 依赖
- **语义搜索**：基于 Lucene 的全文搜索，支持类名、方法名、字段名、注释和元数据搜索
- **关系分析**：构建类继承、实现、使用关系图和方法调用图
- **框架感知**：自动识别 Spring Boot 的 HTTP 端点、消息队列消费者/生产者和定时任务
- **依赖管理**：选择性索引项目实际使用的二方库，避免索引整个依赖树

## ✨ 核心功能

### 1. 代码搜索 (`search_code`)
全文搜索项目代码库，支持在类名、方法名、字段名、方法签名、Javadoc 注释和元数据中搜索关键字。

### 2. 端点查找 (`find_endpoint`)
根据 URL 路径片段或 HTTP 方法查找 Spring MVC/Spring Boot 的 REST 端点。

### 3. 消息队列消费者查找 (`find_consumer`)
查找监听指定 Topic 或 Queue 的消费者方法，支持 Kafka、RabbitMQ、JMS 等框架。

### 4. 消息队列生产者查找 (`find_producer`)
查找向指定 Topic 或 Queue 发送消息的生产者方法。

### 5. 代码关系查询 (`find_relationships`)
查询类或方法之间的各种关系：
- `subclasses` - 子类
- `superclasses` - 父类
- `implementations` - 实现类
- `usages` - 使用该类的类
- `callers` - 调用者
- `callees` - 被调用者

### 6. 定时任务查找 (`find_job`)
查找 Spring 的定时任务方法（通过 `@Scheduled` 注解识别）。

### 7. 依赖信息查询
- `get_dependency_info` - 查询外部依赖的基本信息（轻量级）
- `get_dependency_details` - 查询外部依赖的详细结构信息（类、方法、字段列表）

### 8. 索引重建 (`rebuild_index`)
手动触发项目代码索引的增量更新或完整重建。

## 🛠️ 技术栈

- **Java 21** - 编程语言
- **Maven** - 构建工具
- **Apache Lucene 9.9.1** - 全文搜索引擎
- **JavaParser 3.25.7** - Java 源码解析
- **ClassGraph 4.8.165** - 字节码扫描和类路径分析
- **JGraphT 1.5.2** - 图结构存储（关系图）
- **MCP Java SDK** - Model Context Protocol 官方 SDK
- **SLF4J + Logback** - 日志框架

## 📦 构建项目

### 前置要求

- JDK 21 或更高版本
- Maven 3.6 或更高版本

### 构建步骤

```bash
# 克隆项目
git clone <repository-url>
cd java_mcp

# 编译项目
mvn clean compile

# 运行测试
mvn test

# 打包为可执行 JAR
mvn clean package

# 构建后的 JAR 文件位于
# target/java-mcp-server-1.0.0-SNAPSHOT.jar
```

## 🚀 使用方法

### 命令行运行

```bash
java -jar target/java-mcp-server-1.0.0-SNAPSHOT.jar \
  --root /path/to/your/java/project \
  [--index-path /path/to/index] \
  [--exclude target,build,.git] \
  [--log-level INFO]
```

### 参数说明

- `--root` / `-r` (必需): Java 项目根目录（绝对路径）
- `--index-path` / `-i` (可选): 索引存储目录，默认为 `<root>/.mcp-index/`
- `--exclude` / `-e` (可选): 排除的目录列表（逗号分隔），默认为 `target,build,.git,.idea`
- `--log-level` / `-l` (可选): 日志级别（DEBUG, INFO, WARN, ERROR），默认为 INFO

## 🔧 MCP 客户端配置

### Cursor IDE 配置

在项目根目录或全局配置文件中创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "java-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "E:/code/java_mcp/target/java-mcp-server-1.0.0-SNAPSHOT.jar",
        "--root",
        "E:/code/java_mcp",
        "--exclude",
        "target,build,.git,.idea",
        "--log-level",
        "INFO"
      ],
      "env": {
        "JAVA_HOME": "C:/Program Files/Java/jdk-21"
      }
    }
  }
}
```

**重要提示**：
- JAR 包路径和项目根目录必须使用**绝对路径**
- Windows 路径使用正斜杠 `/` 或双反斜杠 `\\`
- 确保 JAR 文件已构建：`mvn clean package`

### Claude Desktop 配置

根据操作系统，编辑配置文件：

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "java-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/java-mcp-server-1.0.0-SNAPSHOT.jar",
        "--root",
        "/path/to/your/java/project",
        "--exclude",
        "target,build",
        "--log-level",
        "INFO"
      ],
      "env": {
        "JAVA_HOME": "/path/to/jdk-21"
      }
    }
  }
}
```

配置完成后，重启客户端使配置生效。

## 📁 项目结构

```
java_mcp/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/javamcp/
│   │   │       ├── Main.java                    # 主入口类
│   │   │       ├── ServerConfig.java            # 命令行配置
│   │   │       ├── IndexItem.java               # 索引项数据结构
│   │   │       ├── ItemType.java                # 索引项类型枚举
│   │   │       ├── index/                       # 索引引擎
│   │   │       │   ├── ProjectIndexer.java      # 项目索引器（主控制器）
│   │   │       │   ├── JavaSourceIndexer.java   # Java 源码索引器
│   │   │       │   ├── BytecodeScanner.java     # 字节码扫描器
│   │   │       │   ├── DependencyJarIndexer.java # 依赖 JAR 索引器
│   │   │       │   ├── LuceneIndex.java         # Lucene 索引封装
│   │   │       │   ├── RelationshipGraph.java   # 关系图存储
│   │   │       │   └── ...
│   │   │       └── mcp/                         # MCP 协议实现
│   │   │           ├── ToolHandlers.java        # 工具处理器工厂
│   │   │           └── tools/                   # 各个工具的处理器
│   │   │               ├── SearchCodeToolHandler.java
│   │   │               ├── FindEndpointToolHandler.java
│   │   │               └── ...
│   │   └── resources/
│   │       └── logback.xml                      # 日志配置
│   └── test/                                    # 测试代码
├── pom.xml                                      # Maven 配置文件
├── doc/                                         # 文档目录
│   └── mcp_configuration.md                    # MCP 配置指南
└── README.md                                    # 本文件
```

## 🔍 索引机制

### 源码索引

使用 JavaParser 解析 `.java` 文件，提取：
- 类、接口、枚举、记录
- 方法、字段
- Javadoc 注释
- 注解信息
- 方法调用关系

### 字节码索引

使用 ClassGraph 扫描 JAR 文件，提取：
- 类层次结构
- 方法签名
- 字段信息
- 注解使用情况

### 选择性依赖索引

**阶段 1: 依赖发现**
1. 解析 `pom.xml` 获取所有依赖列表
2. 使用 Maven Resolver API 解析依赖

**阶段 2: 引用分析**
1. 扫描项目源码，收集所有外部类引用
2. 构建"被引用类集合"

**阶段 3: 选择性索引**
1. 仅对"被引用类集合"中的类进行索引
2. 避免索引整个依赖树，提高效率

### 增量索引

- 跟踪文件修改时间和哈希值
- 仅重新索引变更的文件
- 支持增量更新和完整重建

## 🐛 故障排查

### 服务器无法启动

- 检查 Java 版本是否为 21+: `java -version`
- 检查 JAR 包路径是否正确
- 检查项目根目录路径是否存在

### 索引失败

- 查看日志文件: `.mcp-index/server.log`
- 确保项目目录有读写权限
- 尝试手动运行: `java -jar mcp-server.jar --root /path/to/project`

### 工具不可用

- 确认服务器已成功启动并完成索引
- 检查客户端日志
- 尝试调用 `rebuild_index` 工具重建索引

## 📝 开发规范

### 代码设计原则

- 遵循 SOLID 原则
- 单一职责、开闭原则、依赖倒置、接口隔离
- DRY（Don't Repeat Yourself）
- KISS（Keep It Simple, Stupid）
- YAGNI（You Aren't Gonna Need It）

### 代码实现规范

- 代码必须写中文注释
- 一个文件不能超过 500 行
- 使用中文进行文档和注释

## 📄 许可证

[待添加许可证信息]

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📚 相关文档

- [MCP 配置指南](doc/mcp_configuration.md)
- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)