Agency Opportunity Radar

MCP server that finds evidence-backed opportunities for digital agencies.

Agency Opportunity Radar helps an AI research public business websites, identify observable website or SEO problems, match them to an agency's declared services, and explain every score with measurements, URLs, and timestamps.

It is a research tool, not an outreach tool. It does not discover personal contact details, submit forms, send messages, or provide a standalone dashboard. The MCP client—ChatGPT, Claude, Codex, or another compatible client—remains the interface.

What the interaction looks like

Ask the connected AI:

Find fintech websites in Argentina that our agency could optimize.

The AI can first discover explicit URLs or public Google Places results, request a bounded audit for promising candidates, and then compare the saved results. A synthetic result might be summarized like this:

Río Ledger shows one directly observed technical SEO issue:

- Missing meta description (severity 3/5, confidence 0.99)
  Evidence: no non-empty meta description was found on
  https://rio-ledger.example/ at 2026-07-27T14:01:58Z.

Overall opportunity score: 73.5/100
- Need: 60
- Agency fit: 90
- Doability: 80
- Likely impact: 60
- Confidence: 80

Limitation: only one page was inspected. No traffic, revenue, budget, or
willingness-to-buy claim was made.

The complete structured example is in examples/example-audit-response.json.

Why this is not a lead database

A lead database answers “who might I contact?” This server focuses on a different chain of reasoning:

1. Need — Is there an observable problem?
2. Fit — Does it map to a service the agency actually offers?
3. Doability — Is the likely work compatible with declared capabilities and exclusions?
4. Evidence — Which public observation supports each finding?

The server returns those inputs and deterministic score contributions. The connected AI interprets them and keeps uncertainty visible.

Requirements

• Node.js 22.19 or newer
• An MCP-compatible client
• No API key for manual discovery and static website audits
• Optional Google Places API key for query/location discovery
• Optional PageSpeed Insights API key for mobile lab measurements

Install and build

From this repository:

npm install
npm run check

The compiled stdio server is dist/server.js. To run it directly:

node dist/server.js

The process speaks MCP over stdio, so it normally appears idle when started in a terminal. Configure it in an MCP client instead of typing into it.

MCP client configuration

Use absolute paths for the server, database, and export directory:

{
  "mcpServers": {
    "agency-opportunity-radar": {
      "command": "node",
      "args": [
        "/absolute/path/to/agency-opportunity-radar/dist/server.js"
      ],
      "env": {
        "RADAR_DATABASE_PATH": "/absolute/path/to/radar-data/opportunities.db",
        "RADAR_EXPORT_ROOT": "/absolute/path/to/radar-data/exports"
      }
    }
  }
}

A copyable version is available at examples/mcp-config.json.

Optional environment variables

Variable	Default	Purpose
RADAR_DATABASE_PATH	./agency-opportunity-radar.db	Local SQLite database
RADAR_EXPORT_ROOT	./exports	Only directory to which exports may be written
GOOGLE_PLACES_API_KEY	unset	Enables Google Places Text Search discovery
PAGESPEED_API_KEY	unset	Enables mobile PageSpeed measurements
RADAR_REQUEST_TIMEOUT_MS	10000	Per-request timeout
RADAR_MAX_RESPONSE_BYTES	2000000	Maximum response body read
RADAR_MAX_REDIRECTS	5	Redirect limit
RADAR_REQUESTS_PER_MINUTE	12	Per-domain request limit
RADAR_CACHE_TTL_SECONDS	86400	Provider and audit freshness window
RADAR_VERBOSE	0	Structured operational logs on stderr
RADAR_ALLOW_PRIVATE_NETWORK	0	Permit intentional local-site audits

Keep RADAR_ALLOW_PRIVATE_NETWORK=0 for ordinary use. Enabling it disables the private-network SSRF boundary and is intended only for trusted local fixtures or development sites.

First workflow

1. Configure the agency with agency_profile_set. The example at examples/agency-profile.json includes technical SEO, performance, and conversion services.
2. Ask the AI to call opportunity_discover with provider: "manual" and a list of public websites.
3. Call opportunity_audit for a returned candidateId.
4. Compare two or more saved reports with opportunity_compare.
5. Record a human decision with opportunity_record_outcome.
6. Retrieve it in a later conversation with opportunity_search_history.
7. Export selected snapshots with opportunity_export.

Manual discovery is intentionally useful without paid APIs:

{
  "query": "fintech websites in Argentina",
  "location": "Argentina",
  "provider": "manual",
  "websites": [
    "https://public-business.example/"
  ],
  "limit": 10
}

MCP tools

Tool	Bounded job
agency_profile_set	Create or replace the local agency profile
agency_profile_get	Inspect the active profile before research
opportunity_discover	Normalize manual URLs or optional Places results
opportunity_audit	Crawl and inspect one candidate with strict limits
opportunity_compare	Return a compact comparison of saved snapshots
opportunity_search_history	Filter searches, audits, and outcomes
opportunity_record_outcome	Append a human-reported business outcome
opportunity_export	Write selected results as JSON or CSV inside the configured root

Supported checks

The static detector pack currently covers:

• missing page titles, meta descriptions, and canonical URLs;
• accidental noindex directives;
• missing or multiple primary headings;
• missing mobile viewport declarations;
• multiple parser-blocking scripts;
• large declared images that load eagerly;
• missing static primary actions;
• forms without a visible privacy link;
• HTTPS pages posting forms to HTTP;
• public placeholder content;
• stale copyright years as low-confidence supporting evidence;
• crawled internal destinations returning HTTP errors;
• mobile LCP, INP, and CLS when PageSpeed is configured.

Every signal refers to one or more evidence IDs. Evidence stores the minimum necessary observation rather than full page bodies. Audit responses also include pages inspected, failed checks, next investigations, limitations, and the exact scoring configuration.

Scoring

All dimensions use a 0–100 scale. The initial, inspectable formula is:

overall =
  30% need
  25% agency fit
  20% doability
  15% likely impact
  10% confidence

This is a deterministic starting point, not an objective truth. Each audit stores its scoring version, weights, dimension values, contributing signal IDs, and plain-language reasons. A refresh creates a new snapshot instead of rewriting the old result.

Confidence falls when pages or providers fail, no inspectable page is available, or only one page is inspected. Likely impact is relative and directional; the server does not invent revenue or conversion-loss estimates.

Network and data safety

• Only HTTP and HTTPS targets are accepted.
• Credentials in URLs are rejected.
• Loopback, private, link-local, carrier-grade NAT, multicast, reserved, and metadata-service addresses are blocked by default.
• DNS is checked and pinned for each request, and every redirect is checked again.
• Crawls respect robots.txt and enforce page, redirect, response-size, timeout, concurrency, and per-domain request bounds.
• Login, logout, cart, checkout, and admin crawl paths are skipped.
• Query tokens and common credential parameters are redacted from stored URLs.
• API keys come from environment variables and are never written to results or operational logs.
• Full HTML bodies are not stored.
• Forms are never submitted.
• CSV exports neutralize spreadsheet-formula prefixes and never overwrite files.
• Exports cannot escape RADAR_EXPORT_ROOT.
• The MVP collects no personal email addresses or phone numbers and performs no outreach.

Current limitations

• Google Places is optional, quota-controlled, and may omit website fields.
• Static HTML checks cannot prove that a visually rendered interaction works.
• JavaScript-rendered content may be absent from the static response.
• PageSpeed availability depends on API access and external service behavior.
• The crawler inspects only a bounded subset of public pages.
• It does not bypass authentication, CAPTCHAs, paywalls, or access controls.
• It has no backlink index, paid-ad intelligence, social analysis, contact enrichment, CRM automation, or standalone UI.
• deep increases the bounded page sample; it does not perform the Phase 4 destructive or form-submission interactions excluded by the build plan.

Failed checks remain in the report and reduce confidence rather than disappearing.

Local storage

SQLite tables keep agency-profile snapshots, services, searches, candidates, audits, evidence, signals, scoring snapshots, outcomes, and provider cache entries. This gives a later AI conversation canonical history even when chat history is summarized or unavailable.

The server does not train an opaque ranking model from outcomes. Recorded outcomes are returned as transparent context.

Development and tests

npm run typecheck
npm test
npm run build

npm run check runs all three.

The deterministic test suite includes:

• URL normalization, secret redaction, and private-address boundaries;
• redirect, timeout, and response-size handling;
• ten local website fixtures spanning healthy, broken, ambiguous, and blocked behavior;
• evidence-to-signal referential integrity;
• score calculation and confidence penalties;
• SQLite migrations, immutable snapshots, restart durability, and outcomes;
• Places caching and partial PageSpeed failures;
• export confinement and overwrite protection;
• MCP tool discovery and end-to-end invocation over an in-memory transport.

Network-dependent live evaluations are intentionally separate. See test/evaluation/README.md for the human-review requirements before a public site becomes evaluation ground truth.

Project boundaries

This MVP is for evidence-led research. It is not a spam system, contact-enrichment service, automatic proposal generator, or substitute for human review. Use public and authorized data, respect site policies, and verify consequential conclusions before acting.

License

MIT