{"_id":"@aspereo/mcp-seatable","_rev":"3-2e9512d392d553303c02dedc0ecfba96","name":"@aspereo/mcp-seatable","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@aspereo/mcp-seatable","version":"1.0.1","keywords":["mcp","model-context-protocol","seatable","database","api","server","ai","assistant","sql","crud"],"author":{"name":"Brian Money"},"license":"MIT","_id":"@aspereo/mcp-seatable@1.0.1","maintainers":[{"name":"brianmoney","email":"brian@aspereo.com"}],"homepage":"https://github.com/brianmoney/mcp-seatable#readme","bugs":{"url":"https://github.com/brianmoney/mcp-seatable/issues"},"bin":{"mcp-seatable":"bin/seatable-mcp.cjs","seatable-mcp":"bin/seatable-mcp.cjs"},"dist":{"shasum":"340089814650eeac383959f0c76d4ee0ea5431ea","tarball":"https://registry.npmjs.org/@aspereo/mcp-seatable/-/mcp-seatable-1.0.1.tgz","fileCount":140,"integrity":"sha512-40KyEoEMkwviEauTqqC4x4QqnypdtYoGQZJoio0qUl62yt/2ZSVC8G7bszot7RIB33R96yNZH5SNqTk5abAwlA==","signatures":[{"sig":"MEYCIQDMItDP4OESf31C62kSEJtweshY+wtQYOKar4p99zr1lAIhAOf6ugDR8EFbem/DSzxFYAPEjHS1z091opYsuUUmjRFg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":310912},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"7d2eb3ebecfda0d909634d3466b1211c64711869","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint . --ext .ts","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","format":"prettier --check .","prepare":"npm run build","lint:fix":"eslint . --ext .ts --fix","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest","setup:hooks":"git config core.hooksPath .githooks","prepublishOnly":"npm run build && npm run test && npm run lint"},"_npmUser":{"name":"brianmoney","email":"brian@aspereo.com"},"repository":{"url":"git+https://github.com/brianmoney/mcp-seatable.git","type":"git"},"_npmVersion":"10.2.3","description":"A comprehensive MCP (Model Context Protocol) server that provides full SeaTable database access through 11 powerful tools","directories":{},"_nodeVersion":"20.10.0","dependencies":{"zod":"^3.23.8","pino":"^9.4.0","axios":"^1.7.7","dotenv":"^16.4.5","bottleneck":"^2.19.5","axios-retry":"^4.5.0","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^1.17.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.1","eslint":"^9.11.1","vitest":"^2.1.1","prettier":"^3.3.3","typescript":"^5.6.2","@types/node":"^22.5.4","typescript-eslint":"^8.5.0","eslint-plugin-import":"^2.29.1","eslint-config-prettier":"^9.1.0","@typescript-eslint/parser":"^8.5.0","@typescript-eslint/eslint-plugin":"^8.5.0","eslint-plugin-simple-import-sort":"^12.1.1"},"_npmOperationalInternal":{"tmp":"tmp/mcp-seatable_1.0.1_1756822952862_0.5668778664381542","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aspereo/mcp-seatable","version":"1.0.2","keywords":["mcp","model-context-protocol","seatable","database","api","server","ai","assistant","sql","crud"],"author":{"name":"Brian Money"},"license":"MIT","_id":"@aspereo/mcp-seatable@1.0.2","maintainers":[{"name":"brianmoney","email":"brian@aspereo.com"}],"homepage":"https://github.com/brianmoney/mcp-seatable#readme","bugs":{"url":"https://github.com/brianmoney/mcp-seatable/issues"},"bin":{"mcp-seatable":"bin/seatable-mcp.cjs","seatable-mcp":"bin/seatable-mcp.cjs"},"dist":{"shasum":"0c6f773e0ce471a5de43d6fe660a15123ccd3d14","tarball":"https://registry.npmjs.org/@aspereo/mcp-seatable/-/mcp-seatable-1.0.2.tgz","fileCount":140,"integrity":"sha512-P4JkzGm3YbSdvXzeyTLJ0vw9KrvY0LCx54QV6tHsl+FNulrqlQ/W/8P6gqgToWRdAfki4NL4sA0hlo+3EvmM6Q==","signatures":[{"sig":"MEUCIGfq9oKfMImLtSDmiV2L6VhBQLV5Fcte4j1pfs9XKebQAiEAx+/Ud/wFdAzsTUI72wAR7AXN7q66Id3dcI9LyF1CFHU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":311562},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"024cf54553cbcfb66ca2c6ee142286b019e1a23d","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint . --ext .ts","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","format":"prettier --check .","prepare":"npm run build","lint:fix":"eslint . --ext .ts --fix","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest","setup:hooks":"git config core.hooksPath .githooks","prepublishOnly":"npm run build && npm run test && npm run lint"},"_npmUser":{"name":"brianmoney","email":"brian@aspereo.com"},"repository":{"url":"git+https://github.com/brianmoney/mcp-seatable.git","type":"git"},"_npmVersion":"10.2.3","description":"A comprehensive MCP (Model Context Protocol) server that provides full SeaTable database access through 11 powerful tools","directories":{},"_nodeVersion":"20.10.0","dependencies":{"zod":"^3.23.8","pino":"^9.4.0","axios":"^1.7.7","dotenv":"^16.4.5","bottleneck":"^2.19.5","axios-retry":"^4.5.0","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^1.17.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.1","eslint":"^9.11.1","vitest":"^2.1.1","prettier":"^3.3.3","typescript":"^5.6.2","@types/node":"^22.5.4","typescript-eslint":"^8.5.0","eslint-plugin-import":"^2.29.1","eslint-config-prettier":"^9.1.0","@typescript-eslint/parser":"^8.5.0","@typescript-eslint/eslint-plugin":"^8.5.0","eslint-plugin-simple-import-sort":"^12.1.1"},"_npmOperationalInternal":{"tmp":"tmp/mcp-seatable_1.0.2_1756824013377_0.9343190242328681","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aspereo/mcp-seatable","version":"1.0.3","type":"module","license":"MIT","description":"A comprehensive MCP (Model Context Protocol) server that provides full SeaTable database access through 11 powerful tools","keywords":["mcp","model-context-protocol","seatable","database","api","server","ai","assistant","sql","crud"],"author":{"name":"Brian Money"},"repository":{"type":"git","url":"git+https://github.com/brianmoney/mcp-seatable.git"},"bugs":{"url":"https://github.com/brianmoney/mcp-seatable/issues"},"homepage":"https://github.com/brianmoney/mcp-seatable#readme","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"bin":{"seatable-mcp":"bin/seatable-mcp.cjs","mcp-seatable":"bin/seatable-mcp.cjs"},"publishConfig":{"access":"public"},"scripts":{"dev":"tsx watch src/index.ts","build":"tsc -p tsconfig.json","start":"node dist/index.js","test":"vitest run","test:watch":"vitest","lint":"eslint . --ext .ts","lint:fix":"eslint . --ext .ts --fix","format":"prettier --check .","typecheck":"tsc -p tsconfig.json --noEmit","setup:hooks":"git config core.hooksPath .githooks","prepublishOnly":"npm run build && npm run test && npm run lint","prepare":"npm run build","cf:dev":"wrangler dev src/cloudflare/worker.ts --local","cf:secrets:sync":"tsx scripts/sync-wrangler-secrets.ts","cf:secrets:sync:prod":"tsx scripts/sync-wrangler-secrets.ts --env production","schemas:snapshot":"tsx scripts/snapshot-schemas.ts","parity:test":"tsx scripts/transport-parity.ts"},"engines":{"node":">=18"},"dependencies":{"@cloudflare/workers-oauth-provider":"^0.0.11","@modelcontextprotocol/sdk":"^1.17.4","agents":"^0.2.6","axios":"^1.7.7","axios-retry":"^4.5.0","bottleneck":"^2.19.5","dotenv":"^16.4.5","pino":"^9.4.0","zod":"^3.23.8","zod-to-json-schema":"^3.24.6"},"devDependencies":{"@types/node":"^22.5.4","@typescript-eslint/eslint-plugin":"^8.5.0","@typescript-eslint/parser":"^8.5.0","eslint":"^9.11.1","eslint-config-prettier":"^9.1.0","eslint-plugin-import":"^2.29.1","eslint-plugin-simple-import-sort":"^12.1.1","eventsource":"^4.0.0","node-fetch":"^3.3.2","prettier":"^3.3.3","tsx":"^4.19.1","typescript":"^5.6.2","typescript-eslint":"^8.5.0","vitest":"^2.1.1","wrangler":"^4.39.0"},"_id":"@aspereo/mcp-seatable@1.0.3","gitHead":"d6d199613c22587d2333897ea381a8a13ebb5e83","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-C26D8rk6Qb4w/je/awf6yJUY3C9RQU+zhF8wjVunPgtHeLmQGaHFJvkm4t/cg3Z5FECLJ5KmQxOTgqROXG78jQ==","shasum":"1c00105a436a8d1aa3e9280c3607fe3a634725e8","tarball":"https://registry.npmjs.org/@aspereo/mcp-seatable/-/mcp-seatable-1.0.3.tgz","fileCount":156,"unpackedSize":407279,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDdAFLSScq6FB8zxy1TIj8be3VueRIk/zNO0JxDatjn5wIgcSgxK4T1FNa+lmX8vVURG3abPNvYc4R5IsaGMJYeGgc="}]},"_npmUser":{"name":"brianmoney","email":"brian@aspereo.com"},"directories":{},"maintainers":[{"name":"brianmoney","email":"brian@aspereo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-seatable_1.0.3_1759238104287_0.12589966405409725"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-02T14:22:32.781Z","modified":"2025-09-30T13:15:04.687Z","1.0.1":"2025-09-02T14:22:33.155Z","1.0.2":"2025-09-02T14:40:13.566Z","1.0.3":"2025-09-30T13:15:04.487Z"},"bugs":{"url":"https://github.com/brianmoney/mcp-seatable/issues"},"author":{"name":"Brian Money"},"license":"MIT","homepage":"https://github.com/brianmoney/mcp-seatable#readme","keywords":["mcp","model-context-protocol","seatable","database","api","server","ai","assistant","sql","crud"],"repository":{"type":"git","url":"git+https://github.com/brianmoney/mcp-seatable.git"},"description":"A comprehensive MCP (Model Context Protocol) server that provides full SeaTable database access through 11 powerful tools","maintainers":[{"name":"brianmoney","email":"brian@aspereo.com"}],"readme":"# mcp-seatable\n\nA comprehensive MCP (Model Context Protocol) server that provides full SeaTable dat```javascript\n// Connect to your deployed Worker instance\nconst mcpClient = new MCPClient('https://your-worker-name.your-account.workers.dev/mcp');se access through 18+ powerful tools. Deploy anywhere: traditional CLI, local SSE server, or scalable Cloudflare Workers.\n\n> NOTE: As of v1.0.3 the Cloudflare Worker deployment exposes all tools without authentication. Do NOT deploy to a public URL containing sensitive data until OAuth + scoped permissions (planned) are enabled. You can mitigate risk by keeping the Worker URL private or restricting via Cloudflare Access.\n\n## 🚀 Deployment Options\n\n### Option 1: Cloudflare Workers (Recommended for Production)\n\nDeploy your own scalable MCP server on Cloudflare Workers with session persistence and dual transport support:\n\n```bash\n# Clone and deploy\ngit clone https://github.com/brianmoney/mcp-seatable\ncd mcp-seatable\nnpm install\nnpx wrangler deploy\n\n# After deployment, use your worker URL\nnpx mcp-remote https://your-worker-name.your-account.workers.dev/sse\n```\n\n**Features:**\n\n- ✅ Persistent sessions with Durable Objects\n- ✅ Both SSE (`/sse`) and Streamable HTTP (`/mcp`) transports\n- ✅ Automatic scaling and global distribution\n- ✅ Zero cold start issues\n- ✅ Built-in health monitoring\n\n### Option 2: Local SSE Server (Best for Development)\n\nRun a local HTTP server with SSE transport for network-accessible MCP:\n\n```bash\n# Install and run locally\nnpm install -g @aspereo/mcp-seatable\nPORT=3001 MCP_SEATABLE_TRANSPORT=sse mcp-seatable\n\n# Or with npx\nPORT=3001 npx -y @aspereo/mcp-seatable --sse\n\n# Test endpoints\ncurl http://localhost:3001/health\ncurl -H \"Accept: text/event-stream\" http://localhost:3001/mcp\n```\n\n**Features:**\n\n- ✅ Network accessible over HTTP\n- ✅ Real-time SSE communication\n- ✅ Perfect for development and testing\n- ✅ MCP Inspector compatible\n\n### Option 3: Traditional CLI (MCP Clients)\n\nDirect integration with MCP clients like Claude Desktop, Cursor, and VS Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n## ⚡ Quick Start Examples\n\n### For Claude Desktop (Traditional CLI)\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable@1.0.3\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://cloud.seatable.io\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n### For Web Applications (Cloudflare Worker)\n\n```javascript\n// Connect to your deployed Worker instance\nconst mcpClient = new MCPClient('https://your-worker-name.your-account.workers.dev/mcp')\nawait mcpClient.initialize()\nconst tables = await mcpClient.callTool('list_tables', {})\n```\n\n### For Development (Local SSE Server)\n\n```bash\n# Terminal 1: Start server\nPORT=3001 npx -y @aspereo/mcp-seatable --sse\n\n# Terminal 2: Test with MCP Inspector\nnpx @modelcontextprotocol/inspector@latest\n# Connect to: http://localhost:3001/mcp\n```\n\n### Required Environment Variables\n\nAll deployment methods need these environment variables:\n\n- `SEATABLE_SERVER_URL` - Your SeaTable server (e.g., `https://cloud.seatable.io`)\n- `SEATABLE_API_TOKEN` - Your SeaTable API token\n- `SEATABLE_BASE_UUID` - Your SeaTable base UUID\n\nOptional:\n\n- `SEATABLE_TABLE_NAME` - Default table name\n- `SEATABLE_MOCK=true` - Enable mock mode for testing\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n| Issue                    | Solution                                       |\n| ------------------------ | ---------------------------------------------- |\n| `command not found: npx` | Install Node.js 18+                            |\n| `Invalid API token`      | Check `SEATABLE_API_TOKEN` in environment      |\n| `Base not found`         | Verify `SEATABLE_BASE_UUID` is correct         |\n| `Connection timeout`     | Check `SEATABLE_SERVER_URL` and network access |\n| `Permission denied`      | Ensure API token has required base permissions |\n\n### Testing Your Setup\n\n```bash\n# Test basic connectivity\nnode scripts/test-client.mjs\n\n# Test specific tool\nnode scripts/mcp-call.cjs list_tables\n\n# Test with mock data\nSEATABLE_MOCK=true node scripts/test-client.mjs\n```\n\n### Debug Mode\n\nEnable verbose logging:\n\n```bash\n# For CLI mode\nDEBUG=mcp-seatable:* npx -y @aspereo/mcp-seatable\n\n# For SSE mode\nDEBUG=mcp-seatable:* PORT=3001 npx -y @aspereo/mcp-seatable --sse\n```\n\n## What is this?\n\nThis project implements a production-ready MCP server using the `@modelcontextprotocol/sdk` that integrates with SeaTable's REST API. It provides a complete toolkit for database operations including CRUD operations, advanced querying, schema management, and raw SQL execution. All tools use Zod validation and return structured JSON responses.\n\n## Key Features\n\n- **Complete CRUD Operations**: Create, read, update, delete rows and tables\n- **Advanced Querying**: Client-side filtering with DSL and raw SQL support\n- **Schema Management**: Create, modify, and delete tables and columns\n- **Safe SQL Execution**: Parameterized queries with injection protection\n- **Real-time Health Monitoring**: Connection status and latency tracking\n- **Production Ready**: Comprehensive error handling and logging\n- **Mock Mode**: In-memory testing without live SeaTable connection\n\n## Architecture\n\nBuilt with a modern, proven architecture pattern:\n\n- **Server + setRequestHandler pattern**: Reliable MCP implementation following best practices from airtable-mcp-server\n- **Centralized tool management**: All tools managed in a single `handleListTools`/`handleCallTool` pattern\n- **Comprehensive validation**: Zod schemas for all inputs with detailed error messages\n- **Type-safe client**: Full TypeScript support with proper error handling\n- **Flexible deployment**: Supports both API Gateway and direct SeaTable API endpoints\n\n## Installation\n\nNo installation required! This MCP server can be used directly with `npx -y @aspereo/mcp-seatable`.\n\nAlternatively, you can install globally:\n\n```bash\nnpm install -g @aspereo/mcp-seatable\n```\n\n## Usage\n\n### Claude Desktop\n\nTo use with Claude Desktop, add the server config:\n\nOn MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\nOn Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to your Cursor settings by opening the command palette (`Cmd/Ctrl+Shift+P`) and selecting \"Preferences: Open Settings (JSON)\":\n\n```json\n{\n  \"mcp.servers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n### VSCode with GitHub Copilot\n\nInstall the MCP extension for VSCode, then add to your VSCode settings.json:\n\n```json\n{\n  \"mcp.servers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\nAll configuration is done through environment variables:\n\n- `SEATABLE_SERVER_URL` - Your SeaTable server URL\n- `SEATABLE_API_TOKEN` - Your SeaTable API token\n- `SEATABLE_BASE_UUID` - Your SeaTable base UUID\n- `SEATABLE_TABLE_NAME` - Optional default table name\n- `SEATABLE_MOCK` - Set to `true` for offline testing with mock data\n- `SEATABLE_ACCESS_TOKEN_EXP` - Token expiry (default: `1h`)\n- `SEATABLE_TOKEN_ENDPOINT_PATH` - Custom token endpoint path if needed\n\n## Programmatic Usage\n\nYou can also use mcp-seatable as a library in your Node.js applications:\n\n```bash\nnpm install @aspereo/mcp-seatable\n```\n\n```typescript\nimport { createMcpServer } from '@aspereo/mcp-seatable'\n\n// Create and start the MCP server\nconst server = await createMcpServer({\n  serverUrl: 'https://your-seatable-server.com',\n  apiToken: 'your-api-token',\n  baseUuid: 'your-base-uuid',\n})\n\n// The server will handle MCP protocol communications\n```\n\n## Mock Mode\n\nEnable a fast, offline mock:\n\n```bash\nSEATABLE_MOCK=true npm run dev\n```\n\nThe mock implements in-memory tables and rows and returns synthetic metadata. Useful for demos and tests without a live SeaTable.\n\n## 🏗️ Architecture & Transport Details\n\n### Deployment Architecture Comparison\n\n| Feature                | **Cloudflare Worker**              | **Local SSE Server**        | **Traditional CLI**           |\n| ---------------------- | ---------------------------------- | --------------------------- | ----------------------------- |\n| **Scalability**        | ✅ Auto-scaling, global            | 📍 Single instance          | 📍 Per-client process         |\n| **Session Management** | ✅ Durable Objects (persistent)    | ⚠️ In-memory (may timeout)  | ✅ Direct stdio               |\n| **Network Access**     | ✅ HTTPS endpoints                 | ✅ HTTP endpoints           | ❌ Local only                 |\n| **Cold Starts**        | ✅ Eliminated with Durable Objects | ✅ Always warm              | ❌ Process startup            |\n| **Transport Support**  | ✅ Both SSE + Streamable HTTP      | ✅ SSE only                 | ✅ stdio only                 |\n| **Use Cases**          | Production, multi-user, web apps   | Development, testing, demos | IDE integration, personal use |\n\n### Transport Protocol Details\n\n#### Cloudflare Worker Endpoints\n\n**SSE Transport** (Recommended for compatibility):\n\n```bash\n# Connection flow\nGET /sse                              # Establish SSE connection\nPOST /sse/message?sessionId=xxx      # Send MCP messages\n```\n\n**Streamable HTTP Transport** (Modern, single-endpoint):\n\n```bash\n# All communication through one endpoint\nPOST /mcp                            # Initialize + all subsequent messages\n# Session managed via Mcp-Session-Id headers\n```\n\n#### Local SSE Server Endpoints\n\n```bash\nGET /mcp                             # SSE connection (different path!)\nPOST /messages?sessionId=xxx         # Message handling\nGET /health                          # Health probe\n```\n\n#### Traditional CLI (stdio)\n\n```bash\n# Direct stdin/stdout communication\nnode dist/index.js                   # Starts MCP server on stdio\n./bin/seatable-mcp.cjs              # Binary wrapper\n```\n\n### Development & Deployment Commands\n\n```bash\n# Local development\nnpm run dev                          # TypeScript watch mode\nPORT=3001 npm start -- --sse        # Local SSE server\nnpm run cf:dev                       # Local Worker with Wrangler\n\n# Deployment\nnpx wrangler deploy                  # Deploy to Cloudflare Workers\nnpm run cf:secrets:sync             # Sync environment to Worker\n\n# Testing\n./scripts/test-worker.sh             # Test deployed Worker\nnode scripts/test-client.mjs        # Interactive testing\n```\n\n## Version Pinning (recommended)\n\nTo avoid unexpected changes when new versions are released, pin the package version in your MCP client configuration. Replace `1.0.2` with the version you want to lock to.\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable@1.0.3\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\n```json\n{\n  \"mcp.servers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable@1.0.3\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n### VSCode with GitHub Copilot\n\n```json\n{\n  \"mcp.servers\": {\n    \"seatable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aspereo/mcp-seatable@1.0.3\"],\n      \"env\": {\n        \"SEATABLE_SERVER_URL\": \"https://your-seatable-server.com\",\n        \"SEATABLE_API_TOKEN\": \"your-api-token\",\n        \"SEATABLE_BASE_UUID\": \"your-base-uuid\"\n      }\n    }\n  }\n}\n```\n\n## 🛠️ MCP Tools\n\nOur server provides 18+ comprehensive tools for complete SeaTable database management:\n\n### Core Data Operations\n\n- **`ping_seatable`** - Health check with connection status and latency monitoring\n- **`list_tables`** - Get all tables with metadata\n- **`get_schema`** - Get complete database structure and metadata\n- **`list_rows`** - Paginated row listing with filtering and sorting\n- **`find_rows`** - Advanced client-side filtering with powerful DSL\n- **`search_rows`** - Full-text search across table data\n- **`get_row`** - Retrieve specific row by ID\n- **`add_row`** - Add single new row\n- **`append_rows`** - Add multiple rows (bulk operations)\n- **`update_row`** - Update single row\n- **`upsert_rows`** - Insert or update rows (bulk operations)\n- **`delete_row`** - Remove single row by ID\n- **`link_rows`** - Create relationships between rows\n- **`unlink_rows`** - Remove relationships between rows\n\n### Table & Schema Management\n\n- **`manage_tables`** - Create, rename, and delete tables\n- **`manage_columns`** - Add, modify, and delete table columns\n- **`bulk_set_select_options`** - Bulk manage dropdown/multi-select options\n\n### File Operations\n\n- **`attach_file_to_row`** - Upload and attach files to table rows\n\nAll tools support comprehensive input validation with Zod schemas, structured JSON responses, and detailed error handling.\n\nAll tools include comprehensive input validation with Zod schemas and return structured JSON responses.\n\n## Tool Examples\n\n### Basic Operations\n\n```json\n// List all tables\n{ \"tool\": \"list_tables\", \"args\": {} }\n\n// Get rows with pagination and filtering\n{ \"tool\": \"list_rows\", \"args\": { \"table\": \"Tasks\", \"page_size\": 10, \"order_by\": \"_ctime\", \"direction\": \"desc\" } }\n\n// Add new rows\n{ \"tool\": \"append_rows\", \"args\": { \"table\": \"Tasks\", \"rows\": [{ \"Title\": \"New Task\", \"Status\": \"Todo\" }] } }\n\n// Update existing rows\n{ \"tool\": \"update_rows\", \"args\": { \"table\": \"Tasks\", \"rows\": [{ \"row_id\": \"abc123\", \"row\": { \"Status\": \"Done\" } }] } }\n```\n\n### Advanced Querying\n\n```json\n// Find rows with complex filters\n{\n  \"tool\": \"find_rows\",\n  \"args\": {\n    \"table\": \"Tasks\",\n    \"filter\": {\n      \"and\": [\n        { \"Status\": { \"eq\": \"Todo\" } },\n        { \"Priority\": { \"in\": [\"High\", \"Medium\"] } },\n        { \"Title\": { \"contains\": \"urgent\" } }\n      ]\n    },\n    \"limit\": 20\n  }\n}\n\n// Execute raw SQL queries\n{ \"tool\": \"query_sql\", \"args\": { \"sql\": \"SELECT Status, COUNT(*) as count FROM Tasks WHERE Created > ? GROUP BY Status\", \"parameters\": [\"2025-01-01\"] } }\n```\n\n### Schema Management\n\n```json\n// Create new table\n{ \"tool\": \"manage_tables\", \"args\": { \"operation\": \"create\", \"table_name\": \"Projects\" } }\n\n// Get complete schema\n{ \"tool\": \"get_schema\", \"args\": {} }\n\n// Health check\n{ \"tool\": \"ping_seatable\", \"args\": {} }\n```\n\n## 🧪 Testing & Development\n\n### Testing Individual Tools\n\nTest specific MCP tools using the included test script:\n\n```bash\n# Test basic operations\nnode scripts/mcp-call.cjs ping_seatable '{}'\nnode scripts/mcp-call.cjs list_tables '{}'\nnode scripts/mcp-call.cjs list_rows '{\"table\": \"Tasks\", \"page_size\": 5}'\n\n# Test data operations\nnode scripts/mcp-call.cjs add_row '{\"table\": \"Tasks\", \"row\": {\"Title\": \"Test Task\"}}'\nnode scripts/mcp-call.cjs find_rows '{\"table\": \"Tasks\", \"filter\": {\"Status\": {\"eq\": \"Todo\"}}}'\nnode scripts/mcp-call.cjs search_rows '{\"table\": \"Tasks\", \"query\": \"urgent\"}'\n\n# Test schema operations\nnode scripts/mcp-call.cjs get_schema '{}'\nnode scripts/mcp-call.cjs manage_tables '{\"operation\": \"create\", \"table_name\": \"TestTable\"}'\n```\n\n### Cloudflare Worker Testing\n\nComprehensive test suite for Worker deployment:\n\n```bash\n# Run full automated test suite\n./scripts/test-worker.sh\n\n# Interactive testing with step-by-step validation\n./scripts/test-worker.sh --interactive\n\n# Interactive MCP client for live Worker testing\nnode scripts/test-client.mjs\n```\n\n### Development Environment Setup\n\nSet up complete development environment with VS Code configs and MCP Inspector:\n\n```bash\n# Install MCP Inspector, mcp-remote, and create dev configs\n./scripts/setup-test-env.sh\n```\n\n### Available Scripts\n\n- `scripts/mcp-call.cjs` - Test individual MCP tools directly\n- `scripts/test-worker.sh` - Comprehensive Worker testing suite\n- `scripts/test-client.mjs` - Interactive MCP client for live testing\n- `scripts/setup-test-env.sh` - Complete development environment setup\n- `scripts/sync-wrangler-secrets.ts` - Sync environment variables to Worker secrets\n- `scripts/probe-token.ts` - SeaTable API token validation utility\n\n## Troubleshooting\n\n### Connection Issues\n\n- Ensure `.env` values are correct and the API token has access to the base\n- Check network connectivity to `SEATABLE_SERVER_URL`\n- Use `ping_seatable` tool to verify connection and measure latency\n- If token exchange fails (404 on endpoints), set `SEATABLE_TOKEN_ENDPOINT_PATH` to your deployment's path\n\n### Query Issues\n\n- For SQL errors, check the returned error message in the tool response\n- Use parameterized queries (`?` placeholders) to avoid SQL injection\n- Remember that SQL queries have a 10,000 row limit and default to 100 rows\n- Column names in SQL must match exactly (case-sensitive)\n\n### Development\n\n- Use `SEATABLE_MOCK=true` for offline development and testing\n- Check logs for detailed request information including `op`, `method`, `url`, `status`, `request_id`, and `duration_ms`\n- Run individual tool tests with `node scripts/mcp-call.cjs <tool_name> '<args_json>'`\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 18\n- npm\n\n### Setup for Development\n\n1. Clone this repository\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n3. Copy `.env.example` to `.env` and configure your SeaTable settings\n4. Run in development mode:\n   ```bash\n   npm run dev\n   ```\n\n### Development Scripts\n\n- `npm run dev` – Start server in watch mode (tsx)\n- `npm run build` – Compile TypeScript\n- `npm run start` – Run compiled server\n- `npm run test` – Run tests (vitest)\n- `npm run test:watch` – Watch tests\n- `npm run lint` – Lint code\n- `npm run lint:fix` – Lint and fix issues\n- `npm run format` – Check formatting\n- `npm run typecheck` – TypeScript type check\n\n### Running from Source\n\n```bash\n# Development\nnpm run dev\n\n# Production build\nnpm run build\nnpm run start\n\n# Direct execution\nnpx tsx src/index.ts\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}