# `batch-mcp` — archived, superseded by `batch-cep`

> ⚠️ **This repo is archived.** The active project is now [`batch-cep`](https://github.com/alexandrebouchez/driven-alex-plugins/tree/master/batch-cep) — a Claude skill (Cowork / Claude Code) that wraps Batch.com via direct `fetch()`, without an MCP server in the middle.

## Why the pivot

This repository was a TypeScript MCP server for Batch.com (CEP v2.x + MEP v1.1) — 60 typed tools, 318 Vitest specs, deployable via npm `npx` or HTTP on Vercel. Architecturally solid, but the target audience changed mid-project:

- **Original target** : developers using Claude Code / Claude Desktop with stdio MCP.
- **Real target** (Drivenlabs clients) : **knowledge workers** (CEOs, marketers, growth teams) using **Claude Cowork** in the browser.

Cowork accepts custom Agent Skills (uploadable `.zip` packages with `SKILL.md` + scripts) but the MCP-server route there requires **OAuth 2.1** (hosted server). For a per-customer credentials model — every Batch user has their own REST API key — the OAuth route means becoming a SaaS, which contradicts the small, self-distributed spirit of the project.

The Skill+scripts approach :
- Distributes via [`alexandrebouchez/driven-alex-plugins`](https://github.com/alexandrebouchez/driven-alex-plugins) marketplace (Claude Code) OR `.zip` upload (Cowork).
- Runs scripts locally in the Cowork sandbox — no hosting, no OAuth, no SaaS.
- Stores credentials per-customer in `${PROJECT_FOLDER}/batch-credentials.json` (server-side from the user's POV, never sent anywhere except api.batch.com).
- Same 60 Batch endpoints covered — same surface, just different packaging.

## Where it lives now

- **Plugin** : [driven-alex-plugins/batch-cep](https://github.com/alexandrebouchez/driven-alex-plugins/tree/master/batch-cep)
- **Install Claude Code** :
  ```bash
  claude plugin marketplace add alexandrebouchez/driven-alex-plugins
  claude plugin install batch-cep@driven-alex-plugins
  ```
- **Install Cowork** : zip `batch-cep/skills/batch-cep/` → upload via Settings > Skills

## What stays in this repo

This repo remains accessible (read-only) as a **reference of Batch API surface modeling**:

- 25 CEP tools fully spec'd + tested (Phase 2, merged to `main`, see [PR #1](https://github.com/alexandrebouchez/batch-mcp/pull/1))
- 34 MEP tools fully spec'd + tested (Phase 3, branch `phase3-mep-tools`, see [PR #2](https://github.com/alexandrebouchez/batch-mcp/pull/2) — closed without merge)
- Comprehensive Zod schemas, error mapping (`BatchApiError`), async 202 + indexing_token handling, confirm gates
- 318 Vitest specs covering RED cases, happy paths, edge cases

If you ever want to revive the MCP server angle (e.g., for users of Claude Code who prefer MCP), the code here is a complete reference implementation.

## Original design docs

- [Phase 2 design spec (CEP tools, 973 lines)](docs/superpowers/specs/2026-05-12-phase2-cep-tools-design.md)
- [Phase 3 design spec (MEP tools, 1529 lines)](docs/superpowers/specs/2026-05-12-phase3-mep-tools-design.md)
- [Phase 2 implementation plan](docs/superpowers/plans/2026-05-12-phase2-cep-tools.md)
- [Phase 3 implementation plan](docs/superpowers/plans/2026-05-12-phase3-mep-tools.md)

---

<details>
<summary>Original README (archived)</summary>

## What it did

Let any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, Continue, the Anthropic API, ChatGPT, etc.) operate a Batch.com account: update profiles, manage audiences, send transactional pushes, orchestrate omnichannel campaigns, request data exports, and more — through a curated set of typed tools.

Every Batch endpoint that ships in their public docs was exposed as a tool. Destructive operations required an explicit `confirm: true`. Async 202 operations returned the indexing token so the agent could poll completion explicitly.

## Install (stdio)

```bash
npx -y @alexandrebouchez/batch-mcp
```

Configure your client (Claude Desktop example, `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "batch": {
      "command": "npx",
      "args": ["-y", "@alexandrebouchez/batch-mcp"],
      "env": {
        "BATCH_REST_KEY": "your_rest_key",
        "BATCH_PROJECT_KEY": "your_project_key",
        "BATCH_IOS_LIVE_KEY": "...",
        "BATCH_ANDROID_LIVE_KEY": "..."
      }
    }
  }
}
```

See [`.env.example`](.env.example) for the full env var list.

## Install (HTTP, self-hosted on Vercel)

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdrivenlabs%2Fbatch-mcp&project-name=batch-mcp&env=BATCH_REST_KEY,BATCH_PROJECT_KEY)

Once deployed, point your MCP client at `https://<your-deploy>.vercel.app/api/mcp`.

## Development

```bash
pnpm install
pnpm dev          # starts both packages in watch mode
pnpm test
pnpm typecheck
pnpm lint
```

Monorepo layout:

```
packages/server   — @alexandrebouchez/batch-mcp (npm)
apps/web          — Next.js landing + /api/mcp endpoint (Vercel)
```

## License

AGPL-3.0-only. If you run a modified version of this server as a service, you must publish your source under AGPL-3.0. See [LICENSE](LICENSE).

This is intentional: it lets the community fork and improve the server freely, while preventing closed-source SaaS providers (including Batch.com itself) from absorbing the code without contributing back.

## Disclaimer

This project is **not affiliated with, endorsed by, or sponsored by Batch SAS**. "Batch" is a trademark of its respective owner. This is an independent open-source integration built against the public Batch.com REST API.

</details>