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

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

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

# verify the MCP binary
npx geoaeo-mcp --help

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. For jsonld, type may be software, product, faq, or breadcrumb. Reads geoaeo.config.ts in the current directory.

`humanize`

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

Run directly

npx geoaeo mcp
# equivalent
npx geoaeo-mcp

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

Configure a harness

Minimal MCP config. 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

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.