# 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

```mermaid
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:

```text
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.

```bash
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:

```bash
npm run dev
```

The endpoints are:

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

For local stdio:

```bash
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:

```bash
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:

```bash
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

```bash
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:

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

```text
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

```bash
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.