代码架构可视化工具

🗺️ 代码制图师：Python的架构MRI

将意大利面条代码转化为清晰的层次结构图。发现隐患。上车更快。

代码制图员 是一个智能MCP（模型上下文协议）服务器，充当代码库的视觉GPS。

与标准依赖关系图不同，它结合了 静态分析（AST） 随着 生成型人工智能（双子座-2.5-flash） 揭示“影子架构”——隐含的联系、技术债务和在显性导入中没有出现的风险。

📸 在行动中看到它

1.可视化：从混沌到秩序

该系统强制执行 分层自上而下布局，自动打破循环依赖关系以创建可读的映射。

2.人工智能驱动的洞察

它不只是画画；它理解。AI检测 “影子链接” （通过数据库表、API路由或消息队列的逻辑连接），并将它们可视化为红色虚线。

✨ 主要特点

• 🕵️ 智能存储库扫描： *解析Python AST以构建精确的依赖关系图。
  • 自动处理导入和项目结构。
• 🏥 建筑MRI：
  • 风险热图： 识别高复杂度模块和紧密耦合的组件（红色节点）。
  • 阴影链接检测： 查找隐式耦合（例如，服务A写入 users 表，服务B从中读取）。
• 🎨 智能可视化：
  • 生成高分辨率PNG贴图。
  • 使用智能的“骨架布局”算法，即使在混乱的项目中也能强制使用树结构。
• 💾 智能存储和缓存：
  • 集中式 StorageManager 索引按项目路径扫描。
  • 自动清理旧工件以节省磁盘空间。
  • 持久化结果，这样你就不会不必要地重新运行昂贵的人工智能分析。
• 📚 RAG资源图： *LLM的上下文查找（例如，“谁依赖于 auth_service?").

📂 项目结构

code-cartographer/
├── src/
│   ├── server.py                 # MCP entry point
│   ├── services/
│   │   ├── repository_scanner.py # AST scanning
│   │   ├── ai_analyzer.py        # Gemini integration
│   │   ├── graph_generator.py    # Graph rendering
│   │   └── storage_manager.py    # Persistence & cache
│   └── models/
│       └── schemas.py            # Pydantic schemas
├── mcp_storage/                  # Generated artifacts
└── requirements.txt

🛠️ 安装和设置

先决条件

• Python 3.10+
• uv（pip安装uv）
• Google Gemini API密钥
• 克劳德桌面版

1.️⃣ 克隆和安装

git clone https://github.com/RebeccaSimanTov/code-cartographer.git
cd code-cartographer
uv sync

2.️⃣ 配置环境

创建一个 .env 项目根目录中的文件：

GEMINI_API_KEY=your_google_api_key_here

🛠️ 快速测试（MCP检查员）

想要测试工具 没有设置克劳德?
使用 MCP检查员 ---一个用于运行的交互式web界面 工具和检查输出。

# Run the Inspector directly
npx @modelcontextprotocol/inspector uv run src/server.py

这将打开一个浏览器窗口，您可以在其中手动触发工具 喜欢
scan_repository 并查看JSON结果。

🔌 连接到克劳德桌面

要将Code Cartographer集成到您的AI工作流程中，请编辑Claude 桌面配置文件：

• 视窗
  %APPDATA%\Claude\claude_desktop_config.json

• macOS
  ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置
(更新路径以匹配您的本地项目位置):

{
  "mcpServers": {
    "code-cartographer": {
      "command": "uv",
      "args": [
        "run", "python",
        "C:/Path/To/code-cartographer/src/server.py"
      ]
    }
  }
}

💡 使用指南

连接后，只需与Claude交谈即可操作该工具：

❓ 故障排除和常见问题

如果在运行服务器时遇到问题，请检查以下常见解决方案：

1.“未找到图形ID”

• 原因： 你正试图逃跑 generate_quick_map 或 run_architectural_mri 不先扫描。
• 解决方案： 总是先问克劳德 “扫描[路径]处的存储库”。这将生成所有其他工具所需的ID。

2.Google Gemini API错误（403或429）

• 403禁止： 您的API密钥无效或丢失。检查你的 .env 文件。
• 429请求太多： 您已达到免费等级的费率上限。系统具有内置重试功能，但如果仍然存在，请等待1-2分钟。

3.“未找到Python文件”

• 原因： 提供的路径不包含 .py 文件或位于跳过的目录中（如 venv).
• 解决方案： 提供到项目根的绝对路径（例如。， C:/Users/Dev/MyProject).

⚠️ 限制和边缘案例

Code Cartographer是为健壮性而设计的，但它是如何处理边缘情况的：

• 🔄 循环依赖性： 如果模块A导入B，B导入A，可视化工具会自动打破循环，强制执行可读的树布局（自上而下），尽管逻辑链接仍保留在图形数据中。
• 🕵️ 动态导入： 扫描仪使用 静态分析（AST）。它捕获标准进口(import x, from y import z).复杂的动态导入，如 importlib.import_module(variable) 可能无法检测到。
• 📉 大型Monoreps： 对于超过3000个文件的存储库，AI分析步骤可能会达到上下文窗口限制。系统将首先处理最中心的节点，以实现价值最大化。
• 🔒 网络限制： 这 AIAnalyzer 被配置为绕过受限公司网络（如NetFree）中常见的SSL验证错误，但Gemini API需要稳定的互联网连接。

🏗️ 架构决策

为什么选择原始HTTP（httpx）而不是LangChain/SDK？

这个项目故意使用直接 httpx 请求与Gemini API交互，避免使用诸如 langchain 或 google-genai这一决定是由三个核心工程原则推动的：

1. 🛡️ 企业网络兼容性： 在严格的企业环境（金融、国防或过滤网络）中的生产环境通常需要自定义SSL上下文处理或代理配置。高级SDK通常过于抽象传输层，使得绕过SSL验证错误或注入自定义证书变得困难。使用 httpx 授予对TLS握手的完全控制权，确保该工具在安全环境中工作。

2. 🪶 最小占地面积和速度： 像LangChain这样的库引入了一个庞大的依赖树（“膨胀”）。通过使用标准的HTTP调用，我们保持了安装的即时性(uv 友好），容器大小小，执行可预测。

3. ⚡ 精确错误处理： 直接API访问允许使用针对该特定应用程序定制的自定义指数退避逻辑对HTTP 429（速率限制）与403（禁止）进行细粒度处理，而不是依赖于包装器库的通用重试逻辑。