# adpilot-mcp

The MCP (Model Context Protocol) server from AdPilot, a production system where AI agents run marketing operations, ad campaigns, content, outreach and SEO, across a set of projects, with a human in the loop for anything that matters.

This repo is the **agent-facing tool surface**: the MCP server and its tool definitions. The data-access layer it calls (Postgres, and the Google Ads, Meta, GA4 and Search Console integration clients) is part of the private AdPilot app and is not included here. What is published is the part worth reading: how the tools are designed, and how the approval model keeps autonomous agents safe on real accounts.

## Why it exists
Agents are good at drafting a campaign, writing a post, or preparing outreach. They are not something I want spending real ad budget or emailing real people without a check. AdPilot lets agents *propose* actions through these tools, and a tiered approval gate decides what happens next.

## The approval model
Every action-taking tool routes through `queue_approval` with a tier:
- **Tier 1 (auto):** low-risk, runs immediately (for example, pulling a performance report).
- **Tier 2 (approval):** anything with consequences waits for a human sign-off in Discord before it executes (publishing content, sending outreach, changing spend).
- **Tier 3 (blocked):** never allowed from an agent.

An agent can do the whole job end to end, but the blast radius is bounded. Read-only tools return data directly. Write tools return a queued item, not a completed action.

## Tools

**Read:**
- `list_projects` - projects and their integration status
- `get_campaign_summary` - campaigns and spend for a project
- `get_performance` - GA4 sessions and Search Console keywords
- `get_spend_ledger` - spend history for a project
- `get_pending_approvals` / `get_pending_content` / `get_pending_outreach` - the approval queues

**Write (queued behind approval):**
- `queue_approval` - queue an action at a given tier
- `queue_content` - queue a social post across one or more platforms
- `queue_outreach` - queue an outreach message
- `create_blog_post` / `update_blog_post` / `publish_blog_post` - blog workflow
- `upload_asset` - register a generated image, video or audio asset

Plus a project-intelligence tool group.

## How it is wired
Standard MCP: a `Server` over `StdioServerTransport`, a `ListToolsRequest` handler that returns the catalogue above, and a `CallToolRequest` handler that dispatches to the tool implementations in `mcp/tools/`. Built on `@modelcontextprotocol/sdk`.

## Note
This is excerpted from a live private system, for reference. It is not a runnable package on its own, the data and integration layers are omitted deliberately. It is here to show the tool design and the approval model, not to be installed.

## License
MIT