diff --git a/README.md b/README.md index 2358b4a3..9b2b8d84 100644 --- a/README.md +++ b/README.md @@ -259,6 +259,17 @@ You can also enable both ClickHouse and chDB simultaneously: 4. Restart Claude Desktop to apply the changes. +### Quick Install with ypipe + +Install and run **ypipe** with a single command using JBang: +```bash +jbang ypipe@iunera/ypipe +``` +Or download the desktop app from [ypipe.com](https://ypipe.com). Once opened, simply import the pre-configured blueprint files to install with one click: +* **Embedded chDB:** [chdb.ypipe](./chdb.ypipe) +* **SQL Playground:** [clickhouseplayground.ypipe](./clickhouseplayground.ypipe) +* **Custom ClickHouse:** [localclickhouse.ypipe](./localclickhouse.ypipe) + ### Optional Write Access By default, this MCP enforces read-only queries so that accidental mutations cannot happen during exploration. To allow DDL or INSERT/UPDATE statements, set the `CLICKHOUSE_ALLOW_WRITE_ACCESS` environment variable to `true`. The server keeps enforcing read-only mode if the ClickHouse instance itself disallows writes. @@ -367,7 +378,7 @@ logger = logging.getLogger("my-middleware") class LoggingMiddleware(Middleware): """Log all tool calls.""" - + async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext): tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown' logger.info(f"Calling tool: {tool_name}") diff --git a/chdb.ypipe b/chdb.ypipe new file mode 100644 index 00000000..9d1be8bb --- /dev/null +++ b/chdb.ypipe @@ -0,0 +1,96 @@ +--- +apiVersion: "mcp.ypipe.com/v1" +kind: "McpIntegrationBlueprint" +metadata: + name: "chdb" + namespace: "system" +spec: + displayName: "chDB (Embedded ClickHouse)" + description: "Embedded ClickHouse engine (chDB) for analytical queries on local\ + \ files (Parquet, CSV, JSON) and in-memory data." + source: "https://github.com/ClickHouse/mcp-clickhouse" + configurationSchema: + CHDB_DATA_PATH: + type: "string" + required: false + default: ":memory:" + description: "Path for persistent storage, or ':memory:' for in-memory database" + sensitive: null + pattern: null + mcpConfig: + type: "stdio" + command: "uv" + args: + - "run" + - "--with" + - "mcp-clickhouse" + - "--python" + - "3.10" + - "mcp-clickhouse" + env: + CHDB_ENABLED: "true" + CLICKHOUSE_ENABLED: "false" + CHDB_DATA_PATH: "${CHDB_DATA_PATH}" + url: null + headers: null + disabledTools: null + suggestions: + - id: "chdb-chdb-query-local-files" + title: "chDB: Query Local Files" + label: "Run SQL on local Parquet or CSV files" + action: "Use chDB to execute a SELECT query on my local data files (like Parquet\ + \ or CSV) and show the results." + actionType: null + target: null + - id: "chdb-chdb-in-memory-analytics" + title: "chDB: In-Memory Analytics" + label: "Perform high-speed SQL in memory" + action: "Run an analytical SQL aggregation on an in-memory dataset using the chDB\ + \ engine." + actionType: null + target: null + tools: + run_chdb_select_query: + description: "Execute SQL queries on local data files or in-memory using the\ + \ embedded chDB engine." + usageIntent: null + discoveryHint: "Query and analyze local data files or in-memory datasets using\ + \ the high-performance, embedded chDB engine, which brings the power of ClickHouse\ + \ directly to your local environment without the need for a separate server\ + \ process. This tool is exceptionally well-suited for serverless SQL analysis,\ + \ allowing you to perform ad-hoc data processing, complex aggregations, and\ + \ advanced analytical queries on various file formats including Parquet, CSV,\ + \ JSON, Arrow, and more. By leveraging the chDB library, which is essentially\ + \ an in-process version of ClickHouse, the agent initiates a sophisticated\ + \ analytical sequence where the engine directly reads from the local filesystem,\ + \ parses the data according to the specified schema, and executes optimized\ + \ SQL operations with sub-second latency. This is essential for a wide variety\ + \ of tasks, including large-scale log analysis, data engineering pipelines,\ + \ and real-time exploratory data science. The tool supports the full range\ + \ of ClickHouse SQL functions, ensuring compatibility with complex analytical\ + \ workflows that require window functions, arrays, and nested data structures.\ + \ Synonyms for this tool's functionality include local data analysis, embedded\ + \ SQL querying, in-memory data processing, ad-hoc file exploration, serverless\ + \ analytics, and in-process OLAP. Common use cases involve reading multi-gigabyte\ + \ Parquet files to extract specific business metrics, joining multiple large\ + \ CSV files in memory for rapid reporting, converting data between different\ + \ formats (e.g., CSV to JSON) using familiar SQL syntax, or performing sentiment\ + \ analysis on locally stored text files. Keywords: chDB, ClickHouse, SQL analytics,\ + \ Parquet querying, in-memory database, OLAP, data exploration, embedded engine,\ + \ serverless SQL, local analytics. Behavioral notes: the engine uses a column-oriented\ + \ storage and execution model, which provides massive performance gains for\ + \ analytical queries that only reference a subset of columns. It can seamlessly\ + \ handle datasets that exceed available RAM by using temporary storage on\ + \ disk if configured correctly. Caveats: ensure that the file paths are correctly\ + \ specified and accessible; if a file is missing or formatted incorrectly,\ + \ the engine will return a clear error. This tool is the 'analytical engine'\ + \ for the AI, providing a way to perform professional-grade data analysis\ + \ directly on the user's local machine with minimal overhead and maximum speed.\ + \ It bridges the gap between raw files and meaningful business intelligence,\ + \ ensuring that every local dataset is a potential source of deep insights.\ + \ The AI should think of this tool as its personal, high-speed data scientist\ + \ that can handle millions of rows in the blink of an eye, all while staying\ + \ entirely within the local environment." + properties: null + required: null + modelSemantics: null diff --git a/clickhouseplayground.ypipe b/clickhouseplayground.ypipe new file mode 100644 index 00000000..fe9dc45c --- /dev/null +++ b/clickhouseplayground.ypipe @@ -0,0 +1,165 @@ +--- +apiVersion: "mcp.ypipe.com/v1" +kind: "McpIntegrationBlueprint" +metadata: + name: "clickhouseplayground" + namespace: "system" +spec: + displayName: "ClickHouse SQL Playground" + description: "Instant read-only access to the ClickHouse SQL Playground. Explore\ + \ ClickHouse features and sample datasets without any setup." + source: "https://github.com/ClickHouse/mcp-clickhouse" + configurationSchema: {} + mcpConfig: + type: "stdio" + command: "uv" + args: + - "run" + - "--with" + - "mcp-clickhouse" + - "--python" + - "3.10" + - "mcp-clickhouse" + env: + CLICKHOUSE_HOST: "sql-clickhouse.clickhouse.com" + CLICKHOUSE_PORT: "8443" + CLICKHOUSE_USER: "demo" + CLICKHOUSE_PASSWORD: "" + CLICKHOUSE_SECURE: "true" + CLICKHOUSE_VERIFY: "true" + CLICKHOUSE_CONNECT_TIMEOUT: "30" + CLICKHOUSE_SEND_RECEIVE_TIMEOUT: "300" + url: null + headers: null + disabledTools: null + suggestions: + - id: "clickhouseplayground-clickhouse-playground-discover-data" + title: "Clickhouse Playground: Discover Data" + label: "List all available sample databases" + action: "List all available databases with ${metadata.name}_list_databases\ + \ to see what I can explore." + actionType: null + target: null + - id: "clickhouseplayground-clickhouse-playground-whats-inside-the-wiki-database" + title: "Clickhouse Playground: Whats inside the Wiki Database?" + label: "List all tables in the 'wiki' database" + action: "List tables in the database 'wiki' by calling tool '${metadata.name}_list_tables'." + actionType: null + target: null + - id: "clickhouseplayground-playground-wiki-stats" + title: "Playground: Wiki Stats" + label: "View top Wikipedia statistics" + action: "Run the query 'SELECT * FROM \"wiki\".\"wikistat_top\" LIMIT 100' using\ + \ ${metadata.name}_run_query." + actionType: null + target: null + tools: + list_databases: + description: "List available databases on the ClickHouse SQL Playground." + usageIntent: null + discoveryHint: "List and browse all available sample databases currently hosted\ + \ on the public ClickHouse SQL Playground environment. This tool serves as\ + \ the critical initial entry point for data discovery, allowing the AI to\ + \ identify which namespaces and datasets are currently available for inspection\ + \ and analysis without needing prior knowledge of the cluster's contents.\ + \ By exploring the database list, the agent can understand the broad scope\ + \ of data domains present—ranging from the 'system' database containing internal\ + \ metrics to the 'default' and 'sample' databases where the primary analytical\ + \ data resides. Synonyms for this action include database discovery, namespace\ + \ listing, schema reconnaissance, remote environment orientation, identifying\ + \ data targets, and cluster mapping. Common use cases include performing initial\ + \ reconnaissance on a new ClickHouse instance, verifying the availability\ + \ of specific sample datasets mentioned in documentation, and identifying\ + \ which databases contain the most relevant information for a given analytical\ + \ task (e.g., finding the 'uk_price_paid' database for real estate trends).\ + \ Behavioral notes: The listing is retrieved via a system query against the\ + \ 'system.databases' table and reflects the real-time state of the playground\ + \ environment. The AI should think of this as building its 'mental map' of\ + \ the accessible data structures before attempting any more granular operations.\ + \ Keywords: data discovery, metadata management, remote exploration, database\ + \ inventory, SQL namespace, cluster orientation, schema discovery. Caveats:\ + \ While most databases are public, some system-level namespaces might be visible\ + \ but restricted or contain cryptic internal metrics that are less relevant\ + \ for general user-facing analysis. The playground is a dynamic environment,\ + \ and the list of available sample databases may be modified by the ClickHouse\ + \ team as new data is added or old datasets are retired. Security implications\ + \ are negligible as this is a read-only metadata retrieval tool, but it is\ + \ a fundamental step for ensuring that subsequent queries are directed at\ + \ the correct database, avoiding 'table not found' errors and ensuring a smooth\ + \ research workflow. This tool is the 'first glance' at the remote data world." + properties: null + required: null + list_tables: + description: "List tables in a specific playground database. Give databasename\ + \ as parameter." + usageIntent: null + discoveryHint: "Retrieve a comprehensive and detailed list of all tables, views,\ + \ and dictionaries residing within a specific, named database on the ClickHouse\ + \ SQL Playground cluster. once a database has been identified using 'list_databases',\ + \ this tool is the next logical and critical step for understanding the internal\ + \ organizational structure of that dataset. It reveals the exact names of\ + \ all data entities, which is essential for target identification before writing\ + \ any SELECT queries. By listing the tables, the AI can distinguish between\ + \ raw event logs (often the largest tables), pre-aggregated rollup tables,\ + \ and materialized views that provide specific analytical perspectives. Synonyms\ + \ for this tool's action include table listing, entity discovery, metadata\ + \ retrieval, schema mapping, relational structure inspection, and table inventory.\ + \ Common use cases include identifying the core data assets within a sample\ + \ database like 'hits' or 'visits', checking for the existence of specific\ + \ temporary tables, or mapping out the dependencies between views and their\ + \ underlying data sources. Behavioral notes: You must provide a valid and\ + \ precisely spelled database name as a parameter. The output will include\ + \ all entities supported by ClickHouse, including standard MergeTree tables,\ + \ Log engines, and sophisticated materialized views. The AI should use this\ + \ tool to narrow its focus from the entire cluster to a specific set of interesting\ + \ tables for deeper investigation. Keywords: table inventory, data mapping,\ + \ entity discovery, ClickHouse schema, remote data assets, table enumeration,\ + \ metadata collection. Caveats: In the playground environment, some tables\ + \ might be incredibly massive, containing billions of rows, while others are\ + \ small lookup tables or dictionaries. This tool provides only the names and\ + \ types; it does not provide row counts, file sizes, or column definitions.\ + \ Therefore, it should always be followed by a 'describe_table' call to understand\ + \ the data's internal structure before any complex analytical operations are\ + \ attempted. This ensures that the AI is fully aware of the data it is about\ + \ to process, preventing inefficient queries or incorrect assumptions about\ + \ the data's shape and size. It is the bridge between knowing a database exists\ + \ and knowing how to query its contents effectively." + properties: null + required: null + run_query: + description: "Execute read-only SQL queries on the ClickHouse SQL Playground." + usageIntent: null + discoveryHint: "Execute read-only SQL SELECT queries on the ClickHouse SQL Playground\ + \ to explore massive, multi-billion row datasets with lightning-fast, sub-second\ + \ performance. This tool is specifically designed for high-level data exploration,\ + \ analytical experimentation, and learning the unique features of ClickHouse-specific\ + \ SQL syntax without the need for any local infrastructure or complex server\ + \ setup. The playground environment provides a wealth of curated sample datasets,\ + \ including real-world web traffic logs (hits and visits), flight data, and\ + \ genomic information. By sending a query through this tool, the AI agent\ + \ initiates a sequence where the underlying ClickHouse engine parses the SQL,\ + \ optimizes the execution plan for a columnar storage model, and retrieves\ + \ results from a high-performance remote cluster. This is essential for a\ + \ wide range of tasks, including performance benchmarking of complex analytical\ + \ queries, validating query logic before deployment, or simply browsing public\ + \ datasets to find trends and anomalies. Synonyms for this tool's action include\ + \ querying the cloud, analytical data exploration, SQL-based research, sample\ + \ dataset analysis, remote OLAP execution, and cloud-native querying. Common\ + \ use cases include running multi-dimensional aggregations on web traffic\ + \ data, performing time-series analysis on system logs, or testing advanced\ + \ ClickHouse functions like 'uniqCombined' for cardinality estimation or 'arrayJoin'\ + \ for nested data processing. Keywords: OLAP, real-time analytics, big data,\ + \ sample datasets, ClickHouse SQL dialect, cloud sandbox, remote SQL execution,\ + \ analytical benchmarking. Behavioral notes: This tool strictly enforces a\ + \ read-only policy; any attempts to use DDL (Data Definition Language) like\ + \ 'CREATE' or 'DROP' or DML (Data Manipulation Language) like 'INSERT' or\ + \ 'UPDATE' will be rejected by the server. It utilizes the standard ClickHouse\ + \ HTTPS interface, which might have inherent rate limits or execution time\ + \ constraints for extremely heavy queries. The AI should think of this tool\ + \ as its gateway to massive-scale data without the overhead of management.\ + \ It provides a frictionless way to prove a concept or find a data point across\ + \ billions of rows of historical information, ensuring that every analytical\ + \ hypothesis can be tested against real-world scale data in real-time." + properties: null + required: null + modelSemantics: null diff --git a/localclickhouse.ypipe b/localclickhouse.ypipe new file mode 100644 index 00000000..a1dc775d --- /dev/null +++ b/localclickhouse.ypipe @@ -0,0 +1,241 @@ +--- +apiVersion: "mcp.ypipe.com/v1" +kind: "McpIntegrationBlueprint" +metadata: + name: "localclickhouse" + namespace: "system" +spec: + displayName: "ClickHouse (local)" + description: "Connect your own ClickHouse cluster to your AI assistant. Supports\ + \ high-performance analytical queries and database exploration." + source: "https://github.com/ClickHouse/mcp-clickhouse" + configurationSchema: + CLICKHOUSE_HOST: + type: "string" + required: true + default: "localhost" + description: "The hostname of your ClickHouse server" + sensitive: false + pattern: null + CLICKHOUSE_PORT: + type: "string" + required: true + default: "8443" + description: "The port number (8443 for HTTPS, 8123 for HTTP)" + sensitive: false + pattern: null + CLICKHOUSE_USER: + type: "string" + required: true + default: "default" + description: "The username for authentication" + sensitive: false + pattern: null + CLICKHOUSE_PASSWORD: + type: "string" + required: false + default: "" + description: "The password for authentication" + sensitive: true + pattern: null + CLICKHOUSE_DATABASE: + type: "string" + required: false + default: null + description: "Default database to connect to" + sensitive: false + pattern: null + CLICKHOUSE_SECURE: + type: "boolean" + required: null + default: "true" + description: "Enable HTTPS connection" + sensitive: false + pattern: null + CLICKHOUSE_VERIFY: + type: "boolean" + required: null + default: "true" + description: "Verify SSL certificates" + sensitive: false + pattern: null + CLICKHOUSE_ALLOW_WRITE_ACCESS: + type: "boolean" + required: null + default: "false" + description: "Allow write operations (DDL and DML). If false, queries are read-only." + sensitive: false + pattern: null + mcpConfig: + type: "stdio" + command: "uv" + args: + - "run" + - "--with" + - "mcp-clickhouse" + - "--python" + - "3.10" + - "mcp-clickhouse" + env: + CLICKHOUSE_HOST: "${CLICKHOUSE_HOST}" + CLICKHOUSE_PORT: "${CLICKHOUSE_PORT}" + CLICKHOUSE_USER: "${CLICKHOUSE_USER}" + CLICKHOUSE_PASSWORD: "${CLICKHOUSE_PASSWORD}" + CLICKHOUSE_DATABASE: "${CLICKHOUSE_DATABASE}" + CLICKHOUSE_SECURE: "${CLICKHOUSE_SECURE}" + CLICKHOUSE_VERIFY: "${CLICKHOUSE_VERIFY}" + CLICKHOUSE_ALLOW_WRITE_ACCESS: "${CLICKHOUSE_ALLOW_WRITE_ACCESS}" + CLICKHOUSE_CONNECT_TIMEOUT: "30" + CLICKHOUSE_SEND_RECEIVE_TIMEOUT: "300" + url: null + headers: null + disabledTools: null + suggestions: [] + tools: + list_databases: + description: "List available databases on your ClickHouse instance." + usageIntent: null + discoveryHint: "List and browse all available databases currently hosted on your\ + \ local or organizational ClickHouse instance. This tool is fundamental for\ + \ data discovery and reconnaissance, providing a high-level inventory of which\ + \ namespaces are accessible for querying and management. It is almost always\ + \ the first step in any analytical workflow, allowing the AI to identify relevant\ + \ databases such as the 'default' workspace, 'system' metrics, or custom business-specific\ + \ schemas. By retrieving the list of databases, the agent builds an internal\ + \ map of the data landscape before attempting more granular operations. Synonyms\ + \ for this action include database discovery, namespace listing, schema reconnaissance,\ + \ cluster orientation, identifying data targets, and cluster inventory. Common\ + \ use cases include performing initial reconnaissance on a new ClickHouse\ + \ environment, verifying the successful creation of a new database during\ + \ a migration, or identifying which databases contain the most relevant data\ + \ for a specific project or department. Behavioral notes: The listing is retrieved\ + \ via a system query against the 'system.databases' table and reflects the\ + \ real-time state of the server. The AI should use this tool to confirm the\ + \ existence of a target namespace before attempting to list its tables or\ + \ run queries. Keywords: data discovery, metadata management, ClickHouse inventory,\ + \ namespace listing, schema exploration, cluster orientation, database mapping.\ + \ Caveats: Some system-level databases (like 'system' or 'information_schema')\ + \ may be visible but restricted or contain internal telemetry that is not\ + \ relevant for general business analysis. The server environment is dynamic,\ + \ and databases may be added or removed by other users or automated data pipelines.\ + \ Security-wise, it only exposes metadata, but this provides the structural\ + \ context needed for more privileged actions. Performance is virtually instantaneous,\ + \ as this information is cached in the ClickHouse server's memory. This tool\ + \ is the 'ls' or 'dir' equivalent for the ClickHouse cluster, providing the\ + \ basic visibility required for any subsequent data management or analytical\ + \ task. It ensures the AI is navigating based on a current and accurate map\ + \ of the system's data structure." + properties: null + required: null + run_select_query: + description: "Execute SQL queries on your local ClickHouse cluster." + usageIntent: null + discoveryHint: "Execute high-performance SQL queries against your local or private\ + \ ClickHouse cluster to perform lightning-fast analytical operations on massive\ + \ datasets. This tool is the primary interface for professional data analysis,\ + \ enabling sub-second latency queries for real-time dashboards, internal reporting,\ + \ and deep ad-hoc data exploration. By leveraging ClickHouse's industry-leading\ + \ columnar storage engine and vectorised execution model, the agent can run\ + \ complex aggregations over millions or billions of rows with unprecedented\ + \ efficiency. This is essential for a wide variety of tasks, including large-scale\ + \ log analysis, real-time monitoring of infrastructure, financial modeling,\ + \ and identifying trends in high-velocity event streams. Synonyms for this\ + \ action include analytical querying, SQL execution, time-series exploration,\ + \ OLAP processing, database data retrieval, and data mining. Common use cases\ + \ include calculating real-time error rates from system logs, grouping billions\ + \ of transactions by user segment, performing time-series forecasting on historical\ + \ data, or running complex multi-stage joins for data enrichment using local\ + \ reference tables. Behavioral notes: The tool connects via the ClickHouse\ + \ HTTPS or HTTP interface and supports the full breadth of the ClickHouse\ + \ SQL dialect, including advanced window functions, array manipulation, and\ + \ specialized aggregation functions like 'uniqCombined' or 'quantile'. Depending\ + \ on the 'CLICKHOUSE_ALLOW_WRITE_ACCESS' configuration setting, this tool\ + \ can perform read-only SELECT queries or full DDL/DML operations (including\ + \ CREATE, INSERT, UPDATE, DROP) if specifically authorized. Keywords: OLAP,\ + \ real-time analytics, big data, SQL dialect, time-series database, columnar\ + \ storage, vectorised execution, data warehousing. Caveats: Be mindful of\ + \ query complexity; while ClickHouse is exceptionally fast, inefficient JOINs\ + \ or queries without proper primary key filters can still impact cluster performance\ + \ and memory usage. Always leverage the partition key and primary key in your\ + \ 'WHERE' clauses to take advantage of ClickHouse's sparse indexing system.\ + \ Security-wise, ensure that write access is only enabled when strictly necessary\ + \ and that the AI is not executing destructive commands without explicit human\ + \ confirmation. This tool is the 'analytical engine' of the agent, providing\ + \ a way to perform professional-grade data analysis directly on the user's\ + \ local or private infrastructure with maximum speed and accuracy. It ensures\ + \ that every local dataset is a potential source of deep, actionable insights." + properties: null + required: null + describe_table: + description: "Retrieve the schema and structural metadata for a ClickHouse table." + usageIntent: null + discoveryHint: "Inspect and retrieve the complete technical schema, column definitions,\ + \ and structural metadata for a specific table or view on your local ClickHouse\ + \ cluster. This tool provides granular, technical insights into the internal\ + \ organization of a data entity, revealing every column's name, its precise\ + \ ClickHouse data type (e.g., Int64, String, DateTime64, Array, or specialized\ + \ types like LowCardinality or AggregateFunction), and associated attributes\ + \ like default values, compression codecs, and TTL (Time-To-Live) policies.\ + \ Understanding the schema is absolutely paramount for writing syntactically\ + \ correct and performant SQL queries, especially when dealing with ClickHouse's\ + \ advanced features like Bloom filters or specialized indexing. Synonyms for\ + \ this action include schema inspection, column definition retrieval, technical\ + \ profiling, metadata deep-dive, table structure analysis, and schema audit.\ + \ Common use cases include identifying the primary join keys for a multi-table\ + \ analysis, understanding the time granularity of a 'DateTime' column for\ + \ report grouping, verifying the availability of specific dimensions, and\ + \ identifying columns that are optimized for certain types of queries (like\ + \ sorting keys). Behavioral notes: The tool executes a 'DESCRIBE TABLE' command\ + \ on the server and returns a structured representation of the schema. The\ + \ AI should think of this as its 'final check' before committing to a large-scale\ + \ analytical query. Keywords: schema metadata, data types, technical profiling,\ + \ ClickHouse columns, table definition, schema verification, column audit.\ + \ Caveats: Some tables might use complex storage engines (like ReplicatedMergeTree)\ + \ or have sophisticated partitioning schemes that require specialized query\ + \ patterns to avoid excessive resource consumption. Knowing the primary key,\ + \ partition key, and sorting key—which are often clearly visible in the schema—\ + allows the AI to write filters that are significantly faster by leveraging\ + \ ClickHouse's sparse indexing system. This tool is essential for an AI to\ + \ act as a truly expert data analyst, ensuring its queries are not only correct\ + \ but also perfectly optimized for the underlying data distribution and storage\ + \ engine. Security-wise, it provides structural awareness without exposing\ + \ the actual data content, ensuring a safe and informed data exploration process." + properties: null + required: null + list_tables: + description: "List tables and views in a specific ClickHouse database." + usageIntent: null + discoveryHint: "Retrieve a comprehensive and detailed list of all tables, views,\ + \ and dictionaries residing within a specific, named database on your local\ + \ ClickHouse cluster. Once a target database has been identified using 'list_databases',\ + \ this tool is the next logical step for understanding the internal organization\ + \ of that namespace. It reveals the exact names of all data entities, which\ + \ is essential for target identification before writing any analytical SQL.\ + \ By listing the tables, the AI can distinguish between raw event logs (often\ + \ using MergeTree engines), pre-aggregated rollup tables, materialized views,\ + \ and external dictionaries. Synonyms for this tool's action include table\ + \ listing, entity discovery, metadata retrieval, schema mapping, relational\ + \ structure inspection, and table inventory. Common use cases include identifying\ + \ the core tables for a specific analysis, checking for the existence of newly\ + \ ingested data assets, mapping out the relationships between raw data and\ + \ summarized views, or auditing a database for temporary tables that need\ + \ cleanup. Behavioral notes: You must provide a valid and correctly spelled\ + \ database name as a parameter. The output will include all entities supported\ + \ by the ClickHouse engine, including specialized engines like Kafka, S3,\ + \ or Distributed tables. Keywords: table inventory, data mapping, ClickHouse\ + \ schema, entity discovery, database structure, metadata collection, table\ + \ enumeration. Caveats: In a production cluster, some databases might contain\ + \ thousands of tables. This tool provides the names and types but does not\ + \ include row counts, disk sizes, or individual column details. Therefore,\ + \ it should always be followed by a 'describe_table' call for a specific target\ + \ to understand its internal structure, sorting keys, and data types before\ + \ any complex analytical operations are attempted. Security-wise, this is\ + \ a safe, read-only metadata operation. Performance is extremely fast. The\ + \ AI should use this tool to narrow its focus from the entire database down\ + \ to the specific tables needed for the current task, ensuring accuracy and\ + \ avoiding 'table not found' errors in later queries. It provides the essential\ + \ structural context needed to interact with the database in a professional\ + \ and informed manner." + properties: null + required: null + modelSemantics: null