feat: External API integration with MCP tools and Raycast support

[datlechin]

Summary

Ships TablePro's first-class External API for Raycast, Cursor, Claude Desktop, and other MCP-compatible clients. Three integration channels with clearly separated responsibilities:

• tablepro:// URL scheme for navigation actions (open connection, table, query)
• MCP HTTP server for data exchange and AI tool calls
• Pairing flow with PKCE code exchange for one-click token issuance

49 commits across Swift (foundation, pairing, audit, tools, CLI binary, settings rename), Mintlify docs (full External API section + cross-references through the existing docs site), and unit tests (export injection regression).

What's new

Swift

• UUID-keyed tablepro:// URL scheme; new integrations/pair, integrations/start-mcp, connect/<uuid>/query?...&token= actions
• Per-connection External Access setting (blocked / readOnly / readWrite, defaults to readOnly)
• MCPPairingService with PKCE exchange + native approval sheet
• SQLite audit log (mcp-audit.db, 90-day retention) + Activity Log view in Settings
• Five new MCP tools: list_recent_tabs, search_query_history, open_connection_window, open_table_tab, focus_query_tab
• tablepro-mcp stdio CLI binary embedded in the app bundle (enables Cursor / Claude Desktop / Claude Code without an extension)
• MCP server lazy-starts on first external request (no manual Settings toggle)
• Settings tab renamed MCP to Integrations
• MCP support files moved to ~/Library/Application Support/TablePro/ (matches macOS convention for non-sandboxed apps)

Security hardening (post-review)

• export_data table names validated against ^[A-Za-z0-9_][A-Za-z0-9_.]*$ and dialect-quoted; synthesized queries now route through checkQueryPermission like the explicit query branch
• list_connections filtered by the token's allowedConnectionIds; empty Set means no access
• focus_query_tab rejects tabs without a connection (no auth bypass via nil-connection scratch tabs)
• open_connection_window, open_table_tab, focus_query_tab only require readOnly (was blocking the default Raycast user since readOnly is the connection default)
• export_data output_path restricted to ~/Downloads/; symlinks and .. resolved before the bounds check
• Auth checks run before any side effect in focus_query_tab (no window-focus-then-deny TOCTOU)

Docs

• Full docs/external-api/ section: URL scheme reference, MCP tools catalog, MCP resources, pairing sequence, tokens model, MCP clients (9 client config examples), versioning policy
• Cross-linked from landing, features overview, AI Assistant, Safe Mode, Connections overview, Connection Sharing, Tabs, Query History, Keyboard Shortcuts
• Removed stale features/deep-links.mdx
• Rewrote features/mcp.mdx from 307 lines to 81 as an orientation page that links into docs/external-api/

Tests

• MCPToolHandlerExportTests (new, 7 cases): regression tests for export_data table-name injection (;DROP TABLE, backtick escape, leading dot, empty), schema-qualified-name acceptance, sandbox enforcement on output_path

Note on the Raycast extension

The Raycast extension that consumes this API is shipped separately to the official Raycast Store via a PR to github.com/raycast/extensions, per Raycast's distribution model (every Store extension lives in that monorepo). That follow-up PR is staged locally and will go up after this lands and the next TablePro version ships, so the extension can reference shipped behavior.

Breaking changes

• tablepro://connect/<name>/... deep links removed. Replace with UUID-keyed paths via Copy Connection Deep Link in the sidebar context menu. User-saved bookmarks must be regenerated.
• MCP server data directory moved from ~/Library/Application Support/com.TablePro/ to ~/Library/Application Support/TablePro/. Existing tokens, audit log, and handshake files are not migrated. Re-pair Raycast / Cursor / Claude Desktop / any external clients after upgrading. Optionally delete the old directory: rm -rf ~/Library/Application Support/com.TablePro/

Architecture decisions

Decision	Rationale
Two channels (URL scheme + MCP), not one	URL scheme auto-launches the GUI on cold start; MCP can't run if the app isn't running
Per-integration scoped tokens (existing MCPTokenStore)	Already supports scopes + per-connection allowlists + revocation
TablePro is tool provider, not AI host	Raycast / Cursor / Claude run their own models. Same architecture works for every consumer
HTTP + stdio MCP transports	HTTP for the Raycast extension, stdio for native MCP clients (Raycast 1.98+, Cursor, Claude Desktop)
Per-connection External Access flag	Default readOnly belt-and-suspenders against accidental mutations from a token with fullAccess scope
UUID-keyed URLs (no name fallback)	Names get renamed; UUIDs don't
Native pairing sheet (PKCE), not copy-paste tokens	Token never shown to the user. PKCE binds the code to the original requester

Test plan

• xcodebuild ... build succeeds clean
• Cold launch shows welcome window without UI freeze
• Settings → Integrations tab present, External Access picker on connection editor → Advanced
• open "tablepro://connect/<uuid>" opens the connection; old name-keyed paths fail gracefully
• Pair with TablePro from a Raycast extension → approval sheet → token round-trips back; appears in Settings → Integrations → Authentication
• open_table_tab works from Raycast on a default readOnly connection (regression check for the readWrite-gate fix)
• Run Query against a readOnly connection rejects mutating SQL with 403
• export_data rejects table names with SQL metacharacters; only writes under ~/Downloads/
• Activity Log shows entries with token name, action, connection, outcome
• Wire tablepro-mcp into Claude Desktop's mcp-config.json, restart, @tablepro lists tools

Related

• Builds on top of merged refactor: Apple-pattern storage DI plus 3 product bug fixes #955 (Apple-pattern storage DI + 3 product fixes, in main as of c9a17b1)