@gluip/chart-canvas-mcp 0.1.5 → 0.2.0

package/README.md

@@ -16,7 +16,9 @@ Watch the [full demo on YouTube](https://www.youtube.com/watch?v=XVucQstPisc) to
 🎨 **Interactive Dashboard**: Drag-and-drop grid layout with real-time updates  
 🔄 **Live Synchronization**: Changes appear instantly in your browser  
 📊 **Rich Visualizations**: Powered by ECharts and Mermaid  
-🚀 **Easy Setup**: One command to get started  
+�️ **SQL Database Integration**: Query SQLite databases directly and visualize results  
+⚡ **Smart Data Flow**: Execute queries server-side without passing data through LLM  
+�🚀 **Easy Setup**: One command to get started  
 🌐 **Production Ready**: Built-in production mode with optimized builds
 
 ## Quick Start
@@ -68,6 +70,12 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 "Draw a flowchart for the user authentication process"
 
 "Make a table with team member information"
+
+"Show me the database schema for my SQLite database"
+
+"Query the athletes table and show the top 10 with most personal records"
+
+"Create a chart showing sales trends from the database grouped by region"
 ```
 
 ## MCP Tools
@@ -77,6 +85,7 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 Create charts, diagrams, and tables on the canvas.
 
 **Supported Types**:
+
 - `line` - Line charts with multiple series
 - `bar` - Bar charts for comparisons
 - `scatter` - Scatter plots for data distribution
@@ -85,6 +94,7 @@ Create charts, diagrams, and tables on the canvas.
 - `flowchart` - Mermaid diagrams (flowcharts, sequence diagrams, Gantt charts, etc.)
 
 **Example**:
+
 ```typescript
 {
   type: "line",
@@ -109,6 +119,60 @@ Remove all visualizations from the canvas.
 
 Open the dashboard in your default browser.
 
+### getDatabaseSchema
+
+Inspect the structure of a SQLite database to understand available tables and columns before writing queries.
+
+**Parameters**:
+
+- `databasePath` - Path to SQLite database file (e.g., `./data/mydb.sqlite` or absolute path)
+
+**Example**:
+
+```typescript
+{
+  databasePath: "/path/to/database.db";
+}
+```
+
+**Returns**: Formatted schema showing all tables, columns, data types, and constraints.
+
+### queryAndVisualize
+
+Execute a SQL query on a SQLite database and create a visualization from the results. Queries are executed server-side and must be read-only (SELECT only). Maximum 10,000 rows.
+
+**Parameters**:
+
+- `databasePath` - Path to SQLite database file
+- `query` - SQL SELECT query (read-only)
+- `visualizationType` - Type of chart: `line`, `bar`, `scatter`, `pie`, or `table`
+- `columnMapping` (optional for table) - Mapping of columns to chart axes:
+  - `xColumn` - Column for X-axis (required for charts)
+  - `yColumns` - Array of columns for Y-axis (required for charts)
+  - `seriesColumn` - Column to group data into separate series (optional)
+  - `groupByColumn` - Alternative grouping column (optional)
+- `title` - Optional title for visualization
+- `description` - Optional description
+- `useColumnAsXLabel` - If true, use X column values as labels instead of numbers
+
+**Example**:
+
+```typescript
+{
+  databasePath: "./data/sales.db",
+  query: "SELECT region, SUM(revenue) as total FROM sales GROUP BY region",
+  visualizationType: "bar",
+  columnMapping: {
+    xColumn: "region",
+    yColumns: ["total"]
+  },
+  title: "Revenue by Region",
+  useColumnAsXLabel: true
+}
+```
+
+**Security**: Only SELECT and WITH (CTE) queries are allowed. INSERT, UPDATE, DELETE, DROP, and other modifying operations are blocked.
+
 ## Architecture
 
 - **Backend**: Node.js + TypeScript + Express + MCP SDK
@@ -128,7 +192,7 @@ cd chart-canvas
 cd backend
 npm install
 
-# Install frontend dependencies  
+# Install frontend dependencies
 cd ../frontend
 npm install
 

package/dist/database.js

@@ -0,0 +1,112 @@
+import Database from "better-sqlite3";
+import { existsSync } from "fs";
+import { resolve } from "path";
+const FORBIDDEN_KEYWORDS = [
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "DROP",
+    "CREATE",
+    "ALTER",
+    "TRUNCATE",
+    "REPLACE",
+    "ATTACH",
+    "DETACH",
+    "PRAGMA",
+];
+const MAX_ROWS = 10000;
+const QUERY_TIMEOUT_MS = 5000;
+/**
+ * Validate database path - must exist and be a file
+ */
+export function validateDatabasePath(dbPath) {
+    const resolvedPath = resolve(dbPath);
+    if (!existsSync(resolvedPath)) {
+        throw new Error(`Database file does not exist: ${dbPath}`);
+    }
+    return resolvedPath;
+}
+/**
+ * Validate SQL query - must be read-only (SELECT only)
+ */
+export function validateReadOnlyQuery(sql) {
+    const upperSQL = sql.trim().toUpperCase();
+    // Must start with SELECT or WITH (for CTEs)
+    if (!upperSQL.startsWith("SELECT") && !upperSQL.startsWith("WITH")) {
+        throw new Error("Only SELECT queries are allowed");
+    }
+    // Check for forbidden keywords
+    for (const keyword of FORBIDDEN_KEYWORDS) {
+        const regex = new RegExp(`\\b${keyword}\\b`, "i");
+        if (regex.test(sql)) {
+            throw new Error(`Query contains forbidden keyword: ${keyword}`);
+        }
+    }
+}
+/**
+ * Get database schema for all tables
+ */
+export function getDatabaseSchema(dbPath) {
+    const resolvedPath = validateDatabasePath(dbPath);
+    const db = new Database(resolvedPath, { readonly: true });
+    try {
+        // Get all table names (excluding sqlite internal tables)
+        const tables = db
+            .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+            .all();
+        const schema = {
+            tables: [],
+        };
+        // Get columns for each table
+        for (const table of tables) {
+            const columns = db
+                .prepare(`PRAGMA table_info(${table.name})`)
+                .all();
+            schema.tables.push({
+                name: table.name,
+                columns: columns.map((col) => ({
+                    name: col.name,
+                    type: col.type,
+                    notNull: col.notnull === 1,
+                    defaultValue: col.dflt_value,
+                    primaryKey: col.pk === 1,
+                })),
+            });
+        }
+        return schema;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Execute a SQL query with timeout and row limit
+ */
+export function executeQuery(dbPath, sql) {
+    const resolvedPath = validateDatabasePath(dbPath);
+    validateReadOnlyQuery(sql);
+    const db = new Database(resolvedPath, {
+        readonly: true,
+        timeout: QUERY_TIMEOUT_MS,
+    });
+    try {
+        // Prepare and execute query
+        const stmt = db.prepare(sql);
+        const rows = stmt.all();
+        // Check row limit
+        if (rows.length > MAX_ROWS) {
+            throw new Error(`Query returned ${rows.length} rows, exceeding limit of ${MAX_ROWS}`);
+        }
+        // Get column names from first row or statement columns
+        const columns = rows.length > 0
+            ? Object.keys(rows[0])
+            : stmt.columns().map((c) => c.name);
+        return {
+            rows,
+            columns,
+        };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/index.js

@@ -4,6 +4,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { stateManager } from "./state.js";
 import { startApiServer, getServerPort } from "./api.js";
+import { getDatabaseSchema, executeQuery } from "./database.js";
+import { transformToTable, transformToSeries, extractXLabels, } from "./transformers.js";
 import open from "open";
 const server = new Server({
     name: "chart-canvas-server",
@@ -123,6 +125,78 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {},
                 },
             },
+            {
+                name: "getDatabaseSchema",
+                description: "Get the schema of a SQLite database including all tables and columns. Use this to understand the database structure before writing queries.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        databasePath: {
+                            type: "string",
+                            description: "Path to the SQLite database file (e.g., './data/atletiek.db' or '/absolute/path/to/db.sqlite')",
+                        },
+                    },
+                    required: ["databasePath"],
+                },
+            },
+            {
+                name: "queryAndVisualize",
+                description: "Execute a SQL query on a SQLite database and create a visualization from the results. The query must be read-only (SELECT only). You must specify how to map columns to the visualization.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        databasePath: {
+                            type: "string",
+                            description: "Path to the SQLite database file",
+                        },
+                        query: {
+                            type: "string",
+                            description: "SQL SELECT query to execute (read-only, max 10000 rows)",
+                        },
+                        visualizationType: {
+                            type: "string",
+                            enum: ["line", "bar", "scatter", "table", "pie"],
+                            description: "Type of visualization to create from the query results",
+                        },
+                        columnMapping: {
+                            type: "object",
+                            properties: {
+                                xColumn: {
+                                    type: "string",
+                                    description: "Column to use for X-axis (required for charts, not needed for table)",
+                                },
+                                yColumns: {
+                                    type: "array",
+                                    items: { type: "string" },
+                                    description: "Column(s) to use for Y-axis values (required for charts, not needed for table)",
+                                },
+                                seriesColumn: {
+                                    type: "string",
+                                    description: "Optional: Column to group data into separate series (e.g., 'category', 'product_name')",
+                                },
+                                groupByColumn: {
+                                    type: "string",
+                                    description: "Optional: Column to group by (alternative to seriesColumn)",
+                                },
+                            },
+                            description: "Mapping of query result columns to chart axes. Not required for table type.",
+                        },
+                        title: {
+                            type: "string",
+                            description: "Optional title for the visualization",
+                        },
+                        description: {
+                            type: "string",
+                            description: "Optional description for the visualization",
+                        },
+                        useColumnAsXLabel: {
+                            type: "boolean",
+                            description: "If true, use the xColumn values as labels instead of numeric values (useful for dates/categories)",
+                        },
+                    },
+                    required: ["databasePath", "query", "visualizationType"],
+                },
+            },
         ],
     };
 });
@@ -200,6 +274,115 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
         }
+        case "getDatabaseSchema": {
+            try {
+                const { databasePath } = args;
+                const schema = getDatabaseSchema(databasePath);
+                // Format schema as readable text
+                let schemaText = `Database schema for: ${databasePath}\n\n`;
+                for (const table of schema.tables) {
+                    schemaText += `Table: ${table.name}\n`;
+                    schemaText += `Columns:\n`;
+                    for (const col of table.columns) {
+                        const constraints = [];
+                        if (col.primaryKey)
+                            constraints.push("PRIMARY KEY");
+                        if (col.notNull)
+                            constraints.push("NOT NULL");
+                        if (col.defaultValue)
+                            constraints.push(`DEFAULT ${col.defaultValue}`);
+                        const constraintStr = constraints.length > 0 ? ` (${constraints.join(", ")})` : "";
+                        schemaText += `  - ${col.name}: ${col.type}${constraintStr}\n`;
+                    }
+                    schemaText += `\n`;
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: schemaText,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error getting database schema: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                };
+            }
+        }
+        case "queryAndVisualize": {
+            try {
+                const { databasePath, query, visualizationType, columnMapping, title, description, useColumnAsXLabel, } = args;
+                // Execute query
+                const result = executeQuery(databasePath, query);
+                if (result.rows.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Query returned 0 rows. No visualization created.",
+                            },
+                        ],
+                    };
+                }
+                // Create visualization based on type
+                let viz;
+                if (visualizationType === "table") {
+                    // For tables, just transform all columns
+                    const tableData = transformToTable(result.rows, result.columns);
+                    viz = stateManager.addVisualization({
+                        type: "table",
+                        table: tableData,
+                        title,
+                        description,
+                    });
+                }
+                else {
+                    // For charts, need column mapping
+                    if (!columnMapping ||
+                        !columnMapping.xColumn ||
+                        !columnMapping.yColumns) {
+                        throw new Error("columnMapping with xColumn and yColumns is required for chart visualizations");
+                    }
+                    const series = transformToSeries(result.rows, result.columns, columnMapping);
+                    const xLabels = useColumnAsXLabel
+                        ? extractXLabels(result.rows, columnMapping.xColumn)
+                        : undefined;
+                    viz = stateManager.addVisualization({
+                        type: visualizationType,
+                        series,
+                        title,
+                        description,
+                        xLabels,
+                    });
+                }
+                const port = getServerPort() || 3000;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Created ${visualizationType} visualization with ${result.rows.length} rows. ID: ${viz.id}. View at http://localhost:${port}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error executing query and creating visualization: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                };
+            }
+        }
         default:
             throw new Error(`Unknown tool: ${name}`);
     }

package/dist/transformers.js

@@ -0,0 +1,138 @@
+/**
+ * Transform SQL query results to TableData format
+ */
+export function transformToTable(rows, columns) {
+    if (rows.length === 0) {
+        return {
+            headers: columns,
+            rows: [],
+        };
+    }
+    return {
+        headers: columns,
+        rows: rows.map((row) => columns.map((col) => row[col])),
+    };
+}
+/**
+ * Transform SQL query results to SeriesData format for charts
+ */
+export function transformToSeries(rows, columns, mapping) {
+    if (rows.length === 0) {
+        return [];
+    }
+    const { xColumn, yColumns, seriesColumn, groupByColumn } = mapping;
+    // Validate required columns
+    if (!xColumn) {
+        throw new Error("xColumn is required for chart transformation");
+    }
+    if (!yColumns || yColumns.length === 0) {
+        throw new Error("At least one yColumn is required for chart transformation");
+    }
+    // Validate columns exist
+    if (!columns.includes(xColumn)) {
+        throw new Error(`xColumn '${xColumn}' not found in query results`);
+    }
+    for (const yCol of yColumns) {
+        if (!columns.includes(yCol)) {
+            throw new Error(`yColumn '${yCol}' not found in query results`);
+        }
+    }
+    if (seriesColumn && !columns.includes(seriesColumn)) {
+        throw new Error(`seriesColumn '${seriesColumn}' not found in query results`);
+    }
+    if (groupByColumn && !columns.includes(groupByColumn)) {
+        throw new Error(`groupByColumn '${groupByColumn}' not found in query results`);
+    }
+    // If there's a seriesColumn, group data by series
+    if (seriesColumn) {
+        return transformWithSeriesColumn(rows, xColumn, yColumns[0], seriesColumn);
+    }
+    // If there's a groupByColumn, create separate series for each group
+    if (groupByColumn) {
+        return transformWithGroupBy(rows, xColumn, yColumns[0], groupByColumn);
+    }
+    // Otherwise, create one series per yColumn
+    return transformMultipleYColumns(rows, xColumn, yColumns);
+}
+/**
+ * Transform data with a series column (e.g., different product lines)
+ */
+function transformWithSeriesColumn(rows, xColumn, yColumn, seriesColumn) {
+    const seriesMap = new Map();
+    for (const row of rows) {
+        const seriesName = String(row[seriesColumn]);
+        const xValue = parseNumericValue(row[xColumn]);
+        const yValue = parseNumericValue(row[yColumn]);
+        if (!seriesMap.has(seriesName)) {
+            seriesMap.set(seriesName, new Map());
+        }
+        seriesMap.get(seriesName).set(xValue, yValue);
+    }
+    const result = [];
+    for (const [seriesName, dataMap] of seriesMap.entries()) {
+        const data = Array.from(dataMap.entries()).sort((a, b) => a[0] - b[0]);
+        result.push({
+            name: seriesName,
+            data,
+        });
+    }
+    return result;
+}
+/**
+ * Transform data with a group by column
+ */
+function transformWithGroupBy(rows, xColumn, yColumn, groupByColumn) {
+    return transformWithSeriesColumn(rows, xColumn, yColumn, groupByColumn);
+}
+/**
+ * Transform data with multiple Y columns (each becomes a series)
+ */
+function transformMultipleYColumns(rows, xColumn, yColumns) {
+    const result = [];
+    for (const yColumn of yColumns) {
+        const data = rows
+            .map((row) => {
+            const xValue = parseNumericValue(row[xColumn]);
+            const yValue = parseNumericValue(row[yColumn]);
+            return [xValue, yValue];
+        })
+            .sort((a, b) => a[0] - b[0]);
+        result.push({
+            name: yColumn,
+            data,
+        });
+    }
+    return result;
+}
+/**
+ * Parse a value to number, handling various formats
+ */
+function parseNumericValue(value) {
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "string") {
+        // Try to parse as number
+        const parsed = parseFloat(value);
+        if (!isNaN(parsed)) {
+            return parsed;
+        }
+        // Try to parse as date
+        const date = Date.parse(value);
+        if (!isNaN(date)) {
+            return date;
+        }
+    }
+    // For other types, try to convert to number
+    const num = Number(value);
+    if (!isNaN(num)) {
+        return num;
+    }
+    throw new Error(`Cannot convert value to number: ${value}`);
+}
+/**
+ * Extract X labels from query results
+ */
+export function extractXLabels(rows, xColumn) {
+    return rows.map((row) => String(row[xColumn]));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gluip/chart-canvas-mcp",
-  "version": "0.1.5",
-  "description": "MCP server for creating interactive visualizations (charts, diagrams, tables) through AI assistants",
+  "version": "0.2.0",
+  "description": "MCP server for creating interactive visualizations (charts, diagrams, tables) and querying SQLite databases through AI assistants",
   "author": "Martijn",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,11 @@
     "echarts",
     "mermaid",
     "ai",
-    "llm"
+    "llm",
+    "sqlite",
+    "database",
+    "sql",
+    "query"
   ],
   "repository": {
     "type": "git",
@@ -41,12 +45,14 @@
     "@modelcontextprotocol/sdk": "^1.0.4",
     "express": "^4.21.2",
     "cors": "^2.8.5",
-    "open": "^10.1.0"
+    "open": "^10.1.0",
+    "better-sqlite3": "^11.8.1"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
     "@types/cors": "^2.8.17",
     "@types/node": "^22.10.5",
+    "@types/better-sqlite3": "^7.6.12",
     "typescript": "^5.7.3",
     "tsx": "^4.19.2"
   }