🗺️ CodeAtlas MCP 服务器

npm version License TypeScript Node

一个独立的 MCP 服务器，将 CodeAtlas 分析数据公开给 AI 助手 —— Gemini、Claude、Cursor、Windsurf、VS Code Copilot 等。

v1.4.0 新功能：🧠 AI 系统记忆 — AI 可以记住您在不同对话之间的系统流程。

⚡ 快速开始

1. 分析您的项目

Ctrl+Shift+P → CodeAtlas: Analyze Project

这将在您的项目根目录下生成 .codeatlas/analysis.json。

2. 添加 MCP 配置

选择您的 AI 助手并添加配置：

打开设置 (Ctrl+,) → 搜索 mcp → 点击 在 settings.json 中编辑，然后添加：

{
  "mcp": {
    "servers": {
      "codeatlas": {
        "command": "npx",
        "args": ["-y", "@giauphan/codeatlas-mcp"]
      }
    }
  }
}

或者通过工作区 .vscode/settings.json 添加以进行项目级配置。

添加到 .gemini/settings.json：

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

添加到 .windsurf/mcp.json：

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

就是这样！ 您的 AI 助手现在可以查询您的代码库结构、依赖关系和见解了。

🛠️ 可用工具

代码分析 (6 个工具)

工具	描述
`list_projects`	列出所有已分析的项目（自动发现 `~/`）
`get_project_structure`	获取模块、类、函数、变量
`get_dependencies`	获取导入/调用/包含关系
`get_insights`	获取 AI 生成的代码质量见解
`search_entities`	按名称搜索函数、类（模糊匹配）
`get_file_entities`	获取特定文件中定义的所有实体

🧠 AI 系统记忆 (3 个工具 — v1.4.0 新增)

工具	描述
`generate_system_flow`	自动生成 Mermaid 架构图。范围：`modules-only`、`full`、`feature`
`sync_system_memory`	创建/更新 `.agents/memory/` 文件夹 — AI 的持久化长期记忆
`trace_feature_flow`	追踪功能在代码库中的流程。按依赖顺序返回文件

🧠 AI 系统记忆

AI 助手在对话之间会丢失上下文。CodeAtlas MCP 通过持久化记忆文件解决了这个问题。

工作原理

Conversation 1 → AI writes code → calls sync_system_memory
                                          │
                                   .agents/memory/
                                   ├── system-map.md
                                   ├── modules.json
                                   ├── business-rules.json
                                   ├── conventions.md
                                   ├── feature-flows.json
                                   └── change-log.json
                                          │
Conversation 2 → AI reads .agents/memory/ → knows full system flow instantly

设置 AI 记忆

将规则模板复制到您的项目：

mkdir -p /path/to/your-project/.agents/rules/

创建 .agents/rules/auto-memory.md，其中包含告诉 AI 执行以下操作的规则：
- 在每次对话开始时读取 .agents/memory/
- 在进行更改前使用 trace_feature_flow
- 在完成更改后调用 sync_system_memory
运行一次 sync_system_memory 以生成初始记忆快照。

📖 完整设置指南和规则模板：CodeAtlas 文档

📦 替代方案：全局安装

如果您更喜欢全局安装而不是使用 npx：

npm install -g @giauphan/codeatlas-mcp

然后在您的 MCP 配置中使用 "command": "codeatlas-mcp"（无需 args）。

🔧 环境变量

变量	描述
`CODEATLAS_PROJECT_DIR`	强制指定特定的项目目录

默认情况下，服务器会自动发现您主目录下所有带有 .codeatlas/analysis.json 的项目。

🌐 支持的语言

语言	功能
TypeScript / JavaScript	完整 AST：导入、类、函数、变量、调用
Python	类、函数、变量、导入、调用
PHP	类、接口、特性、枚举、函数、属性、常量
Blade Templates	`@extends`, `@include`, `@component`, `<x-component>`

🧑💻 开发

git clone https://github.com/giauphan/codeatlas-mcp.git
cd codeatlas-mcp
npm install
npm run build
npm start

许可证

MIT

CodeAtlas MCP Server