Run geoaeo as a Model Context Protocol server. The agent calls geoaeo without leaving the chat. One version feeds the library, the CLI, and the MCP server at parity.

What you get

CLI bins: geoaeo and geoaeo-mcp
CLI commands: audit, init, gen, humanize, mcp — no other commands exist
MCP server command: npx -y geoaeo mcp over stdio
MCP tools: audit, gen, humanize

Prerequisites

Node.js 20 or later
A site directory or a live URL to audit
An MCP-capable harness — Claude Code, Cursor, Windsurf, Codex, Gemini CLI, Copilot, or Continue

Install the plugin

In Claude Code, Cursor, or Codex:

/plugin marketplace add pooriaarab/usegeoaeo
/plugin install geoaeo@geoaeo

The plugin starts npx geoaeo mcp over stdio. MCP tools are audit, gen, and humanize.

Windsurf, Gemini CLI, Continue, and Copilot have no plugin dialect. Use the JSON fallback below.

Install

# one-off
npx geoaeo audit ./ --json

# or add to the project
npm install geoaeo
npx geoaeo --help

# verify the MCP server starts (it waits on stdin; Ctrl+C to stop)
npx -y geoaeo mcp

You do not run geoaeo mcp by hand when the harness manages it. The harness starts it over stdio.

Transport

stdio only. No SSE or HTTP transport exists. The server reads from stdin and writes to stdout. The harness spawns it with command: npx and args: ["-y", "geoaeo", "mcp"].

Tools

Tool	Input	Description
audit	target: string	Score a URL or local dir 0–100 and list gaps
gen	artifact, type?	Generate one artifact from geoaeo.config.ts
humanize	glob, write?	Find or fix AI-writing tells in prose files

`audit`

{ "target": "./" }
{ "target": "https://example.com" }

Returns JSON: score, checks[], topFixes[], pages[]. Use topFixes to choose the next gen call.

`gen`

{ "artifact": "llms" }
{ "artifact": "llms-full" }
{ "artifact": "sitemap" }
{ "artifact": "robots" }
{ "artifact": "webmcp" }
{ "artifact": "jsonld", "type": "software" }

artifact enum: llms, llms-full, jsonld, webmcp, sitemap, robots, ogimage, rss, hreflang, mdmirror. For jsonld, type may be software, product, faq, breadcrumb, organization, website, article, howto, person, or review. Reads geoaeo.config.ts in the current directory.

`humanize`

{ "glob": "content/**/*.md", "write": false }
{ "glob": "src/**/*.tsx", "write": true }

Run directly

npx -y geoaeo mcp
# equivalent: run the geoaeo-mcp bin
npx -y --package=geoaeo geoaeo-mcp

The process waits on stdin. You only run this for manual testing. Harnesses spawn it for you.

Configure a harness

JSON paste is the fallback for Windsurf, Gemini CLI, Continue, and Copilot. The harness starts the server for you:

{
  "mcpServers": {
    "geoaeo": {
      "command": "npx",
      "args": ["-y", "geoaeo", "mcp"]
    }
  }
}

The exact file path depends on the harness. See the harness guides:

Claude Code — .mcp.json
Cursor — .cursor/mcp.json
Muse — ~/.codex/config.toml
Windsurf — ~/.codeium/windsurf/mcp_config.json
Gemini CLI — ~/.gemini/settings.json
GitHub Copilot — .vscode/mcp.json
Continue — ~/.continue/config.yaml

Set up in your agent

Claude Code, Cursor, and Codex install the plugin above. Windsurf, Gemini CLI, Continue, and Copilot have no plugin dialect. Paste this prompt instead:

Set up geoaeo in this agent. Detect the harness, then configure the
geoaeo MCP server with command `npx` and args `-y geoaeo mcp`.
Run an audit on the current directory. Report the score and the
top three fixes.

Then try one of these:

Audit https://example.com and list the top 3 fixes.
Generate llms.txt for this repo.

Troubleshooting

Server shows as disconnected. Run npx -y geoaeo mcp in a terminal. It should wait on stdin. Press Ctrl+C. If npx fails, check Node 20+ and npm registry access.

Config not picked up. Validate JSON with cat .mcp.json | jq .. Restart the harness after any config change.

gen returns Cannot find config. Run npx geoaeo init ./ to scaffold geoaeo.config.ts.