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. The active service contracts include source management, query execution, catalog discovery, workspaces, feedback, episodes, traces, and search. SearchService searches Coral’s catalog and its local memory of values observed during supported source scans. It returns typed, bounded matches for tables, table functions, columns, filters, and observed values, plus status, coverage, and truncation metadata. Before searching its local index, it prepares the current workspace query runtime and catalog. Runtime preparation can read stored credentials, initialize source providers, and inspect file metadata in local or object storage, but it does not execute the user’s data query or return source rows. Use the returned locations with coral sql or the MCP sql tool to fetch current data.

​
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.