GenuDo Market Intelligence MCP

A shared, evidence-first market-intelligence server for deciding which AI employees GenuDo should build and package across Egypt, Saudi Arabia, and the UAE.

The repository runs as both:

• a remote Streamable HTTP MCP at /mcp, designed for Apify Actor Standby;
• a local stdio MCP for development and offline client testing.

Architecture

flowchart LR
    A["GitHub repository"] --> B["Apify Actor Standby"]
    B --> C["Source adapters"]
    C --> D["Meta Ads Actor"]
    C -. future .-> E["Search, jobs, web, social, pricing, reviews"]
    B --> F["Central research store"]
    G["ChatGPT / Codex"] --> B
    H["Claude"] --> B
    I["Other MCP clients"] --> B

The MCP owns taxonomy, normalization, scoring, caching, research history, and evidence retrieval. Source Actors only collect data. This keeps the seven public tools stable as new sources are added.

V1 tools

Tool	Purpose	Starts a paid source run?
search_meta_ads	Search public Meta ads by query and market	Yes
research_ai_employee_market	Research one AI employee category across selected markets	Yes
analyze_competitor_ads	Deep-dive one competitor's ads, messages, creative mix, landing pages, and social metadata	Yes
compare_ai_employee_opportunities	Compare stored category evidence and GenuDo process fit	No
get_market_evidence	Retrieve the ads and advertisers supporting a finding	No
get_research_run	Retrieve a saved research run and its methodology	No
list_sources	Show connectivity, roadmap, taxonomy, storage, and recent runs	No

Every live tool limits result counts. Deep competitor research is opt-in because advertiser and per-ad enrichment costs more.

What the score means

The V1 opportunity-screening score is:

45% GenuDo process fit
30% commercial validation from visible Meta ad activity
25% competitive whitespace

Meta ads show commercial supply, advertiser breadth, localization, creative testing, and campaign persistence. They do not directly prove buyer demand, conversions, advertising spend, or ROAS. The output repeats that caveat. Search demand, jobs, reviews, customer research, and willingness-to-pay evidence belong in later source adapters before an investment decision.

Included taxonomy

The initial taxonomy covers GenuDo's current positions and adjacent expansion candidates:

• Sales Agent
• Customer Support
• Customer Success
• Appointment Setter
• Receptionist
• Lead Qualifier
• Follow-up / Reactivation
• SDR / BDR
• Accounts Receivable / Collections
• Order / Fulfillment
• HR Onboarding / Employee Operations
• Recruiting / Candidate Screening
• Procurement / Supplier Operations
• IT Service Desk
• Claims / Case Processing

Each category includes English and Arabic market-discovery queries. Call list_sources for the canonical IDs and process-fit metadata.

Local setup

Requirements: Node.js 20 or newer.

npm install
cp .env.example .env
npm test

Put APIFY_TOKEN in your local .env file or secret manager. Never commit it or paste it into chat.

Start the HTTP server:

npm run dev

The endpoints are:

GET  http://localhost:3000/health
POST http://localhost:3000/mcp

For local stdio:

npm run build
npm run start:stdio

Runtime configuration

Variable	Required	Default	Purpose
APIFY_TOKEN	For local live research	injected by Apify when hosted	Calls source Actors and enables centralized Apify storage
APIFY_META_ADS_ACTOR	No	apify/facebook-ads-scraper	Meta Ads source Actor
APIFY_RESEARCH_STORE_NAME	No	genudo-market-intelligence	Named shared key-value store
MCP_BEARER_TOKEN	Recommended outside Apify-managed auth	none	Optional application-level bearer authentication
MCP_ALLOWED_HOSTS	Recommended when binding publicly	none	Comma-separated accepted HTTP hostnames
PORT	No	3000	HTTP port
HOST	No	127.0.0.1 locally	Bind address; Docker sets 0.0.0.0
ACTOR_WEB_SERVER_PORT	Injected by Apify	typically 4321	Apify container/Standby port; takes precedence over PORT

With APIFY_TOKEN, completed and failed runs are appended to a named Apify dataset while full run records and normalized evidence are saved in the named key-value store. This avoids a shared mutable index when Standby scales to multiple instances. Without the token, development uses .data/research-store.json and live source calls remain unavailable.

Deploy to Apify

The repo includes .actor/actor.json and a multi-stage Docker image. It is configured for Actor Standby and exposes /mcp.

Recommended GitHub deployment:

1. Create a private Actor in Apify.
2. Set the source type to Git repository.
3. Enter this repository URL and use the main branch.
4. For a private GitHub repository, add the read-only deployment key supplied by Apify.
5. Build the Actor. Apify injects the authenticated run user's APIFY_TOKEN; do not duplicate an owner token in actor.json.
6. Open Standby, select the successful build, and copy the Standby hostname.
7. Set MCP_ALLOWED_HOSTS to localhost,127.0.0.1,YOUR-STANDBY-HOST (without https:// or a path), then restart the Standby run.
8. Confirm https://YOUR-STANDBY-HOST/health, then use https://YOUR-STANDBY-HOST/mcp as the MCP URL.

For development, the Apify CLI can push the same Actor definition:

apify login
apify push

Actor Standby keeps the HTTP server warm, scales incoming requests, and bills while a warm run is active. Tune memory, concurrency, and idle timeout in the Standby settings after observing real usage.

Authentication choices

Choose one deliberate access model:

1. Apify-managed private access: keep the Actor private and initially connect with an authenticated Apify token. For team use, create a dedicated GenuDo service user/account instead of distributing an owner-level token.
2. Application bearer access: make the endpoint reachable and set a strong MCP_BEARER_TOKEN in Apify secrets.
3. OAuth gateway: place a team identity gateway in front of the Actor later when per-user revocation and audit are required.

Do not distribute GenuDo's owner-level APIFY_TOKEN to team devices. That token belongs only in the hosted server environment.

Connect Codex / ChatGPT Desktop

Store the team bearer value in each device's environment, not in shell history:

export GENUDO_INTELLIGENCE_TOKEN="..."
codex mcp add genudo-intelligence \
  --url https://YOUR-STANDBY-HOST/mcp \
  --bearer-token-env-var GENUDO_INTELLIGENCE_TOKEN

Or use Settings → MCP servers → Add server → Streamable HTTP, then restart the client after saving.

For an unauthenticated development endpoint, omit --bearer-token-env-var.

Connect Claude Code

claude mcp add --transport http --scope user \
  genudo-intelligence https://YOUR-STANDBY-HOST/mcp \
  --header "Authorization: Bearer ${GENUDO_INTELLIGENCE_TOKEN}"

For team-shared Claude project configuration, prefer environment-variable expansion in .mcp.json so the secret itself is never committed:

{
  "mcpServers": {
    "genudo-intelligence": {
      "type": "http",
      "url": "https://YOUR-STANDBY-HOST/mcp",
      "headers": {
        "Authorization": "Bearer ${GENUDO_INTELLIGENCE_TOKEN}"
      }
    }
  }
}

Adding the next source

Implement a new adapter under src/sources, return normalized evidence, and keep source-specific fields out of the stable tools. Planned adapters include:

search_google
search_jobs
research_linkedin
research_instagram
scrape_competitor_website
research_pricing
research_reviews

The scoring layer should only label a metric “demand” after direct demand evidence is connected.

Verification

npm run check
npm test
docker build -t genudo-market-intelligence-mcp .

Tests validate Meta URL generation, Arabic normalization, supply metrics, and the full seven-tool MCP manifest.

Security and data handling

• Secrets are read only from the runtime environment.
• Health and source-status outputs never include token values.
• Raw public-source records are stored for auditability but omitted from normal MCP responses.
• Evidence retrieval is capped and filterable to avoid flooding model context.
• Only public Meta Ad Library material should be collected, subject to applicable laws and platform terms.
• Use a private repository and least-privilege deployment credentials until the service is ready for broader use.