@vinhnguyen/coda-mcp 1.0.0

package/README.md

@@ -0,0 +1,246 @@
+# Coda MCP Server
+
+A Model Context Protocol (MCP) server that connects Claude to [Coda](https://coda.io) — enabling full read/write access to docs, pages, tables, rows, columns, formulas, controls, and automations. Designed to turn Coda into a powerful **knowledge base** for AI assistants.
+
+## Features
+
+- **40 tools** covering the complete Coda API v1
+- Full CRUD for docs, pages, tables, and rows
+- Page content export (HTML/Markdown) with automatic async polling
+- Table search and bulk row retrieval for knowledge base queries
+- Doc structure overview in a single call
+- Formula and control value reading
+- Automation triggering
+- Button pressing on table rows
+- Analytics access
+- Mutation status tracking for async write operations
+
+## Quick Start
+
+### 1. Get a Coda API Token
+
+1. Go to [Coda Account Settings](https://coda.io/account#apiSettings)
+2. Click **Generate API token**
+3. Copy the token
+
+### 2. Install
+
+**Option A: npx (no install)**
+```bash
+npx @vinhnguyen/coda-mcp
+```
+
+**Option B: Global install**
+```bash
+npm install -g @vinhnguyen/coda-mcp
+```
+
+**Option C: From source**
+```bash
+git clone https://github.com/glorynguyen/coda-mcp.git
+cd coda-mcp
+npm install
+npm start
+```
+
+### 3. Configure with Claude
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "coda": {
+      "command": "npx",
+      "args": ["-y", "@vinhnguyen/coda-mcp"],
+      "env": {
+        "CODA_API_TOKEN": "your-api-token-here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `~/.claude.json` or project `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "coda": {
+      "command": "npx",
+      "args": ["-y", "@vinhnguyen/coda-mcp"],
+      "env": {
+        "CODA_API_TOKEN": "your-api-token-here"
+      }
+    }
+  }
+}
+```
+
+Or run from source:
+
+```json
+{
+  "mcpServers": {
+    "coda": {
+      "command": "node",
+      "args": ["/path/to/coda-mcp/index.js"],
+      "env": {
+        "CODA_API_TOKEN": "your-api-token-here"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CODA_API_TOKEN` | Yes | API token from [Coda Account Settings](https://coda.io/account#apiSettings) |
+
+## Tools Reference
+
+### Doc Operations (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_docs` | List accessible docs with optional search filter |
+| `coda_get_doc` | Get doc metadata (name, owner, timestamps, link) |
+| `coda_create_doc` | Create a new doc, optionally from a template |
+| `coda_update_doc` | Update doc title or icon |
+| `coda_delete_doc` | Delete a doc |
+
+### Page Operations (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_pages` | List all pages in a doc with hierarchy |
+| `coda_get_page` | Get page details (name, subtitle, parent/children) |
+| `coda_create_page` | Create a page with optional content (HTML/Markdown) |
+| `coda_update_page` | Update page name, content (replace or append), icon, cover |
+| `coda_delete_page` | Delete a page |
+| `coda_get_page_content` | Export page content as HTML or Markdown |
+
+### Table Operations (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_tables` | List all tables and views in a doc |
+| `coda_get_table` | Get table details (schema, row count, filters) |
+
+### Column Operations (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_columns` | List all columns in a table with types |
+| `coda_get_column` | Get column details |
+
+### Row Operations (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_rows` | List rows with optional filtering and sorting |
+| `coda_get_row` | Get a specific row with all values |
+| `coda_upsert_rows` | Insert or update rows (with upsert key columns) |
+| `coda_update_row` | Update a specific row |
+| `coda_delete_row` | Delete a single row |
+| `coda_delete_rows` | Delete multiple rows by IDs |
+| `coda_push_button` | Trigger a button column on a row |
+
+### Formula & Control Operations (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_formulas` | List named formulas in a doc |
+| `coda_get_formula` | Get a formula and its current value |
+| `coda_list_controls` | List controls (sliders, pickers, etc.) |
+| `coda_get_control` | Get a control and its current value |
+
+### Utility Operations (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_resolve_browser_link` | Resolve a Coda URL to its resource type and ID |
+| `coda_get_mutation_status` | Check status of an async write operation |
+| `coda_whoami` | Get current API token owner info |
+
+### Analytics Operations (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_list_doc_analytics` | Get doc-level analytics (views, copies) |
+| `coda_list_page_analytics` | Get page-level analytics |
+
+### Automation Operations (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `coda_trigger_automation` | Trigger an automation rule by ID |
+
+### Knowledge Base Helpers (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coda_search_docs` | Search docs by name |
+| `coda_get_doc_structure` | Get full doc overview: pages + tables in one call |
+| `coda_search_table` | Search rows in a table by query |
+| `coda_get_page_with_content` | Get page metadata + exported content in one call |
+| `coda_list_all_rows` | Bulk retrieve all rows with automatic pagination |
+
+## Knowledge Base Usage
+
+This MCP server is specifically designed to make Coda work as a knowledge base for AI. Here are common patterns:
+
+### Discover available knowledge
+```
+"What Coda docs do I have access to?"
+→ coda_list_docs
+
+"Show me the structure of my wiki doc"
+→ coda_get_doc_structure
+```
+
+### Read knowledge base content
+```
+"Read the Getting Started page from my doc"
+→ coda_get_page_with_content (returns Markdown)
+
+"Show me all entries in the FAQ table"
+→ coda_list_all_rows
+```
+
+### Search for information
+```
+"Find docs about onboarding"
+→ coda_search_docs
+
+"Search the knowledge base table for authentication"
+→ coda_search_table
+```
+
+### Write to knowledge base
+```
+"Add a new article to the wiki"
+→ coda_create_page (with Markdown content)
+
+"Add a new entry to the FAQ table"
+→ coda_upsert_rows
+```
+
+## Rate Limits
+
+The Coda API enforces rate limits:
+- **Read operations**: 100 requests per 6 seconds
+- **Write operations**: 10 requests per 6 seconds
+- **Doc content writes**: 5 requests per 10 seconds
+
+The server returns errors for 429 responses. Implement retry logic in your usage patterns if needed.
+
+## License
+
+MIT