Struct HyperMcpServer 

pub struct HyperMcpServer { /* private fields */ }

The MCP server that registers all Hyper tools and routes invocations.

The Engine is lazily initialized behind a Mutex<Option<Engine>> so that the expensive HyperProcess startup only happens on the first actual tool call, not during MCP handshake. This keeps initialize fast and avoids starting hyperd if the client never calls a tool.

Implementations

impl HyperMcpServer

pub fn new(persistent_path: Option<String>, read_only: bool) -> Self

Create a server instance. Pass Some(path) for persistent workspace, None for ephemeral (temp directory, auto-cleaned).

The saved-queries store is chosen to match the workspace mode: persistent workspaces get a crate::saved_queries::WorkspaceStore (backed by a meta-table in the .hyper file so queries survive restarts), ephemeral workspaces get an in-memory crate::saved_queries::SessionStore.

When read_only is true, the execute, load_data, load_file, save_query, delete_query, and set_table_metadata tools return a ReadOnlyViolation error, and exporting to the hyper format (which is a raw file copy, harmless) remains allowed.

When bare is true, the server does not create or maintain the _table_catalog table, and saved queries fall back to the in-memory crate::saved_queries::SessionStore regardless of workspace_path persistent_path is the resolved path to the persistent database (Some) or None for --ephemeral-only mode.

pub fn with_no_daemon( persistent_path: Option<String>, read_only: bool, no_daemon: bool, ) -> Self

Create a server instance with explicit daemon control.

pub fn subscriptions_handle(&self) -> Arc<SubscriptionRegistry>

Return a clone of the subscription registry so background tasks (notably the directory watcher) can fire resource updates after their own ingest completes.

pub fn engine_handle(&self) -> Arc<Mutex<Option<Engine>>>

Return a clone of the engine Arc so background tasks (watchers) can share access to the same lazy-initialized engine instance.

pub fn watchers_handle(&self) -> Arc<WatcherRegistry>

Return a clone of the watcher registry handle for tool handlers.

pub fn attachments_handle(&self) -> Arc<AttachRegistry>

Return a clone of the attachments registry handle for tool handlers and the with_engine replay path.

pub fn is_read_only(&self) -> bool

Whether the server is running in read-only mode.

pub fn warm_up_engine(&self)

Eagerly initialize the engine at server startup, before any tool call arrives. This makes read-only observer tools like status able to report full stats on the very first call without having to trigger initialization themselves — status stays a pure, non-blocking observer (honoring issue #118).

Errors are logged and swallowed rather than propagated: if hyperd is unreachable at startup the server still comes up, and the first data-plane tool call will retry initialization via with_engine.

impl HyperMcpServer

pub fn query_data_tool_attr() -> Tool

Generated tool metadata function for query_data

pub fn query_file_tool_attr() -> Tool

Generated tool metadata function for query_file

pub fn load_data_tool_attr() -> Tool

Generated tool metadata function for load_data

pub fn load_file_tool_attr() -> Tool

Generated tool metadata function for load_file

pub fn load_files_tool_attr() -> Tool

Generated tool metadata function for load_files

pub fn load_iceberg_tool_attr() -> Tool

Generated tool metadata function for load_iceberg

pub fn query_tool_attr() -> Tool

Generated tool metadata function for query

pub fn execute_tool_attr() -> Tool

Generated tool metadata function for execute

pub fn sample_tool_attr() -> Tool

Generated tool metadata function for sample

pub fn chart_tool_attr() -> Tool

Generated tool metadata function for chart

pub fn watch_directory_tool_attr() -> Tool

Generated tool metadata function for watch_directory

pub fn unwatch_directory_tool_attr() -> Tool

Generated tool metadata function for unwatch_directory

pub fn describe_tool_attr() -> Tool

Generated tool metadata function for describe

pub fn inspect_file_tool_attr() -> Tool

Generated tool metadata function for inspect_file

pub fn export_tool_attr() -> Tool

Generated tool metadata function for export

pub fn save_query_tool_attr() -> Tool

Generated tool metadata function for save_query

pub fn delete_query_tool_attr() -> Tool

Generated tool metadata function for delete_query

pub fn set_table_metadata_tool_attr() -> Tool

Generated tool metadata function for set_table_metadata

pub fn kv_get_tool_attr() -> Tool

Generated tool metadata function for kv_get

pub fn kv_set_tool_attr() -> Tool

Generated tool metadata function for kv_set

pub fn kv_delete_tool_attr() -> Tool

Generated tool metadata function for kv_delete

pub fn kv_list_tool_attr() -> Tool

Generated tool metadata function for kv_list

pub fn kv_list_stores_tool_attr() -> Tool

Generated tool metadata function for kv_list_stores

pub fn kv_size_tool_attr() -> Tool

Generated tool metadata function for kv_size

pub fn kv_pop_tool_attr() -> Tool

Generated tool metadata function for kv_pop

pub fn kv_clear_tool_attr() -> Tool

Generated tool metadata function for kv_clear

pub fn status_tool_attr() -> Tool

Generated tool metadata function for status

pub fn get_readme_tool_attr() -> Tool

Generated tool metadata function for get_readme

pub fn attach_database_tool_attr() -> Tool

Generated tool metadata function for attach_database

pub fn detach_database_tool_attr() -> Tool

Generated tool metadata function for detach_database

pub fn list_attached_databases_tool_attr() -> Tool

Generated tool metadata function for list_attached_databases

pub fn copy_query_tool_attr() -> Tool

Generated tool metadata function for copy_query

impl HyperMcpServer

pub fn analyze_table_prompt_attr() -> Prompt

pub fn analyze_table( &self, Parameters: Parameters<AnalyzeTableArgs>, ) -> Pin<Box<dyn Future<Output = Vec<PromptMessage>> + Send + '_>>

Deep analysis of a single table: schema, sample, column statistics, data quality flags.

pub fn compare_tables_prompt_attr() -> Prompt

pub fn compare_tables( &self, Parameters: Parameters<CompareTablesArgs>, ) -> Pin<Box<dyn Future<Output = Vec<PromptMessage>> + Send + '_>>

Compare two tables side-by-side: schema alignment, common keys, JOIN suggestions.

pub fn data_quality_prompt_attr() -> Prompt

pub fn data_quality( &self, Parameters: Parameters<DataQualityArgs>, ) -> Pin<Box<dyn Future<Output = Vec<PromptMessage>> + Send + '_>>

Systematic data quality assessment: nulls, duplicates, cardinality, outliers.

pub fn suggest_queries_prompt_attr() -> Prompt

pub fn suggest_queries( &self, Parameters: Parameters<SuggestQueriesArgs>, ) -> Pin<Box<dyn Future<Output = Vec<PromptMessage>> + Send + '_>>

Propose useful analytical queries for a table, optionally guided by a goal.

impl HyperMcpServer

pub fn resource_body_for_uri( &self, uri: &str, ) -> Result<Option<ResourceBody>, McpError>

Produce the body for a resource URI without constructing an MCP RequestContext. Factored out of Self::read_resource so tests can exercise URI dispatch without standing up the full MCP runtime.

Returns Ok(None) if the URI isn’t recognized at all (the async trait method surfaces this as an invalid_params error to clients).

The returned ResourceBody carries its own MIME type so non-JSON resources (hyper://readme, hyper://tables/{name}/csv-sample, etc.) can be served verbatim as markdown / CSV.

Errors

Propagates any McpError from the underlying engine call (status probe, table description, CSV sample, saved-query listing, etc.) and bubbles up ErrorCode::TableNotFound for hyper://tables/{name}/... URIs whose table is absent from the workspace.

pub fn list_resource_uris(&self) -> Vec<String>

Produce the list of MCP resources without constructing an MCP RequestContext. Factored out of Self::list_resources for tests.

Returns one URI for the workspace, one for the full tables list, one for the workspace readme, one for the KV store schema, three per existing table (schema, sample, csv-sample), and two per saved query (definition, result).

Trait Implementations

impl Debug for HyperMcpServer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ServerHandler for HyperMcpServer

async fn subscribe( &self, request: SubscribeRequestParams, context: RequestContext<RoleServer>, ) -> Result<(), ErrorData>

Handle a resources/subscribe request by recording the calling peer in the registry under the requested URI.

MCP does not mandate that the server validate the URI exists beforehand — subscriptions to URIs that don’t resolve today (e.g. a saved-query result before save_query is called) are allowed and will start delivering notifications as soon as the URI becomes reachable.

async fn unsubscribe( &self, request: UnsubscribeRequestParams, context: RequestContext<RoleServer>, ) -> Result<(), ErrorData>

Handle a resources/unsubscribe request. Clears every subscription recorded against the URI in this process (see the module-level docs on crate::subscriptions for why we don’t attempt to match peers individually).

async fn list_resources( &self, _request: Option<PaginatedRequestParams>, _context: RequestContext<RoleServer>, ) -> Result<ListResourcesResult, ErrorData>

List MCP resources: the workspace, the tables list, a markdown readme, the KV store schema, and three entries per existing table (schema, JSON sample, CSV sample). Calling this lazily starts the engine, so it doubles as a “wake up” signal for MCP clients that pre-fetch resources at connection time.

async fn list_resource_templates( &self, _request: Option<PaginatedRequestParams>, _context: RequestContext<RoleServer>, ) -> Result<ListResourceTemplatesResult, ErrorData>

Advertise URI templates so clients can construct resource URIs for tables they know about without round-tripping list_resources.

async fn read_resource( &self, request: ReadResourceRequestParams, _context: RequestContext<RoleServer>, ) -> Result<ReadResourceResult, ErrorData>

Read a resource by URI. Dispatches via HyperMcpServer::resource_body_for_uri which returns both the content and its MIME type (JSON for metadata URIs, markdown for the workspace readme, CSV for per-table samples).

fn get_info(&self) -> ServerInfo

async fn initialize( &self, request: InitializeRequestParams, context: RequestContext<RoleServer>, ) -> Result<InitializeResult, ErrorData>

async fn call_tool( &self, request: CallToolRequestParams, context: RequestContext<RoleServer>, ) -> Result<CallToolResult, ErrorData>

Handle a tools/call request from a client.

async fn list_tools( &self, _request: Option<PaginatedRequestParams>, _context: RequestContext<RoleServer>, ) -> Result<ListToolsResult, ErrorData>

fn get_tool(&self, name: &str) -> Option<Tool>

Get a tool definition by name.

async fn get_prompt( &self, request: GetPromptRequestParams, context: RequestContext<RoleServer>, ) -> Result<GetPromptResult, ErrorData>

async fn list_prompts( &self, _request: Option<PaginatedRequestParams>, _context: RequestContext<RoleServer>, ) -> Result<ListPromptsResult, ErrorData>

fn enqueue_task( &self, _request: CallToolRequestParams, _context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<CreateTaskResult, ErrorData>> + MaybeSendFuture

fn ping( &self, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

fn complete( &self, request: CompleteRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<CompleteResult, ErrorData>> + MaybeSendFuture

fn set_level( &self, request: SetLevelRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

fn on_custom_request( &self, request: CustomRequest, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<CustomResult, ErrorData>> + MaybeSendFuture

fn on_cancelled( &self, notification: CancelledNotificationParam, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_progress( &self, notification: ProgressNotificationParam, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_initialized( &self, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_roots_list_changed( &self, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_custom_notification( &self, notification: CustomNotification, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn list_tasks( &self, request: Option<PaginatedRequestParams>, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<ListTasksResult, ErrorData>> + MaybeSendFuture

fn get_task_info( &self, request: GetTaskInfoParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<GetTaskResult, ErrorData>> + MaybeSendFuture

fn get_task_result( &self, request: GetTaskResultParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<GetTaskPayloadResult, ErrorData>> + MaybeSendFuture

fn cancel_task( &self, request: CancelTaskParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<CancelTaskResult, ErrorData>> + MaybeSendFuture