使用说明

cpal-你的朋友克劳德

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

相反的通用公共许可证 --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 CLI

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="Hardest problem", model="fable")  # most capable, premium cost
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)

# Per-call tool call cap (override the default 1000)
consult_claude(query="Quick scan", max_tool_calls=50)

实用工具

# 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

组成顺序：

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

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

安全

所有文件访问都被沙盒化到启动cpal的目录中
阻止了路径遍历和符号链接攻击
会话按以下方式隔离 session_id
文件大小限制：10MB文本，20MB媒体
机密文件denylist：内置模式阻止读取常见机密文件(.env*, *.pem, *.key, *_key, id_rsa*, .git/config等等）跨越所有读取表面。通过以下方式扩展列表 denied_path_patterns 在 ~/.config/cpal/config.toml --配置模式添加到内置组件中，它们永远不会取代它们。这 .env 文件从不自动加载API密钥；使用 --key-file 或 ANTHROPIC_API_KEY.
注意：只读git工具仍然可以显示整个存储库的提交历史（例如。 git log 或 git show 没有path参数），即使cpal是在较大存储库的子目录中启动的，因为git可以从任何子目录对整个存储库进行操作。

批次API

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

# Submit a batch (any tier works — including Fable)
create_batch(queries=[
    {"custom_id": "review-1", "query": "Review this code: ..."},
    {"custom_id": "review-2", "query": "Review this other code: ..."},
], model="fable")

# 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客户端的只读自检端点：

URI	描述
`resource://server/info`	服务器版本、功能和特性列表
`resource://models`	具有ID、描述和默认值的可用模型
`resource://config/limits`	安全限制（文件大小、搜索上限、会话TTL）
`resource://sessions`	列出所有活动会话
`resource://session/{session_id}`	特定会话的详细信息（消息计数、预览）
`resource://tools/internal`	Claude用于自主探索的工具

模型

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

别名	回退ID	最适合
`fable`	`claude-fable-5`	最有能力——前沿情报，溢价
`opus`	`claude-opus-4-8`	深度推理，难题（默认）
`sonnet`	`claude-sonnet-4-6`	平衡推理、代码审查
`haiku`	`claude-haiku-4-5`	快速探索，快速提问

默认情况下，Claude每个查询最多可以进行1000次自主工具调用。用全局覆盖 CPAL_MAX_TOOL_CALLS 环境变量，或每次调用 max_tool_calls=N 上 consult_claude.

备注

会话在内存中 --服务器重新启动时，历史记录会丢失。会话在1小时不活动后有资格到期；当活动会话计数超过100时，将运行清理。
模型需要花钱 --Opus是默认的，也是最昂贵的。看人为定价.使用 haiku 或 sonnet 为了降低成本。
视觉 --支持PNG、JPEG、GIF、WebP和PDF（最大20MB）。
1M上下文 --需要 API 4级无烟煤+。20万代币以上适用溢价。标准上下文窗口是20万个令牌；通过 context_1m=True 通过beta端点访问1M窗口。

发展

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

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

许可证

麻省理工学院

使用说明

cpal-你的朋友克劳德

特性

安装

API密钥（选择一个）

配置

Gemini CLI

克劳德代码

手动（光标等）

用法

工具参考

实用工具

运作原理

自定义系统提示

安全

批次API

MCP资源

模型

备注

发展

许可证

相关 MCP

代码索引分析工具

代码分析服务器

GitHub仓库解析工具

VSCode MCP桥接工具

语言服务协议MCP

上下文管理服务