Metadata-Version: 2.4
Name: fiveclaw-agent
Version: 1.0.6
Summary: Local MCP agent for FiveClaw — FiveM AI development tools
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.0
Provides-Extra: ssh
Requires-Dist: paramiko>=3.0; extra == "ssh"

# fiveclaw-agent

Local MCP agent for [FiveClaw](https://fiveclaw.xyz) — AI-powered FiveM development tools.

## What it does

`fiveclaw-agent` runs on your machine alongside your FiveM server. It handles local operations (file search, logs, MySQL, txAdmin, SSH deploy) and relays AI analysis requests to the FiveClaw platform using your API key.

**Local tools** (run on your machine):
- Resource map generation and querying
- File search across Lua/JS resources
- Lua syntax checking
- Log reading
- MySQL query execution
- txAdmin server control (start/stop/restart resources, send console commands)
- SSH deployment to remote servers
- Persistent context memory

**Cloud tools** (powered by FiveClaw, gated by your plan):

*fivem-mcp (all plans):*
- FiveM native docs — 6,400+ native functions
- ESX, QBCore, ox_lib & ox_core framework docs
- Best practices, anti-pattern guides, error solutions
- Live CFX documentation fetch

*ai-fivem-dev-mcp (Pro + Enterprise):*
- Resource validation and health checks
- Anti-pattern and duplicate code detection
- Security scanner — injection, auth & logic vulnerabilities
- Export contract validation and NUI completeness checks
- Event tracer — trace any event from trigger to handler
- Find exports, event handlers, and triggers across your codebase
- Full test engine — unit, event, database, and coverage tests
- Auto-generate test stubs from existing code
- Pattern library — scaffold new resources from reusable templates
- Load order validator and dependency graph (Enterprise)
- Team patterns — shared scaffolds across your whole team (Enterprise)

## Requirements

- Python 3.10+
- A [FiveClaw](https://fiveclaw.xyz) account with an active subscription
- A FiveClaw API key (generate one at [fiveclaw.xyz/dashboard/keys](https://fiveclaw.xyz/dashboard/keys))

## Installation

```bash
pip install fiveclaw-agent

# With SSH deployment support
pip install fiveclaw-agent[ssh]
```

## Setup

The interactive setup guide at [fiveclaw.xyz/dashboard/download](https://fiveclaw.xyz/dashboard/download) generates your config automatically. The steps below cover it manually.

### Step 1 — Install

```bash
pip install fiveclaw-agent

# Optional: SSH deployment support
pip install fiveclaw-agent[ssh]
```

### Step 2 — Configure your server (optional)

All settings go directly in your AI client's MCP config as `env` variables. Nothing is sent to FiveClaw — credentials stay on your machine. Only `FIVECLAW_API_KEY` is required; everything else is optional.

### Step 3 — Add to your AI client

Add the following to your AI client's MCP config file. Replace placeholder values with your own and remove any lines you don't use.

| Client | Config file |
|---|---|
| Claude Code | Project: `.mcp.json` · Global: `~/.claude.json` |
| Cursor | Project: `.cursor/mcp.json` · Global: `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Kilo Code | Project: `.kilocode/mcp.json` · Global: extension settings |
| Gemini CLI | `~/.gemini/settings.json` — merge `mcpServers` into the existing file |

```json
{
  "mcpServers": {
    "fiveclaw": {
      "command": "fiveclaw-agent",
      "env": {
        "FIVECLAW_API_KEY": "fc_live_YOUR_API_KEY_HERE",
        "FIVEM_PROJECT_ROOT": "/path/to/your/fivem-server",
        "FIVEM_RESOURCES_DIR": "/path/to/your/fivem-server/resources",
        "FIVEM_SSH_HOST": "YOUR_SERVER_IP",
        "FIVEM_SSH_USER": "root",
        "FIVEM_SSH_KEY": "~/.ssh/id_rsa",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "YOUR_MYSQL_PASSWORD",
        "MYSQL_DATABASE": "fivem",
        "TXADMIN_URL": "http://localhost:40120",
        "TXADMIN_USER": "admin",
        "TXADMIN_PASS": "YOUR_TXADMIN_PASSWORD"
      }
    }
  }
}
```

Restart your AI client after saving the config.

### Step 4 — Verify

Ask your AI client: *"Run mcp_health to check my FiveClaw connection."*

This confirms the agent is running, your API key is valid, and all configured tools are active.

## Links

- [FiveClaw Dashboard](https://fiveclaw.xyz/dashboard)
- [Setup Guide](https://fiveclaw.xyz/dashboard/download)
- [Pricing](https://fiveclaw.xyz/pricing)
