Overview
Coral is split into seven crates. The two entry points, the CLI and the MCP server, share the same runtime throughcoral-client and coral-app.
Request flow
A query follows this path:- Entry point: a user runs
coral sqlor an agent calls thesqlMCP tool - Bootstrap: the caller decides whether to start a local
coral-appserver or dial an existing endpoint coral-client: connects to that endpoint and sends the request over gRPCcoral-app: loads installed sources from local state, delegates spec validation tocoral-spec, and hands validated specs tocoral-enginecoral-engine: compiles specs into DataFusion table providers, registers them in a session, and executes SQL- Result: Arrow record batches flow back through gRPC to the client, which formats them as table or JSON output (CLI) or structured MCP tool results (MCP)
Crates
coral-cli
The user-facing command-line interface.
| Owns | Details |
|---|---|
| Command parsing | coral sql, coral source, coral onboard, coral mcp-stdio |
| Interactive prompts | Variables and secrets during source add |
| Output formatting | Table and JSON via coral-client helpers |
main.rs is a small wrapper, bootstrap.rs owns CLI bootstrap, and lib.rs owns shared command parsing and dispatch for Coral binaries. Query/result helpers stay in coral-client.
For black-box CLI tests, contributors can enable the CORAL_ENDPOINT bootstrap override with cargo nextest run --locked -p coral-cli --features cli-test-server.
coral-client
Shared client library used by both coral-cli and coral-mcp.
| Owns | Details |
|---|---|
| Endpoint dialing | AppClient::connect(endpoint) builds typed gRPC clients for an existing endpoint |
| Explicit local bootstrap | local::{ServerBuilder, ServerMode, RunningServer} for callers that need local server control |
| Result decoding | Arrow IPC → record batches |
| Error decoding | Decodes AIP-193 ErrorInfo from tonic::Status details (status_error.rs) |
| Formatting helpers | format_batches_table, format_batches_json |
coral-app
The local server and core orchestrator.
| Owns | Details |
|---|---|
| Server bootstrap | In-process gRPC server lifecycle (bootstrap/) |
| Source management | Install, add from file, list, validate, remove (sources/) |
| Workspace state | Config, secrets, and workspace layout (state/, storage/) |
| Feedback persistence | Workspace-scoped blocked-agent feedback reports (feedback/) |
| Query orchestration | Loads sources, builds the engine, executes SQL (query/) |
| Catalog discovery | Lists/searches/describes query-visible tables and columns (catalog/) |
coral-spec and coral-engine together and manages all persistent local state.
coral-spec
Source spec parsing and validation.
| Owns | Details |
|---|---|
| YAML parsing | Deserializes source specs into typed Rust structs |
| Validation | Structural invariants, required fields, backend-specific rules (validate.rs) |
| Input discovery | Extracts required variables and secrets from specs (inputs.rs) |
| Backend-specific models | HTTP, MCP, and file spec shapes (backends/) |
coral-engine consumes. No runtime or I/O, pure data transformation.
coral-engine
Query execution engine.
| Owns | Details |
|---|---|
| Backend compilation | Turns validated specs into DataFusion TableProvider implementations (backends/) |
| Runtime registry | Registers table providers into a DataFusion session (runtime/) |
| Query contracts | Engine-facing types for catalog and query results (contracts/) |
| Backend implementations | HTTP, MCP, and native file backends (backends/http, backends/mcp, backends/file) |
coral-mcp
The MCP stdio server.
| Owns | Details |
|---|---|
| MCP protocol | Tool and resource handlers via the rmcp SDK (server.rs) |
| Surface shaping | Tool/resource/error helpers split across surface/{mod,tools,resources,errors}.rs; discovery semantics come from coral-app |
| Tools | sql, list_catalog, search_catalog, describe_table, list_columns, optional feedback |
| Resources | coral://guide, coral://tables |
coral-client to reach coral-app, same transport as the CLI.
coral-api
The shared gRPC contract.
| Owns | Details |
|---|---|
| Protobuf definitions | proto/coral/v1/ — query.proto, sources.proto, catalog.proto, resources.proto |
| Generated bindings | Tonic-generated Rust types and service traits |
coral-client and coral-app goes through these generated types.
Dependency graph
coral-spec and coral-engine do not depend on each other. coral-app is the integration point that connects them.
Key design choices
- Local gRPC server. The CLI and MCP server don’t embed the engine directly, they go through a local gRPC server managed by
coral-app. This keeps the engine lifecycle in one place and makes the client/server boundary explicit. - Spec vs engine separation.
coral-specis pure validation (no I/O, no runtime).coral-engineis pure execution (no YAML parsing, no persistence).coral-appbridges the two.