jcgraph 0.2.2

Java代码知识图谱构建工具 - 基于语义分析的 Java 项目理解和查询工具，支持 MCP Server

jcgraph

Java 代码知识图谱构建工具 - 基于语义分析的 Java 项目理解和查询工具

jcgraph 通过静态分析构建 Java 代码的知识图谱，支持类、方法、字段的语义搜索和调用链分析。特别适合大型 Java 项目的代码理解、重构分析和 AI 辅助开发。

✨ 核心特性

• 🔍 语义级搜索 - 搜索类、方法、字段，支持模糊匹配和类型过滤
• 🕸️ 调用链分析 - 追踪方法调用关系，支持双向追溯（调用者/被调用者）
• 🏗️ 类结构解析 - 完整解析类的字段、方法、继承、注解等信息
• 🤖 MCP Server 支持 - 为 Claude、Cursor 等 AI 工具提供代码理解能力
• 📊 关系图谱 - 继承、实现、依赖注入、方法调用等关系的完整建模
• 🚀 高性能查询 - 基于 SQLite 的本地存储，快速查询响应

📦 安装

基础安装

pip install jcgraph

完整功能（包含 Web 服务和向量检索）

pip install jcgraph[full]

MCP Server 支持（需要 Python >= 3.10）

pip install jcgraph[mcp]

🚀 快速开始

1. 扫描 Java 项目

# 进入 Java 项目目录
cd /path/to/your/java/project

# 扫描项目并构建知识图谱
jcgraph scan . --name my-project

# 查看统计信息
jcgraph stats

输出示例：

扫描结果统计
┏━━━━━━━━┳━━━━━━┓
┃ 指标   ┃ 数量 ┃
┡━━━━━━━━╇━━━━━━┩
│ 文件数 │  450 │
│ 类数   │  150 │
│ 方法数 │  890 │
│ 字段数 │  420 │
│ 调用关系│ 2340 │
└────────┴──────┘

2. 使用诊断工具

# 检查类信息
jcgraph check class UserService

# 检查方法调用关系
jcgraph check method login --show-calls

# 查看未解析的调用
jcgraph check unresolved

# 导出诊断报告
jcgraph diagnose

3. 启动 Web 服务（可选）

jcgraph serve --port 8080

访问 http://localhost:8080 查看可视化界面。

🤖 AI 集成（MCP Server）

jcgraph 提供 Model Context Protocol (MCP) Server，让 AI 助手能够理解你的 Java 代码。

配置到 Claude CLI

# 自动配置
jcgraph mcp setup --client claude-cli

# 查看配置状态
jcgraph mcp status

配置到 Cursor

jcgraph mcp setup --client cursor

配置到 Claude Desktop

jcgraph mcp setup --client claude-desktop

MCP 工具列表

配置后，AI 助手可以使用以下工具：

1. search_code - 搜索 Java 类、方法、字段
2. get_call_chain - 查询方法调用链（向上/向下追溯）
3. get_class_structure - 获取类的完整结构信息
4. get_method_detail - 查看方法详情和源代码
5. get_callers - 快速查询谁调用了某个方法

使用示例

在 Claude 或 Cursor 中：

查找 UserService 类
查看 login 方法的实现
分析 processOrder 方法被谁调用

AI 助手会自动调用 jcgraph MCP 工具获取准确的代码信息。

详细文档：MCP Server 使用指南

📚 CLI 命令参考

项目管理

jcgraph init              # 初始化配置目录
jcgraph scan <path>       # 扫描 Java 项目
jcgraph serve             # 启动 Web 服务

诊断工具

jcgraph stats                    # 显示数据库统计
jcgraph check class <name>       # 检查类信息
jcgraph check method <name>      # 检查方法信息
jcgraph check unresolved         # 查看未解析调用
jcgraph diagnose                 # 导出诊断报告

MCP Server

jcgraph mcp setup --client <name>   # 配置到客户端
jcgraph mcp status                   # 查看配置状态
jcgraph mcp remove --client <name>  # 移除配置
jcgraph mcp debug                    # 调试模式运行

🏗️ 支持的分析特性

代码实体识别

• ✅ 类（class/interface/enum/abstract）
• ✅ 方法（包括静态、抽象、构造函数）
• ✅ 字段（包括注入的依赖）
• ✅ 注解（类级别和成员级别）
• ✅ 泛型参数

关系分析

• ✅ 继承关系（extends）
• ✅ 接口实现（implements）
• ✅ 方法调用（包括链式调用）
• ✅ 依赖注入（@Autowired, @Resource, @Inject）
• ✅ 方法覆写（@Override）
• ✅ 字段方法调用（如 userRepository.findById()）

高级特性

• ✅ Lombok 注解解析（@Data, @Getter, @Setter 等）
• ✅ 多分支实现识别（如 UserServiceImpl, UserServiceMock）
• ✅ 未解析调用标记（区分项目内/外部依赖）
• ✅ 调用链深度控制
• ✅ 增量更新（重新扫描自动更新）

📖 文档

• MCP Server 使用指南
• 架构设计文档
• 开发指南

🛠️ 技术栈

• 解析器: Tree-sitter（精确的语法分析）
• 存储: SQLite（轻量级本地数据库）
• CLI: Click + Rich（美观的命令行界面）
• Web: FastAPI + Uvicorn（可选）
• MCP: Anthropic MCP SDK（AI 集成）

🔧 系统要求

• Python >= 3.9（基础功能）
• Python >= 3.10（MCP Server 功能）
• Java 项目（支持 Java 8 及以上版本）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT License - 详见 LICENSE 文件

🔗 相关链接

• GitHub: https://github.com/your-org/jcgraph
• PyPI: https://pypi.org/project/jcgraph/
• Issues: https://github.com/your-org/jcgraph/issues
• Model Context Protocol: https://modelcontextprotocol.io

📝 更新日志

v0.2.0

• ✨ 新增 MCP Server 支持（5 个 AI 工具）
• ✨ 新增自动日志记录（~/.jcgraph/logs/）
• ✨ 新增 diagnose 命令（诊断导出）
• ✨ 新增 MCP 配置命令（setup/status/remove）
• ✨ 新增诊断工具（check class/method/unresolved）
• 🐛 改进错误提示（添加建议和反馈链接）
• 📚 完整的 MCP Server 使用文档

v0.1.0

• 🎉 首次发布
• 基础扫描和解析功能
• 调用链分析
• Web 可视化界面

---

Made with ❤️ for Java developers and AI-assisted coding