Skip to main content

​
Overview

Coral is split into seven crates. The two entry points, the CLI and the MCP server, share the same runtime through coral-client and coral-app.

​
Request flow

A query follows this path:
  1. Entry point: a user runs coral sql or an agent calls the sql MCP tool
  2. Bootstrap: the caller decides whether to start a local coral-app server or dial an existing endpoint
  3. coral-client: connects to that endpoint and sends the request over gRPC
  4. coral-app: loads installed sources from local state, delegates spec validation to coral-spec, and hands validated specs to coral-engine
  5. coral-engine: compiles specs into DataFusion table providers, registers them in a session, and executes SQL
  6. 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. Intentionally thin at the binary boundary — 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.

​
coral-app

The local server and core orchestrator. This is the largest crate. It ties coral-spec and coral-engine together and manages all persistent local state.

​
coral-spec

Source spec parsing and validation. Produces a validated spec model that coral-engine consumes. No runtime or I/O, pure data transformation.

​
coral-engine

Query execution engine.

​
coral-mcp

The MCP stdio server. Uses coral-client to reach coral-app, same transport as the CLI.

​
coral-api

The shared gRPC contract. All inter-crate communication between 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-spec is pure validation (no I/O, no runtime). coral-engine is pure execution (no YAML parsing, no persistence). coral-app bridges the two.