api

Files (6)

• SKILL.md
• auth.md · references/
• openapi.md · references/
• product.md · references/
• sumcli.md · references/
• sum_api.py · scripts/

SKILL.md (first lines)

# Summation

When a shell is available, day-to-day data work goes through **sumcli** (full sum-api contract — see `references/sumcli.md`). Shell-less hosts (Claude Desktop, sandboxes) use the hosted **`summation` MCP server** (curated subset) and domain skills. Browser sign-in owns MCP auth; `sumcli auth login` owns the CLI session. Do **not** invent REST for normal work.

**Default MCP (fallback):** `https://mcp.summation.com/mcp`

## Before you answer “what’s supported?”

1. **Fetch `https://docs.summation.com/llms.txt`** (live product map — do not rely on a baked-in list).  
2. Open the linked doc for that feature or connector.  
3. See **`references/product.md`** for how to use the index and plugin skill routing.  
4. Never invent “unsupported” from a failed fetch, wrong URL, homepage marketing, or truncated OpenAPI.

## Core workflow

1. Pick the surface: shell available → **sumcli**; shell-less → MCP.  
2. Auth: CLI → `sumcli auth whoami` (401 → `sumcli auth login`); MCP → **`whoami`** (if needed → **signin** skill).  
3. Prefer a domain skill: `start`, `opportunities`, `report`, `validate`, `query`, `catalog`, `schedule`, `connect`, `diagnose`.  
4. Else: sumcli commands (discover live: `sumcli | jq '.result.resources'`) or MCP tools (below). Speak in outcomes to the user.  
5. Auth errors → `sumcli auth login` / signin; never ask for tokens in chat.

## MCP tools (curated — shell-less fallback)

Identity / projects: `whoami`, `get_org`, `list_projects`, `get_default_project`, `get_project`, `create_project`

Analyst: `ask_analyst`, `reply_to_analyst`, `list_conversations`, `get_conversation`, `list_chat_models`

Sources: `list_data_connections`, `list_connection_datasets`, `browse_connection_resources`, `attach_connection_datasets`, `test_data_connection`, `snapshot_dataset`, `list_snapshot_runs`, `list_app_connections`, `browse_app_catalog`

Tables / views / query: `search_tables`, `get_table_schema`, `preview_table_data`, `get_table_lineage`, `create_calc_table`, `materialize_table`, `sync_table`, `append_table_rows`, `search_views`, `get_view`, `preview_view_data`, `run_query`

Files: `list_files`, `download_file`, `upload_file`, `request_file_upload`, `finalize_file_upload`, `import_file_to_table`

Catalog / reports / playbooks / schedules: `list_catalog_entries`, `attach_catalog_entry`, `start_report`, `list_reports`, `get_report_status`, `export_report`, `validate_report`, `list_playbooks`, `get_playbook`, `list_schedules`, `get_schedule`, `list_schedule_runs`, `create_schedule` — plus any create/update/detach tools the live server exposes (use them when present).

Prefer the **live server’s tool list** over this doc if names differ.

## Client behaviors (required)

- **Long tools** (`ask_analyst`, `start_report`, `validate_report`, `import_file_to_table`): tell the user you’re working; **reports can take a few minutes** — brief progress every ~30–45s until status is terminal.  
- **Auth errors** → CLI: `sumcli auth login`; MCP: signin.  
- **Views** may 404 on ids from search — fall back to tables.  
- **Schedules** that email people — confirm recipients + cadence (with timezone) first.  
- **Secrets:** never in tool args or chat; **connect** skill + web app for passwords.  
- **Attach datasets:** always set human-readable **`name`** (table name). Never leave auto `*_dataset_N` names.  
- **Success:** verify with list/test/export before telling the user it’s done.  
- **User chat:** product language only — no OpenAPI dumps, path lists, or key-guessing experiments.

## Auth summary

See `signin` / `signout` and `references/auth.md`. Headerless plugin MCP; host OAuth. Do not re-register with an Authorization header.

## Safety

- Confirm email schedules and destructive actions.  
- Prefer list before mutate.  
- Preserve org/project from `whoami` / project tools.  
- On hard failures, you may mention a `request_id` if present (for support) — still explain in plain language.

## sumcli

When a shell is available, **sumcli is the preferred surface**; MCP is the fallback for shell-less hosts (Claude Desktop, sandboxes) and anywhere the CLI cannot run. The CLI exposes the full sum-api contract; the hosted MCP is a curated subset — all deletes, connection management, schedule and catalog updates, and ingestion batches are CLI-only. Needs **sumcli ≥ 0.1.3** (see `references/sumcli.md`). Newer CLIs are always compatible — `sumcli update` to PyPI latest.

**Install on first need.** If `sumcli` is missing or too old when a CLI call is due, ask the user and **wait for a yes** before running the bootstrap — the same consent bar as `SUMCLI_AUTO_INSTALL`. On no, fall back to MCP for that request. SessionStart only nudges; it never installs. First CLI use also needs `sumcli auth login` (browser device-code) — MCP's host OAuth and the CLI session are separate credentials.

Two import routes: `import_file_to_table` is the agent-workflow route, gated on some tenants (409 `feature_not_enabled`); the **direct pipeline** is ungated and available on both surfaces — `sumcli tables import` (CLI) or `create_asset_upload_url` → `preview_import_asset` → `create_table_import` (MCP). On a 409, switch to the direct pipeline on whichever surface you are already using. A 403 with tool-profile text is a Connected Apps problem — not recoverable by switching surface; tell the user.

## Legacy helper

`scripts/sum_api.py` is **not** for normal customer flows. Prefer sumcli / MCP + domain skills (`signin`, `diagnose`, …).

If you must run the helper (internal/debug only), **never** use relative `../api/scripts/sum_api.py` — hosts often mount skills as `summation:api` / `summation:doctor`, so `../api` resolves outside the plugin and fails. Use the plugin root:

```bash
python3 "${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}/skills/api/scripts/sum_api.py" doctor
```

If both `PLUGIN_ROOT` and `CLAUDE_PLUGIN_ROOT` are unset, resolve from the installed package path the host shows for this skill — still under `…/skills/api/scripts/sum_api.py`, not `…/plugins/api/…`.

From summationai/summation-plugin, MIT.

More from summationai/summation-plugin