项目介绍
🦡 codebadger
一个容器化的模型上下文协议（MCP）服务器，使用Joern的代码属性图（CPG）技术提供静态代码分析，支持Java、C/C++、JavaScript、Python、Go、Kotlin、C#、Ghidra、Jimple、PHP、Ruby和Swift。
先决条件
在开始之前，请确保您已安装：
- Docker 和 Docker Compose
- Python 3.10+（推荐使用Python 3.13）
- pip（Python 包管理器）
验证您的设置：
docker --version
docker-compose --version
python --version
快速入门
1. 安装Python依赖
# 创建虚拟环境（可选但推荐）
python -m venv venv
# 安装依赖
pip install -r requirements.txt
2. 启动Docker服务（Joern）
docker compose up -d
这将启动：
- Joern服务器：静态代码分析引擎（运行CPG生成和查询）
验证服务是否正在运行：
docker compose ps
3. 启动MCP服务器
# 启动服务器
python main.py &
MCP服务器将在http://localhost:4242可用。
4. 停止所有服务
# 停止MCP服务器（终端中按Ctrl+C）
# 停止Docker服务
docker-compose down
# 可选：清理一切
bash cleanup.sh
清理脚本
使用提供的清理脚本来重置您的环境：
bash cleanup.sh
这将：
- 停止并删除Docker容器
- 杀死孤立的Joern/MCP进程
- 清除Python缓存（
__pycache__，.pytest_cache） - 可选地清除playground目录（CPGs和缓存的代码库）
集成
GitHub Copilot集成
编辑VS Code中的MCP配置文件（GitHub Copilot）：
路径：
~/.config/Code/User/mcp.json
示例配置：
{
"inputs": [],
"servers": {
"codebadger": {
"url": "http://localhost:4242/mcp",
"type": "http"
}
}
}
Claude Code集成
要将codebadger集成到Claude Desktop，编辑：
路径：
Claude → 设置 → 开发者 → 编辑配置 → claude_desktop_config.json
添加以下内容：
{
"mcpServers": {
"codebadger": {
"url": "http://localhost:4242/mcp",
"type": "http"
}
}
}
可用工具
核心工具（基于哈希）
generate_cpg：为代码库生成CPG（从本地路径或GitHub URL）get_cpg_status：通过codebase_hash获取CPG的状态和存在情况run_cpgql_query：执行CPGQL查询（同步）
代码浏览工具
-
get_codebase_summary：获取代码库概述 -
list_files：列出源文件 -
list_methods：发现方法/函数 -
get_method_source：检索方法源代码 -
list_calls：查找函数调用关系 -
get_call_graph：构建调用图 -
list_parameters：获取参数信息 -
find_literals：搜索硬编码值 -
get_code_snippet：检索代码片段 -
find_taint_sources：定位外部输入点 -
find_taint_sinks：定位危险接收点 -
find_taint_flows：查找数据流路径 -
find_argument_flows：查找表达式复用 -
check_method_reachability：检查调用图连接 -
list_taint_paths：列出详细的污染路径 -
get_program_slice：构建程序切片
贡献与测试
感谢您的贡献！这里有一个快速指南，帮助您开始运行测试和贡献代码。
先决条件
- Python 3.10+（CI中使用3.13）
- Docker和Docker Compose（用于集成测试）
本地开发设置
- 创建虚拟环境并安装依赖
python -m venv venv
pip install -r requirements.txt
- 启动Docker服务（用于集成测试）
docker-compose up -d
- 运行单元测试
pytest tests/ -q
- 运行集成测试（需要Docker Compose运行）
# 在后台启动MCP服务器
python main.py &
# 运行集成测试
pytest tests/integration -q
# 停止MCP服务器
pkill -f "python main.py"
- 运行所有测试
pytest tests/ -q
- 测试后清理
bash cleanup.sh
docker-compose down
代码贡献
请遵循以下准则进行贡献：
- 遵循仓库约定
- 对行为变更编写测试
- 提交PR前确保所有测试通过
- 在PR描述中包含清晰的变更日志
- 如需更新文档，请进行更新
配置
MCP服务器可以通过环境变量或config.yaml进行配置。
环境变量
关键设置（可选，默认值显示）：
# 服务器
MCP_HOST=0.0.0.0
MCP_PORT=4242
# Joern
JOERN_BINARY_PATH=joern
JOERN_JAVA_OPTS="-Xmx4G -Xms2G -XX:+UseG1GC -Dfile.encoding=UTF-8"
# CPG生成
CPG_GENERATION_TIMEOUT=600
MAX_REPO_SIZE_MB=500
# 查询
QUERY_TIMEOUT=30
QUERY_CACHE_ENABLED=true
QUERY_CACHE_TTL=300
配置文件
从config.example.yaml创建config.yaml：
cp config.example.yaml config.yaml
然后根据需要自定义。