Elliot

Elliot

将任意 API 或数据库转化为 Claude Code、Cursor、OpenClaw 和 Codex 的 MCP 工具——内置可观测性。

文档 · 快速入门 · 概念 · 五项原则

Elliot 是一个开源平台，可将你现有的产品——REST API、SQL 数据库、文件——转化为 AI Agent 能够良好使用的工具。不只是连接起来，还要做到快速、安全且可观测：尽量减少令牌用量，提供 Agent 能够恢复的结构化错误，并完整追踪每个 Agent 会话。

目标用户是产品工程师：他们已有可用的 API 或数据库，并希望 AI Agent 能原生地与之交互，同时尽可能减少令牌用量、实现简洁的错误恢复和全面的可观测性。

AX 之于 Agent，正如 UX 之于用户、DX 之于开发者。Elliot 的任务是让 AX 可衡量。

目录

• 为什么选择 Elliot
• 功能特性
• 快速入门
• 实际效果
• 工作原理
• 连接你的编码 Agent
• 项目结构
• 文档
• 路线图
• 参与贡献
• 社区与支持
• 许可证

为什么选择 Elliot

将 API 连接到 Agent 很简单，让它良好运行却并不容易。以下情况会导致 Agent 失败：

• 工具描述含糊不清——Agent 会选错工具。
• 结果过于庞大——答案还没生成，上下文窗口就已填满。
• 错误没有结构化——Agent 无法恢复或升级处理。
• 缺乏可观测性——直到用户投诉，你才发现系统出了问题。

Elliot 让这些问题都清晰可见，并且能够修复。每个工具都附带结构化架构、令牌用量估算、可执行的错误格式和会话追踪——记录每次调用和每个 Agent，并标明对应的客户端和模型。

功能特性

• 专为 Agent 打造——每个工具在发布前都会根据五项具体原则进行检查：描述以动词开头、参数有类型、结果适配上下文。
• 默认安全——参数化 SQL、数据库只读事务、通过环境变量提供密钥，连接器文件中不包含密钥。连接器文件可以安全地提交到代码库。
• 每次调用均可观测——记录每次 Agent 调用的令牌用量、延迟、参数和错误，并将数据流式写入审计日志，在 Studio 中呈现。
• 一条命令即可运行——使用 Docker 启动整个技术栈。无需安装 Python、Node 或工具链。
• 兼容所有 Agent——Claude Code、Cursor、OpenClaw 和 Codex。Elliot 会自动向它们注册。
• Agent 可构建连接器——发现、构建、检查、评估、部署。平台本身具备 Agent 能力：Agent 可以通过 Elliot 构建连接器。

快速入门

只想运行 Elliot？ 唯一的前置条件是安装 Docker——无需 Python、Node、uv 或 pnpm：

curl -LsSf https://raw.githubusercontent.com/EliBarak12/Elliot/main/scripts/install.sh | sh

此命令会拉取预构建镜像、生成本地 .env、启动全部三个服务，并在 http://localhost:8080 打开 Studio。你可以随时运行 docker compose -f docker-compose.run.yml down 停止服务。

想开发 Elliot？ 改为从源代码构建：

# Prerequisites: uv (Python 3.13) and pnpm (Node 22)
git clone https://github.com/EliBarak12/Elliot.git && cd Elliot
make setup
make dev          # boots plugin (:3000) + studio (:5173)
                  # and writes the MCP config for every detected coding agent
                  # the runtime (:3001) starts on demand when you deploy a connector

然后在 http://localhost:5173 打开 Studio，搭建连接器并对其运行 lint，之后你的 Agent 就能在同一会话中使用它。

现场演示

Elliot Studio 演示——这个可视化仪表板可以观察、运行和编辑 Agent 构建的一切。

上方的循环会依次展示 Studio 的每个页面。要观看完整画质的屏幕录制，请观看视频演示。

Studio 详情：

工具——以动词开头、带类型的契约，供 Agent 调用。设计、验证并测试每个工具。	指标——统计所有工具的调用次数、错误率、延迟和令牌效率。
Agent 控制台——实时追踪每个 Agent 会话：提示词、工具调用、令牌和错误。	数据源——REST API、PostgreSQL、MySQL 和文件，均可在一处发现和管理。

工作原理

1. Connect your data sources
   REST APIs, PostgreSQL, MySQL, CSV / JSON files — all in one connector

2. Build tools (no SQL required)
   Define name, description, parameters, filters, and return fields
   Elliot generates safe, parameterised queries
   Or let an agent build the connector for you with the agentic builder

3. Lint for agent-readiness
   elliot lint my-domain.connector.json

4. Write and run eval cases
   elliot eval my-domain.eval.yaml — pass/fail plus a token estimate

5. Deploy and connect agents
   plugin (:3000) serves tools to any MCP client
   runtime (:3001) executes them against live data
   studio observes, runs, and edits everything

6. (Optional) Ship the connector as a plugin
   elliot export-plugin my-domain.connector.json
   produces an installable Codex + Claude Code plugin folder

首次连接时，Agent 会自动调用 prompts/get name=getting_started——这个提示词会介绍五项原则、标准工作流以及可用的参考资源。

连接编码 Agent

make dev 会运行 elliot connect，自动检测你机器上的所有编码 Agent，并写入其 MCP 配置。要手动配置客户端：

/plugin marketplace add EliBarak12/Elliot
/plugin install elliot@elliot

{ "mcpServers": { "elliot": {
  "url": "https://api.elliot-cloud.com/b/mcp"
}}}

codex plugin marketplace add EliBarak12/Elliot

openclaw plugins install elliot@elliot

每种安装方式都只配置 MCP URL——Elliot 的服务仍需在本地或托管端点运行。技能位于仓库根目录的 skills/ 目录中；Claude Code 和 Codex 会自动发现这些技能，其他所有 MCP 客户端都会收到相同的指导内容，形式为 MCP 提示词。

将 Elliot 添加到 Claude.ai 和 Claude Desktop

上方的表格介绍的是 Claude Code 插件。要在 Claude.ai（网页端）或 Claude Desktop / mobile 应用中使用 Elliot，请将其添加为远程 Connector——Elliot 托管的端点使用 MCP HTTP 传输并完成完整的 OAuth 2.1 握手，因此无需粘贴密钥：

1. 在 Claude 中，打开 Settings → Connectors。
2. 点击 Add custom connector。
3. 粘贴 Elliot MCP URL 并确认：

   https://api.elliot-cloud.com/b/mcp
   

4. Claude 会注册自身（RFC 7591 动态客户端注册），然后将你带到 Elliot 授权页面。登录后点击 Allow，Claude 随即会显示已连接。

Elliot 的工具现在会显示在每个聊天的连接器选择器中。访问授权会列在 Elliot 控制面板的 Connected agents 下，你可以随时在那里撤销。由于连接器会为每位用户单独进行身份验证（scope: per_user），每位团队成员都会使用自己的身份授权——无需共享密钥。

要自托管 Elliot？请将连接器指向你自己的部署中的 /b/mcp URL。OAuth 发现文档由同一主机提供，因此只需确保它可通过 HTTPS 访问。

要让 Elliot 显示在 Anthropic 内置的 Connectors directory 中（这样用户无需粘贴 URL 即可添加），请参阅 docs/claude-connector-directory.md。

将连接器打包为独立插件

构建好连接器后，可将其打包为独立插件，以便安装到 Codex 和 Claude Code 中：

elliot export-plugin my-domain.connector.json

这会生成一个 my-domain-plugin/ 文件夹，其中包含 Codex 和 Claude Code 清单、市场、一个通过标准输入输出提供连接器服务的 .mcp.json（elliot-mcp --connector），以及一个 skills/ 目录。MCP 服务以连接器 slug 命名，因此其工具为 mcp__<slug>__<tool-id>；生成的技能——一份使用指南，以及每个连接器工作流各一份——已经引用了此前缀。使用 /plugin marketplace add <folder>（Claude Code）或 codex plugin marketplace add <folder>（Codex）进行安装。

项目结构

Elliot 是由四个包组成的单体仓库：

连接器文件位于 connectors/，插件附带入门模板（通过 elliot://templates/ MCP 资源浏览），所有环境变量均记录在 .env.example 中。

文档

完整文档请访问 elibarak12.github.io/Elliot。

• 快速入门 — 几分钟内运行连接器
• 概念 — 数据源、工具、技能、连接器
• 五项原则 — 每个连接器都遵循的设计规则
• 连接器规范 — 完整的 .connector.json 架构
• 架构 — 三项服务如何协同工作
• 部署 — Docker 镜像、环境变量、托管

路线图

Elliot 的目标是让所有人都能使用，而不只是开发者。进展记录在 dev/docs/USER_ONBOARDING.md 中。

参与贡献

欢迎贡献代码、连接器、文档和 Bug 报告。

• 浏览适合新手的问题，开始参与。
• 新连接器尤其有价值 — 请参阅连接器请求模板。
• 创建 PR 前，请运行以下必需检查。六项检查必须全部通过。

uv run ruff check .
uv run ruff format --check .
uv run mypy packages/core/src packages/mcp-plugin/src packages/connector-runtime/src
uv run pytest --tb=short
pnpm --filter @elliot/studio run typecheck
pnpm --filter @elliot/studio test --run

社区与支持

发现 Bug、有功能请求，或想提议添加连接器？请在问题跟踪器中创建问题 — 我们会阅读每一条。

许可证

Elliot 采用 MIT 许可证发布。