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.

Related MCP server: muze-mcp

V1 tools

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

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.