Gemini代码分析服务

gpal

MCP服务器，使您的IDE或代理能够通过自主代码库探索访问Google Gemini。你的朋友双子座。

为什么选择gpal？

当你问gpal一个问题时，双子座不会只是猜测—— 探索你的代码库本身。它列出目录、读取文件并在回答之前搜索模式。这使其非常适合：

• 🔍 深度代码分析 --“查找此代码库中的所有错误处理模式”
• 🏗️ 建筑评论 --“身份验证是如何实现的？”
• 🐛 虫子打猎 --“为什么此函数可能返回null？”
• 📚 代码库入职培训 --“解释请求管道是如何工作的”
• 🖼️ 目视检查 --通过分析屏幕截图、图表、视频 media_paths
• 📋 结构化提取 -“将所有API终结点列为JSON”

特性

限制： 10MB文件读取，20MB内联媒体，最多20个搜索匹配。

模型层

自动模式： Lite自主探索代码库（便宜、彻底），然后Flash对Lite发现的内容进行合成。使用 model="pro" 用于深度推理（Lite探索，然后Pro思考高）。

可观察性和追踪

gpal支持本地OpenTetry用于监控和分布式跟踪。它会自动传播 traceparent 来自传入MCP请求的标头。

# Configure via standard environment variables
export OTEL_SERVICE_NAME="gpal-server"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

# Or via CLI argument
uv run gpal --otel-endpoint localhost:4317

上下文缓存

通过在谷歌服务器上缓存上下文来降低大型项目的成本：

1. 使用上传大文件 upload_file.
2. 使用创建缓存 create_context_cache 使用返回的URI。
3. 在中引用缓存名称 consult_gemini 通过电话 cached_content 参数。
4. 通过查看活动缓存 gpal://caches 资源。

文件搜索

使用Google原生FileSearch API的语义代码搜索-无本地嵌入或数据库：

# Create a store and upload files
create_file_store("my-project")
upload_to_file_store("stores/...", "src/server.py")

# Gemini searches stores automatically during generation
consult_gemini("find authentication logic", model="auto")

• 谷歌处理分块、嵌入和检索
• 通过以下方式管理的商店 create_file_store, upload_to_file_store, list_file_stores, delete_file_store
• 当商店存在时，Gemini会在以下时间自动搜索它们 consult_gemini 电话

自定义系统提示

通过编写来自多个来源的系统提示，自定义Gemini对您、您的项目或工作流程的“了解”。

配置文件 (~/.config/gpal/config.toml):

# Files loaded in order and concatenated
system_prompts = [
    "~/.config/gpal/GEMINI.md",
    "~/CLAUDE.md",
]

# Inline text appended after files
system_prompt = "常に日本語で回答してください (Always respond in Japanese)"

# Set to false to fully replace the built-in prompt with your own
include_default_prompt = true

路径支持 ~ 和 $ENV_VAR 扩展，因此您可以使用 $WORKSPACE/CLAUDE.md 等等

CLI标志 （可重复，按顺序连接）：

# Append additional prompt files
uv run gpal --system-prompt /path/to/project-context.md

# Multiple files
uv run gpal --system-prompt ~/GEMINI.md --system-prompt ./CLAUDE.md

# Replace the built-in prompt entirely
uv run gpal --system-prompt ~/my-prompt.md --no-default-prompt

组成顺序：

1. 内置gpal系统指令（除非 include_default_prompt = false 或 --no-default-prompt)
2. 文件来源 system_prompts 在config.toml中
3. 内联 system_prompt 来自config.toml
4. 文件来源 --system-prompt CLI标志

通过查看活动内容 gpal://info 资源——它显示了哪些源做出了贡献以及总指令长度。

安装

先决条件

• Python 3.12+
• 紫外线 （推荐）
• Gemini API密钥

快速开始

git clone https://github.com/tobert/gpal.git
cd gpal
export GEMINI_API_KEY="your_key_here"  # or GOOGLE_API_KEY
uv run gpal

用法

克劳德桌面/光标/VS代码

添加到您的MCP配置中（例如。， claude_desktop_config.json):

{
  "mcpServers": {
    "gpal": {
      "command": "uv",
      "args": ["--directory", "/path/to/gpal", "run", "gpal"],
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

然后问你的AI助手：

“请Gemini分析此代码库中的身份验证流程”

“使用 consult_gemini 找出处理错误的地方”

发展

uv run pytest              # Run tests
uv run pytest -v           # Verbose output

⚠️ 注： 集成测试(test_connectivity.py, test_agentic.py, test_switching.py)进行API实时调用，并将产生Gemini API成本。

另见

• CPAL --相反：一个允许Gemini（或任何MCP客户端）咨询Claude的MCP服务器。你的朋友克劳德。

许可证

麻省理工学院——见 许可证

路线图/TODO

• 重构代理： 一个编辑文件、运行测试的循环（通过 code_execution 或shell），并迭代直到绿色。
• 审核代理： 用于输出结构化注释的代码审查的专门系统指令。