JinDaGe - joern-mcp MCP Details

article

README

🚀 🕷️ joern-mcp

joern-mcp 是一个模型上下文协议（MCP）服务器，它借助 Joern 的代码属性图（CPG）技术，为 AI 助手赋予静态代码分析能力。

🚀 快速开始

前提条件

Python 3.8 及以上版本
Docker
Redis
Git

安装步骤

克隆仓库并安装依赖：

git clone https://github.com/Lekssays/joern-mcp.git
cd joern-mcp
pip install -r requirements.txt

进行设置（构建 Joern 镜像并启动 Redis）：

./setup.sh

配置（可选）：

cp config.example.yaml config.yaml
# 根据需要编辑 config.yaml

启动服务器：

python main.py
# 服务器将在 http://localhost:4242 可用

✨ 主要特性

多语言支持：支持 Java、C/C++、JavaScript、Python、Go、Kotlin、C#、Ghidra、Jimple、PHP、Ruby、Swift 等多种语言。
Docker 隔离：每个分析会话都在安全的容器中运行。
GitHub 集成：可直接从 GitHub URL 分析仓库。
基于会话：具有持久的 CPG 会话，并能自动清理。
Redis 支持：实现快速缓存和会话管理。
异步查询：支持非阻塞的 CPG 生成和查询执行。
内置安全查询：提供预配置的常见漏洞查询。

💻 使用示例

基础用法

# 创建 GitHub 会话
{
  "tool": "create_cpg_session",
  "arguments": {
    "source_type": "github",
    "source_path": "https://github.com/user/repo",
    "language": "java"
  }
}

# 获取代码库概述
{
  "tool": "get_codebase_summary",
  "arguments": {
    "session_id": "abc-123-def"
  }
}

# 列出代码库中的所有方法
{
  "tool": "list_methods",
  "arguments": {
    "session_id": "abc-123-def",
    "include_external": false,
    "limit": 50
  }
}

# 获取特定方法的源代码
{
  "tool": "get_method_source",
  "arguments": {
    "session_id": "abc-123-def",
    "method_name": "authenticate"
  }
}

# 查找调用特定函数的方法
{
  "tool": "get_call_graph",
  "arguments": {
    "session_id": "abc-123-def",
    "method_name": "execute_query",
    "depth": 2,
    "direction": "incoming"
  }
}

# 搜索硬编码的秘密
{
  "tool": "find_literals",
  "arguments": {
    "session_id": "abc-123-def",
    "pattern": "(?i).*(password|secret|api_key).*",
    "limit": 20
  }
}

# 从文件中获取代码片段
{
  "tool": "get_code_snippet",
  "arguments": {
    "session_id": "abc-123-def",
    "filename": "src/main.c",
    "start_line": 10,
    "end_line": 25
  }
}

# 运行自定义 CPGQL 查询
{
  "tool": "run_cpgql_query",
  "arguments": {
    "session_id": "abc-123-def",
    "query": "cpg.method.name.l"
  }
}

高级用法

预构建查询

list_queries 工具提供 20 多种预配置的查询，包括：

安全方面：SQL 注入检测、XSS 漏洞、硬编码秘密、命令注入、路径遍历。
内存安全方面：缓冲区溢出风险、内存泄漏、空指针解引用、未初始化变量。
代码质量方面：所有方法/函数、控制结构、函数调用、字符串字面量。

📚 详细文档

与 GitHub Copilot 集成

服务器使用 可流式 HTTP 传输以实现网络可访问性，并支持多个并发客户端。在你的 VS Code settings.json 中添加以下内容：

{
  "github.copilot.advanced": {
    "mcp": {
      "servers": {
        "joern-mcp": {
          "url": "http://localhost:4242/mcp",
        }
      }
    }
  }
}

在与 Copilot 一起使用之前，请确保服务器正在运行：

python main.py

可用工具

核心工具

create_cpg_session：从本地路径或 GitHub URL 初始化分析会话。
run_cpgql_query：执行同步 CPGQL 查询并以 JSON 格式输出结果。
run_cpgql_query_async：执行异步查询并跟踪状态。
get_session_status：检查会话状态和元数据。
list_sessions：查看活动会话并可进行过滤。
close_session：清理会话资源。
list_queries：获取预构建的安全和质量查询。

代码浏览工具

get_codebase_summary：获取代码库的高级概述（文件数量、方法数量、语言）。
list_files：列出所有源文件，并可选择使用正则表达式进行过滤。
list_methods：通过名称、文件或外部状态过滤来发现所有方法/函数。
get_method_source：检索特定方法的实际源代码。
list_calls：查找函数调用关系和依赖项。
get_call_graph：构建调用图（传出被调用者或传入调用者），并可配置深度。
list_parameters：获取方法的详细参数信息。
find_literals：搜索硬编码的值（字符串、数字、API 密钥等）。
get_code_snippet：从文件中检索指定行范围的代码片段。

配置

config.yaml 中的关键设置如下：

server:
  host: 0.0.0.0
  port: 4242
  log_level: INFO

redis:
  host: localhost
  port: 6379

sessions:
  ttl: 3600                # 会话超时时间（秒）
  max_concurrent: 50       # 最大并发会话数

cpg:
  generation_timeout: 600  # CPG 生成超时时间（秒）
  supported_languages: [java, c, cpp, javascript, python, go, kotlin, csharp, ghidra, jimple, php, ruby, swift]

环境变量可以覆盖配置文件中的设置（例如，MCP_HOST、REDIS_HOST、SESSION_TTL）。

示例 CPGQL 查询

查找所有方法

cpg.method.name.l

查找硬编码的秘密

cpg.literal.code("(?i).*(password|secret|api_key).*").l

查找 SQL 注入风险

cpg.call.name(".*execute.*").where(_.argument.isLiteral.code(".*SELECT.*")).l

查找复杂方法

cpg.method.filter(_.cyclomaticComplexity > 10).l

🔧 技术细节

架构

FastMCP 服务器：基于 FastMCP 2.12.4 框架构建，采用 可流式 HTTP 传输。
HTTP 传输：支持多个并发客户端的网络可访问 API。
Docker 容器：每个会话使用一个隔离的 Joern 容器。
Redis：用于会话状态和查询结果缓存。
异步处理：支持非阻塞的 CPG 生成。
CPG 缓存：对于相同的源/语言组合，可重用 CPG。

开发

项目结构

joern-mcp/
├── src/
│   ├── services/       # 会话、Docker、Git、CPG、查询服务
│   ├── tools/          # MCP 工具定义
│   ├── utils/          # Redis、日志记录、验证器
│   └── models.py       # 数据模型
├── playground/         # 测试代码库和 CPG
├── main.py            # 服务器入口点
├── config.yaml        # 配置文件
└── requirements.txt   # 依赖项

运行测试

# 安装开发依赖
pip install -r requirements.txt

# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=src --cov-report=html

代码质量

# 格式化代码
black src/ tests/
isort src/ tests/

# 代码检查
flake8 src/ tests/
mypy src/

故障排除

设置问题

# 重新运行设置以重建和重启服务
./setup.sh

Docker 问题

# 验证 Docker 是否正在运行
docker ps

# 检查 Joern 镜像
docker images | grep joern

# 检查 Redis 容器
docker ps | grep joern-redis

Redis 连接问题

# 测试 Redis 连接
docker exec joern-redis redis-cli ping

# 查看 Redis 日志
docker logs joern-redis

# 重启 Redis
docker restart joern-redis

服务器连接问题

# 测试服务器是否正在运行
curl http://localhost:4242/health

# 查看服务器日志以查找错误
python main.py

调试日志

export MCP_LOG_LEVEL=DEBUG
python main.py

📄 许可证

文档中未提及许可证相关信息。

贡献

Fork 仓库。
创建功能分支：git checkout -b feature-name。
进行更改并添加测试。
运行测试：pytest && black . && flake8。
提交拉取请求。

致谢

Joern - 静态分析平台
FastMCP - MCP 框架
Model Context Protocol - MCP 规范

joern-mcp