Metadata-Version: 2.4
Name: leadee-mcp
Version: 0.2.0
Summary: MCP server for Leadee.ai: SEO and AI visibility tools for Claude, Cursor and other MCP clients
License-Expression: MIT
Project-URL: Homepage, https://leadee.ai
Project-URL: Source, https://github.com/netbasecorp/leadee/tree/main/mcp
Project-URL: Changelog, https://github.com/netbasecorp/leadee/blob/main/mcp/CHANGELOG.md
Keywords: mcp,seo,geo,ai-visibility,leadee,claude
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

# leadee-mcp

[MCP](https://modelcontextprotocol.io) server wrapping the [Leadee.ai](https://leadee.ai) GEO
platform REST API: AI-visibility Audit (M1), Visibility Tracker (M2), Prompt Discovery (M3),
Citation Graph (M4), Fix Engine (M5), AI Traffic (M6) and billing. Thin wrapper — every tool is a
direct call to one `/v1/...` endpoint; see `src/leadee_mcp/tools.py` for the full mapping.

Version 0.2.0 (see `CHANGELOG.md`). Ready to publish but not published to PyPI or the MCP
registry yet — see `docs/specs/geo-platform-spec.md` §6 row G6, `docs/specs/mcp-coverage-v2.md` and
`docs/integrations/mcp.md` for client setup.

<!-- Ownership marker the official MCP registry reads from the PyPI description: -->
mcp-name: io.github.netbasecorp/leadee-mcp

## Install (available after publish)

One line, no install step: [`uvx`](https://docs.astral.sh/uv/) fetches the package and runs it.

```bash
# Claude Code
claude mcp add leadee -e LEADEE_API_KEY=<your-leadee-api-key> -- uvx leadee-mcp
```

Or with pip: `pip install leadee-mcp`, then run `leadee-mcp`. `leadee-mcp --help` lists the
settings; `leadee-mcp --version` prints the version.

Until then, install from the repo:

```bash
pip install -e mcp
```

## Run

```bash
export LEADEE_API_KEY=<your-leadee-api-key>   # needed for every account tool
export LEADEE_API_URL=https://leadee.ai   # default; point at a self-hosted deployment instead
leadee-mcp
```

Transport defaults to stdio (what Claude Desktop, Cursor and most MCP clients spawn as a
subprocess). Set `LEADEE_MCP_TRANSPORT=streamable-http` to run it instead as a long-lived HTTP
server other clients (e.g. a ChatGPT connector) can point at:

```bash
LEADEE_MCP_TRANSPORT=streamable-http leadee-mcp
```

See `docs/integrations/mcp.md` for Claude Desktop / Cursor / ChatGPT connector config snippets.

## Tools

| Tool | Endpoint | Module |
|---|---|---|
| `free_scan` | `POST /v1/free-scan` | — (public, no API key) |
| `index_check` | `POST /v1/free-tools/index-checker` | — (public, no API key; behind `LEADEE_INDEX_CHECKER_PUBLIC`) |
| `analyze_url` | none — runs `leadee.urlanalysis` inside the MCP process (stdio only for now) | One-URL SEO + GEO report and fix list, see `docs/specs/mcp-analyze-url-spec.md` |
| `check_entity` | `POST /v1/free-tools/entity-check` | — (public, no API key) |
| `score_content` | `POST /v1/free-tools/content-score` | — (public, no API key) |
| `estimate_plan` | `POST /v1/free-tools/price-calculator` | — (public, no API key) |
| `validate_schema`, `generate_llms_txt`, `check_ai_readiness` | `POST /v1/free-tools/schema-markup-validator`, `/llms-txt-generator`, `/ai-visibility-checker` | ldee-ttmcp — public, read-only; returns a review-only `fix_plan` (see `docs/integrations/mcp.md`) |
| `create_audit`, `get_audit`, `get_audit_report` | `/v1/audits*` | M1 Audit |
| `list_brands`, `create_brand` | `/v1/brands*` | — |
| `list_prompt_sets`, `create_prompt_set` | `/v1/prompt-sets*` | — |
| `suggest_prompts`, `accept_prompt_suggestions` | `/v1/prompt-sets/{id}/suggest*` | M3 Prompt Discovery |
| `start_tracker_run`, `get_visibility_metrics`, `get_answers`, `estimate_cost` | `/v1/tracker/*` | M2 Visibility Tracker |
| `get_citation_domains`, `get_citation_urls`, `get_citation_gaps` | `/v1/citations/*` | M4 Citation Graph |
| `list_fixes`, `get_fix`, `generate_fixes`, `update_fix_status` | `/v1/fixes*` | M5 Fix Engine |
| `get_traffic_bots`, `get_traffic_referrals`, `get_traffic_pages` | `/v1/traffic/*` | M6 AI Traffic |
| `get_billing_plans` | `GET /v1/billing/plans` | — (public, no API key) |
| `get_billing_subscription` | `GET /v1/billing/subscription` | — |
| `get_plan_usage` | `GET /v1/billing/plan-usage` | s40b — plan, limits, month usage, next plan; same numbers as the workspace |
| `get_usage` | `GET /v1/usage` | — |
| `list_data_connections`, `create_data_connection`, `import_ai_report` | `/v1/connections*` | C1/C2 Data Connections |
| `get_google_ai_report`, `get_bing_ai_report` | `GET /v1/ai-reports/*` | C2 AI report imports |
| `keyword_import`, `cluster_build`, `cluster_get` | `/v1/projects/{id}/keywords/import`, `/v1/projects/{id}/clusters*` | ldee-clu2 Keyword clusters (behind `LEADEE_CONTENT_OPS_ENABLED`) |
| `index_push_summary`, `index_push_submit` | `/v1/projects/{id}/index-push/*` | ldee-ixp1/ldee-ixp2 Index Push — per-project % indexed (Google), Bing data, 7-day regressions, Bing quota, and manual (re)submit, customer access behind `LEADEE_INDEX_PUSH_CUSTOMER_ENABLED` (job ldee-ixp3b) |
| `get_brand_serp`, `refresh_brand_serp` | `/v1/projects/{id}/brand-serp*` | ldee-bsp1 Brand SERP report |
| `get_keyword_brand_split` | `GET /v1/projects/{id}/keywords/brand-split` | ldee-kwbr1 — keyword count/clicks/impressions/volume by brand class |
| `get_keyword_cards` | `GET /v1/projects/{id}/keywords` | ldee-kwc2 — same enriched list as `keyword_analysis`, filterable by the keyword card's own `keyword_type`/`keyword_tier`/`win_chance`/`brand_class` fields (behind `LEADEE_CONTENT_OPS_ENABLED`) |
| `get_market_size`, `get_market_competitors`, `get_kpi_forecast` | `GET /v1/projects/{id}/market*` | ldee-mkt1/ldee-mkt2/ldee-kpi1 — cached market-size/competitor/KPI snapshots (paid projects or the internal tenant only, behind `LEADEE_CONTENT_OPS_ENABLED`) |
| `get_reality_check` | `GET /v1/projects/{id}/reality-check` | ldee-rlc1 — this project's own GSC/GA4 traffic vs. a cached third-party estimate |

### Added in 0.2.0 (job ldee-mcpx1, `src/leadee_mcp/coverage_tools.py`)

Each one wraps one existing route (`COVERAGE_ROUTES` in that module; the main repo's
`tests/test_mcp_server.py` checks every route exists). Full table with gates:
`docs/specs/mcp-coverage-v2.md`.

| Tools | Endpoints | Area |
|---|---|---|
| `list_keyword_imports`, `get_keyword_status`, `get_keyword_overview`, `list_clusters`, `get_cluster_map`, `get_cluster_page_type_gaps`, `get_kpi_reality`, `get_kpi_refresh_cost`, `get_cluster_brief`, `get_cluster_article_links`, `get_hub_report` | `/v1/projects/{id}/keywords/*`, `/clusters*`, `/market/kpi/*`, `/cluster-items/*`, `/cluster-articles/*`, `/hub-report` | SEO data |
| `get_bing_summary`, `get_bing_ai_topics`, `list_index_push_urls`, `get_project_visibility`, `get_prompt_fanout`, `create_prompt_fanout`, `verify_data_connection` | `/v1/projects/{id}/bing/summary`, `/v1/ai-reports/bing/topics`, `/v1/projects/{id}/index-push/urls`, `/visibility`, `/v1/prompts/{id}/fan-out`, `/v1/connections/{id}/verify` | SEO data |
| `get_monitoring`, `list_monitoring_runs`, `list_monitoring_issues`, `mark_monitoring_issue_fixed`, `verify_monitoring`, `list_monitoring_notifications`, `mark_notification_read` | `/v1/projects/{id}/monitoring*` | Monitoring |
| `list_issues`, `list_fix_plans`, `get_fix_plan`, `get_fix_plan_markdown` | `/v1/projects/{id}/issues`, `/v1/fix-plans*` | Issues, fix plans |
| `list_content_audits`, `get_content_audit`, `list_content_audit_pages`, `create_content_audit` | `/v1/content-audits*` | Content audits |
| `list_alert_rules`, `get_alert_rule`, `list_alert_events` | `/v1/alerts/*` | Alerts |
| `get_project_report`, `list_report_rows`, `get_report_permalink`, `get_report_email_preference`, `set_report_email_preference`, `get_report_digest` | `/v1/projects/{id}/report`, `/v1/reports/*`, `/v1/projects/{id}/report-email-preference`, `/v1/me/report-digest` | Reports |
| `get_public_profile`, `set_public_profile`, `get_public_brand_report` | `/v1/brands/{id}/public-report`, `/v1/public/brand-reports/{domain}` | Public brand profile |
| `list_articles`, `get_article_board`, `get_article`, `get_article_markdown`, `list_article_publications`, `list_publish_connections`, `publish_article` | `/v1/articles*`, `/v1/projects/{id}/publish-connections` | Articles, publishing (an agent's `publish_article` goes to the approval inbox) |
| `list_members`, `get_actions_catalog`, `get_benchmark`, `list_methodology_checks` | `/v1/members`, `/v1/actions-catalog`, `/v1/benchmarks/{industry}`, `/v1/methodology/checks` | Team, catalog |
| `technical_seo_audit`, `check_page_speed`, `check_meta_tags`, `validate_sitemap`, `check_redirects`, `check_hreflang`, `test_robots_txt` | `POST /v1/free-tools/*` | Free SEO checkers |

`analyze_url` is listed only when the `leadee.urlanalysis` engine is importable (a repo checkout or
an install next to the `leadee` package). The published wheel alone does not list it.

Every tool except `free_scan` and `get_billing_plans` requires `LEADEE_API_KEY` — the server
forwards it as the `X-Leadee-Key` header, and the API rejects calls without it with
`missing_api_key`.

## Prompts

| Prompt | Does |
|---|---|
| `audit_and_propose_fixes(url)` | Audit a site, summarize it, generate fix tickets, and (on confirmation) apply one |
| `weekly_visibility_summary(brand_id)` | Summarize a brand's week-over-week Tracker/Citation Graph/AI Traffic |
| `brand_growth_review(project)` | Run the leadee-brand-growth skill's workflow and return its 8-part plan (see below) |

## leadee-brand-growth skill

`src/leadee_mcp/skills/leadee-brand-growth/` (`SKILL.md` + `references/*.md`) is the method behind
the `brand_growth_review(project)` prompt — EEAT inventory, market player brands, AI brand
position, the six-tier keyword structure, cluster map, market/KPI, and an 8-part plan. Shipped as
package data (`pyproject.toml`'s `package-data`), so it stays readable after a real `pip install`,
not just from a source checkout; every MCP client also sees it as three read-only resources:

- `leadee://skills/leadee-brand-growth/SKILL.md`
- `leadee://skills/leadee-brand-growth/references/kpi-method.md`
- `leadee://skills/leadee-brand-growth/references/page-templates.md`

The skill itself names no client/brand — `mcp/tests/test_skill_resources.py` checks that against a
word list of Netbase's own internal/client brands.

Job `ldee-mcpg1`'s brief also named `get_page_changes` and `get_hub_report`; neither had a matching
`/v1/...` route on `main` when `mcpg1` ran, so neither was a tool at the time — see
`src/leadee_mcp/tools.py`'s module docstring for what was checked before skipping them.
`get_page_changes` is now covered by `list_page_changes` (job `ldee-drf1`, merged after `mcpg1`);
`get_hub_report` was added in 0.2.0 (job `ldee-mcpx1`) once `GET /v1/projects/{id}/hub-report` existed.

## Registry listings (not submitted — see owner spec §6 row G6)

- `server.json`: official [MCP registry](https://registry.modelcontextprotocol.io) manifest
  (schema `2025-12-11`, validated against it by job ldee-mcpx1). References `leadee-mcp` on PyPI
  at version `0.2.0` — publish the package first (David's PyPI account; `python -m build mcp` makes
  the sdist and wheel), then `mcp-publisher login github && mcp-publisher publish` from this
  directory. The registry checks the `mcp-name:` line near the top of this README (it becomes the
  PyPI description) to confirm the PyPI package belongs to this server.
- `.well-known/mcp/server-card.json`: Smithery's optional static server-card fallback (used only
  if Smithery's automatic scan of a public server URL can't complete). Needs to actually be served
  at that path by a deployed instance — it's not useful sitting in the repo until D1 phase B is
  live on `leadee.ai`.
- Glama and mcp.so (owner spec §5) don't document a repo-committed manifest format as of
  2026-10-22 — they index from GitHub/the official registry directly, so there is nothing to add
  here for them; submission is a web form once the server is published.

## Tests

```bash
pip install -e ".[dev]"   # from the repo root — pulls in the `mcp` SDK dev dependency
pytest mcp/tests
```

`mcp/tests/` mocks the Leadee API over `httpx.MockTransport` (no network). The repo root's
`tests/test_mcp_server.py` additionally runs every tool in-process against the real FastAPI app
(same DB-backed fixtures as the rest of the test suite) — see `AGENTS.md`.
