java-class-analyzer-mcp-server 1.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,285 @@
+# Java Class Analyzer MCP Server
+
+一个基于Model Context Protocol (MCP)的Java类分析服务，可以扫描Maven项目依赖、反编译Java类文件、获取class方法列表等详细信息，并提供给LLM进行代码分析。
+
+## 适用场景
+Cursor等AI工具直接生成调用二方（内部调用）、三方包（外部调用）接口的代码，但因AI无法读取未在当前工程中打开的依赖源码，导致生成的代码错误频出，甚至出现幻觉式编码。
+
+为解决此问题，一般会直接拷贝源码内容喂给LLM；或者先将源码文件放到当前工程内，再在对话中引用。
+
+而使用本地反编译MCP方案最有效，能精准解析jar包中的类与方法，显著提升代码生成的准确性和可用性。
+
+## 功能特性
+
+- **🚀使用方便**：mcp服务基于TypeScript实现，使用npm打包，方便分发和安装，弱环境依赖。
+- 🔍 **依赖扫描**: 自动扫描Maven项目的所有依赖JAR包
+- 📦 **类索引**: 建立类全名到JAR包路径的映射索引
+- 🔄 **反编译**: 使用CFR工具（已内置有）实时反编译.class文件为Java源码
+- 📊 **类分析**: 分析Java类的结构、方法、字段、继承关系等
+- 💾 **智能缓存**: 按包名结构缓存反编译结果，支持缓存控制
+- 🚀 **自动索引**: 执行分析前自动检查并创建索引
+- ⚙️ **灵活配置**: 支持外部指定CFR工具路径
+- 🤖 **LLM集成**: 通过MCP协议为LLM提供Java代码分析能力
+
+## 使用示例
+### 在IDE中注册mcp服务
+![工具列表](./doc/mcp-tools.jpg)
+
+### 在智能体对话中使用mcp
+![示例](./doc/mcp-use-case.jpg)
+
+## 使用说明
+
+### mcp服务安装
+
+#### 全局安装（推荐）
+
+```bash
+npm install -g java-class-analyzer-mcp-server
+```
+
+安装后可以直接使用 `java-class-analyzer-mcp` 命令。
+
+#### 本地安装
+
+```bash
+npm install java-class-analyzer-mcp-server
+```
+
+#### 从源码安装
+
+```bash
+git clone https://github.com/handsomestWei/java-class-analyzer-mcp-server.git
+cd java-class-analyzer-mcp-server
+npm install
+npm run build
+```
+
+### MCP服务配置
+
+#### 方法1：使用生成的配置（推荐）
+
+运行以下命令生成配置模板：
+```bash
+java-class-analyzer-mcp config -o mcp-client-config.json
+```
+
+然后将生成的配置内容添加到你的MCP客户端配置文件中。
+
+#### 方法2：手动配置
+
+参考以下配置示例，添加到MCP客户端配置文件中：
+
+**全局安装后的配置：**
+```json
+{
+    "mcpServers": {
+        "java-class-analyzer": {
+            "command": "java-class-analyzer-mcp",
+            "args": ["start"],
+            "env": {
+                "NODE_ENV": "production",
+                "MAVEN_REPO": "D:/maven/repository",
+                "JAVA_HOME": "C:/Program Files/Java/jdk-11"
+            }
+        }
+    }
+}
+```
+
+**本地安装后的配置：**
+```json
+{
+    "mcpServers": {
+        "java-class-analyzer": {
+            "command": "node",
+            "args": [
+                "node_modules/java-class-analyzer-mcp-server/dist/index.js"
+            ],
+            "env": {
+                "NODE_ENV": "production",
+                "MAVEN_REPO": "D:/maven/repository",
+                "JAVA_HOME": "C:/Program Files/Java/jdk-11"
+            }
+        }
+    }
+}
+```
+
+#### 参数说明
+- `command`: 运行MCP服务器的命令，这里使用 `node`
+- `args`: 传递给Node.js的参数，指向`npm run build`编译后的dist文件夹内文件
+- `env`: 环境变量设置
+
+#### 环境变量说明
+- `NODE_ENV`: 运行环境标识
+  - `production`: 生产环境，减少日志输出，启用性能优化
+  - `development`: 开发环境，输出详细调试信息
+  - `test`: 测试环境
+- `MAVEN_REPO`: Maven本地仓库路径（可选）
+  - 如果设置，程序会使用指定的仓库路径扫描JAR包
+  - 如果未设置，程序会使用默认的 `~/.m2/repository` 路径
+- `JAVA_HOME`: Java安装路径（可选）
+  - 如果设置，程序会使用 `${JAVA_HOME}/bin/java` 执行Java命令（用于CFR反编译）
+  - 如果未设置，程序会使用PATH中的 `java` 命令
+- `CFR_PATH`: CFR反编译工具的路径（可选，程序会自动查找）
+
+### 可用的工具
+
+#### 1. scan_dependencies
+扫描Maven项目的所有依赖，建立类名到JAR包的映射索引。
+
+**参数:**
+- `projectPath` (string): Maven项目根目录路径
+- `forceRefresh` (boolean, 可选): 是否强制刷新索引，默认false
+
+**示例:**
+```json
+{
+  "name": "scan_dependencies",
+  "arguments": {
+    "projectPath": "/path/to/your/maven/project",
+    "forceRefresh": false
+  }
+}
+```
+
+#### 2. decompile_class
+反编译指定的Java类文件，返回Java源码。
+
+**参数:**
+- `className` (string): 要反编译的Java类全名，如：com.example.QueryBizOrderDO
+- `projectPath` (string): Maven项目根目录路径
+- `useCache` (boolean, 可选): 是否使用缓存，默认true。避免每次都重复生成。
+- `cfrPath` (string, 可选): CFR反编译工具的jar包路径。已内置有，可以额外指定版本。
+
+**示例:**
+```json
+{
+  "name": "decompile_class",
+  "arguments": {
+    "className": "com.example.QueryBizOrderDO",
+    "projectPath": "/path/to/your/maven/project",
+    "useCache": true,
+    "cfrPath": "/path/to/cfr-0.152.jar"
+  }
+}
+```
+
+#### 3. analyze_class
+分析Java类的结构、方法、字段等信息。
+
+**参数:**
+- `className` (string): 要分析的Java类全名
+- `projectPath` (string): Maven项目根目录路径
+
+**示例:**
+```json
+{
+  "name": "analyze_class",
+  "arguments": {
+    "className": "com.example.QueryBizOrderDO",
+    "projectPath": "/path/to/your/maven/project",
+  }
+}
+```
+
+### 缓存文件
+在当前工程，会生成以下缓存目录和文件。
+- `.mcp-class-index.json`: 类索引缓存文件
+- `.mcp-decompile-cache/`: 反编译结果缓存目录（按包名结构）
+- `.mcp-class-temp/`: 临时文件目录（按包名结构）
+
+## 工作流程
+
+1. **自动索引**: 首次调用`analyze_class`或`decompile_class`时，自动检查并创建索引
+2. **智能缓存**: 反编译结果按包名结构缓存，支持缓存控制
+3. **分析类**: 使用`analyze_class`或`decompile_class`获取类的详细信息
+4. **LLM分析**: 将反编译的源码提供给LLM进行代码分析
+
+## 技术架构
+
+### 核心组件
+
+- **DependencyScanner**: 负责扫描Maven依赖和建立类索引
+- **DecompilerService**: 负责反编译.class文件
+- **JavaClassAnalyzer**: 负责分析Java类结构
+- **MCP Server**: 提供标准化的MCP接口
+
+### 依赖扫描流程
+
+1. 执行`mvn dependency:tree`获取依赖树
+2. 解析每个JAR包，提取所有.class文件
+3. 建立"类全名 -> JAR包路径"的映射索引
+4. 缓存索引到`.mcp-class-index.json`文件
+
+### 反编译流程
+
+1. 根据类名查找对应的JAR包路径
+2. 检查缓存，如果存在且启用缓存则直接返回
+3. 从JAR包中提取.class文件到`.mcp-class-temp`目录（按包名结构）
+4. 使用CFR工具反编译.class文件
+5. 保存反编译结果到缓存`.mcp-decompile-cache`目录（按包名结构）
+6. 返回Java源码
+
+## 故障排除
+
+### 常见问题
+
+1. **Maven命令失败**
+   - 确保Maven已安装并在PATH中
+   - 检查项目是否有有效的pom.xml文件
+
+2. **CFR反编译失败**
+   - 确保CFR jar包已下载（支持任意版本号）
+   - 检查Java环境是否正确配置
+   - 可通过`cfrPath`参数指定CFR路径
+
+3. **类未找到**
+   - 程序会自动检查并创建索引
+   - 检查类名是否正确
+   - 确保项目依赖已正确解析
+
+## 测试说明
+
+### 构建项目
+
+```bash
+npm install
+npm run build
+```
+
+### 测试工具使用
+
+项目提供了独立的测试工具，可以直接测试MCP服务的各个功能，无需通过MCP客户端。
+
+```bash
+# 测试所有工具
+node test-tools.js
+
+# 测试特定工具
+node test-tools.js --tool decompile_class --class com.alibaba.excel.EasyExcelFactory --project /path/to/project
+
+# 不使用缓存
+node test-tools.js --tool decompile_class --no-cache
+
+# 指定CFR路径
+node test-tools.js --tool decompile_class --cfr-path /path/to/cfr.jar
+```
+
+### 测试工具参数
+
+- `-t, --tool <工具名>`: 指定要测试的工具 (scan|decompile|analyze|all)
+- `-p, --project <路径>`: 项目路径
+- `-c, --class <类名>`: 要分析的类名
+- `--no-refresh`: 不强制刷新依赖索引
+- `--no-cache`: 不使用反编译缓存
+- `--cfr-path <路径>`: 指定CFR反编译工具的jar包路径
+- `-h, --help`: 显示帮助信息
+
+### 日志级别控制
+
+通过 `NODE_ENV` 环境变量控制日志输出：
+
+- `development`: 输出详细调试信息
+- `production`: 只输出关键信息

package/dist/analyzer/JavaClassAnalyzer.d.ts

@@ -0,0 +1,61 @@
+export interface ClassField {
+    name: string;
+    type: string;
+    modifiers: string[];
+}
+export interface ClassMethod {
+    name: string;
+    returnType: string;
+    parameters: string[];
+    modifiers: string[];
+}
+export interface ClassAnalysis {
+    className: string;
+    packageName: string;
+    modifiers: string[];
+    superClass?: string;
+    interfaces: string[];
+    fields: ClassField[];
+    methods: ClassMethod[];
+}
+export declare class JavaClassAnalyzer {
+    private scanner;
+    constructor();
+    /**
+     * 分析Java类的结构信息
+     */
+    analyzeClass(className: string, projectPath: string): Promise<ClassAnalysis>;
+    /**
+     * 使用 javap 工具分析JAR包中的类结构
+     */
+    private analyzeClassWithJavap;
+    /**
+     * 解析 javap 输出
+    */
+    private parseJavapOutput;
+    /**
+     * 解析类声明
+     */
+    private parseClassDeclaration;
+    /**
+     * 从 javap 输出解析方法
+     */
+    private parseMethodFromJavap;
+    /**
+     * 智能分割参数，处理泛型和嵌套类型
+     */
+    private splitParameters;
+    /**
+     * 获取javap命令路径
+     */
+    private getJavapCommand;
+    /**
+     * 获取类的继承层次结构
+     */
+    getInheritanceHierarchy(className: string, projectPath: string): Promise<string[]>;
+    /**
+     * 查找类的所有子类
+     */
+    findSubClasses(className: string, projectPath: string): Promise<string[]>;
+}
+//# sourceMappingURL=JavaClassAnalyzer.d.ts.map

package/dist/analyzer/JavaClassAnalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JavaClassAnalyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/JavaClassAnalyzer.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,OAAO,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,OAAO,CAAoB;;IAMnC;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBlF;;OAEG;YACW,qBAAqB;IAmBnC;;MAEE;IACF,OAAO,CAAC,gBAAgB;IAyGxB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiC7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqE5B;;OAEG;IACH,OAAO,CAAC,eAAe;IA6BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACG,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiBxF;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAiBlF"}