sqlite-hub 1.5.0 → 2.0.1

package/README.md

@@ -265,7 +265,11 @@ rows as JSON, generating schema types, and working with Markdown documents. See
 
 ## API
 
-SQLite Hub also provides a local JSON API for app info, database metadata, tables, saved queries, exports, documents, and schema type generation. `/api/v1/info` returns the same app/version status as `sqlite-hub --info`; database data is protected by database-specific API itokens created in Settings. See the [API documentation](./docs/API.md) for authentication, endpoints, and examples.
+SQLite Hub also provides a local JSON API for app info, database metadata, tables, saved queries, exports, documents, and schema type generation. `/api/v1/info` returns the same app/version status as `sqlite-hub --info`; database data is protected by database-specific API tokens created in Settings. See the [API documentation](./docs/API.md) for authentication, endpoints, and examples.
+
+## MCP
+
+SQLite Hub includes a local MCP server for agents such as Codex. When SQLite Hub is running, the MCP endpoint is available at `/mcp`; a stdio fallback is also available through `sqlite-hub-mcp`. It exposes the shared API/CLI service layer as guarded tools for schema inspection, read-only queries, query-plan explanation, backups, type generation, documents, and chart creation. See the [MCP documentation](./docs/MCP.md) for setup, tool names, and security boundaries.
 
 ## Changelog
 

package/bin/sqlite-hub-mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { startMcpStdioServer } = require("../server/mcp/stdioServer");
+
+startMcpStdioServer().catch((error) => {
+  process.stderr.write(`SQLite Hub MCP failed to start: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/docs/MCP.md

@@ -0,0 +1,109 @@
+# SQLite Hub MCP
+
+SQLite Hub ships a local MCP server so agents can inspect and automate the same imported SQLite databases that the UI, CLI, and local API use.
+
+The MCP server uses the shared SQLite Hub service layer. API, CLI, and MCP calls all go through the same database registry, query execution, type generation, backup, document, and chart logic.
+
+## Start With SQLite Hub
+
+When SQLite Hub is running, the MCP server is available on the same local web server:
+
+```toml
+[mcp_servers.sqlitehub]
+url = "http://127.0.0.1:4173/mcp"
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+If SQLite Hub is started with a custom port, use that port in the URL:
+
+```toml
+[mcp_servers.sqlitehub]
+url = "http://127.0.0.1:PORT/mcp"
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+The Settings `MCP` tab shows a copyable Codex config with the active host and port.
+
+## Stdio Fallback
+
+When SQLite Hub is installed from npm, use:
+
+```bash
+sqlite-hub-mcp
+```
+
+For a local checkout, Codex can also spawn the stdio server directly:
+
+```toml
+[mcp_servers.sqlitehub]
+command = "node"
+args = ["/absolute/path/to/sqlite-hub/bin/sqlite-hub-mcp.js"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+The stdio fallback is intended for local agents running on the same machine as SQLite Hub. It does not expose a network listener and does not require API tokens for local stdio use.
+
+## Tools
+
+Read-only and safe tools:
+
+- `list_connections`: list imported SQLite Hub database ids and labels.
+- `get_database_overview`: inspect database health, SQLite metadata, table counts, and schema-map statistics.
+- `list_tables`: list database tables.
+- `describe_table`: inspect columns, indexes, foreign keys, triggers, and row counts for one table.
+- `get_schema`: return tables, views, indexes, triggers, and raw schema entries.
+- `get_indexes`: return all indexes or indexes for one table.
+- `get_foreign_keys`: return all foreign keys or foreign keys for one table.
+- `run_readonly_query`: execute a read-only `SELECT`, `PRAGMA`, or `EXPLAIN` query.
+- `explain_query_plan`: run `EXPLAIN QUERY PLAN` and return structured plan rows plus index hints when a table scan appears.
+- `read_documents`: read database-scoped Markdown documents.
+
+Controlled write tools:
+
+- `create_backup`: create a verified backup through SQLite Hub's existing backup mechanism.
+- `generate_types`: generate TypeScript, Rust, Kotlin, or Swift types from one table or all tables.
+- `create_chart_from_query`: create a saved chart from a read-only `SELECT` query. It writes chart metadata to SQLite Hub but does not export files.
+
+## Security
+
+`run_readonly_query` validates SQL server-side before execution. Only `SELECT`, `PRAGMA`, and `EXPLAIN` statements that return rows are allowed.
+
+These statements are blocked in `run_readonly_query`:
+
+- `INSERT`
+- `UPDATE`
+- `DELETE`
+- `DROP`
+- `ALTER`
+- `CREATE`
+- `ATTACH`
+- `DETACH`
+- `VACUUM`
+- other non-reader or mutating statements
+
+Backups are always created through SQLite Hub's managed backup service. Chart creation stores chart metadata only. The MCP server does not write arbitrary local files.
+
+The HTTP MCP endpoint runs on SQLite Hub's existing loopback server. It is local-only and uses the same localhost request guard as the internal API. API tokens are not exposed through MCP tool responses.
+
+## Settings Status
+
+The Settings view has an `MCP` tab. It shows whether the MCP server is running, whether an agent is connected, active client count, the last connection time, last tool call, transport, exposed tools, and a copyable Codex config example.
+
+For HTTP, connection state is tracked from MCP `initialize` and tool calls against `/mcp`. For stdio, connection state is tracked from MCP `initialize` and tool calls in the spawned process. When the stdio MCP process exits cleanly, SQLite Hub marks the session as disconnected.
+
+## Example Prompts
+
+```text
+Use SQLite Hub MCP to inspect my current database schema and suggest missing indexes.
+```
+
+```text
+Use SQLite Hub MCP to create a backup before generating TypeScript types.
+```
+
+```text
+Use SQLite Hub MCP to explain the query plan for this SQL query.
+```

package/docs/changelog.md

@@ -1,3 +1,8 @@
+# v2.0.0
+
+- mcp
+- mcp http endpoint starts with sqlite hub
+
 # v1.5.0
 
 - synthetic data generation

package/docs/todo.md

@@ -1,4 +1,3 @@
 # Maybe
 
 - Data Pipeline Light/hook, programmable triggers?
-- MCP

package/frontend/js/api.js

@@ -558,6 +558,10 @@ export function checkAppVersion() {
   return request("/api/settings/version-check");
 }
 
+export function getSettingsMcpStatus() {
+  return request("/api/settings/mcp");
+}
+
 export function createApiToken(name) {
   return request("/api/settings/api-tokens", {
     method: "POST",

package/frontend/js/app.js

@@ -2577,6 +2577,16 @@ async function handleAction(actionNode) {
             }
             return;
         }
+        case 'copy-mcp-config': {
+            const configNode = document.querySelector('[data-mcp-config]');
+            const config = configNode instanceof HTMLTextAreaElement ? configNode.value : '';
+
+            if (config && navigator.clipboard?.writeText) {
+                await navigator.clipboard.writeText(config);
+                showToast('MCP config copied.', 'success');
+            }
+            return;
+        }
         case 'open-row-editor-url':
             openRowEditorUrl(actionNode);
             return;

package/frontend/js/store.js

@@ -332,6 +332,9 @@ const state = {
         versionCheck: null,
         versionCheckLoading: false,
         versionCheckError: null,
+        mcpStatus: null,
+        mcpStatusLoading: false,
+        mcpStatusError: null,
     },
     overview: {
         data: null,
@@ -1568,6 +1571,22 @@ async function refreshSettingsState() {
     }
 }
 
+async function refreshSettingsMcpStatus() {
+    state.settings.mcpStatusLoading = true;
+    state.settings.mcpStatusError = null;
+    emitChange();
+
+    try {
+        const response = await api.getSettingsMcpStatus();
+        state.settings.mcpStatus = response.data ?? null;
+    } catch (error) {
+        state.settings.mcpStatusError = normalizeError(error);
+    } finally {
+        state.settings.mcpStatusLoading = false;
+        emitChange();
+    }
+}
+
 function buildLogRequestOptions({ append = false } = {}) {
     const filters = normalizeLogFilters(state.logs.filters);
 
@@ -1674,7 +1693,8 @@ export async function createSettingsApiToken(name) {
 }
 
 export function setSettingsSection(section) {
-    const normalizedSection = section === 'api-tokens' ? 'api-tokens' : 'information';
+    const normalizedSection =
+        section === 'api-tokens' ? 'api-tokens' : section === 'mcp' ? 'mcp' : 'information';
 
     if (state.settings.section === normalizedSection) {
         return;
@@ -1726,7 +1746,9 @@ export async function loadMoreLogs() {
     await loadLogs({ append: true });
 }
 
-export async function checkSettingsAppVersion() {
+export async function checkSettingsAppVersion(options = {}) {
+    const silent = Boolean(options.silent);
+
     state.settings.versionCheckLoading = true;
     state.settings.versionCheckError = null;
     emitChange();
@@ -1736,14 +1758,18 @@ export async function checkSettingsAppVersion() {
         const result = response.data ?? null;
 
         state.settings.versionCheck = result;
-        pushToast(
-            result?.updateAvailable ? `SQLite Hub v${result.latestVersion} is available.` : 'SQLite Hub is up to date.',
-            'success',
-        );
+        if (!silent) {
+            pushToast(
+                result?.updateAvailable ? `SQLite Hub v${result.latestVersion} is available.` : 'SQLite Hub is up to date.',
+                'success',
+            );
+        }
         return result;
     } catch (error) {
         state.settings.versionCheckError = normalizeError(error);
-        pushToast('Version check failed.', 'alert');
+        if (!silent) {
+            pushToast('Version check failed.', 'alert');
+        }
         return null;
     } finally {
         state.settings.versionCheckLoading = false;
@@ -2964,6 +2990,8 @@ async function loadRouteData(route, options = {}) {
             return;
         case 'settings':
             await refreshSettingsState();
+            await refreshSettingsMcpStatus();
+            await checkSettingsAppVersion({ silent: true });
             return;
         default:
     }

package/frontend/js/views/settings.js

@@ -6,6 +6,7 @@ function renderSettingsNavigation(activeSection) {
     const items = [
         { id: 'information', icon: 'info', label: 'Information' },
         { id: 'api-tokens', icon: 'key', label: 'API Tokens' },
+        { id: 'mcp', icon: 'hub', label: 'MCP' },
     ];
 
     return `
@@ -90,6 +91,187 @@ function renderVersionCheckStatus(settings) {
     `;
 }
 
+function renderMcpTimestamp(value) {
+    return value ? formatCompactDateTime(value) : 'Never';
+}
+
+function renderMcpStatusSummary(status) {
+    if (status?.error) {
+        return {
+            label: 'Server Error',
+            icon: 'error',
+            badgeClass: 'status-badge border-error/30 bg-error-container/20 text-error',
+            message: status.error,
+        };
+    }
+
+    if (status?.connected) {
+        return {
+            label: 'Agent Connected',
+            icon: 'check_circle',
+            badgeClass: 'status-badge status-badge--success',
+            message: `Last tool call: ${status.lastToolName || 'none'} at ${renderMcpTimestamp(status.lastToolCallAt)}`,
+        };
+    }
+
+    if (status?.enabled) {
+        return {
+            label: 'Waiting For Agent',
+            icon: 'radio_button_unchecked',
+            badgeClass: 'status-badge',
+            message: status.lastConnectedAt
+                ? `Last agent connection: ${renderMcpTimestamp(status.lastConnectedAt)}`
+                : 'No MCP agent connected yet.',
+        };
+    }
+
+    return {
+        label: 'Stopped',
+        icon: 'block',
+        badgeClass: 'status-badge',
+        message: 'No MCP agent connected yet.',
+    };
+}
+
+function renderMcpMetric(label, value) {
+    return `
+      <div class="border border-outline-variant/10 bg-surface-container-high px-4 py-3">
+        <div class="font-mono text-[10px] uppercase tracking-[0.18em] text-on-surface-variant/55">
+          ${escapeHtml(label)}
+        </div>
+        <div class="mt-2 break-words font-mono text-sm text-on-surface">
+          ${escapeHtml(value)}
+        </div>
+      </div>
+    `;
+}
+
+function renderMcpSection(settings) {
+    if (settings.mcpStatusLoading && !settings.mcpStatus) {
+        return `
+          <div class="flex min-h-[240px] items-center justify-center border border-outline-variant/10 bg-surface-container-low">
+            <div class="text-center text-on-surface-variant/40">
+              <span class="material-symbols-outlined mb-3 text-4xl">progress_activity</span>
+              <p class="font-mono text-[10px] uppercase tracking-[0.22em]">LOADING_MCP_STATUS</p>
+            </div>
+          </div>
+        `;
+    }
+
+    if (settings.mcpStatusError) {
+        return `
+          <div class="border border-error/20 bg-error-container/10 px-6 py-5 text-sm text-on-surface">
+            <div class="font-body text-xs font-bold uppercase tracking-[0.18em] text-error">
+              ${escapeHtml(settings.mcpStatusError.code ?? 'MCP_STATUS_FAILED')}
+            </div>
+            <div class="mt-2">${escapeHtml(settings.mcpStatusError.message ?? 'MCP status could not be loaded.')}</div>
+          </div>
+        `;
+    }
+
+    const status = settings.mcpStatus ?? {};
+    const summary = renderMcpStatusSummary(status);
+    const tools = status.toolDetails?.length
+        ? status.toolDetails
+        : (status.exposedTools ?? []).map(name => ({ name, description: '' }));
+    const codexConfig = status.codexConfig ?? '';
+    const command = status.command ?? 'sqlite-hub-mcp';
+
+    return `
+      <div class="space-y-6">
+        <section class="shell-section overflow-hidden">
+          <div class="flex items-center justify-between border-b border-outline-variant/10 bg-surface-container-highest px-4 py-2">
+            <span class="text-[10px] font-bold uppercase tracking-[0.25em]">MCP Status</span>
+            <span class="material-symbols-outlined text-xs text-primary-container">hub</span>
+          </div>
+          <div class="space-y-5 p-6">
+            <div class="flex flex-col gap-3 border border-outline-variant/10 bg-surface-container-high px-4 py-4 sm:flex-row sm:items-center sm:justify-between">
+              <div class="min-w-0">
+                <div class="flex items-center gap-3">
+                  <span class="material-symbols-outlined text-base text-primary-container">${summary.icon}</span>
+                  <span class="${summary.badgeClass}">${escapeHtml(summary.label)}</span>
+                </div>
+                <div class="mt-2 text-sm leading-6 text-on-surface-variant">
+                  ${escapeHtml(summary.message)}
+                </div>
+              </div>
+              <div class="font-mono text-[10px] uppercase tracking-[0.18em] text-on-surface-variant/60">
+                ${escapeHtml(status.transport ?? 'unknown')}
+              </div>
+            </div>
+            <div class="grid grid-cols-1 gap-3 md:grid-cols-3">
+              ${renderMcpMetric('MCP Server', status.serverRunning ? 'Running' : 'Stopped')}
+              ${renderMcpMetric('Agent connected', status.connected ? 'Yes' : 'No')}
+              ${renderMcpMetric('Active clients', String(status.activeClientCount ?? 0))}
+              ${renderMcpMetric('Last connected', renderMcpTimestamp(status.lastConnectedAt))}
+              ${renderMcpMetric('Last disconnected', renderMcpTimestamp(status.lastDisconnectedAt))}
+              ${renderMcpMetric('Last tool call', status.lastToolCallAt ? renderMcpTimestamp(status.lastToolCallAt) : 'Never')}
+              ${renderMcpMetric('Last tool name', status.lastToolName ?? 'None')}
+              ${renderMcpMetric('Transport', status.transport ?? 'unknown')}
+              ${renderMcpMetric('Exposed tools', String(status.exposedTools?.length ?? tools.length))}
+            </div>
+          </div>
+        </section>
+
+        <section class="shell-section overflow-hidden">
+          <div class="flex items-center justify-between border-b border-outline-variant/10 bg-surface-container-highest px-4 py-2">
+            <span class="text-[10px] font-bold uppercase tracking-[0.25em]">Tools</span>
+            <span class="material-symbols-outlined text-xs text-primary-container">construction</span>
+          </div>
+          <div class="grid grid-cols-1 gap-3 p-6 md:grid-cols-2">
+            ${tools
+                .map(
+                    tool => `
+                  <div class="border border-outline-variant/10 bg-surface-container-high px-4 py-3">
+                    <div class="font-mono text-xs font-bold text-primary-container">${escapeHtml(tool.name)}</div>
+                    <div class="mt-2 text-sm leading-6 text-on-surface-variant">${escapeHtml(tool.description || 'SQLite Hub MCP tool.')}</div>
+                  </div>
+                `,
+                )
+                .join('')}
+          </div>
+        </section>
+
+        <section class="shell-section overflow-hidden">
+          <div class="flex items-center justify-between border-b border-outline-variant/10 bg-surface-container-highest px-4 py-2">
+            <span class="text-[10px] font-bold uppercase tracking-[0.25em]">Codex Setup</span>
+            <span class="material-symbols-outlined text-xs text-primary-container">terminal</span>
+          </div>
+          <div class="space-y-4 p-6">
+            <div>
+              <div class="text-[10px] font-mono uppercase tracking-[0.2em] text-on-surface-variant/60">
+                MCP_ENDPOINT
+              </div>
+              <div class="mt-3 border border-outline-variant/10 bg-surface-container-high px-4 py-3 font-mono text-sm text-primary-container">
+                ${escapeHtml(command)}
+              </div>
+            </div>
+            <div class="grid grid-cols-1 gap-3 md:grid-cols-[minmax(0,1fr)_auto]">
+              <textarea class="settings-mcp-config-input custom-scrollbar control-input font-mono text-xs leading-6" readonly data-mcp-config>${escapeHtml(codexConfig)}</textarea>
+              <button class="standard-button self-start" data-action="copy-mcp-config" type="button">
+                <span class="material-symbols-outlined text-sm">content_copy</span>
+                Copy Config
+              </button>
+            </div>
+          </div>
+        </section>
+
+        <section class="shell-section overflow-hidden">
+          <div class="flex items-center justify-between border-b border-outline-variant/10 bg-surface-container-highest px-4 py-2">
+            <span class="text-[10px] font-bold uppercase tracking-[0.25em]">Security</span>
+            <span class="material-symbols-outlined text-xs text-primary-container">shield</span>
+          </div>
+          <div class="space-y-2 p-6 text-sm leading-6 text-on-surface-variant">
+            <div>Read-only queries are limited to SELECT, PRAGMA, and EXPLAIN.</div>
+            <div>Mutating SQL statements are blocked server-side before execution.</div>
+            <div>Destructive actions must use existing SQLite Hub safety mechanisms such as verified backups.</div>
+            <div>The local HTTP MCP endpoint is bound to SQLite Hub's loopback server and does not expose API tokens.</div>
+          </div>
+        </section>
+      </div>
+    `;
+}
+
 function renderApiTokenRow(token, tokenSaving) {
     const callCount = Number(token.callCount ?? 0);
     const createdAt = token.createdAt ? formatCompactDateTime(token.createdAt) : 'Unknown';
@@ -188,7 +370,8 @@ function renderSettingsContent(state) {
     `;
     }
 
-    const activeSection = state.settings.section === 'api-tokens' ? 'api-tokens' : 'information';
+    const activeSection =
+        state.settings.section === 'api-tokens' ? 'api-tokens' : state.settings.section === 'mcp' ? 'mcp' : 'information';
     const appVersion = escapeHtml(state.settings.appVersion ?? '0.0.0');
     const sqliteVersion = escapeHtml(state.settings.sqliteVersion ?? 'unknown');
     const versionCheckLoading = Boolean(state.settings.versionCheckLoading);
@@ -377,11 +560,12 @@ function renderSettingsContent(state) {
         </div>
       </section>
     `;
+    const mcpSection = renderMcpSection(state.settings);
 
     return `
       <div class="space-y-6">
         ${renderSettingsNavigation(activeSection)}
-        ${activeSection === 'api-tokens' ? apiTokensSection : informationSection}
+        ${activeSection === 'api-tokens' ? apiTokensSection : activeSection === 'mcp' ? mcpSection : informationSection}
       </div>
     `;
 }
@@ -396,7 +580,9 @@ export function renderSettingsView(state) {
               subtitle:
                   state.settings.section === 'api-tokens'
                       ? 'Security // Database API access'
-                      : 'Application // Build + Credits',
+                      : state.settings.section === 'mcp'
+                        ? 'Agents // Local MCP access'
+                        : 'Application // Build + Credits',
           })}
           ${renderSettingsContent(state)}
         </div>