gpal
MCP服务器，使您的IDE或代理能够通过自主代码库探索访问Google Gemini。你的朋友双子座。
为什么选择gpal？
当你问gpal一个问题时，双子座不会只是猜测—— 探索你的代码库本身。它列出目录、读取文件并在回答之前搜索模式。这使其非常适合：
- 🔍 深度代码分析 --“查找此代码库中的所有错误处理模式”
- 🏗️ 建筑评论 --“身份验证是如何实现的？”
- 🐛 虫子打猎 --“为什么此函数可能返回null？”
- 📚 代码库入职培训 --“解释请求管道是如何工作的”
- 🖼️ 目视检查 --通过分析屏幕截图、图表、视频
media_paths - 📋 结构化提取 -“将所有API终结点列为JSON”
特性
| 特性 | 描述 |
|---|---|
| 有意义的会议 | 通过以下方式维护对话历史记录 ctx.session_id |
| 自主探索 | Gemini有列出、读取和搜索文件的工具 |
| 文件查找器 | 通过Google的原生FileSearch API进行语义代码搜索 |
| 双子座3系列 | 支持Flash和Pro，具有统一的自动模式 |
| 上下文缓存 | 存储大型代码上下文以降低成本和延迟 |
| 可观测性 | 原生开放遥测支持（OTLP-gRPC） |
| 分布式跟踪 | 传播 traceparent 来自MCP请求 |
| 多模态 | 分析图像、音频、视频、PDF |
| 批处理 | 异步折扣（约50%）Gemini批API |
限制： 10MB文件读取，20MB内联媒体，最多20个搜索匹配。
模型层
| 工具 | 模型 | 用例 |
|---|---|---|
consult_gemini | auto （默认） | Lite探索，然后Flash合成 |
consult_gemini | flash | 快速、高效的映射和搜索 |
consult_gemini | pro | 深入的推理，复杂的评论 |
consult_gemini_oneshot | flash / pro | 无状态单次查询，无会话历史记录 |
自动模式： 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上下文缓存
通过在谷歌服务器上缓存上下文来降低大型项目的成本：
- 使用上传大文件
upload_file. - 使用创建缓存
create_context_cache使用返回的URI。 - 在中引用缓存名称
consult_gemini通过电话cached_content参数。 - 通过查看活动缓存
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 等等
命令行标志 （可重复，按顺序连接）：
# 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组成顺序：
- 内置gpal系统指令（除非
include_default_prompt = false或--no-default-prompt) - 文件来源
system_prompts在config.toml中 - 内联
system_prompt来自config.toml - 文件来源
--system-prompt命令行标志
通过查看活动内容 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成本。
另见
- 组合探针锚定连接 --相反：一个允许Gemini（或任何MCP客户端）咨询Claude的MCP服务器。你的朋友克劳德。
许可证
麻省理工学院——见 许可证
路线图/TODO
- 重构代理： 一个编辑文件、运行测试的循环（通过
code_execution或shell），并迭代直到绿色。 - 审核代理： 用于输出结构化注释的代码审查的专门系统指令。