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.

Related MCP server: joa

Requirements

• Node.js 18+

• macOS, Linux, or Windows

Installation

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):

{
  "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:

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

And add the rule to your projects:

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

OpenAI Codex CLI

Add to ~/.codex/config.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:

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.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:

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.

search_reviews

Full-text search across all reviews.

get_context

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

list_reviews

Browse entries with optional filters.

update_review

Update an existing review.

delete_review

Remove an obsolete review.

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:

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

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:

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

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.