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
11 changes: 11 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,17 @@ SeaTable SQL behaviour verified against 7.0, which the tool texts rely on:

To see how real models use the tools, run the series in `docs/testing-with-models.md`.

### Row IDs and `find_rows` filters

An answer of "0 rows" reads like a fact, so a request the server can't apply must not end in one. `normalizeWhere()` in `src/mcp/tools/findRows.ts` repairs a filter whose meaning is clear (a JSON string, `{Name: {eq: "x"}}`, `{eq: {column: "Name", value: "x"}}`, aliases such as `=` or `not_in`), and `checkCondition()` reports the rest. `resolveColumns()` corrects the case of a column if only one fits and says so in a `notice`; a typo stays an error. `evalWhere()` compares across types (`"10"` against a number cell as a number) and orders empty cells like SQL, matching none of them. The API returns dates with a time (`2026-08-05T00:00:00+02:00`), so a plain date in a filter compares with the day of the cell, and a date in another format such as `01.08.2026` is reported, as its meaning depends on the locale. Coverage is in `tests/rowLookup.spec.ts`.

SeaTable's answers for a row ID it doesn't know, verified on SeaTable Cloud. Models tend to pass a visible value such as an auto-number, so `ROW_ID_NOTE` is in every tool description and `withRowIdNote()` adds it to these errors:

- `get_row`, `download_file`, `upload_file`: `row _id not exits`. `update_rows`: `row not found`. `link_rows`: `Row does not exist`.
- `delete_rows`: `param row_ids invalid` for an ID of another form like `D-0008`, otherwise success with `deleted_rows: 0`. The tool reports that count, not the number of IDs it was given.
- `unlink_rows`: success with `deleted_links_count: 0`. The tool reports `success: false` with a notice.
- `get_row_activities`: an empty list, the same as for an existing row whose activities are past the retention period, which varies. The tool looks up the row on an empty result to tell them apart, and its notice names no period.

### Server instructions and tool annotations

The `instructions` in `src/mcp/server.ts` reach every client, and the SeaTable AI chat plugin (`seatable-plugin-ai-chat`) embeds them in its system prompt instead of keeping its own SQL rules. A change there takes effect for all clients on the next deployment, without a plugin release. If a rule moves here from a client, deploy the server first.
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@seatable/mcp-seatable",
"version": "1.9.4",
"version": "1.9.5",
"type": "module",
"license": "MIT",
"mcpName": "io.github.seatable/seatable",
Expand Down
8 changes: 7 additions & 1 deletion src/mcp/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ import { registerUnlinkRows } from './tools/unlinkRows.js'
import { registerUpdateRows } from './tools/updateRow.js'
import { registerUploadFile } from './tools/uploadFile.js'
import { registerUpsertRows } from './tools/upsertRows.js'
import { ROW_ID_NOTE } from './tools/utils.js'

// Helper function to convert Zod schemas to JSON Schema for MCP tools
const getInputSchema = (schema: z.ZodType<object>): ListToolsResult['tools'][0]['inputSchema'] => {
Expand Down Expand Up @@ -79,6 +80,11 @@ const CLIENT_ERROR_CODES = new Set([
'ERR_FILE_TOO_LARGE', 'ERR_AUTH_EXPIRED', 'ERR_RATE_LIMITED',
])

/** SeaTable's wordings for an unknown or malformed row ID, one with a typo; "exi" also matches if it gets fixed. */
function withRowIdNote(message: string): string {
return /row _id not exi|row not found|row does not exist|param row_ids invalid/i.test(message) ? `${message.replace(/\.$/, '')}. ${ROW_ID_NOTE}` : message
}

export class SeaTableMCPServer {
private readonly server: Server
private readonly client: ClientLike
Expand Down Expand Up @@ -331,7 +337,7 @@ export class SeaTableMCPServer {
content: [{
type: 'text',
text: JSON.stringify(
`Error in tool ${toolName}: ${error instanceof Error ? error.message : String(error)}`
`Error in tool ${toolName}: ${withRowIdNote(error instanceof Error ? error.message : String(error))}`
),
}],
isError: true,
Expand Down
19 changes: 16 additions & 3 deletions src/mcp/tools/deleteRow.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { z } from 'zod'

import { ToolRegistrar } from './types.js'
import { ROW_ID_NOTE } from './utils.js'

const InputSchema = z.object({
table: z.string().describe('Target table name'),
Expand All @@ -12,14 +13,26 @@ export const registerDeleteRows: ToolRegistrar = (server, { client, getInputSche
'delete_rows',
{
title: 'Delete Rows',
description: 'Delete one or more rows from a table by their IDs.',
description: `Delete one or more rows from a table by their IDs. ${ROW_ID_NOTE}`,
inputSchema: getInputSchema(InputSchema),
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
},
async (args: unknown) => {
const { table, row_ids } = InputSchema.parse(args)
await client.deleteRows(table, row_ids)
return { content: [{ type: 'text', text: JSON.stringify({ success: true, deleted_count: row_ids.length }) }] }
const res = await client.deleteRows(table, row_ids)
// SeaTable counts what it deleted, and answers 0 for IDs it doesn't know
const deleted = res.deleted_rows ?? row_ids.length
const notFound = row_ids.length - deleted
return {
content: [{
type: 'text',
text: JSON.stringify({
success: notFound === 0,
deleted_count: deleted,
...(notFound > 0 && { notice: `${notFound} of ${row_ids.length} row IDs matched no row and nothing was deleted for them. ${ROW_ID_NOTE}` }),
}),
}],
}
}
)
}
3 changes: 2 additions & 1 deletion src/mcp/tools/downloadFile.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { z } from 'zod'

import { ToolRegistrar } from './types.js'
import { ROW_ID_NOTE } from './utils.js'

const InputSchema = z.object({
table: z.string().describe('Target table name'),
Expand All @@ -14,7 +15,7 @@ export const registerDownloadFile: ToolRegistrar = (server, { client, getInputSc
'download_file',
{
title: 'Download File',
description: `Read the content of a file attached to a row in a file or image column. Use get_row first to see available files in the column, then pass the exact file_name to select a specific file.
description: `Read the content of a file attached to a row in a file or image column. Use get_row first to see available files in the column, then pass the exact file_name to select a specific file. ${ROW_ID_NOTE}

Returns JSON with: file_name, file_size (bytes), content, content_type, and download_link (only when content_type is "binary_url").

Expand Down
Loading
Loading