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

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.

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:

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.