# TrueSource GEO MCP Server

> AI-Readiness auditing as an MCP tool surface — for Claude Desktop, Cursor, VS Code Copilot, and 70+ other MCP clients.

## What is this?

This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes TrueSource's GEO-Audit methodology as standardized tools. Any MCP-compatible AI assistant can:

- **Audit websites** for AI-readiness (robots.txt, llms.txt, schema markup, E-E-A-T signals)
- **Generate GEO files** (AI-optimized robots.txt, llms.txt)
- **Create VibeTags** for emotional AI brand resonance
- **Check robots.txt** for AI bot allow/block status

## Quick Start

### Option A: npx (Recommended)

> ⚠️ The `-y` flag is **critical** — without it, npx silently waits for install confirmation in the background and the server freezes.

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "truesource": {
      "command": "npx",
      "args": ["-y", "truesource-geo-mcp"],
      "env": {
        "TRUESOURCE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### Cursor / VS Code

Add to `.cursor/mcp.json` or VS Code MCP settings:

```json
{
  "mcpServers": {
    "truesource": {
      "command": "npx",
      "args": ["-y", "truesource-geo-mcp"],
      "env": {
        "TRUESOURCE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Option B: Local Build

```bash
cd packages/geo-mcp
npm install
npm run build
```

```json
{
  "mcpServers": {
    "truesource-geo": {
      "command": "node",
      "args": ["/absolute/path/to/packages/geo-mcp/build/index.js"],
      "env": {
        "TRUESOURCE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### 3. Restart Your MCP Host & Use

Ask your AI assistant:
- *"What's the AI-readiness score for my-website.com?"*
- *"Generate a robots.txt for https://example.com"*
- *"Check which AI bots are blocked on competitor.com"*
- *"Create VibeTags for our brand at my-website.com"*

## Available Tools

| Tool | Trigger | Description |
|------|---------|-------------|
| `geo_score` | "audit", "score", "check AI readiness" | Full AI-readiness audit → 0-100 score, grade, checks, recommendations |
| `geo_inject` | "generate robots.txt", "create llms.txt" | Generate AI-optimized robots.txt + llms.txt (ready to deploy) |
| `vibetags_generate` | "brand perception", "VibeTags", "how AI sees" | Emotional AI brand resonance analysis (4-layer VibeGap Bridge) |
| `geo_check_robots` | "robots.txt", "which bots blocked" | Quick robots.txt AI bot status check (9 bots) |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `TRUESOURCE_API_KEY` | **Yes** | — | API key for Railway backend authentication |
| `TRUESOURCE_API_URL` | No | Railway production URL | GEO-Inject API base URL |
| `TRUESOURCE_TIMEOUT` | No | `30000` | Request timeout in ms (MCP hosts timeout at ~60s) |

## Testing with MCP Inspector

```bash
npm run inspect
```

This opens the interactive MCP Inspector at `http://localhost:6274`, where you can:
- See all registered tools and their schemas
- Invoke tools with test data
- Inspect JSON-RPC request/response pairs

## Architecture

```
┌─────────────────────────────┐
│  MCP Host (Claude Desktop)  │
│  User: "Audit example.com"  │
└─────────────┬───────────────┘
              │ Stdio (JSON-RPC 2.0)
              ▼
┌─────────────────────────────┐
│  truesource-geo-mcp v1.2.0  │
│  (TypeScript MCP Server)    │
│                             │
│  Tools:                     │
│  ├── geo_score              │
│  ├── geo_inject             │
│  ├── vibetags_generate      │
│  └── geo_check_robots       │
└─────────────┬───────────────┘
              │ HTTPS + Bearer Auth
              ▼
┌─────────────────────────────┐
│  Railway API                │
│  (FastAPI / Python)         │
│  truesource-mcp-api         │
│                             │
│  POST /audit/robust         │
│  POST /activate/robots      │
│  POST /activate/llms        │
│  POST /semantize            │
│  GET  /check/robots         │
└─────────────────────────────┘
```

## Changelog

### v1.2.0 (2026-03-29) — Gemini Review Release
- **Security:** API key authentication (Bearer token via `TRUESOURCE_API_KEY`)
- **Performance:** Timeout reduced 180s → 30s (MCP host compatibility)
- **Performance:** HTML streaming with `</head>` early-abort for Schema/OG checks
- **DX:** Improved tool descriptions with explicit trigger words for better LLM routing
- **DX:** `npx -y` install flow documented (prevents silent freeze)

### v1.1.0 (2026-03-29) — Optimization Release
- **Performance:** Parallelized 5 checks with `Promise.allSettled` (3s → ~1s)
- **Bugfix:** Register `geo_check_robots` tool
- **Bugfix:** Fix `{{HOST}}` placeholder in generated robots.txt
- **Bugfix:** Fix response format mismatch in check-robots

### v1.0.0 (2026-03-28) — Initial Release
- 3 tools: `geo_score`, `geo_inject`, `vibetags_generate`
- Stdio transport, Railway API integration

## License

MIT — TrueSource AI / Sascha Deforth