Metadata-Version: 2.4
Name: audigeo-mcp
Version: 0.1.2
Summary: AudiGEO MCP server — exposes AudiGEO.ai capabilities (audits, monitoring, hallucinations, content) to MCP-compatible agents.
Author-email: Sponge Theory <support@audigeo.ai>
License: SPONGE THEORY PROPRIETARY LICENSE
Keywords: ai-monitoring,audigeo,claude,geo,mcp,sponge-theory
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: pydantic-settings<3,>=2.2
Requires-Dist: pydantic<3,>=2.6
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# audigeo-mcp

MCP server exposing the **AudiGEO.ai** GEO platform to MCP-compatible agents
(Claude Code, Claude Desktop, and any other MCP host).

Talks to the existing AudiGEO REST API at `https://audigeo.ai/api/v1` using
an organization-level API key sent as `Authorization: Bearer <key>`. Requires
plan **Pro** or **Agency**.

---

## What's exposed (v0.1.1)

**26 tools** across 8 modules, **3 resources**, and **3 prompt templates**.
All tool names are prefixed `audigeo_` so they don't collide with tools from
other MCP servers a host might have mounted.

| Module | Tool | Type |
|---|---|---|
| `sites` | `audigeo_list_sites` | read |
| | `audigeo_get_site` | read |
| | `audigeo_create_site` | write |
| `audit` | `audigeo_list_audits` | read |
| | `audigeo_get_audit` | read (composite) |
| | `audigeo_list_recommendations` | read |
| | `audigeo_launch_audit` | write |
| `brand_profile` | `audigeo_get_brand_profile` | read |
| | `audigeo_update_brand_profile` | write |
| `monitoring` | `audigeo_get_monitoring_kpis` | read |
| | `audigeo_get_monitoring_results` | read |
| | `audigeo_get_competitors_analysis` | read |
| | `audigeo_get_citations_gap` | read |
| | `audigeo_run_monitoring_now` | write |
| `hallucinations` | `audigeo_list_hallucinations` | read |
| | `audigeo_get_hallucination_stats` | read |
| `content` | `audigeo_list_content` | read |
| | `audigeo_get_content` | read |
| | `audigeo_generate_content` | write |
| | `audigeo_generate_markdown_mirror` | write |
| `alerts` | `audigeo_list_alerts` | read |
| | `audigeo_mark_alert_read` | write |
| `workflows` | `audigeo_audit_executive_summary` | composite |
| | `audigeo_brand_safety_check` | composite |
| | `audigeo_competitive_analysis` | composite |
| | `audigeo_geo_action_plan` | composite |

**Resources** (URI-addressable, read-only): `audigeo://audits/{audit_id}`,
`audigeo://monitoring/results/{site_id}`, `audigeo://reports/{report_id}`.

**Prompts**: `geo_audit_briefing`, `monitoring_weekly_recap`,
`hallucination_response_draft` — all fr/en/es.

Set `AUDIGEO_READ_ONLY=true` to disable every write tool at startup.

---

## Configuration

| Env var | Required | Default | Purpose |
|---|---|---|---|
| `AUDIGEO_API_KEY` | yes | — | Your AudiGEO API key (`agk_...`). Generate at https://audigeo.ai → Settings → API Keys. |
| `AUDIGEO_API_URL` | no | `https://audigeo.ai/api/v1` | Override for staging / self-hosted. |
| `AUDIGEO_READ_ONLY` | no | `false` | Disable write tools. |
| `AUDIGEO_DEFAULT_SITE_ID` | no | — | UUID used when an agent omits `site_id`. |
| `AUDIGEO_TIMEOUT_S` | no | `60` | Per-request timeout. |
| `AUDIGEO_LOG_LEVEL` | no | `INFO` | DEBUG / INFO / WARNING / ERROR / CRITICAL. |

---

## Use from Claude Desktop

Install the AudiGEO `.mcpb` bundle (downloadable from Settings → Intégrations
Claude on audigeo.ai). Claude Desktop will prompt for your API key on
install — no manual config, no Python prerequisite (the bundle provisions its
own environment on first launch).

## Use from Claude Code

Two ways to install, from most to least automated:

**Via the Sponge Theory marketplace:**

```
/plugin marketplace add ezeeFlop/audigeo
/plugin install audigeo@sponge-theory
```

**Manually**, from the downloaded `audigeo-claude-code-<version>.tar.gz`
(Settings → Intégrations Claude on audigeo.ai):

```bash
mkdir -p ~/.claude/plugins
tar -xzf audigeo-claude-code-*.tar.gz -C ~/.claude/plugins/
```

Either way, the plugin's `.mcp.json` launches the server via
`uv tool run --from <plugin>/server audigeo-mcp` — **`uv` must be installed**
(https://docs.astral.sh/uv/getting-started/installation/), but no `pip
install` of `audigeo-mcp` is needed: `uv` builds and caches an isolated
environment from the bundled source on first launch.

Set your key once, then restart Claude Code:

```bash
export AUDIGEO_API_KEY=agk_...
```

## Use from any other MCP host

The server speaks MCP over stdio. Point your host at:

```bash
AUDIGEO_API_KEY=agk_... audigeo-mcp
```

---

## Development

```bash
cd mcp
uv pip install -e ".[dev]"
pytest -q
ruff check .
```

Smoke test against a local AudiGEO dev server:

```bash
export AUDIGEO_API_KEY=agk_test_$(openssl rand -hex 8)
export AUDIGEO_API_URL=http://localhost:8000/api/v1
audigeo-mcp  # then send MCP frames over stdin
```

Build all three distributable artifacts (wheel, .mcpb, Claude Code plugin):

```bash
./build/build_wheel.sh
./build/build_mcpb.sh
./build/build_plugin.sh
```

---

## License

Sponge Theory proprietary. Distribution restricted to AudiGEO subscribers.
