Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion .cursor-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion gemini-extension.json
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
4 changes: 2 additions & 2 deletions plugins/corsair/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
7 changes: 4 additions & 3 deletions plugins/corsair/README.md
Original file line number Diff line number Diff line change
@@ -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 |
Expand Down
4 changes: 2 additions & 2 deletions plugins/corsair/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion plugins/corsair/server.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
26 changes: 14 additions & 12 deletions plugins/corsair/skills/corsair-data/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,34 +9,35 @@ 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 |

Start with `search` when the user is looking for something. Use `read_data` when they need the current state or a complete list (every open issue, today's events). Use `run_script` only to change something. If this connection has neither `read_data` nor `run_script`, it can't reach apps live: answer from `search` and say so.

## 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

Expand All @@ -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.
Expand Down
74 changes: 74 additions & 0 deletions plugins/corsair/skills/corsair-files/SKILL.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading