Metadata-Version: 2.4
Name: jcgraph
Version: 0.2.3
Summary: Java代码知识图谱构建工具 - 基于语义分析的 Java 项目理解和查询工具，支持 MCP Server
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/jcgraph
Project-URL: Documentation, https://github.com/your-org/jcgraph/blob/main/docs/MCP_SERVER_GUIDE.md
Project-URL: Repository, https://github.com/your-org/jcgraph
Project-URL: Issues, https://github.com/your-org/jcgraph/issues
Keywords: java,code-analysis,knowledge-graph,mcp-server,ai-tools,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: full
Requires-Dist: tree-sitter>=0.21; extra == "full"
Requires-Dist: tree-sitter-java>=0.21; extra == "full"
Requires-Dist: fastapi>=0.100; extra == "full"
Requires-Dist: uvicorn>=0.20; extra == "full"
Requires-Dist: chromadb>=0.4; extra == "full"
Requires-Dist: networkx>=3.0; extra == "full"
Provides-Extra: mcp
Requires-Dist: mcp>=0.9.0; python_version >= "3.10" and extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# jcgraph

[![PyPI version](https://badge.fury.io/py/jcgraph.svg)](https://badge.fury.io/py/jcgraph)
[![Python Version](https://img.shields.io/pypi/pyversions/jcgraph.svg)](https://pypi.org/project/jcgraph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

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

## ✨ 核心特性

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

## 📦 安装

### 基础安装

```bash
pip install jcgraph
```

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

```bash
pip install jcgraph[full]
```

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

```bash
pip install jcgraph[mcp]
```

## 🚀 快速开始

### 1. 扫描 Java 项目

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

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

# 查看统计信息
jcgraph stats
```

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

### 2. 使用诊断工具

```bash
# 检查类信息
jcgraph check class UserService

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

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

# 导出诊断报告
jcgraph diagnose
```

### 3. 启动 Web 服务（可选）

```bash
jcgraph serve --port 8080
```

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

## 🤖 AI 集成（MCP Server）

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

### 配置到 Claude CLI

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

# 查看配置状态
jcgraph mcp status
```

### 配置到 Cursor

```bash
jcgraph mcp setup --client cursor
```

### 配置到 Claude Desktop

```bash
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 使用指南](https://github.com/your-org/jcgraph/blob/main/docs/MCP_SERVER_GUIDE.md)

## 📚 CLI 命令参考

### 项目管理

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

### 诊断工具

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

### MCP Server

```bash
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 使用指南](https://github.com/your-org/jcgraph/blob/main/docs/MCP_SERVER_GUIDE.md)
- [架构设计文档](https://github.com/your-org/jcgraph/blob/main/docs/ARCHITECTURE.md)
- [开发指南](https://github.com/your-org/jcgraph/blob/main/docs/DEVELOPMENT.md)

## 🛠️ 技术栈

- **解析器**: 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](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**
