@villion-inc/mcp

GEO (Generative Engine Optimization) tools for AI coding assistants.

Teach Claude Code, Cursor, Codex, and any MCP-capable host to build websites that show up in ChatGPT, Perplexity, Gemini, and Claude answers.

What it does

@villion-inc/mcp adds 5 GEO tools to your AI coding assistant, backed by Villion's production GEO engine:

| Tool | Use it when | |------|-------------| | villion_audit_html | You just wrote HTML and want to know what's hurting AI-search discoverability. Runs 30 production GEO rules, returns P0/P1/P2 issues with concrete fix suggestions. | | villion_audit_url | You want to audit a live URL — your own, a competitor's, or a staging site. Same 30-rule engine, fetches the page for you (Pro: JS rendering for SPAs). | | villion_generate_jsonld | You need production-ready structured data (Article, FAQPage, HowTo, Product…). | | villion_validate_jsonld | You wrote JSON-LD and want to catch schema.org + Google Rich Results issues. | | villion_get_bot_traffic | Quick stats on which AI bots are hitting your site, which pages they land on, by vendor. |

Every tool returns concrete fix suggestions — your AI assistant applies them directly.

The audit_* tools run a curated 30-rule HTML-only subset of Villion's full 92-check engine — no network or LLM calls, sub-second response, every rule maps 1:1 to the production audit pipeline used by the Villion dashboard.

Quick start

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "villion": {
      "command": "npx",
      "args": ["-y", "@villion-inc/mcp"],
      "env": {
        "VILLION_API_KEY": "vk_beta_...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

VILLION_API_KEY is required (get one at https://villion.io/contact?ref=mcp-access). OPENAI_API_KEY is optional — set it to have LLM calls billed to your OpenAI account instead of Villion's.

Restart Claude Desktop. You should now see 5 villion_* tools available in the tool picker.

Try it:

Paste an HTML page into Claude and ask: "Audit this for GEO issues and suggest fixes."

Cursor

Add to ~/.cursor/mcp.json (or via Cursor → Settings → MCP):

{
  "mcpServers": {
    "villion": {
      "command": "npx",
      "args": ["-y", "@villion-inc/mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Windsurf

Cascade → Settings → MCP Servers → Add custom server, then paste the same command/args/env shape. Windsurf auto-discovers tools, resources, and prompts.

Codex CLI

Add to your Codex config (e.g. ~/.config/codex/mcp.json):

{
  "villion": {
    "command": "npx",
    "args": ["-y", "@villion-inc/mcp"],
    "env": {
      "OPENAI_API_KEY": "sk-..."
    }
  }
}

Any other MCP-capable host

Standard stdio transport, zero-install:

npx -y @villion-inc/mcp

Protocol: MCP 2024-11-05. Capabilities: tools, resources, prompts.

Any MCP client

# Stdio transport, zero-install invocation:
npx -y @villion-inc/mcp

# With an API key (Pro tier):
VILLION_API_KEY=vk_live_xxx npx -y @villion-inc/mcp

# Offline / demo mode (no network calls):
VILLION_MCP_DEMO=1 npx -y @villion-inc/mcp

Pricing — two tiers

| Tier | Price | What you get | Who it's for | |------|-------|--------------|--------------| | Free (Beta) | $0 | All 4 tools + 10 resources + 3 prompts at full production quality · BYOK OpenAI required for LLM tools · static HTML audit only | Devs who already have an OpenAI key and audit mostly static/SSR sites | | Pro | $10 / mo | Villion hosts the LLM (no BYOK needed) · render_js=true unlocks ZenRows-backed JS rendering for SPAs / React / CSR sites | Teams auditing SPAs, or who don't want to manage an OpenAI key |

Everything else (Team, Enterprise, rate-limit overrides, ML-heavy tools) stays disabled until we exit beta.

Request access: https://villion.io/contact?ref=mcp-access — say what you're building and whether you need Pro (for JS rendering or Villion-hosted LLM). Free keys ship same-day for approved use cases; Pro invoicing is handled manually for now.

Once issued, set the key in your MCP config:

"env": {
  "VILLION_API_KEY": "vk_beta_...",
  "OPENAI_API_KEY": "sk-..."
}

Free tier requires BYOK for LLM tools

villion_generate_jsonld calls OpenAI. On the Free tier, @villion-inc/mcp forwards your OPENAI_API_KEY as an X-User-OpenAI-Key header so your OpenAI account pays for the call. If the key is missing, the backend responds 402 byok_required with an upgrade hint.

Pro callers may omit OPENAI_API_KEY — Villion uses its server-side key and eats the LLM cost. Non-LLM tools (audit, validate) never see any OpenAI key. Villion never logs or stores either key.

JS rendering (render_js=true) is Pro-only

villion_audit_url accepts a render_js flag. When true, Villion routes the fetch through ZenRows so client-rendered content is visible to the auditor. Because ZenRows costs Villion per-request, this is gated behind Pro. Free callers get a 402 with the Pro upgrade hint.

Configuration

| Env var | CLI flag | Default | Description | |---------|----------|---------|-------------| | OPENAI_API_KEY | --openai-key <key> | none | BYOK. When set, LLM-backed tools use your key directly (you pay OpenAI, Villion quota untouched). | | VILLION_USER_OPENAI_KEY | --openai-key <key> | none | Alias for OPENAI_API_KEY — use this if you want a Villion-specific override. | | VILLION_API_KEY | --api-key <key> | none | Authenticates Pro/Team/Enterprise tier (use when you don't want to manage your own OpenAI key). | | VILLION_API_BASE_URL | --base-url <url> | Villion-managed | Override only when self-hosting the Villion backend. Most users should leave this unset. | | VILLION_MCP_DEMO | --demo | false | Return canned sample responses without any network call. |

CLI flags take precedence over env vars. Most devs already have OPENAI_API_KEY set, so the Free tier works with zero extra setup.

Rate limits

| Scope | Default | Env override | |-------|---------|--------------| | Per authenticated API key | 200 calls / minute | VILLION_MCP_RPM |

Sliding-window counter, Redis-backed when available, in-memory fallback. Hitting the cap returns HTTP 429 with Retry-After: 60. Need a higher quota? Mention it in your access request.

What happens on every call

1. Your AI host invokes a villion_* tool over stdio MCP.
2. @villion-inc/mcp validates arguments with zod and forwards them to the Villion backend.
3. The backend runs the real audit / schema generation / validation, and returns a structured response.
4. The tool wraps it in an MCP text-content block for the host.

No data from your codebase is stored unless you explicitly pass it to a tool. No telemetry is sent from @villion-inc/mcp to Villion servers outside of the tools you invoke.

Example session

User:  Here's my new pricing page draft:
       <html>…</html>
       Can you make it GEO-ready?

Claude: I'll audit this first.
        [calls villion_audit_html]

        Found 3 issues:
        • P0: Missing Product JSON-LD
        • P1: No BLUF sentence in hero
        • P2: Meta description is 68 chars, should be 120+

        Generating structured data:
        [calls villion_generate_jsonld]

        Added Product + Offer JSON-LD. Validating:
        [calls villion_validate_jsonld]

        ✓ Valid. Here's the updated HTML:
        <html>…</html>

MCP surface in v0.1

5 Tools

• villion_audit_html, villion_audit_url — 30-rule GEO audit (HTML-only subset of Villion's 92-check engine). P0/P1/P2 issues + concrete fix suggestions, no LLM/network calls. Categories covered: indexability, title/description/H1, heading hierarchy, JSON-LD/schema, content depth & answer-format (BLUF/Q&A/entity placement), internal-link quality, OG/Twitter, image alt + modern formats, hreflang, mobile/JS-rendering risk.
• villion_generate_jsonld — production-ready JSON-LD via Villion's schema_agent.
• villion_validate_jsonld — schema.org + Google Rich Results validation with auto-correction.
• villion_get_bot_traffic — AI-bot hit summary (vendors + top pages) from the caller's Villion Analytics tenant. Requires a user-issued MCP key.

12 Resources (host-attachable reference material, no tokens burned)

• villion://best-practices/geo — agent cheat sheet.
• villion://best-practices/citability-checklist — per-passage rewrite checklist.
• villion://schema-examples/{Article|Product|FAQPage|HowTo|Organization|WebSite|Recipe|JobPosting|LocalBusiness|Event} — canonical JSON-LD patterns.

3 Prompts (slash commands in Claude Desktop / Cursor / Codex)

• geo-audit-page — audit + apply top fixes to the current page.
• geo-build-article — draft a GEO-ready article skeleton from a topic.
• geo-compare-competitors — audit competitor URLs and surface structural gaps.

Roadmap

v0.2:

• Pro tools: villion_suggest_meta_tags, villion_rewrite_for_geo, villion_generate_faq, villion_check_brand_visibility
• More schema-example resources (Recipe, JobPosting, Event, LocalBusiness)
• Full 92-check villion_full_audit_url (async, task polling)

v1.0:

• Citation Probability Predictor (villion_predict_citation_probability)
• Inverse GEO gap-slot analysis
• Competitor pattern library (villion://patterns/{industry})
• MCP Sampling support (Claude Desktop uses host's Claude — no BYOK needed)

Links

• Villion platform: https://villion.io

License

MIT