diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 097187c..9a86e69 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "corsair", "source": "./plugins/corsair", - "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, search across them and your connected apps, and set up routines.", + "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, query your Postgres databases, hand files to your connected apps, search across all of it, and set up routines.", "category": "productivity", "tags": [ "integrations", diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index d53bf56..89ef1b1 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -11,7 +11,7 @@ { "name": "corsair", "source": "./plugins/corsair", - "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, search across them and your connected apps, and set up routines.", + "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, query your Postgres databases, hand files to your connected apps, search across all of it, and set up routines.", "logo": "https://corsair.dev/corsair-logo.png", "category": "productivity" }, diff --git a/README.md b/README.md index 19fdff8..f3aff3e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Plugins that install [Corsair](https://corsair.dev) into AI clients. One tree se | Plugin | For | Contains | | --- | --- | --- | -| [`corsair`](plugins/corsair) | People working in Corsair's PM and CRM, or their connected apps, from an agent | The Corsair MCP server and six skills for using it | +| [`corsair`](plugins/corsair) | People working in Corsair's PM and CRM, or their connected apps, from an agent | The Corsair MCP server and seven skills for using it | | [`corsair-sdk`](plugins/corsair-sdk) | Developers adding the Corsair SDK to an app | The `corsair` setup skill and the Corsair docs MCP server | ## Install diff --git a/gemini-extension.json b/gemini-extension.json index 64ab98f..66e1390 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,6 +1,6 @@ { "name": "corsair", - "version": "0.1.6", + "version": "0.1.7", "description": "Use your connected apps from your agent: read and act on them, search synced data and set up automations.", "mcpServers": { "corsair": { diff --git a/plugins/corsair/.claude-plugin/plugin.json b/plugins/corsair/.claude-plugin/plugin.json index 53921a8..a6bdb29 100644 --- a/plugins/corsair/.claude-plugin/plugin.json +++ b/plugins/corsair/.claude-plugin/plugin.json @@ -1,9 +1,9 @@ { "name": "corsair", - "version": "0.1.6", + "version": "0.1.7", "displayName": "Corsair", "icon": "./assets/icon.png", - "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, search across them and your connected apps, and set up routines.", + "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, query your Postgres databases, hand files to your connected apps, search across all of it, and set up routines.", "author": { "name": "Corsair", "email": "primary@corsair.dev", diff --git a/plugins/corsair/README.md b/plugins/corsair/README.md index 4f3dae1..cc77d9f 100644 --- a/plugins/corsair/README.md +++ b/plugins/corsair/README.md @@ -1,13 +1,14 @@ # Corsair -Work in [Corsair](https://corsair.dev) from your agent: track issues in Corsair's PM, keep people, companies and deals in its CRM, use the other apps you've connected, search across all of them, and set up automations that run on app events or a schedule. +Work in [Corsair](https://corsair.dev) from your agent: track issues in Corsair's PM, keep people, companies and deals in its CRM, query your Postgres databases, use the other apps you've connected, hand files to them, search across all of them, and set up automations that run on app events or a schedule. -The plugin adds the Corsair MCP server, `https://mcp.corsair.dev/mcp`, and six skills: +The plugin adds the Corsair MCP server, `https://mcp.corsair.dev/mcp`, and seven skills: | Skill | Covers | | --- | --- | -| `corsair-workspace` | Corsair's own PM and CRM: filing and updating issues, and keeping people, companies, deals, notes and tasks | +| `corsair-workspace` | Corsair's own apps: filing and updating issues in its PM, keeping people, companies, deals, notes and tasks in its CRM, querying the user's Postgres databases through pg, and reading Mate chats | | `corsair-connect-apps` | Finding an app, handing over its sign-in link or pointing to the Connect button on Corsair's card, and confirming the connection | +| `corsair-files` | Getting a file into Corsair's Files from a chat, a URL or the user's machine, handing it to an app by its id, and reading, editing and saving files | | `corsair-data` | When to search synced data, read an app live, make a change or wait on a long job; what apps on Corsair's account cost; when to send Corsair feedback | | `corsair-automations` | Building automations from plain English or exact steps, then checking their runs | | `corsair-approvals` | Permission modes, and what to do when an action needs approval | diff --git a/plugins/corsair/plugin.json b/plugins/corsair/plugin.json index 83c0231..ef839de 100644 --- a/plugins/corsair/plugin.json +++ b/plugins/corsair/plugin.json @@ -1,8 +1,8 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "corsair", - "version": "0.1.6", - "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, search across them and your connected apps, and set up routines.", + "version": "0.1.7", + "description": "Work in Corsair from your agent: track issues in its PM, keep contacts and deals in its CRM, query your Postgres databases, hand files to your connected apps, search across all of it, and set up routines.", "author": { "name": "Corsair", "email": "primary@corsair.dev", diff --git a/plugins/corsair/server.json b/plugins/corsair/server.json index 0f0becd..6e055b6 100644 --- a/plugins/corsair/server.json +++ b/plugins/corsair/server.json @@ -3,7 +3,7 @@ "name": "dev.corsair/mcp", "title": "Corsair", "description": "Use your connected apps from your agent: search synced data, act in apps and set up automations.", - "version": "0.1.6", + "version": "0.1.7", "websiteUrl": "https://corsair.dev", "repository": { "url": "https://github.com/corsairdev/agent-plugins", diff --git a/plugins/corsair/skills/corsair-data/SKILL.md b/plugins/corsair/skills/corsair-data/SKILL.md index 7d82fd1..e372fd6 100644 --- a/plugins/corsair/skills/corsair-data/SKILL.md +++ b/plugins/corsair/skills/corsair-data/SKILL.md @@ -9,7 +9,7 @@ Three Corsair tools reach the user's data: | | `search` | `read_data` | `run_script` | | --- | --- | --- | --- | -| Reads | Corsair's own PM and CRM, and data Corsair has already synced from connected apps (Slack messages, Gmail, Calendar and so on) | The app's live API | The app's live API | +| Reads | Corsair's own PM, CRM, routines and files, and data Corsair has synced from connected apps (Slack messages, Gmail, Calendar and so on). When an app's synced copy is behind, it reads that app live itself | The app's live API | The app's live API | | Writes | No | No: the script stops at the first write, before that write runs | Yes: send, create, update, delete | | Best for | Finding things ("what did Sarah say about the refund?") | Current state and exact lists | Any change | @@ -17,26 +17,27 @@ Start with `search` when the user is looking for something. Use `read_data` when ## search -Call it once with the whole question in `query`. Matching is by keyword with stemming, then ranked, not by meaning. So: +Call it once with the whole question in `query`, in the user's words, and pass `timeZone` (the user's IANA zone, such as `Asia/Kolkata`) when you know it, so "today" and "this week" follow their calendar. Search works out who, what and when from the question itself ("what did pranay merge this week", "unread today", "what needs my reply", "issues assigned to me", "ENG-25"), so you don't set filters. A first name or handle finds that person in every app: "pranay" finds PranayHaldiya. -- Put synonyms in `keywords`. For "refund requests": `keywords: ["refund", "chargeback", "money back"]`. -- Put people, emails, channels, repos, projects and companies in `about`, not in `query`. `about: ["Sarah Chen"]` also matches messages she wrote. -- Put time limits in `after` and `before` as ISO timestamps, not in `query`. Work out the dates from today's date first. -- Narrow with `apps` (`["slack", "gmail"]`) and `kinds` (`["messages"]`) when you know where the answer lives. -- For the newest items ("my latest emails"), set `sort: "recent"`. +- Search matches words and can't negate them, so leave "not", "except", "without" and "excluding" out of `query`. For a "not X" question, use `sort: "recent"`, a larger `limit` such as 50 and `after` at the start of the day, then leave out X yourself. +- `keywords` adds synonyms when the records may use another word. For "refund requests": `keywords: ["chargeback", "money back"]`. +- For the newest items ("my latest emails"), set `sort: "recent"`. The default ranks by relevance. -The reply has a sync line: which apps are synced and how recently. +What the reply holds: -- When it covers every app in the question, answer from the results. -- When it doesn't, it names the live call to run for each app it misses. Run those together in one `read_data`. +- Each hit shows its app, date, title, the text that matched and an id of the form `app:kind:id`, such as `github:issues:5125830691`. If you only see the structured result, build it from the hit's `pointer`: `plugin:entityType:entityId`. +- When an app's synced copy was behind, search read that app live and put those rows among the hits. You don't need a separate live read for it. +- `coverage` says how far back search looked in each app and what it couldn't cover, such as records without a date. +- When no record answers the question, the reply says nothing matched (`answerable: false` in `coverage`) and lists a few `near_misses`. Don't present those as the answer: say nothing matched, and mention what came closest only as that. +- An app Corsair can't search comes back named, with a `read_data` snippet that looks in it. Run those snippets together in one `read_data`. -Each result shows its app, date, title, the text that matched and an id of the form `app:kind:id`, such as `github:issues:5125830691`. If you only see the structured result, build it from the hit's `pointer`: `plugin:entityType:entityId`. Often the results are enough to answer. When they aren't, such as to read a whole email, document or meeting notes, call `search` again with the ids: +Often the hits are enough to answer. When they aren't, such as to read a whole email, document or meeting notes, call `search` again with the ids: - Pass up to 20 of them in `ids`. - Long text comes in pages, and the reply says when there is more. With one id, ask for the next one with `page`. - This reads Corsair's synced copy, not the app, so it answers fast. For the current state, use `read_data`. -No match means nothing in the synced copy matched. It doesn't mean the thing doesn't exist. Try other keywords, then a live read with `read_data`. +Nothing matched doesn't mean the thing doesn't exist. If `coverage` shows search didn't look back far enough, read the app with `read_data`. ## read_data and run_script @@ -53,6 +54,7 @@ if (!ships) return 'No #ships channel'; return await corsair.slack.api.messages.post({ channel: ships.id, text: 'Deploy finished' }); ``` +- An app that takes a file gets a Files id (`fil_…`) where it takes a file URL, never the file's bytes or base64. See corsair-files to get the file in first. - Return only what answers the question. Map large responses down to the fields you need; very long results are cut short in the text you get back. - Change something only when the user asked for that change. If they didn't say exactly what gets sent or changed, or the change messages other people, deletes, or touches many records, say what you'll do and wait for a yes. - If `read_data` stops because the script reached a write, don't rerun it with `run_script` unless the user asked for that change. diff --git a/plugins/corsair/skills/corsair-files/SKILL.md b/plugins/corsair/skills/corsair-files/SKILL.md new file mode 100644 index 0000000..30a005b --- /dev/null +++ b/plugins/corsair/skills/corsair-files/SKILL.md @@ -0,0 +1,74 @@ +--- +name: corsair-files +description: Use when the user wants one of their apps to work on a file through Corsair (parse a PDF, read a scan, transcribe audio, attach a document to an email or a record) or attaches a file in chat, points at a file on their machine or a URL, or asks what's in their Corsair Files. Explains getting a file in with upload_file, passing its id to an app in a script, reading and editing text files, and saving an app's output as a file. +--- + +# Files + +Every Corsair link has Files, Corsair's own place for the user's files, up to 25 MB each. A script can't carry a file: its arguments are JSON and it has no network. So a file goes into Files first, and scripts pass its id (`fil_…`). + +Never paste a file's bytes or base64 into a script or a tool argument. + +## Get the file in + +`upload_file` adds a file and returns its id. Pass one of these: + +| You have | Pass | What happens | +| --- | --- | --- | +| A file the user attached in ChatGPT | `file` | Corsair fetches it and saves it | +| A public https address | `url` | Corsair fetches it and saves it | +| A file somewhere you can run shell commands: the user's machine, or your code sandbox | `path` | Nothing is saved yet. The reply gives a `curl` command; run it and it sends the file straight to Files and prints the id. Don't read or paste the file yourself | +| None of these | nothing | The reply gives an upload link that works for 10 minutes. Where the chat shows Corsair's card, the user picks the file there and presses Continue; tell them to use the card rather than repeating the link | + +- In claude.ai, a file the user attached sits in your code sandbox under `/mnt/user-data/uploads/`. Pass that path as `path` and run the command in the sandbox. Corsair keeps the file's own name. For other temporary copies (a hash for a name), pass `name` with the name the user's file had. +- If the network refuses Corsair's address, don't retry and don't call `upload_file` again. The user picks the file from the card or link instead. +- Once that file is saved, tell the user once how to skip the picker next time: in claude.ai, add `auth.corsair.dev` (the host in the upload link) under **Settings > Capabilities > Allowed websites**. After that, the command sends their attachments straight from the chat. If the reply names a different host, give that one. +- `folder` puts the file in a folder, like `contracts/2026`. +- `upload_file` only adds files. It never changes or replaces a file already in Files, and the same file sent twice stays one file with one id. + +## Hand it to an app + +Pass the id wherever the app takes a file URL. Before the call reaches the app, Corsair swaps the id for a short-lived link to the file: + +```js +return await corsair.reducto.api.parse.parse({ input: 'fil_8Kq2xVn4' }); +``` + +`{ file_id: 'fil_…' }` in that place works too. When you need the link itself, for example to give the user a download link, `corsair.files.api.files.url({ file_id })` returns one that works for 15 minutes (`minutes`, up to 60). + +## Read, change and keep files + +| To | Action | +| --- | --- | +| List files and folders | `files.api.files.list`, with `folder` or `query` (part of a name) | +| See one file's name, type and size | `files.api.files.get` | +| Read a text file (text, markdown, CSV, JSON) or a PDF's text | `files.api.files.read_text`: 40,000 characters at a time; read on from `next_offset` until it's null. A scanned PDF has no text to read, so send it to a parser app | +| Save text as a new file, such as a summary or a parsed document | `files.api.files.write_text` with `name` and `text`, up to 1 MB | +| Change part of a text file | `files.api.files.edit_text` with `old_text` (copied from `read_text`, enough to match once) and `new_text` | +| Save an app's output, such as an edited image or a filled-in PDF | `files.api.files.save_from_url` with the `url` the app returned. With `file_id` it becomes that file's new version instead of a new file | +| Rename, move, share, or give search a file's text | `files.api.files.update` | +| Delete | `files.api.files.delete` | + +These run like any other action: reads in `read_data`, changes in `run_script` (see corsair-data). + +- A file is private to the link that added it. `files.api.files.update` with `shared: true` lets everyone in the workspace read it. Only the link that added a file can change, share or delete it. +- A new version, an `edit_text` or a delete replaces what the file said, and the user can't get the old content back. Do it only when the user asked for that file to change. +- To find a file, call `search` with its name or what it says and `apps: ["files"]`, or list with `files.api.files.list` and `query` (part of the name). Search reads a file's text when it has some (text files, and PDFs with a text layer). For a scan, pass the parser's output as `text` to `files.api.files.update`, and search can find it from then on. + +## Example: parse an attached PDF and keep the result + +1. `upload_file` with the attachment (`file` in ChatGPT, `path` in claude.ai). It returns `fil_8Kq2xVn4`. +2. One `run_script`: + +```js +const { result } = await corsair.reducto.api.parse.parse({ input: 'fil_8Kq2xVn4' }); +// A long document comes back as a link to the result rather than the chunks. +if (result.type === 'url') { + return await corsair.files.api.files.save_from_url({ url: result.url, name: 'contract-parsed.json', folder: 'contracts' }); +} +const text = result.chunks.map((c) => c.content).join('\n\n'); +await corsair.files.api.files.update({ file_id: 'fil_8Kq2xVn4', text }); +return await corsair.files.api.files.write_text({ name: 'contract-parsed.md', text, folder: 'contracts' }); +``` + +Check an app's return shape with `get_schema` before mapping it. diff --git a/plugins/corsair/skills/corsair-workspace/SKILL.md b/plugins/corsair/skills/corsair-workspace/SKILL.md index fe2ce5b..a66ccad 100644 --- a/plugins/corsair/skills/corsair-workspace/SKILL.md +++ b/plugins/corsair/skills/corsair-workspace/SKILL.md @@ -1,14 +1,16 @@ --- name: corsair-workspace -description: Use when the user wants to track work or customers in Corsair: file, update or list issues and projects in Corsair's PM, or add and update people, companies, deals, notes and tasks in Corsair's CRM. Gives the action names and the usual lookups for both. +description: Use when the user wants to track work or customers in Corsair (file, update or list issues and projects in Corsair's PM; add and update people, companies, deals, notes and tasks in Corsair's CRM), query or change one of their Postgres databases through Corsair's pg, or find and read a Mate chat. Gives the action names and the usual lookups. --- -# Corsair's PM and CRM +# Corsair's own apps -Every Corsair link comes with two apps of Corsair's own. Their data lives in Corsair, so they work without any other app connected. +Every Corsair link comes with apps of Corsair's own. Their data lives in Corsair, so they work without any other app connected. This skill covers PM, CRM, pg and Mate chats; Files, where the user's files live, has its own skill, corsair-files. - **PM** (`pm`): teams, projects, issues with a status, priority, assignee, labels and a due date, plus comments. - **CRM** (`crm`): people, companies and deals. A deal has a stage (Lead, In Progress, Won, Lost), a value, an owner and linked people and company. Any record can have notes and tasks. +- **pg** (`pg`): the user's own Postgres databases, queried by name. The connection URL stays in Corsair; you never see it. +- **Mate** (`assistant`): the chat assistant built into Corsair. You can find and read its chats. Find what's there with `search` first ("what's open for the Kestrel pilot?" finds the deal, its notes and tasks, and the PM issues that name it). Use `read_data` for complete lists and `run_script` for changes, as the corsair-data skill explains. @@ -54,3 +56,22 @@ return await corsair.pm.api.issues.create({ A record's values come back as lists of dated values; the current one has `active_until: null`. Moving a deal to Won or Lost, or deleting anything, changes the user's records: say what you'll change and do it only when they asked for it. + +## pg + +| To | Action | +| --- | --- | +| See the databases and your access | `pg.api.dbs.list`: each has a `name`, your `access` (owner, write or read) and `read_only` | +| Read | `pg.api.query.sql` with `db` (the name), one statement in `sql`, and `params` for `$1`, `$2`, … It runs in a transaction that is always rolled back. Up to 1,000 rows; `truncated` says when it cut | +| Change data or tables | `pg.api.query.exec` with the same arguments. It commits, and needs write access on a database that isn't `read_only` | +| Add a database | `pg.api.dbs.create` with a lowercase `name`. It returns a `setup_url`: give it to the user exactly as returned, and the workspace owner pastes the connection URL there. Never ask for a connection URL or pass one yourself | +| Remove a database | `pg.api.dbs.remove` (owner only) | + +- Look up the tables before you write SQL: `select table_name, column_name, data_type from information_schema.columns where table_schema = 'public'`. +- Put values in `params`, never into the SQL text. +- Reads go in `read_data` and `query.exec` in `run_script`. `query.exec` changes the user's database, so run it only for a change they asked for. Before an UPDATE or DELETE without a narrow WHERE, a DROP or a migration, show the statement and wait for a yes. +- Each member gets 10 queries per 10 seconds per database. Over a limit, the error says how many seconds to wait. + +## Mate chats + +`assistant.db.chats.search` finds chats (filter on `title`, `shared` or `updatedAt`), and `assistant.api.chats.get` with a chat's `id` returns its messages, oldest first. That includes chats in Shared, where each message also says who wrote it. `assistant.api.chats.rename`, `chats.move` and `chats.delete` change a chat; do that only when the user asks.