# Ad Review Log MCP

A local MCP (Model Context Protocol) server that acts as a persistent log of ad creative reviews. It stores each review's ad name, funnel stage, score, media link, and full review text so agents can look back at how past creatives were scored.

Works with **Cursor IDE**, **OpenAI Codex CLI**, **Claude Desktop**, and any MCP-compatible client.

## How It Works

```
┌─────────────┐                        ┌──────────────────────┐
│  Cursor IDE  │── stdio ──────────────►│                      │
├─────────────┤                        │  ad-review-log       │
│  Codex CLI   │── stdio ──────────────►│                      │
├─────────────┤                        │  SQLite + FTS5       │
│  Claude      │── stdio ──────────────►│  ~/.ad-review-log/   │
└─────────────┘                        └──────────────────────┘
```

Each agent spawns its own process instance. All instances read/write the same SQLite database at `~/.ad-review-log/reviews.db`. SQLite WAL mode ensures safe concurrent access.

## Requirements

- Node.js 18+
- macOS, Linux, or Windows

## Installation

```bash
git clone https://github.com/YOUR_USERNAME/ad-review-log.git
cd ad-review-log
npm install
npm run build
```

## Agent Integration

### Cursor IDE

Add to `~/.cursor/mcp.json` (inside the `mcpServers` object):

```json
{
  "mcpServers": {
    "ad-review-log": {
      "command": "node",
      "args": ["/absolute/path/to/ad-review-log/dist/index.js"]
    }
  }
}
```

Optionally, install the Cursor skill for better agent behavior:

```bash
cp -r integration/cursor-skill ~/.cursor/skills/ad-review-log
```

And add the rule to your projects:

```bash
cp integration/cursor-rule.md your-project/.cursor/rules/ad-review-log.md
```

### OpenAI Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.ad-review-log]
command = "node"
args = ["/absolute/path/to/ad-review-log/dist/index.js"]
```

Then append the review instructions to your Codex instructions file:

```bash
cat integration/codex-instructions.md >> ~/.codex/instructions.md
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ad-review-log": {
      "command": "node",
      "args": ["/absolute/path/to/ad-review-log/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop after editing the config.

### Any MCP-Compatible Client

Any tool supporting MCP stdio transport can use this server by spawning:

```bash
node /path/to/ad-review-log/dist/index.js
```

The server communicates via JSON-RPC over stdin/stdout following the MCP specification.

## Tools

### store_review

Store an ad creative review.

| Parameter    | Required | Description                                                                          |
| ------------ | -------- | ------------------------------------------------------------------------------------ |
| ad_name      | Yes      | Name or identifier of the ad creative                                                |
| funnel_stage | Yes      | `Awareness`, `Consideration`, `Conversion`, `Onboarding`, `Retention`, or `Advocacy` |
| score        | Yes      | Overall review score, 0-100                                                          |
| full_review  | Yes      | The full review text / teardown                                                      |
| media_link   | No       | Link to the ad media (video, image, carousel, Drive URL)                             |
| timestamp    | No       | Review timestamp (defaults to now)                                                   |

### search_reviews

Full-text search across all reviews.

| Parameter    | Required | Description                                        |
| ------------ | -------- | -------------------------------------------------- |
| query        | Yes      | Free-text search (ad name, keyword, review phrase) |
| funnel_stage | No       | Filter by funnel stage                             |
| ad_name      | No       | Filter by ad name (substring match)                |
| min_score    | No       | Only reviews with score >= this value              |
| max_score    | No       | Only reviews with score <= this value              |
| limit        | No       | Max results (default 10)                           |

### get_context

Smart retrieval for the current review. Returns top-scoring reviews for the given funnel stages plus FTS matches against the task description.

| Parameter        | Required | Description                                            |
| ---------------- | -------- | ------------------------------------------------------ |
| funnel_stages    | Yes      | Array of funnel stages: `["Conversion", "Awareness"]`  |
| task_description | No       | What you are about to review (used for semantic match) |
| ad_name          | No       | Ad name to look for related prior reviews              |

### list_reviews

Browse entries with optional filters.

| Parameter    | Required | Description                           |
| ------------ | -------- | ------------------------------------- |
| funnel_stage | No       | Filter by funnel stage                |
| ad_name      | No       | Filter by ad name (substring match)   |
| min_score    | No       | Only reviews with score >= this value |
| max_score    | No       | Only reviews with score <= this value |
| limit        | No       | Max results (default 20)              |
| offset       | No       | Pagination offset                     |

### update_review

Update an existing review.

| Parameter   | Required | Description                                 |
| ----------- | -------- | ------------------------------------------- |
| id          | Yes      | The review ID to update                     |
| (any field) | No       | Any field from store_review can be updated  |

### delete_review

Remove an obsolete review.

| Parameter | Required | Description             |
| --------- | -------- | ----------------------- |
| id        | Yes      | The review ID to delete |

## Database

Data is stored at `~/.ad-review-log/reviews.db` (SQLite with FTS5).

The `reviews` table schema:

```
id | timestamp | ad_name | funnel_stage | score | media_link | full_review
```

### Storage Setup

After building, run the interactive setup to choose where data lives:

```bash
npm run setup
```

You will be prompted to choose:

- **Google Drive** (macOS only) — symlinks `~/.ad-review-log/` to your Google Drive folder. Data syncs automatically across machines.
- **Local** — stores data at `~/.ad-review-log/` on disk (default).

You can re-run `npm run setup` at any time to switch between the two.

#### New machine setup

If you previously chose Google Drive:

1. Install Google Drive Desktop and sign in with the same account
2. Clone this repo, `npm install && npm run build`
3. Run `npm run setup` and select Google Drive — it will find your existing data

If Google Drive becomes unavailable (e.g. app not installed), the server automatically falls back to local storage instead of crashing.

### Manual Inspection

```bash
sqlite3 ~/.ad-review-log/reviews.db

-- List recent reviews
SELECT id, ad_name, funnel_stage, score FROM reviews ORDER BY timestamp DESC LIMIT 10;

-- Search by keyword
SELECT * FROM reviews WHERE id IN (
  SELECT rowid FROM reviews_fts WHERE reviews_fts MATCH 'basket'
);

-- Average score by funnel stage
SELECT funnel_stage, ROUND(AVG(score), 1) FROM reviews GROUP BY funnel_stage;
```

### Backup

The database is a single file. Back it up however you prefer:

```bash
cp ~/.ad-review-log/reviews.db ~/.ad-review-log/reviews.db.bak
```

Or add `~/.ad-review-log/` to your backup tool (Time Machine, rsync, etc.).

## Development

```bash
npm run dev          # Run with tsx (hot reload)
npm run build        # Build with tsup
npm run typecheck    # Type-check without emitting
npm start            # Run the built version
```

## How Agents Should Use This

1. **At the start of a review**: Call `get_context` with the relevant funnel stages
2. **Before reviewing an ad**: Call `search_reviews` to check for a prior review
3. **After reviewing an ad**: Call `store_review` with all the details
4. **When re-scoring**: Call `update_review` to amend the existing entry

The `integration/` folder contains skill files and rules that teach agents this workflow automatically.