add ypipe MCP integration blueprints for ClickHouse, ClickHouse Playground, and chDB

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}")

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

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