# Cold Mail Agent MCP

<p align="center">
  <img src="docs/images/mcp-icon.png" alt="Cold Mail Agent MCP envelope icon" width="112" />
</p>

<p align="center">
  <strong>Context-aware cold outreach guidance for any MCP-compatible AI client.</strong>
</p>

<p align="center">
  <a href="#connect">Connect</a> · <a href="#how-it-works">How it works</a> · <a href="#develop">Develop</a> · <a href="docs/protocol.md">Protocol</a>
</p>

Cold Mail Agent MCP gives an AI client a focused cold-outreach playbook: a
writing engine, proven style patterns, channel and follow-up guidance, voice
options, use-case guidance, and a required humanizer pass. It is a public, read-only Cloudflare Worker that
implements the Model Context Protocol (MCP) over Streamable HTTP.

<p align="center">
  <img src="docs/images/mcp-workflow.png" alt="Minimalist diagram showing an AI client calling the Cold Mail Agent MCP endpoint, which loads public writing-playbook reference cards." width="900" />
</p>

## What it does

The server exposes one tool, `cold_email_guidance`. Your MCP client calls it
with the outreach task it is working on. The tool returns the Cold Mail Agent
playbook and its public references so the client can draft, revise, and
humanize a genuinely specific email.

The MCP server does not send email, access inboxes, store contacts, scrape
recipients, or invent personal details. The connected AI client remains
responsible for writing the final response and using any other tools.

| Tool | Input | Returns |
| --- | --- | --- |
| `cold_email_guidance` | `request` string, 1–2,000 characters | The request plus the complete public writing playbook |

## How it works

The examples below are fictional illustrations. They show the difference
between generic cold outreach and an AI client that first loads the MCP's
guidance. They are not claims about a specific model's output.

### Without focused guidance

<p align="center">
  <img src="docs/images/generic-outreach.png" alt="Illustrative minimalist client mockup representing a generic cold email with vague, ungrounded writing." width="760" />
</p>

A generic assistant often starts with vague praise, spends too long on the
sender, and asks for a meeting before earning the recipient's attention.

### With Cold Mail Agent MCP

<p align="center">
  <img src="docs/images/mcp-tool-call.png" alt="Illustrative minimalist developer interface representing a successful call to cold_email_guidance." width="760" />
</p>

The client loads the playbook before it drafts. That guidance emphasizes a true
personalization hook, a compact proof point, a low-friction ask, and a final
humanizer pass.

<p align="center">
  <img src="docs/images/mcp-outreach.png" alt="Illustrative minimalist AI writing interface representing a concise, specific cold outreach draft after MCP guidance." width="760" />
</p>

The resulting email is still the client's work, but it is calibrated against a
clearer system: do the work first, keep the writing simple, and never fake a
fact or personalization.

## Connect

Use this public endpoint in an MCP client that supports Streamable HTTP:

```text
https://cold-mail-agent-mcp.cold-mail-agent.workers.dev/mcp
```

The server does not require authentication. Your client must support MCP over
HTTP and send standard JSON-RPC requests to `/mcp`.

```json
{
  "mcpServers": {
    "cold-mail-agent": {
      "url": "https://cold-mail-agent-mcp.cold-mail-agent.workers.dev/mcp"
    }
  }
}
```

Client configuration formats vary. Use your client's documentation to add a
remote MCP server, then use `cold_email_guidance` before drafting or revising
an email to someone you do not already know.

## Develop

You need Node.js 22 or later and a Cloudflare account for deployment. Install
dependencies, start a local Worker, and connect your client to the local URL.

```sh
npm install
npm run dev
```

The local endpoint is `http://localhost:8788/mcp`.

Run the repository checks and a Worker bundle dry run before opening a pull
request:

```sh
npm run check
```

For deployment steps and production verification, read
[the development guide](docs/development.md).

## Privacy and public content

This repository is public because the deployed Worker reads the approved
playbook files from `content/` at runtime. The public material includes only
writing guidance and examples.

Do not add lead lists, contact data, private notes, API keys, client prompts,
or credentials to this repository. Read the [security policy](SECURITY.md)
before reporting a vulnerability or proposing a data-handling change.

## Documentation

The documentation describes the server contract and operating model:

- [Architecture](docs/architecture.md)
- [MCP protocol contract](docs/protocol.md)
- [Development and deployment](docs/development.md)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)

## License

This project is available under the [MIT License](LICENSE).