cpal (Tobert)

cpal-你的朋友克劳德

一个允许任何AI咨询Claude的MCP服务器。

的逆 gpal --gpal让Claude咨询Gemini，cpal让Gemini（或任何MCP客户）咨询Claude。

特性

• 🧠 默认情况下为Opus --深度推理（十四行诗/俳句可用）
• 💭 延伸思考 --复杂分析的显式思维链
• 🔧 自主探索 --Claude读取文件并搜索您的代码库
• 📸 视觉 --分析图像和PDF
• 💬 有意义的会议 --通话中保留的对话历史记录
• 📦 批次API -即发即弃处理50%的成本折扣
• 🔢 代币计数 --免费端点在发送前估算成本
• 🎛️ 努力控制 --将输出努力从“低”调整到“最大”
• 📚 1M上下文 --选择加入扩展上下文窗口（测试版，需要 API 4级无烟煤+)

安装

需要 紫外线.

git clone https://github.com/tobert/cpal && cd cpal
uv tool install .

API密钥（选择一个）

选项A：密钥文件（推荐）

mkdir -p ~/.config/cpal && chmod 700 ~/.config/cpal
echo "sk-ant-..." > ~/.config/cpal/api_key && chmod 600 ~/.config/cpal/api_key

选项B：环境变量

export ANTHROPIC_API_KEY="sk-ant-..."

如果两者都被设置， --key-file 优先于环境变量。

配置

选择与您的MCP客户端匹配的方法：

双子星命令行工具

gemini mcp add cpal --scope user -- cpal --key-file ~/.config/cpal/api_key

克劳德代码

可用于从不同的Claude实例获取第二意见，或将任务委托给特定的模型层（例如，在Sonnet上运行Claude Code时使用Opus进行深度分析）。

claude mcp add cpal --scope user -- cpal --key-file ~/.config/cpal/api_key

手动（光标等）

添加到MCP配置(~/.cursor/mcp.json等等）：

{
  "mcpServers": {
    "cpal": {
      "command": "cpal",
      "args": ["--key-file", "/home/you/.config/cpal/api_key"]
    }
  }
}

或者使用env var：

{
  "mcpServers": {
    "cpal": {
      "command": "cpal",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

用法

您的AI主机会根据您的提示自动调用这些MCP工具。下面的例子显示了工具签名——你不直接调用它们，你只需要让你的人工智能咨询克劳德。

“让Claude检查src/server.py中的错误” 触发器 consult_claude(query="...", file_paths=[...]) “让Claude设计缓存策略” 触发器 consult_claude(query="...")

成本说明： Opus是默认型号，也是最昂贵的型号。使用 model="haiku" 或 model="sonnet" 为了降低成本。

工具参考

# Basic (uses Opus)
consult_claude(query="Design a caching strategy for this API")

# Extended thinking is enabled by default (extended_thinking=True)
# Control the thinking budget (default 10000, max ~100000)
consult_claude(query="Analyze this algorithm", thinking_budget=50000)

# Disable thinking for simple queries
consult_claude(query="What does this function do?", extended_thinking=False)

# Vision
consult_claude(query="What's wrong with this UI?", media_paths=["screenshot.png"])

# Different models
consult_claude(query="Hard problem", model="opus")   # deep reasoning
consult_claude(query="Quick check", model="haiku")   # fast & cheap

# Multi-turn conversation
consult_claude(query="Explain the auth flow", session_id="review-123")
consult_claude(query="What about edge cases?", session_id="review-123")  # continues

# Effort control — tune output depth (low, medium, high, max)
consult_claude(query="Quick summary", effort="low")
consult_claude(query="Exhaustive analysis", effort="max")

# 1M context window (beta, tier 4+, premium pricing above 200K tokens)
consult_claude(query="Analyze this large codebase", context_1m=True)

实用工具

# List available models and their resolved IDs
list_models()

# Count tokens before sending (free — no API cost)
count_tokens(query="Review this code: ...", model="opus")
count_tokens(query="...", file_paths=["src/server.py"])  # includes file content

运作原理

MCP Client (Gemini, Cursor, etc.)
         │
         ▼ MCP
    ┌─────────┐
    │  cpal   │ ──▶ Anthropic API ──▶ Claude
    └─────────┘
         │
    cpal gives Claude these tools to
    autonomously explore your codebase:
    • list_directory
    • read_file
    • search_project

自定义系统提示

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

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

# Files loaded in order and concatenated
system_prompts = [
    "~/.config/cpal/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
cpal --system-prompt /path/to/project-context.md

# Multiple files
cpal --system-prompt ~/CLAUDE.md --system-prompt ./PROJECT.md

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

组成顺序：

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

通过查看活动内容 resource://server/info --它显示了哪些来源做出了贡献以及总提示长度。

安全

• 所有文件访问都被沙盒化到启动cpal的目录中
• 阻止了路径遍历和符号链接攻击
• 会话按以下方式隔离 session_id
• 文件大小限制：10MB文本，20MB媒体

批次API

这些是你的AI主机可以调用的MCP工具——与 consult_claude，但异步批量处理可以享受50%的成本折扣。批处理在24小时内完成。

# Submit a batch
create_batch(queries=[
    {"custom_id": "review-1", "query": "Review this code: ..."},
    {"custom_id": "review-2", "query": "Review this other code: ..."},
])

# Check status
list_batches()
get_batch(batch_id="msgbatch_...")

# Get results when done
get_batch_results(batch_id="msgbatch_...")

# Cancel a processing batch
cancel_batch(batch_id="msgbatch_...")

不删除API --Anthropic不提供删除批处理结果的端点。批次将在29天后自动清除。

不使用工具 --批处理查询是一次性的（没有代理文件探索）。参数如 file_paths 和 media_paths 在批处理模式下不可用--将内容直接粘贴到 query 弦。

MCP资源

支持资源的MCP客户端的只读自检端点：

模型

模型别名通过Anthropic API自动解析为每层的最新版本。使用 list_models() 查看当前映射。如果无法访问API，则回退ID：

默认情况下，Claude每个查询最多可以进行1000次自主工具调用。用覆盖 CPAL_MAX_TOOL_CALLS 环境变量。

备注

• 会话在内存中 --服务器重新启动时，历史记录会丢失。会话在1小时不活动后过期。
• 模型需要花钱 --Opus是默认的，也是最昂贵的。看 人为定价.使用 haiku 或 sonnet 为了降低成本。
• 视觉 --支持PNG、JPEG、GIF、WebP和PDF（最大20MB）。
• 1M上下文 --需要 API 4级无烟煤+。20万代币以上适用溢价。默认的上下文窗口是20万个令牌。

发展

uv sync --all-extras
uv run pytest tests/test_tools.py -v  # unit tests (free)

⚠️ 跑步 pytest tests/ 随着 ANTHROPIC_API_KEY set将运行需要花钱的集成测试。看 CLAUDE.md 了解详情。

许可证

麻省理工学院