mcp-coda 0.1.0__tar.gz

mcp_coda-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# Required: Coda API token (https://coda.io/account#apiSettings)
+CODA_API_TOKEN=
+
+# Optional: Disable all write operations
+# CODA_READ_ONLY=false
+
+# Optional: Custom API base URL
+# CODA_BASE_URL=https://coda.io/apis/v1
+
+# Optional: HTTP timeout in seconds
+# CODA_TIMEOUT=30
+
+# Optional: SSL certificate verification
+# CODA_SSL_VERIFY=true

mcp_coda-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,28 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff check
+        run: uv run ruff check src/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/

mcp_coda-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-coda
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_coda-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.2.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Update version
+        run: |
+          sed -i "s/^version = .*/version = \"${{ inputs.version }}\"/" pyproject.toml
+
+      - name: Commit and tag
+        run: |
+          git add pyproject.toml
+          git commit -m "chore: release v${{ inputs.version }}"
+          git tag "v${{ inputs.version }}"
+          git push origin main --tags

mcp_coda-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --cov=mcp_coda --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml

mcp_coda-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+.env.local
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+coverage.xml
+.coverage
+*.so
+.DS_Store

mcp_coda-0.1.0/AGENTS.md

@@ -0,0 +1,54 @@
+# mcp-coda — Agent Context
+
+## What This Is
+
+MCP server for the Coda v1 API. 55 tools covering docs, pages, tables, rows, formulas, controls, permissions, folders, publishing, automations, and analytics.
+
+## Architecture
+
+- **Framework**: FastMCP >= 2.13.0
+- **HTTP client**: httpx AsyncClient
+- **Auth**: Bearer token via `CODA_API_TOKEN` env var
+- **Build**: hatchling with `src/` layout
+- **Structure**: Modular tool files in `src/mcp_coda/servers/` (one per domain)
+
+### RBAC Model
+
+1. **Server-level**: `CODA_READ_ONLY=true` blocks all write tools
+2. **MCP annotations**: `readOnlyHint`, `destructiveHint`, `idempotentHint` per tool
+3. **Coda token scope**: API token permissions enforce doc-level access
+
+### Key Patterns
+
+- Tools never raise — all errors return `_err(e)` as JSON string
+- Every tool returns `str` (JSON via `_ok`/`_err`)
+- Write tools call `_check_write(ctx)` first
+- List responses include `{items, has_more, next_cursor, total_count}`
+- Rate limit errors include `retry_after` seconds
+- Async mutations return `requestId` for polling via `coda_get_mutation_status`
+
+## Development
+
+```bash
+uv sync                                    # install deps
+uv run pytest tests/ -v --cov=mcp_coda    # run tests
+uv run ruff check src/ tests/              # lint
+uv run ruff format --check src/ tests/     # format check
+```
+
+## Tool Inventory (55 tools)
+
+| Module | Tools | Type |
+|--------|-------|------|
+| account | 3 | read |
+| docs | 5 | read/write |
+| pages | 8 | read/write |
+| tables | 4 | read |
+| rows | 7 | read/write |
+| formulas | 2 | read |
+| controls | 2 | read |
+| permissions | 6 | read/write |
+| publishing | 3 | read/write |
+| folders | 5 | read/write |
+| automations | 1 | write |
+| analytics | 7 | read |

mcp_coda-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial release.
+
+### Tools (55)
+
+- **Account** (3): whoami, resolve_browser_link, get_mutation_status
+- **Docs** (5): list, get, create, update, delete
+- **Pages** (8): list, get, create, update, delete, get_content, delete_content, export
+- **Tables** (4): list_tables, get_table, list_columns, get_column
+- **Rows** (7): list, get, insert (with upsert), update, delete, bulk_delete, push_button
+- **Formulas** (2): list, get
+- **Controls** (2): list, get
+- **Permissions** (6): get_sharing_metadata, list, add, delete, search_principals, get_acl_settings
+- **Publishing** (3): list_categories, publish, unpublish
+- **Folders** (5): list, get, create, update, delete
+- **Automations** (1): trigger
+- **Analytics** (7): doc_analytics, doc_summary, page_analytics, pack_analytics, pack_summary, pack_formula_analytics, analytics_updated
+
+### Features
+
+- 3-layer RBAC: server read-only toggle, MCP annotations, Coda token scope
+- Rate limit error surfacing with `retry_after` seconds
+- Async mutation tracking via `coda_get_mutation_status`
+- Curated JSON responses with pagination envelope
+- stdio, SSE, and streamable-http transports

mcp_coda-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: mcp-coda
+Version: 0.1.0
+Summary: MCP server for Coda API — docs, pages, tables, rows, formulas, permissions, and more
+Project-URL: Homepage, https://github.com/vish288/mcp-coda
+Project-URL: Repository, https://github.com/vish288/mcp-coda
+Project-URL: Issues, https://github.com/vish288/mcp-coda/issues
+Author: vish288
+License: MIT
+Keywords: ai,automation,coda,coda-api,llm,mcp,mcp-server,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.7
+Requires-Dist: fastmcp>=2.13.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic<3.0,>=2.10.0
+Requires-Dist: python-dotenv>=1.0.1
+Description-Content-Type: text/markdown
+
+# mcp-coda
+
+MCP server for the [Coda API](https://coda.io/developers/apis/v1) — docs, pages, tables, rows, formulas, controls, permissions, folders, publishing, automations, and analytics.
+
+## Features
+
+- 55 tools covering the full Coda v1 API
+- Read-only mode via `CODA_READ_ONLY=true`
+- MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint)
+- Rate limit error surfacing with `retry_after` seconds
+- Async mutation tracking via `coda_get_mutation_status`
+- stdio, SSE, and streamable-http transports
+
+## Installation
+
+```bash
+# Via uvx (recommended)
+uvx mcp-coda
+
+# Via pip
+pip install mcp-coda
+```
+
+## Configuration
+
+Set the `CODA_API_TOKEN` environment variable with your [Coda API token](https://coda.io/account#apiSettings).
+
+```bash
+export CODA_API_TOKEN=your-token-here
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CODA_API_TOKEN` | Yes | — | Coda API token |
+| `CODA_READ_ONLY` | No | `false` | Disable all write operations |
+| `CODA_BASE_URL` | No | `https://coda.io/apis/v1` | API base URL |
+| `CODA_TIMEOUT` | No | `30` | HTTP timeout in seconds |
+| `CODA_SSL_VERIFY` | No | `true` | Verify SSL certificates |
+
+## Usage
+
+### Claude Code / Cursor
+
+Add to your MCP config (`.mcp.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "coda": {
+      "command": "uvx",
+      "args": ["mcp-coda"],
+      "env": {
+        "CODA_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### CLI
+
+```bash
+# stdio (default)
+mcp-coda
+
+# SSE transport
+mcp-coda --transport sse --port 8000
+
+# Read-only mode
+mcp-coda --read-only
+```
+
+## Tools
+
+### Account (3)
+- `coda_whoami` — Get current user info
+- `coda_resolve_browser_link` — Convert browser URL to API IDs
+- `coda_get_mutation_status` — Check async write status
+
+### Docs (5)
+- `coda_list_docs` — List accessible docs
+- `coda_get_doc` — Get doc metadata
+- `coda_create_doc` — Create a new doc
+- `coda_update_doc` — Update doc title/icon
+- `coda_delete_doc` — Delete a doc
+
+### Pages (8)
+- `coda_list_pages` — List pages in a doc
+- `coda_get_page` — Get page metadata
+- `coda_create_page` — Create a page
+- `coda_update_page` — Update page name/content
+- `coda_delete_page` — Delete a page
+- `coda_get_page_content` — Read page content
+- `coda_delete_page_content` — Clear page content
+- `coda_export_page` — Export page content
+
+### Tables (4)
+- `coda_list_tables` — List tables/views
+- `coda_get_table` — Get table metadata
+- `coda_list_columns` — List columns
+- `coda_get_column` — Get column metadata
+
+### Rows (7)
+- `coda_list_rows` — List/filter rows
+- `coda_get_row` — Get a single row
+- `coda_insert_rows` — Insert/upsert rows
+- `coda_update_row` — Update a row
+- `coda_delete_row` — Delete a row
+- `coda_delete_rows` — Bulk delete rows
+- `coda_push_button` — Push a button
+
+### Formulas (2)
+- `coda_list_formulas` — List named formulas
+- `coda_get_formula` — Get formula value
+
+### Controls (2)
+- `coda_list_controls` — List controls
+- `coda_get_control` — Get control value
+
+### Permissions (6)
+- `coda_get_sharing_metadata` — Get sharing config
+- `coda_list_permissions` — List ACL entries
+- `coda_add_permission` — Grant access
+- `coda_delete_permission` — Revoke access
+- `coda_search_principals` — Search users/groups
+- `coda_get_acl_settings` — Get ACL settings
+
+### Publishing (3)
+- `coda_list_categories` — List publishing categories
+- `coda_publish_doc` — Publish a doc
+- `coda_unpublish_doc` — Unpublish a doc
+
+### Folders (5)
+- `coda_list_folders` — List folders
+- `coda_get_folder` — Get folder details
+- `coda_create_folder` — Create a folder
+- `coda_update_folder` — Rename a folder
+- `coda_delete_folder` — Delete a folder
+
+### Automations (1)
+- `coda_trigger_automation` — Trigger an automation rule
+
+### Analytics (7)
+- `coda_list_doc_analytics` — Doc usage metrics
+- `coda_get_doc_analytics_summary` — Aggregated doc metrics
+- `coda_list_page_analytics` — Page usage metrics
+- `coda_list_pack_analytics` — Pack usage metrics
+- `coda_get_pack_analytics_summary` — Aggregated pack metrics
+- `coda_list_pack_formula_analytics` — Formula-level metrics
+- `coda_get_analytics_updated` — Analytics freshness timestamp
+
+## RBAC Model
+
+Three layers of access control:
+
+1. **Server-level**: `CODA_READ_ONLY=true` blocks all write tools
+2. **MCP annotations**: Each tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` for client-side permission prompts
+3. **Coda token scope**: The API token's permissions enforce doc-level access
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+pytest tests/ -v --cov=mcp_coda
+
+# Lint
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Type check
+mypy src/
+```
+
+## License
+
+MIT

mcp_coda-0.1.0/README.md

@@ -0,0 +1,181 @@
+# mcp-coda
+
+MCP server for the [Coda API](https://coda.io/developers/apis/v1) — docs, pages, tables, rows, formulas, controls, permissions, folders, publishing, automations, and analytics.
+
+## Features
+
+- 55 tools covering the full Coda v1 API
+- Read-only mode via `CODA_READ_ONLY=true`
+- MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint)
+- Rate limit error surfacing with `retry_after` seconds
+- Async mutation tracking via `coda_get_mutation_status`
+- stdio, SSE, and streamable-http transports
+
+## Installation
+
+```bash
+# Via uvx (recommended)
+uvx mcp-coda
+
+# Via pip
+pip install mcp-coda
+```
+
+## Configuration
+
+Set the `CODA_API_TOKEN` environment variable with your [Coda API token](https://coda.io/account#apiSettings).
+
+```bash
+export CODA_API_TOKEN=your-token-here
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CODA_API_TOKEN` | Yes | — | Coda API token |
+| `CODA_READ_ONLY` | No | `false` | Disable all write operations |
+| `CODA_BASE_URL` | No | `https://coda.io/apis/v1` | API base URL |
+| `CODA_TIMEOUT` | No | `30` | HTTP timeout in seconds |
+| `CODA_SSL_VERIFY` | No | `true` | Verify SSL certificates |
+
+## Usage
+
+### Claude Code / Cursor
+
+Add to your MCP config (`.mcp.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "coda": {
+      "command": "uvx",
+      "args": ["mcp-coda"],
+      "env": {
+        "CODA_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### CLI
+
+```bash
+# stdio (default)
+mcp-coda
+
+# SSE transport
+mcp-coda --transport sse --port 8000
+
+# Read-only mode
+mcp-coda --read-only
+```
+
+## Tools
+
+### Account (3)
+- `coda_whoami` — Get current user info
+- `coda_resolve_browser_link` — Convert browser URL to API IDs
+- `coda_get_mutation_status` — Check async write status
+
+### Docs (5)
+- `coda_list_docs` — List accessible docs
+- `coda_get_doc` — Get doc metadata
+- `coda_create_doc` — Create a new doc
+- `coda_update_doc` — Update doc title/icon
+- `coda_delete_doc` — Delete a doc
+
+### Pages (8)
+- `coda_list_pages` — List pages in a doc
+- `coda_get_page` — Get page metadata
+- `coda_create_page` — Create a page
+- `coda_update_page` — Update page name/content
+- `coda_delete_page` — Delete a page
+- `coda_get_page_content` — Read page content
+- `coda_delete_page_content` — Clear page content
+- `coda_export_page` — Export page content
+
+### Tables (4)
+- `coda_list_tables` — List tables/views
+- `coda_get_table` — Get table metadata
+- `coda_list_columns` — List columns
+- `coda_get_column` — Get column metadata
+
+### Rows (7)
+- `coda_list_rows` — List/filter rows
+- `coda_get_row` — Get a single row
+- `coda_insert_rows` — Insert/upsert rows
+- `coda_update_row` — Update a row
+- `coda_delete_row` — Delete a row
+- `coda_delete_rows` — Bulk delete rows
+- `coda_push_button` — Push a button
+
+### Formulas (2)
+- `coda_list_formulas` — List named formulas
+- `coda_get_formula` — Get formula value
+
+### Controls (2)
+- `coda_list_controls` — List controls
+- `coda_get_control` — Get control value
+
+### Permissions (6)
+- `coda_get_sharing_metadata` — Get sharing config
+- `coda_list_permissions` — List ACL entries
+- `coda_add_permission` — Grant access
+- `coda_delete_permission` — Revoke access
+- `coda_search_principals` — Search users/groups
+- `coda_get_acl_settings` — Get ACL settings
+
+### Publishing (3)
+- `coda_list_categories` — List publishing categories
+- `coda_publish_doc` — Publish a doc
+- `coda_unpublish_doc` — Unpublish a doc
+
+### Folders (5)
+- `coda_list_folders` — List folders
+- `coda_get_folder` — Get folder details
+- `coda_create_folder` — Create a folder
+- `coda_update_folder` — Rename a folder
+- `coda_delete_folder` — Delete a folder
+
+### Automations (1)
+- `coda_trigger_automation` — Trigger an automation rule
+
+### Analytics (7)
+- `coda_list_doc_analytics` — Doc usage metrics
+- `coda_get_doc_analytics_summary` — Aggregated doc metrics
+- `coda_list_page_analytics` — Page usage metrics
+- `coda_list_pack_analytics` — Pack usage metrics
+- `coda_get_pack_analytics_summary` — Aggregated pack metrics
+- `coda_list_pack_formula_analytics` — Formula-level metrics
+- `coda_get_analytics_updated` — Analytics freshness timestamp
+
+## RBAC Model
+
+Three layers of access control:
+
+1. **Server-level**: `CODA_READ_ONLY=true` blocks all write tools
+2. **MCP annotations**: Each tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` for client-side permission prompts
+3. **Coda token scope**: The API token's permissions enforce doc-level access
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+pytest tests/ -v --cov=mcp_coda
+
+# Lint
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Type check
+mypy src/
+```
+
+## License
+
+MIT