withcoral/coral

 [](https://github.com/withcoral/coral/actions/workflows/validate.yml) [](https://github.com/withcoral/coral/releases) [](./LICENSE) [](https://withcoral.com/docs) [](https://withcoral.com/discord) [](https://deepwiki.com/withcoral/coral) Coral 为 agent 提供了一个本地优先的 SQL runtime，支持 API、文件及其他数据源。你可以通过 CLI 查询、检查 schema 和 table，或者通过 MCP 暴露相同的 runtime，让 agent 无需定制化的工具胶水代码即可使用它。 你可以向你的 agent 提出关于数据的复杂问题：  或者自己运行 SQL 查询：  ## 为什么选择 Coral 大多数 agent 工作流一次只能通过一个工具访问公司数据。这虽然可行，但往往会导致： - 过多的工具调用 - 重复的认证、分页和重试逻辑 - 跨数据源推理能力差 - 高 token 流量 - 脆弱的胶水代码和 prompt Coral 转而为 agent 提供一个统一的查询接口： - 通过 SQL 查询多个实时数据源 - 保持工作流可检查且可脚本化 - 通过 MCP 暴露相同的 runtime - 无需手动拼接工具即可回答跨数据源问题 我们使用 Claude Opus 4.6，针对 82 个多样化的真实 AI 任务，对 Coral 与直接提供服务的 MCP（Datadog、Sentry、Linear、Slack 和 Github）进行了基准测试。主要发现如下： 1. **对性能的广泛影响**。在所有任务中，Claude 使用 Coral 比使用直接提供服务的 MCP 准确率提高了 20%，成本效益提升了 2 倍。使用 Coral，Claude 的延迟也降低了 42%。 2. **对编码 agent 任务的影响最大**。在那些代表编码 agent 工作负载的更复杂任务中（多跳、更高的后处理要求），Claude 使用 Coral 的准确率提高了 31%，成本效益提升了 3.4 倍。 3. **对简单任务的影响较为中性**。对于较简单的 AI 任务，例如从知识库中进行原始事实检索，结果更为接近，Claude 使用 Coral 的准确率提高了 6%，成本效益提升了 2%。 完整的[基准测试报告](https://withcoral.com/benchmarks)。 ## Coral 的工作原理 Coral 位于你的 agent 和数据源之间：你的 agent 编写 SQL，Coral 将其转换为 API 调用或文件读取，然后返回单一的结果集。 ``` graph LR Agent["You / your agent"] -->|SQL query| Coral["Coral (local)"] Coral -->|Result rows| Agent subgraph Sources["Installed sources"] GH["github source
(github.* tables)"] LN["linear source
(linear.* tables)"] FS["file source
(your_files.* tables)"] end Coral --> GH Coral --> LN Coral --> FS subgraph Backing["Backing systems"] GHAPI["GitHub API"] LNAPI["Linear API"] Disk["Local files"] end GH -.->|PAT / gh auth token| GHAPI LN -.->|Personal API key| LNAPI FS -.->|File path| Disk ``` **数据源。** _source spec_ 是一个 YAML 文件，声明了如何连接 API 或本地数据集，以及它暴露了哪些 table 和 column。_source_ 是该 spec 加上你为其配置的凭据和变量。当你运行 `coral source add github` 时，Coral 会安装 `github` 数据源，并在查询时将其作为 `github` SQL schema 暴露出来，因此 `github.issues` 和 `github.pulls` 等 table 就变得可查询了。从[内置数据源](https://withcoral.com/docs/reference/bundled-sources)开始，或者[编写自己的数据源](https://withcoral.com/docs/guides/write-a-custom-source)。 **跨数据源 Joins。** 因为每个数据源都显示为 SQL table，你可以在一个语句中对它们进行 `JOIN`，Coral 会从各自的后端 API 或文件中获取数据后，在本地执行 join。例如，要查看哪些 Linear issue 正在跟踪未解决的 GitHub pull request： ``` SELECT a.issue_identifier, a.url, p.state FROM linear.attachments a JOIN github.pulls p ON p.html_url = a.url WHERE p.owner = 'withcoral' AND p.repo = 'coral' ``` **认证。** 在执行 `coral source add` 时，Coral 会从匹配的环境变量中读取变量和机密信息，或者在你传递 `--interactive` 时提示输入。这些值存储在本地，仅在查询时使用；凭据永远不会离开你的机器。 **为生产环境而生。** Coral 在设计上是一个读取层。对于读取任务，当复杂度超过单个 API 调用的处理能力时，SQL 的表现优于针对单一数据源的工具调用：Coral 处理分页，返回表格化行而不是杂乱无章的 JSON，并让查询仅选择所需的 column。查询下推和缓存机制保持了响应速度，并减少了不必要的 API 流量。 要更深入地了解其内部机制，请参阅[架构页面](https://withcoral.com/docs/project/architecture)。 ## 内置数据源 Coral 开箱即支持多种数据源，如 Datadog、GitHub、Linear、Sentry、Stripe 等——此外还支持本地 JSONL 和 Parquet 文件。 运行 `coral source discover` 查看你的构建中包含哪些数据源，或者查阅[内置数据源参考](https://withcoral.com/docs/reference/bundled-sources)以获取权威列表。如果你需要的数据源不在其中，你可以[编写自定义数据源](https://withcoral.com/docs/guides/write-a-custom-source)，或者[让我们知道你希望 Coral 支持你正在使用的数据源](https://github.com/withcoral/coral/issues/new)。 ## 快速入门 这将引导你从全新[安装](https://withcoral.com/docs/getting-started/installation)Coral 到执行你的第一次 SQL 查询。如果你更喜欢交互式向导，可以运行 `coral onboard`，它将指导你完成下面涵盖的所有内容。 ### 1. 安装 Coral 在 macOS 上： ``` brew install withcoral/tap/coral ``` 或者在 Linux 上： ``` curl -fsSL https://withcoral.com/install.sh | sh ``` 或者在 Windows 10/11 x86_64 上，从最新的 GitHub release 下载 `coral-x86_64-pc-windows-msvc.zip`，并将 `coral.exe` 放到你的 `PATH` 中。 查看[所有安装选项](https://withcoral.com/docs/getting-started/installation)。 ### 2. 发现内置数据源 ``` coral source discover ``` 这会列出你构建版本中可用的内置数据源。 ### 3. 添加数据源 例如，以交互方式添加 GitHub： ``` coral source add --interactive github ``` Coral 会提示输入任何必需的变量或机密信息。对于脚本化设置，省略 `--interactive`，并以同名环境变量的形式提供每个输入，例如 `GITHUB_TOKEN=ghp_... coral source add github`。连接成功后，该数据源的数据即可作为 SQL table 访问。以后若要更新数据源的凭据，再次运行相同的命令即可。 ### 4. 查询你的数据 使用 `coral.tables` 和 `coral.table_functions` 查看可用的查询接口： ``` coral sql "SELECT schema_name, table_name FROM coral.tables ORDER BY 1, 2" coral sql "SELECT schema_name, function_name FROM coral.table_functions ORDER BY 1, 2" ``` 假设你已经连接了 GitHub，尝试列出某个 repo 的未解决 issue： ``` coral sql " SELECT number, title, state, created_at FROM github.issues WHERE owner = 'withcoral' AND repo = 'coral' AND state = 'open' ORDER BY created_at DESC LIMIT 10 " ```  ### 后续步骤 - **[通过 MCP 使用 Coral](https://withcoral.com/docs/guides/use-coral-over-mcp)** — 通过 MCP 将 Coral 暴露给 Claude Code、Cursor 或 VS Code，让你的 agent 可以直接查询数据源 - **[编写自定义 source spec](https://withcoral.com/docs/guides/write-a-custom-source)** — 连接任何尚未内置的 HTTP API 或本地数据集 - **[安装 Coral skills](https://withcoral.com/docs/getting-started/installation#skills)** — 教你的编码 agent 如何使用 Coral ## 与 agent 一起使用 Coral Coral 附带一个内置的 MCP server，它将 Coral 作为只读 SQL 数据库呈现给你的 agent。一旦你添加了至少一个数据源，就可以将 Coral 接入你的 agent： ``` claude mcp add --scope user coral -- coral mcp-stdio # Claude Code codex mcp add coral -- coral mcp-stdio # Codex ``` 有关 Cursor、VS Code、Claude Desktop、OpenCode 的配置和手动配置示例，请参阅[通过 MCP 使用 Coral](https://withcoral.com/docs/guides/use-coral-over-mcp)。 Coral 还发布了一套 skills，教你的 agent 采用“发现优先”的 SQL 工作流（`list_catalog`、`coral.tables`、`coral.table_functions`、`coral.columns` 等）： ``` npx skills add withcoral/skills ``` 连接成功后，要求你的 agent“列出 Coral 中可用的 table”或运行一个小查询。它应该使用 `list_catalog`、`search_catalog` 或 `coral.tables` / `coral.table_functions` 元数据 table 进行数据库目录发现，然后在你可见的 schema、table 和 table 函数上使用 SQL 进行回答。 ## 本地状态 Coral 将本地状态存储在其特定于平台的配置目录中。 你可以使用以下命令覆盖配置目录： ``` export CORAL_CONFIG_DIR=/path/to/coral-config ``` 重要文件包括： - `config.toml` 用于存储已安装数据源的元数据和非机密变量 - 导入的 source spec 位于 `workspaces//sources//manifest.yaml` - 数据源机密单独存储在相同的本地信任边界内 内置 source spec 不会被复制到配置目录中。当你在验证或查询内置数据源时，Coral 会从当前的二进制文件中解析它们，因此在进行升级时，无需重新添加数据源即可获取最新的内置清单。 ## 开发 使用 Homebrew 安装一次本地测试运行器： ``` brew install cargo-nextest ``` 或者使用 Cargo 安装： ``` cargo install cargo-nextest --locked ``` 从仓库根目录运行工作区验证门控： ``` make rust-checks ``` ## 文档 如需设置指南、参考文档和示例，请访问 [withcoral.com/docs](https://withcoral.com/docs)。 ## 安全 请不要在公开的 issue 或 pull request 中报告安全问题。请参阅 [`SECURITY.md`](./SECURITY.md)。 ## 许可证 Coral 采用 Apache License 2.0 授权。请参阅 [`LICENSE`](./LICENSE)。

标签：AI智能体, MCP, SQL运行时, 可视化界面, 多线程, 数据查询, 文档结构分析, 通知系统