# sendpilot-actions

Secure local MCP server for SendPilot Lead Database searches and workspace read operations.

`sendpilot-actions` uses stdio and runs on your Mac. It keeps the SendPilot API key outside the repository and never writes it to Codex configuration or MCP output.

## Scope

The server exposes exactly five tools:

| Tool | Purpose |
| --- | --- |
| `create_lead_database_search` | Create a Lead Database search after explicit user confirmation and native macOS approval. |
| `get_search_status` | Read search status and progress. |
| `get_search_results` | Read paginated results for an existing search. |
| `get_credits` | Read the workspace credit balance. |
| `list_campaigns` | Read campaigns. |

It does **not** send messages, send connection requests, create or modify campaigns, or add leads to campaigns.

Creating a search may consume credits. The tool requires `confirmed: true` and then presents a local macOS approval dialog with a bounded request summary and fingerprint. Declining or timing out prevents the API request.

## Requirements

- Node.js 22 or newer
- macOS for the native approval dialog used by the create-search tool
- A SendPilot API key with access to the endpoints you intend to use

## Install

```bash
git clone https://github.com/MarcoAIEH/sendpilot-actions.git
cd sendpilot-actions
npm ci
npm run build
```

## Credentials

The default local credential file is `~/.config/sendpilot-actions/.env`:

```bash
mkdir -p ~/.config/sendpilot-actions
chmod 700 ~/.config/sendpilot-actions
cp .env.example ~/.config/sendpilot-actions/.env
chmod 600 ~/.config/sendpilot-actions/.env
```

Set `SENDPILOT_API_KEY` in that file. Do not commit it. The loader rejects a non-private directory or file and rejects symlinks. A runtime `SENDPILOT_API_KEY` takes precedence, enabling a secret manager to inject the value without storing it in the repository.

## Codex configuration

After building, register the stdio server without putting a secret in the configuration:

```bash
codex mcp remove sendpilot-actions
codex mcp add sendpilot-actions -- node "$(pwd)/dist/index.js"
```

Restart Codex or open a new task to load the tools.

## Verification

```bash
npm test
npm run typecheck
npm run build
npm run smoke:readonly
```

`smoke:readonly` calls only `GET /v1/credits` and `GET /v1/campaigns?status=all&page=1&limit=1`. It does not create searches or modify any SendPilot resource.

## Security notes

- API keys are read at runtime only; they are never logged or returned through MCP.
- Upstream error text is redacted before it reaches the MCP client.
- All input is validated and bounded before a local approval dialog can be shown.
- This repository is GitHub-only: `private: true` prevents accidental npm publication.

## License

[MIT](LICENSE)