leftbrain

你 AI 代理的左脑。 为语言模型不擅长的一切提供精确、确定性的答案——算术和微积分、日期和时区、单位换算、比例缩放、计数、排序、校验、随机性、哈希——外加可选实时数据（天气、外汇汇率）和文件工具（PDF 文本、图片 → base64）。

可将其作为纯 Python 库使用，或作为 MCP 服务器（stdio 或 HTTPS）与 Claude Code、Claude Desktop、Cursor、Windsurf、Zed 或任何 MCP 客户端配合使用。

pip install "leftbrain[all]"
claude mcp add leftbrain -- leftbrain          # Claude Code, one line

为什么

模型是右脑型的：流畅、直观，但在 9.11 < 9.9、strawberry 中有几个 r、今天是星期几、截止日期前还剩多少个工作日、以及 03/04/2025 是三月还是四月这些问题上会出错。这些问题每一个都有精确答案。leftbrain 是一套小巧、描述清晰的工具集，为模型提供那个答案，而不是让它去猜。

设计规则：

1. 仅确定性。 相同输入，相同输出。工具内不调用 LLM。

2. 拒绝歧义而非猜测。 IST、03/04/2025、ton、oz、KB——每个都返回具体选项，而不是默默假设。

3. 呈现每一种解释。 每个响应都携带 assumptions[]（"按区域设置 IN 读作 DD/MM"）和 warnings[]（"日期被钳制到月末"）。

4. 精确与小数并存。 sqrt(2)/2 和 0.7071…，7/4 和 1.75，这样模型就不会再次四舍五入。

5. 工具少，模式多。 13 个核心工具，每个都有 mode 参数，让工具列表在每一轮都保持轻量。

6. 描述说明何时用，而非是什么。 常见的失败是模型不调用工具。

Related MCP server: Euclid

工具

核心（leftbrain，离线，纯函数）

外部（leftbrain-external，网络，免密钥公共 API）

文件（leftbrain-files，可选启用）

适用于无法自行打开文件的自定义代理循环（Claude Code 等托管代理已经可以）。pdf_text、pdf_info、image_info、image_to_base64（按字节预算调整大小/压缩；返回现成的 Anthropic 和 OpenAI 图像块）、base64_to_file、file_info、read_text、list_dir。访问仅限于 LEFTBRAIN_FILE_ROOTS。

契约

每个工具都返回相同的信封结构：

{"ok": true,  "result": {...}, "assumptions": ["read as DD/MM per locale IN"], "warnings": []}
{"ok": false, "error": "ambiguous", "message": "...", "needs": {"field": "locale", "options": [...]}}
{"ok": false, "error": "invalid_input" | "unsupported" | "timeout" | "needs_rates" | "internal", "message": "..."}

result 永不为 null。当存在 needs 时，选择一个选项并再次调用。

安装

pip install leftbrain                 # library only
pip install "leftbrain[mcp]"          # + MCP servers (stdio)
pip install "leftbrain[all]"          # + external (httpx), files (pypdf, Pillow), HTTP server (uvicorn)

Python 3.11+。零 API 密钥。

从 Python 使用

import leftbrain as lb

lb.math_tool("eval", expr="(3+4i)*(1-2i)")["result"]["decimal"]      # '11 - 2i'
lb.math_tool("solve", equations=["x^2+1=0"])                          # ±i
lb.datetime_tool("convert_tz", value="2026-03-08 09:30", from_tz="Asia/Kolkata", to_tz="America/New_York")
lb.datetime_tool("parse", value="03/04/2025")                         # ok: False, needs.options = DD/MM or MM/DD
lb.datetime_tool("business_days", start="2026-10-01", end="2026-10-31", region="IN")
lb.scale_tool(from_qty=4, to_qty=7, entities=[{"name": "flour", "qty": "2.5", "unit": "cup"}])
lb.convert_tool(value=2, from_unit="ton", to_unit="kg")               # ambiguous: metric / short / long
lb.numbers_tool("allocate", total=100, parts=3)                       # 33.34 / 33.33 / 33.33
lb.numbers_tool("to_words", value=123456.5, system="indian", currency="INR")
lb.validate_tool("id", kind="gstin", value="27AAPFU0939F1ZV")
lb.validate_tool("assert", data=doc, rules=[{"path": "leave.days", "op": "lte", "value": 2}])

lb.TOOLS 将工具名映射到函数，如果你想将它们接入 OpenAI 函数调用、LangChain 或你自己的循环——无需 MCP。

作为 MCP 服务器使用（stdio）

Claude Code

claude mcp add leftbrain -- leftbrain
claude mcp add leftbrain-external -- leftbrain-external
claude mcp add leftbrain-files -e LEFTBRAIN_FILE_ROOTS=/path/to/docs -- leftbrain-files

Claude Desktop / Cursor / Windsurf（claude_desktop_config.json、.cursor/mcp.json）：

{
  "mcpServers": {
    "leftbrain":          { "command": "leftbrain" },
    "leftbrain-external": { "command": "leftbrain-external" }
  }
}

完全无需安装："command": "uvx", "args": ["--from", "leftbrain[all]", "leftbrain"]。

通过 HTTPS 使用（托管）

一个进程即可通过 Streamable HTTP 提供所有工具集：

pip install "leftbrain[server]"
LEFTBRAIN_API_KEY=your-secret leftbrain-serve --port 8080
# core:      http://localhost:8080/mcp
# external:  http://localhost:8080/external/mcp
# files:     add --files (and set LEFTBRAIN_FILE_ROOTS)

默认无状态运行，因此可在任何负载均衡器后水平扩展。TLS 由前面的平台终止：

• Docker：docker build -t leftbrain . && docker run -p 8080:8080 -e LEFTBRAIN_API_KEY=… leftbrain

• Railway / Render / Fly.io：指向仓库即可；Dockerfile 和 $PORT 会被自动识别，HTTPS 由平台提供。

• 自托管：在前面放置 Caddy 或 nginx（reverse_proxy localhost:8080），或使用 Cloudflare Tunnel。

然后将客户端连接到公共 URL：

claude mcp add --transport http leftbrain https://leftbrain.example.com/mcp \
  --header "Authorization: Bearer your-secret"

健康检查：GET /healthz。服务描述：GET /。

每用户 API 密钥（公共免费层）

要让其他人使用你自己的密钥、配额和速率限制来使用你的部署，请启用密钥存储，而不是（或同时使用）静态密钥：

LEFTBRAIN_KEYS_DB=/data/keys.sqlite3 leftbrain-serve     # or --keys-db

该存储支持 SQLite（一个路径，适用于带卷的单个实例）或 Postgres（LEFTBRAIN_KEYS_URL=postgres://…，pip install "leftbrain[postgres]"），适用于没有持久磁盘的平台。DSN 依次从 LEFTBRAIN_KEYS_URL、DATABASE_URL、LEFTBRAIN_KEYS_DB 读取——因此 Northflank/Render/Railway 注入的 DATABASE_URL 会被自动识别。

配置存储后，leftbrain-serve 还会增加一个网站：

• / — 落地页（浏览器）或 JSON 服务描述（Accept: application/json）

• /login — GitHub OAuth；密钥归属于该账户已验证的主邮箱

• /dashboard — 创建最多 3 个有效密钥，有效期 30 / 90 / 365 天（或永不过期，带警告），查看今日用量和每个密钥的到期时间，再次显示密钥，撤销

• /docs — 带 Windows PowerShell / macOS / Linux 标签页的快速入门、MCP 客户端配置

• POST /demo/{numbers|convert|datetime|text} — 免密钥演示，每 IP 30 次/分钟

密钥 API 的行为如下：

• 自助注册：POST /keys/signup {"email": "dev@example.com"} → {"key": "lblz_…", "daily_quota": 1000, "rpm": 60}。限流为每 IP 每天 3 次注册、每邮箱 3 个有效密钥。匿名注册默认关闭，除非设置 LEFTBRAIN_OPEN_SIGNUP=1；有网站时，用户在 /login 登录。

• 每个请求都会被计量：X-RateLimit-Remaining-Today、X-RateLimit-Limit-Day、X-RateLimit-Limit-Minute 响应头；达到限制时返回 429 并带 Retry-After；密钥被禁用时返回 403，密钥到期后返回 403 {"error": "expired", "message": "key expired on 2026-11-25; create a new one at /dashboard"}。已过期的密钥不再计入 3 个有效密钥的上限。

• 调用方自查：GET /keys/me 携带密钥 → 所有者、配额、今日已用、expires_at。

环境变量：GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、LEFTBRAIN_SECRET（用于 Cookie 签名，32 个以上随机字符）、LEFTBRAIN_BASE_URL（例如 https://leftbrain.idlesync.in，用于 OAuth 回调），以及 LEFTBRAIN_TRUSTED_PROXY_HOPS（默认 1）——表示在进程前面有多少个代理向 X-Forwarded-For 追加内容，这样按 IP 的限制是以你的代理写入的入口为准，而不是调用方提供的左起第一个值。一个反向代理（Northflank、Render、Fly、nginx）为 1；前面再加 Cloudflare 就变成 2；0 表示没有代理，且不信任任何转发头。

默认值来自 LEFTBRAIN_DEFAULT_DAILY_QUOTA（1000）、LEFTBRAIN_DEFAULT_RPM（60）、LEFTBRAIN_SIGNUPS_PER_IP_PER_DAY（3）。认证只比较密钥的 SHA-256。当设置了 LEFTBRAIN_SECRET 时，存储中还会保留每个密钥的 Fernet 加密副本，密钥由该 secret 派生，这样已登录的所有者可以在仪表板上再次看到自己的密钥，并自动填入文档示例中。轮换 LEFTBRAIN_SECRET 后，现有密钥仍然可用，但不再可显示；不设置该 secret 则只存储哈希。

管理 CLI（任意 DSN）：

leftbrain-keys create --owner you@example.com --daily 50000 --rpm 300 --expires 90d --note "partner"   # default 365d; --expires never warns
leftbrain-keys list                                     # one JSON line per key, with expires_at / expired
leftbrain-keys disable lblz_xxxxxxxx
leftbrain-keys enable lblz_xxxxxxxx
leftbrain-keys revoke lblz_xxxxxxxx
leftbrain-keys set lblz_xxxxxxxx --daily 20000 --rpm 120 --expires 30d   # --expires counts from now; also revives an expired key
leftbrain-keys usage --days 7
leftbrain-keys stats

适合的免费托管：Northflank 的沙箱（常驻服务 + 免费 Postgres + 自定义域名）——参见 docs/deploy-northflank.md 获取分步指南，包括子域名的 DNS 配置。

变化示例

开发

git clone https://github.com/Lazy-Coder-03/leftbrain && cd leftbrain
python -m venv .venv && . .venv/bin/activate     # .venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest                          # unit tests
python scripts/smoke.py         # every tool, end to end
python scripts/mcp_client_check.py   # spawn each MCP server over stdio and call it
ruff check src tests

布局：src/leftbrain/core/ 存放纯函数（每个工具一个文件），contract.py 存放信封，mcp_server.py 是 stdio 服务器，serve.py 是 HTTP 服务器，external/ 和 files/ 是可选工具集。

发布通过推送 vX.Y.Z 标签完成——参见 docs/releasing.md；每个版本的变更记录在 CHANGELOG.md 中。

路线图

• TypeScript 移植版（相同的工具名称和契约），面向基于 Node 的代理

• 扫描版 PDF 的 OCR 回退方案

• files 中的 csv/xlsx 解析

许可证

MIT