Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions customization/general-settings.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,11 @@ Older servers have neither: MySQL before 5.7.8, MariaDB before 10.1.1. A stateme

## Command line tool

Shows whether `/usr/local/bin/tablepro` links to this copy of the app, with the Terminal line that links or removes it. The command opens database URLs in the app. See [Terminal](/integrations/terminal).
**Command Line** shows whether the shell command links to this copy of the app. Copy its Terminal line to install or remove the link. See [Terminal](/integrations/terminal#install) for installation and commands.

## Trusted links

External links you chose to always allow, each with **Forget**, plus **Forget All**. Only a database on this machine can be trusted; a link to a remote host asks every time.
Use **Forget** to remove one saved link approval, or **Forget All** to remove them all. See [Trusting a link](/integrations/terminal#trusting-a-link) for which links qualify and when they still ask.

## Software update

Expand Down
4 changes: 3 additions & 1 deletion developers/mcp-protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,9 @@ actual path. Use the bundled bridge instead of hard-coding a path.
This file is [outside the stable contract](/developers/versioning#what-is-not-under-the-contract).

Before sending credentials, the bridge checks the file's owner and permissions, expiry, host process,
and socket ownership and location. It then calls `server/discover` over that socket and checks
and socket ownership and location. Before each request, the bridge and CLI check the connected
socket's `LOCAL_PEERPID` against the trusted handshake PID and recheck that process's executable.
It then calls `server/discover` over that socket and checks
`app.tablepro/instanceId` against the handshake. A mismatch refuses the connection. A restart or
socket failure requires a fresh trusted handshake; the bridge does not fall back to TCP.

Expand Down
22 changes: 18 additions & 4 deletions developers/pairing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,8 @@ Three constraints decide whether TablePro accepts the request at all:
name, such as `smb://`, `ssh://` and `webcal://`.

The exchange endpoint takes no bearer token: the single-use code plus the verifier is the credential.
It and `/mcp` are the only paths the server serves, and both accept `POST` only.
The public HTTP routes are `/v1/integrations/exchange` and `/mcp`; both accept `POST` only.
The bundled command also uses a [private revocation route](#revoking-a-token).

## Response modes

Expand Down Expand Up @@ -161,9 +162,22 @@ request, not a grant. **Deny** is the default button: Return and Escape both den
takes a click. The sheet does not take focus from another app; TablePro's Dock icon bounces instead.

Approving mints the token, holds the plaintext against a one-time code for 5 minutes, and opens the
redirect. Pairing again mints a second token rather than replacing the first, so an extension that
re-pairs should stop using its old one. Revoke either under
**Settings > MCP > Authentication**.
redirect. Pairing again creates a separate token. Retire an old token through
[revocation](#revoking-a-token) once the client uses its replacement.

## Revoking a token

Revoke a client's token in **Settings > MCP > Authentication**. For the bundled macOS command,
use [`tablepro unpair`](/integrations/terminal#status-and-pairing).

The command sends `POST /v1/integrations/revoke` over the private Unix socket, with a form-encoded
`token` field. The route does not exist on the TCP listener and is outside the
[stability contract](/developers/versioning#what-is-not-under-the-contract). Do not use it as a
public client API.

A successful response is `200 {}`, including for an unknown or already revoked token. A `503`
means revocation was not saved: the token remains valid. The server refuses the stdio bridge
credential with `400 unsupported_token_type`.

## Security properties

Expand Down
3 changes: 3 additions & 0 deletions developers/tokens.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ Revoking cancels every request that token has in flight and clears the connectio

**Disconnect** in the Connected Clients list revokes that client's token. It is not a soft disconnect: the client has to pair again or be given a new token.

For the bundled macOS command, follow [Status and pairing](/integrations/terminal#status-and-pairing)
to replace or remove its token. Its [revocation route](/developers/pairing#revoking-a-token) is private.

## The stdio bridge token

Every server start mints a token named `__stdio_bridge__` and writes it into the [handshake file](/developers/mcp-protocol#local-socket-and-handshake) for the bundled bridge. The bridge sends it over the private socket after checking the socket and host process. It is **Read & Write**, so an agent going through the bridge can read and write but cannot call `confirm_destructive_operation`.
Expand Down
18 changes: 12 additions & 6 deletions developers/versioning.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,12 +83,16 @@ Treat the port as a setting that defaults to `23508`; the pane's **Status** row

### The tablepro command and the app's identity

- `tablepro`, once installed from **Settings > General**, stays at `/usr/local/bin/tablepro` and
hands each argument to the app the way `open -b com.TablePro` does: database URLs, `tablepro://`
links, `.sql` files and database files. With no argument it opens the app.
- The bundle ID stays `com.TablePro`.
- The MCP bridge stays at `Contents/MacOS/tablepro-mcp` inside the app bundle.
- Where the bundle sits is up to the user. [Find the app](/developers#find-the-app) by bundle ID.
The documented commands, options and [exit statuses](/integrations/terminal#exit-status) keep their
names and meanings within a major version. New commands and options may appear. Use the reference
for your platform: [macOS](/integrations/terminal) or [Linux](/linux/command-line).

On macOS, the command ships at `Contents/SharedSupport/bin/tablepro` inside the app bundle.
The [install command](/integrations/terminal#install) links it into `/usr/local/bin`. Opening files
or URLs targets that app, or a copy already running. No arguments opens the app.

The bundle ID stays `com.TablePro`, and the MCP bridge stays at `Contents/MacOS/tablepro-mcp`.
The install folder is the user's choice; [find the app](/developers#find-the-app) by bundle ID.

## Breaking changes before 1.0

Expand All @@ -110,6 +114,8 @@ These can change in any release, without notice:

- Transport framing, internal message routing, and any HTTP path other than `/mcp` and
`/v1/integrations/exchange`.
- `/v1/integrations/revoke`, used by the bundled macOS command over the private socket. It is not
available through public HTTP. See [Revoking a token](/developers/pairing#revoking-a-token).
- The [handshake file and private socket](/developers/mcp-protocol#local-socket-and-handshake). Use the bundled
`tablepro-mcp` bridge, which finds the server on its own, or connect over HTTP to the port on the
**Status** row in **Settings > MCP**, `23508` by default.
Expand Down
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -448,6 +448,7 @@
"linux/connect",
"linux/sql-editor",
"linux/data-grid",
"linux/command-line",
"linux/keyboard-shortcuts",
"linux/troubleshooting"
]
Expand Down
2 changes: 1 addition & 1 deletion features/query-history.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Search matches partial words, so `cust` finds `customers`. Several words must al
| AI and MCP | Queries run by an AI assistant or an MCP client |
| AppleScript | Queries run by [a script](/developers/applescript) |
| Shortcuts | Queries and inserts run by a [Shortcuts action](/integrations/shortcuts) |
| Command Line | Queries run by [`tablepro query`](/integrations/terminal#run-a-query) |
| Command Line | Queries from the [macOS command](/integrations/terminal#run-a-query) |

**My Queries**, the default, is Editor and Explain. Add **Table Browsing** to see what the app sent while you clicked around a table, **Structure Changes** to review what altered a schema and when.

Expand Down
6 changes: 2 additions & 4 deletions integrations/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,7 @@ sidebarTitle: Overview
description: Use TablePro from AI clients, Raycast, the terminal, DDEV and iOS Shortcuts
---

AI clients and the Raycast extension query your databases through the [MCP server](/features/mcp),
so its limits, tokens and activity log, all reached from **Settings > MCP**, apply to them.
The terminal, DDEV and iOS Shortcuts work without it.
Use the [macOS command](/integrations/terminal) or [Linux command](/linux/command-line) for shell scripts. Use an MCP client for an AI assistant, or a link to open a connection in the app.

<CardGroup cols={2}>
<Card title="MCP clients" icon="robot" href="/integrations/mcp-clients">
Expand All @@ -16,7 +14,7 @@ The terminal, DDEV and iOS Shortcuts work without it.
Search connections, browse schemas and run SQL from Raycast.
</Card>
<Card title="Terminal" icon="terminal" href="/integrations/terminal">
Open database URLs and SQL files with the `tablepro` command.
Install the macOS command and run queries, browse connections or export tables.
</Card>
<Card title="DDEV" icon="cube" href="/integrations/ddev">
Open a project's database with `ddev tablepro`.
Expand Down
42 changes: 41 additions & 1 deletion integrations/mcp-clients.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,47 @@ Zed, in `~/.config/zed/settings.json`:

Claude Desktop starts MCP servers only as commands, so it needs a stdio-to-HTTP bridge of its own to reach this server.

The Linux server has nine tools: `list_connections`, `connect`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`, `browse_table`, `count_rows` and `execute_query`. Each connection's **External Clients** level decides what a client may do there: **Blocked**, **Read Only** (the default) or **Read & Write**. A write runs only after you click **Run** in the connection's window. **Regenerate Access Token…** turns the old token away at the next request, so paste the new one into every client.
### Linux tools

Start with `list_connections` and pass an id from its result as `connection_id`. Call `connect` for
a closed connection; a `connecting` result means the user may need to answer a prompt in the app.
Call it again to check for `open`.

Arguments marked `?` are optional. Unknown arguments are rejected.

| Tool | Arguments | Result |
|---|---|---|
| `list_connections` | None | Saved connections visible to clients, their open state, external access and Safe Mode |
| `connect` | `connection_id` | Opens the connection in a window; returns `connecting` or `open` |
| `list_databases` | `connection_id` | Databases and which one is current; unsupported on engines with no database listing |
| `list_schemas` | `connection_id`, `database?` | Schemas, with default and system flags |
| `list_tables` | `connection_id`, `database?`, `schema?` | Tables and views |
| `describe_table` | `connection_id`, `table`, `database?`, `schema?` | Columns, indexes, foreign keys and a row count where available |
| `get_table_ddl` | `connection_id`, `table`, `database?`, `schema?` | Statements that create the table |
| `browse_table` | `connection_id`, `table`, `schema?`, `filters?`, `logic?`, `sort?`, `limit?` | Filtered and sorted rows |
| `count_rows` | `connection_id`, `table`, `schema?`, `filters?`, `logic?` | Exact count of matching rows |
| `execute_query` | `connection_id`, `query`, `database?`, `read_only?`, `max_rows?`, `timeout_seconds?` | One statement's results, or one SQL Server batch's results |
| `export_data` | `connection_id`, `format`, `tables`, `database?`, `schema?`, `max_rows?` | CSV, JSON or SQL `INSERT` text for each table, with row counts and truncation flags |

`database` defaults to the connection's own database. An override must already be open beside it
through **Open Database…**. `schema` defaults to the connection's default schema. Pass table and
column names without SQL quotes. `execute_query` takes no `schema`; qualify names in the SQL.

`read_only` defaults to `false`. Set it to `true` to refuse anything but a read before asking for
write approval. Query size, row and timeout limits are the same as the
[Linux command](/linux/command-line#run-a-query); its [query rules](/linux/command-line#what-a-query-may-do)
also apply. `browse_table.limit` and `export_data.max_rows` use the query row limits.
`export_data` takes the [export formats and table limit](/linux/command-line#export) and returns text
in the response, without writing a file.

A filter has `column`, `operator`, and either `value` or `values`. Operators are `eq`, `not_eq`, `lt`,
`lt_eq`, `gt`, `gt_eq`, `contains`, `starts_with`, `ends_with`, `like`, `not_like`, `ilike`, `is_null`,
`is_not_null`, `in`, `not_in` and `between`. Use `values` for lists and the two bounds of `between`;
null checks need neither. `logic` is `and` by default, or `or`. Each sort entry has `column` and an
optional `direction`: `ascending` by default, or `descending`.

After **Regenerate Access Token…**, update the token in each MCP client. The
[Linux command](/linux/command-line#check-status) reads the replacement itself.

## HTTP transport

Expand Down
Loading
Loading