@gluip/chart-canvas-mcp 0.1.4 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martijn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# Chart Canvas MCP Server
+
+> Interactive visualization dashboard for AI assistants via Model Context Protocol
+
+Create beautiful charts, diagrams, and tables directly from your AI conversations. Chart Canvas provides a real-time dashboard that displays visualizations as you work with LLMs like Claude.
+
+## Demo
+
+[![Chart Canvas Demo](https://img.youtube.com/vi/XVucQstPisc/maxresdefault.jpg)](https://www.youtube.com/watch?v=XVucQstPisc)
+
+Watch the [full demo on YouTube](https://www.youtube.com/watch?v=XVucQstPisc) to see Chart Canvas in action!
+
+## Features
+
+✨ **Multiple Chart Types**: Line, bar, scatter, pie charts, tables, and Mermaid diagrams  
+🎨 **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  
+�️ **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
+
+### Installation
+
+```bash
+npm install -g @gluip/chart-canvas-mcp
+```
+
+Or use directly with npx (no installation needed):
+
+```bash
+npx @gluip/chart-canvas-mcp
+```
+
+### Configuration
+
+Add to your MCP client configuration (e.g., Claude Desktop):
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "chart-canvas": {
+      "command": "npx",
+      "args": ["-y", "@gluip/chart-canvas-mcp"]
+    }
+  }
+}
+```
+
+### Usage
+
+1. Start your MCP client (e.g., Claude Desktop)
+2. The server will automatically start on port 3000
+3. Use the `showCanvas` tool to open the dashboard in your browser
+4. Ask the AI to create visualizations!
+
+## Example Prompts
+
+```
+"Show me a line chart comparing sales data for 2023 and 2024"
+
+"Create a pie chart showing market share by region"
+
+"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
+
+### addVisualization
+
+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
+- `pie` - Pie charts with labels
+- `table` - Data tables with headers
+- `flowchart` - Mermaid diagrams (flowcharts, sequence diagrams, Gantt charts, etc.)
+
+**Example**:
+
+```typescript
+{
+  type: "line",
+  title: "Monthly Sales",
+  series: [
+    { name: "2023", data: [[1, 120], [2, 132], [3, 101]] },
+    { name: "2024", data: [[1, 220], [2, 182], [3, 191]] }
+  ],
+  xLabels: ["Jan", "Feb", "Mar"]
+}
+```
+
+### removeVisualization
+
+Remove a specific visualization by ID.
+
+### clearCanvas
+
+Remove all visualizations from the canvas.
+
+### showCanvas
+
+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
+- **Frontend**: Vue 3 + ECharts + Mermaid + Grid Layout
+- **Communication**: Real-time polling for instant updates
+
+## Development
+
+### Local Development
+
+```bash
+# Clone repository
+git clone https://github.com/gluip/chart-canvas.git
+cd chart-canvas
+
+# Install backend dependencies
+cd backend
+npm install
+
+# Install frontend dependencies
+cd ../frontend
+npm install
+
+# Development mode (backend + frontend separate)
+# Terminal 1 - Backend
+cd backend
+npm run dev
+
+# Terminal 2 - Frontend
+cd frontend
+npm run dev
+
+# Production mode (single server)
+cd backend
+npm run build:all
+npm run start:prod
+```
+
+### MCP Configuration for Local Development
+
+```json
+{
+  "mcpServers": {
+    "chart-canvas": {
+      "command": "/path/to/node",
+      "args": [
+        "/path/to/chart-canvas/backend/node_modules/.bin/tsx",
+        "/path/to/chart-canvas/backend/src/index.ts"
+      ]
+    }
+  }
+}
+```
+
+## License
+
+MIT © 2026 Martijn
+
+## Links
+
+- [NPM Package](https://www.npmjs.com/package/@gluip/chart-canvas-mcp)
+- [GitHub Repository](https://github.com/gluip/chart-canvas)
+- [Model Context Protocol](https://modelcontextprotocol.io)

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.4",
-  "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",
@@ -31,6 +35,7 @@
   "scripts": {
     "build": "tsc",
     "build:all": "npm run build && cd ../frontend && npm run build",
+    "prepublishOnly": "cp ../README.md . && cp ../LICENSE .",
     "dev": "tsx src/index.ts",
     "dev:api": "tsx src/api-server.ts",
     "start": "node dist/index.js",
@@ -40,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"
   }