fiveclaw-agent 1.0.0__tar.gz

fiveclaw_agent-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: fiveclaw-agent
+Version: 1.0.0
+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.com) — 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):
+- Resource validation and health checks
+- Anti-pattern and duplicate code detection
+- Export/event flow tracing
+- AI code review and test generation
+- FiveM native docs search
+- Pattern library (scaffold new resources/features)
+
+## Requirements
+
+- Python 3.10+
+- A [FiveClaw](https://fiveclaw.com) account with an active subscription
+- A FiveClaw API key (generate one at [fiveclaw.com/dashboard/keys](https://fiveclaw.com/dashboard/keys))
+
+## Installation
+
+```bash
+pip install fiveclaw-agent
+
+# With SSH deployment support
+pip install fiveclaw-agent[ssh]
+```
+
+## Setup
+
+1. **Create a `.env` file** in your FiveM project root:
+
+```env
+FIVECLAW_API_KEY=fc_live_your_key_here
+
+# Optional — auto-detected if not set
+# FIVEM_PROJECT_ROOT=/path/to/your/server
+
+# Optional SSH deployment
+# FIVEM_SSH_HOST=1.2.3.4
+# FIVEM_SSH_USER=root
+# FIVEM_SSH_KEY_PATH=~/.ssh/id_rsa
+# FIVEM_REMOTE_RESOURCES=/server-data/resources
+```
+
+2. **Add to your Claude config** (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "fiveclaw": {
+      "url": "http://localhost:5200/mcp"
+    }
+  }
+}
+```
+
+3. **Start the agent** in your project directory:
+
+```bash
+fiveclaw
+```
+
+The agent runs on `http://localhost:5200/mcp` and stays running while you work. Restart it anytime without restarting Claude.
+
+4. **Verify** by asking Claude: *"Run mcp_health to check my FiveClaw connection."*
+
+## Configuration
+
+SSH, txAdmin, and MySQL settings can also be configured on the [FiveClaw dashboard](https://fiveclaw.com/dashboard/server) — the agent fetches them automatically using your API key, so you don't need to duplicate them in `.env`.
+
+## Links
+
+- [FiveClaw Dashboard](https://fiveclaw.com/dashboard)
+- [Setup Guide](https://fiveclaw.com/dashboard/download)
+- [Pricing](https://fiveclaw.com/pricing)

fiveclaw_agent-1.0.0/README.md

@@ -0,0 +1,89 @@
+# fiveclaw-agent
+
+Local MCP agent for [FiveClaw](https://fiveclaw.com) — 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):
+- Resource validation and health checks
+- Anti-pattern and duplicate code detection
+- Export/event flow tracing
+- AI code review and test generation
+- FiveM native docs search
+- Pattern library (scaffold new resources/features)
+
+## Requirements
+
+- Python 3.10+
+- A [FiveClaw](https://fiveclaw.com) account with an active subscription
+- A FiveClaw API key (generate one at [fiveclaw.com/dashboard/keys](https://fiveclaw.com/dashboard/keys))
+
+## Installation
+
+```bash
+pip install fiveclaw-agent
+
+# With SSH deployment support
+pip install fiveclaw-agent[ssh]
+```
+
+## Setup
+
+1. **Create a `.env` file** in your FiveM project root:
+
+```env
+FIVECLAW_API_KEY=fc_live_your_key_here
+
+# Optional — auto-detected if not set
+# FIVEM_PROJECT_ROOT=/path/to/your/server
+
+# Optional SSH deployment
+# FIVEM_SSH_HOST=1.2.3.4
+# FIVEM_SSH_USER=root
+# FIVEM_SSH_KEY_PATH=~/.ssh/id_rsa
+# FIVEM_REMOTE_RESOURCES=/server-data/resources
+```
+
+2. **Add to your Claude config** (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "fiveclaw": {
+      "url": "http://localhost:5200/mcp"
+    }
+  }
+}
+```
+
+3. **Start the agent** in your project directory:
+
+```bash
+fiveclaw
+```
+
+The agent runs on `http://localhost:5200/mcp` and stays running while you work. Restart it anytime without restarting Claude.
+
+4. **Verify** by asking Claude: *"Run mcp_health to check my FiveClaw connection."*
+
+## Configuration
+
+SSH, txAdmin, and MySQL settings can also be configured on the [FiveClaw dashboard](https://fiveclaw.com/dashboard/server) — the agent fetches them automatically using your API key, so you don't need to duplicate them in `.env`.
+
+## Links
+
+- [FiveClaw Dashboard](https://fiveclaw.com/dashboard)
+- [Setup Guide](https://fiveclaw.com/dashboard/download)
+- [Pricing](https://fiveclaw.com/pricing)

fiveclaw_agent-1.0.0/fiveclaw_agent/__init__.py

@@ -0,0 +1,2 @@
+"""FiveClaw Agent — local MCP client for FiveClaw subscribers."""
+__version__ = "1.0.0"

fiveclaw_agent-1.0.0/fiveclaw_agent/config.py

@@ -0,0 +1,89 @@
+"""Configuration for the FiveClaw Agent."""
+
+import os
+import json
+from pathlib import Path
+
+
+def load_env_file():
+    for candidate in [Path.cwd() / ".env", Path(__file__).parent.parent / ".env"]:
+        if candidate.exists():
+            with open(candidate) as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#") and "=" in line:
+                        key, value = line.split("=", 1)
+                        if key not in os.environ:
+                            os.environ[key] = value
+            break
+
+
+class Config:
+    def __init__(self):
+        load_env_file()
+
+        self.api_key = os.getenv("FIVECLAW_API_KEY", "")
+        self.api_url = os.getenv("FIVECLAW_API_URL", "https://fiveclaw.gg").rstrip("/")
+
+        if not self.api_key:
+            raise RuntimeError(
+                "FIVECLAW_API_KEY is not set.\n"
+                "Add it to your .env file: FIVECLAW_API_KEY=fc_live_...\n"
+                "Get your key at https://fiveclaw.gg/dashboard/keys"
+            )
+
+        # Local project root (auto-detected or explicit)
+        env_root = os.getenv("FIVEM_PROJECT_ROOT", "")
+        if env_root and Path(env_root).exists():
+            self.project_root = Path(env_root)
+        else:
+            self.project_root = self._detect_project_root()
+
+        resources_override = os.getenv("FIVEM_RESOURCES_DIR", "")
+        self.resources_dir = (
+            Path(resources_override)
+            if resources_override
+            else self.project_root / "resources"
+        )
+
+        self.logs_dir = self.project_root / "logs"
+        self.context_dir = self.project_root / ".fiveclaw" / "context"
+        self.context_dir.mkdir(parents=True, exist_ok=True)
+
+        # SSH (for deploy_resource)
+        self.ssh = {
+            "host":     os.getenv("FIVEM_SSH_HOST", ""),
+            "port":     int(os.getenv("FIVEM_SSH_PORT", "22")),
+            "user":     os.getenv("FIVEM_SSH_USER", ""),
+            "key_path": os.getenv("FIVEM_SSH_KEY", ""),
+        }
+
+        # MySQL (direct local connection)
+        self.mysql = {
+            "host":     os.getenv("MYSQL_HOST",     "127.0.0.1"),
+            "port":     int(os.getenv("MYSQL_PORT", "3306")),
+            "user":     os.getenv("MYSQL_USER",     ""),
+            "password": os.getenv("MYSQL_PASSWORD", ""),
+            "database": os.getenv("MYSQL_DATABASE", ""),
+        }
+
+        # txAdmin
+        self.txadmin_url   = os.getenv("TXADMIN_URL",   "http://localhost:40120")
+        self.txadmin_token = os.getenv("TXADMIN_TOKEN", "")
+
+    def has_ssh(self) -> bool:
+        return bool(self.ssh["host"] and self.ssh["user"])
+
+    def has_mysql(self) -> bool:
+        return bool(self.mysql["user"] and self.mysql["database"])
+
+    def _detect_project_root(self) -> Path:
+        check = Path.cwd()
+        for _ in range(10):
+            if (check / "resources").is_dir() and list((check / "resources").glob("*/fxmanifest.lua")):
+                return check
+            parent = check.parent
+            if parent == check:
+                break
+            check = parent
+        return Path.cwd()

fiveclaw_agent-1.0.0/fiveclaw_agent/local.py

@@ -0,0 +1,422 @@
+"""
+Local tool implementations — file I/O, SSH, MySQL, txAdmin.
+These run entirely on the user's machine. No source logic is sent to the VPS.
+"""
+
+import json
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+from .config import Config
+
+
+# ─── File collection helpers ──────────────────────────────────────────────────
+
+def collect_resource_files(resources_dir: Path, resource_name: Optional[str] = None) -> dict[str, str]:
+    """
+    Collect Lua (and JS/TS) source files from one or all resources.
+    Returns {relative_path: content} — content capped at 50 KB per file.
+    """
+    MAX_FILE = 50_000
+    files: dict[str, str] = {}
+
+    dirs = (
+        [resources_dir / resource_name]
+        if resource_name
+        else [d for d in resources_dir.iterdir() if d.is_dir()]
+    )
+
+    for rdir in dirs:
+        if not rdir.exists():
+            continue
+        for ext in ("*.lua", "*.js", "*.ts"):
+            for f in rdir.rglob(ext):
+                try:
+                    content = f.read_text(errors="ignore")
+                    if len(content) > MAX_FILE:
+                        content = content[:MAX_FILE] + "\n-- [truncated]"
+                    rel = str(f.relative_to(resources_dir.parent))
+                    files[rel] = content
+                except Exception:
+                    pass
+
+    return files
+
+
+# ─── RepoMap ──────────────────────────────────────────────────────────────────
+
+class RepoMapTool:
+    def __init__(self, config: Config):
+        self.config = config
+        self._cache_file = config.context_dir / "repomap.json"
+
+    async def generate(self) -> str:
+        if not self.config.resources_dir.exists():
+            return json.dumps({"error": f"Resources directory not found: {self.config.resources_dir}"})
+
+        resources = {}
+        for rdir in self.config.resources_dir.iterdir():
+            if not rdir.is_dir():
+                continue
+            info: dict = {"name": rdir.name, "files": [], "exports": [], "events": []}
+            for f in rdir.rglob("*.lua"):
+                info["files"].append(str(f.relative_to(rdir)))
+                try:
+                    text = f.read_text(errors="ignore")
+                    info["exports"] += re.findall(r'exports\[[\'"](.*?)[\'"]\]', text)
+                    info["events"]  += re.findall(r'RegisterNetEvent\([\'"]([^\'"]+)[\'"]', text)
+                except Exception:
+                    pass
+            resources[rdir.name] = info
+
+        result = {"resources": resources, "count": len(resources)}
+        self._cache_file.parent.mkdir(parents=True, exist_ok=True)
+        self._cache_file.write_text(json.dumps(result, indent=2))
+        return json.dumps({"success": True, "resources_count": len(resources)})
+
+    async def query(self, query_type: str, filter: Optional[str] = None) -> str:
+        if not self._cache_file.exists():
+            return json.dumps({"error": "Run repomap_generate first."})
+        data = json.loads(self._cache_file.read_text())
+        resources = data.get("resources", {})
+
+        if filter:
+            resources = {k: v for k, v in resources.items() if filter.lower() in k.lower()}
+
+        if query_type == "exports":
+            out = {k: v.get("exports", []) for k, v in resources.items()}
+        elif query_type == "events":
+            out = {k: v.get("events", []) for k, v in resources.items()}
+        elif query_type == "files":
+            out = {k: v.get("files", []) for k, v in resources.items()}
+        else:
+            out = resources
+
+        return json.dumps(out, indent=2)
+
+    async def show(self) -> str:
+        if not self._cache_file.exists():
+            return json.dumps({"error": "Run repomap_generate first."})
+        return self._cache_file.read_text()
+
+
+# ─── Search / File info ───────────────────────────────────────────────────────
+
+class FileTool:
+    def __init__(self, config: Config):
+        self.config = config
+
+    async def search(self, pattern: str, path: Optional[str] = None) -> str:
+        search_path = Path(path) if path else self.config.resources_dir
+        if not search_path.exists():
+            return json.dumps({"error": f"Path not found: {search_path}"})
+
+        matches = []
+        for ext in ("*.lua", "*.js", "*.ts", "*.json"):
+            for f in search_path.rglob(ext):
+                try:
+                    for i, line in enumerate(f.read_text(errors="ignore").splitlines(), 1):
+                        if re.search(pattern, line, re.IGNORECASE):
+                            matches.append({
+                                "file": str(f.relative_to(search_path)),
+                                "line": i,
+                                "content": line.strip()[:200],
+                            })
+                            if len(matches) >= 100:
+                                return json.dumps({"matches": matches, "truncated": True})
+                except Exception:
+                    pass
+
+        return json.dumps({"matches": matches, "count": len(matches)})
+
+    async def file_info(self, file_path: str) -> str:
+        p = Path(file_path)
+        if not p.exists():
+            p = self.config.project_root / file_path
+        if not p.exists():
+            return json.dumps({"error": f"File not found: {file_path}"})
+
+        stat = p.stat()
+        try:
+            lines = len(p.read_text(errors="ignore").splitlines())
+        except Exception:
+            lines = None
+
+        return json.dumps({
+            "path": str(p),
+            "size_bytes": stat.st_size,
+            "lines": lines,
+            "modified": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(stat.st_mtime)),
+        })
+
+    async def syntax_check(self, file_path: str) -> str:
+        p = Path(file_path)
+        if not p.exists():
+            p = self.config.resources_dir / file_path
+        if not p.exists():
+            return json.dumps({"error": f"File not found: {file_path}"})
+
+        result = subprocess.run(["luac", "-p", str(p)], capture_output=True, text=True)
+        if result.returncode == 0:
+            return json.dumps({"valid": True, "file": str(p)})
+        return json.dumps({"valid": False, "error": result.stderr.strip()})
+
+    async def read_logs(self, lines: int = 100, pattern: Optional[str] = None) -> str:
+        if not self.config.logs_dir.exists():
+            return json.dumps({"error": f"Logs directory not found: {self.config.logs_dir}"})
+
+        log_files = sorted(self.config.logs_dir.glob("*.log"), key=lambda f: f.stat().st_mtime, reverse=True)
+        if not log_files:
+            return json.dumps({"error": "No log files found."})
+
+        latest = log_files[0]
+        all_lines = latest.read_text(errors="ignore").splitlines()[-lines:]
+        if pattern:
+            all_lines = [l for l in all_lines if re.search(pattern, l, re.IGNORECASE)]
+
+        return json.dumps({"file": latest.name, "lines": all_lines, "count": len(all_lines)})
+
+
+# ─── MySQL ────────────────────────────────────────────────────────────────────
+
+class MySQLTool:
+    def __init__(self, config: Config):
+        self.config = config
+
+    async def query(self, query: str) -> str:
+        if not self.config.has_mysql():
+            return json.dumps({
+                "error": "MySQL not configured.",
+                "setup": "Set MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE in your .env",
+            })
+
+        result = subprocess.run(["which", "mysql"], capture_output=True)
+        if result.returncode != 0:
+            return json.dumps({"error": "mysql client not installed."})
+
+        db = self.config.mysql
+        cmd = [
+            "mysql",
+            "-h", db["host"],
+            "-P", str(db["port"]),
+            "-u", db["user"],
+            f"-p{db['password']}",
+            "-N", "-e", query, db["database"],
+        ]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            return json.dumps({"error": result.stderr.strip()})
+
+        rows = [line.split("\t") for line in result.stdout.strip().splitlines() if line]
+        return json.dumps({"success": True, "rows": rows, "count": len(rows), "database": db["database"]})
+
+
+# ─── txAdmin ──────────────────────────────────────────────────────────────────
+
+class TxAdminTool:
+    def __init__(self, config: Config):
+        self.config = config
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self.config.txadmin_token:
+            h["X-TxAdmin-Token"] = self.config.txadmin_token
+        return h
+
+    async def server_status(self) -> str:
+        import urllib.request, urllib.error
+        try:
+            req = urllib.request.Request(
+                f"{self.config.txadmin_url}/api/server/status",
+                headers=self._headers(),
+            )
+            with urllib.request.urlopen(req, timeout=5) as r:
+                return r.read().decode()
+        except Exception as e:
+            return json.dumps({"error": str(e), "hint": f"Is txAdmin running at {self.config.txadmin_url}?"})
+
+    async def resource_control(self, action: str, resource_name: str) -> str:
+        import urllib.request
+        payload = json.dumps({"action": action, "resource": resource_name}).encode()
+        req = urllib.request.Request(
+            f"{self.config.txadmin_url}/api/server-control/command",
+            data=payload,
+            headers=self._headers(),
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as r:
+                return r.read().decode()
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+    async def server_console(self, command: str) -> str:
+        import urllib.request
+        payload = json.dumps({"command": command}).encode()
+        req = urllib.request.Request(
+            f"{self.config.txadmin_url}/api/server-control/command",
+            data=payload,
+            headers=self._headers(),
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as r:
+                return r.read().decode()
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+
+# ─── Deploy ───────────────────────────────────────────────────────────────────
+
+class DeployTool:
+    def __init__(self, config: Config):
+        self.config = config
+
+    async def deploy(self, resource_name: str, target: str = "production") -> str:
+        source = self.config.resources_dir / resource_name
+        if not source.exists():
+            return json.dumps({"error": f"Resource not found: {resource_name}"})
+
+        if self.config.has_ssh():
+            return await self._deploy_ssh(resource_name, source)
+
+        # Local copy
+        remote_res = os.getenv("FIVEM_REMOTE_RESOURCES_DIR", str(self.config.resources_dir))
+        target_path = (
+            Path(remote_res) / resource_name
+            if target in ("production", "txdata")
+            else Path(target) / resource_name
+        )
+
+        import shutil
+        backup_dir = self.config.project_root / "backups" / "deploy"
+        backup_dir.mkdir(parents=True, exist_ok=True)
+        backup_path = backup_dir / f"{resource_name}_{time.strftime('%Y%m%d_%H%M%S')}"
+
+        if target_path.exists():
+            shutil.copytree(target_path, backup_path)
+            shutil.rmtree(target_path)
+
+        shutil.copytree(source, target_path)
+        return json.dumps({
+            "success": True, "resource": resource_name,
+            "target": str(target_path), "method": "local",
+        })
+
+    async def _deploy_ssh(self, resource_name: str, source: Path) -> str:
+        try:
+            import paramiko
+        except ImportError:
+            return json.dumps({"error": "paramiko not installed. Run: pip install fiveclaw-agent[ssh]"})
+
+        remote_res = os.getenv("FIVEM_REMOTE_RESOURCES_DIR", "")
+        if not remote_res:
+            return json.dumps({"error": "FIVEM_REMOTE_RESOURCES_DIR not set."})
+
+        ssh_cfg = self.config.ssh
+        remote_target = f"{remote_res.rstrip('/')}/{resource_name}"
+
+        try:
+            client = paramiko.SSHClient()
+            client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+            kw: dict = {"hostname": ssh_cfg["host"], "port": ssh_cfg["port"], "username": ssh_cfg["user"]}
+            if ssh_cfg.get("key_path"):
+                kw["key_filename"] = ssh_cfg["key_path"]
+            client.connect(**kw, timeout=15)
+            sftp = client.open_sftp()
+
+            def _upload(local: Path, remote: str):
+                try: sftp.mkdir(remote)
+                except OSError: pass
+                for item in local.iterdir():
+                    r = f"{remote}/{item.name}"
+                    if item.is_dir(): _upload(item, r)
+                    else: sftp.put(str(item), r)
+
+            client.exec_command(f"rm -rf '{remote_target}'")[1].channel.recv_exit_status()
+            _upload(source, remote_target)
+            sftp.close(); client.close()
+            return json.dumps({"success": True, "resource": resource_name, "target": remote_target,
+                               "host": ssh_cfg["host"], "method": "ssh"})
+        except Exception as e:
+            return json.dumps({"error": f"SSH deploy failed: {e}"})
+
+    async def backup(self, resource_name: str) -> str:
+        source = self.config.resources_dir / resource_name
+        if not source.exists():
+            return json.dumps({"error": f"Resource not found: {resource_name}"})
+
+        import shutil
+        backup_dir = self.config.project_root / "backups" / "resources"
+        backup_dir.mkdir(parents=True, exist_ok=True)
+        ts = time.strftime("%Y%m%d_%H%M%S")
+        dest = backup_dir / f"{resource_name}_{ts}"
+        shutil.copytree(source, dest)
+        return json.dumps({"success": True, "backup": str(dest), "timestamp": ts})
+
+
+# ─── Context memory ───────────────────────────────────────────────────────────
+
+class ContextTool:
+    def __init__(self, config: Config):
+        self._file = config.context_dir / "knowledge.json"
+        self._ensure()
+
+    def _ensure(self):
+        self._file.parent.mkdir(parents=True, exist_ok=True)
+        if not self._file.exists():
+            self._file.write_text(json.dumps({"facts": {}, "history": []}))
+
+    def _load(self) -> dict:
+        return json.loads(self._file.read_text())
+
+    def _save(self, data: dict):
+        self._file.write_text(json.dumps(data, indent=2))
+
+    async def remember(self, key: str, value: str, category: str = "general") -> str:
+        data = self._load()
+        data["facts"][key] = {"value": value, "category": category, "ts": time.strftime("%Y-%m-%d %H:%M:%S")}
+        self._save(data)
+        return json.dumps({"saved": key})
+
+    async def recall(self, key: Optional[str] = None) -> str:
+        data = self._load()
+        if key:
+            return json.dumps(data["facts"].get(key, {"error": "Not found"}))
+        return json.dumps(data["facts"], indent=2)
+
+    async def search(self, query: str) -> str:
+        data = self._load()
+        q = query.lower()
+        hits = {k: v for k, v in data["facts"].items()
+                if q in k.lower() or q in str(v.get("value", "")).lower()}
+        return json.dumps(hits, indent=2)
+
+    async def forget(self, key: str) -> str:
+        data = self._load()
+        if key in data["facts"]:
+            del data["facts"][key]
+            self._save(data)
+            return json.dumps({"deleted": key})
+        return json.dumps({"error": f"Key not found: {key}"})
+
+    async def record(self, summary: str, tags: str) -> str:
+        data = self._load()
+        data.setdefault("history", []).append({
+            "summary": summary, "tags": tags.split(","),
+            "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+        })
+        data["history"] = data["history"][-200:]
+        self._save(data)
+        return json.dumps({"recorded": True})
+
+    async def history(self, limit: int = 10) -> str:
+        data = self._load()
+        return json.dumps(data.get("history", [])[-limit:], indent=2)
+
+    async def show(self) -> str:
+        return self._file.read_text()

fiveclaw_agent-1.0.0/fiveclaw_agent/remote.py

@@ -0,0 +1,56 @@
+"""HTTP client — sends tool calls to the FiveClaw VPS for processing."""
+
+import json
+import urllib.request
+import urllib.error
+from typing import Any
+
+
+class RemoteClient:
+    """Authenticated relay to the FiveClaw VPS intelligence API."""
+
+    def __init__(self, api_key: str, api_url: str):
+        self.api_key = api_key
+        self.api_url = api_url
+
+    def call(self, tool: str, params: dict, files: dict[str, str] | None = None) -> str:
+        """
+        POST to /api/mcp/tools with the tool name, params, and optional file content.
+        Returns the raw JSON string result.
+        """
+        payload = {
+            "tool":   tool,
+            "params": params,
+            "files":  files or {},
+        }
+
+        data = json.dumps(payload).encode()
+        req = urllib.request.Request(
+            f"{self.api_url}/api/mcp/tools",
+            data=data,
+            headers={
+                "Content-Type":  "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+            },
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                return resp.read().decode()
+        except urllib.error.HTTPError as e:
+            body = e.read().decode()
+            try:
+                err = json.loads(body)
+            except Exception:
+                err = {"error": body}
+
+            if e.code == 401:
+                return json.dumps({"error": "Invalid or expired API key. Check your FIVECLAW_API_KEY."})
+            if e.code == 402:
+                return json.dumps({"error": "Subscription required. Visit https://fiveclaw.gg/pricing"})
+            if e.code == 403:
+                return json.dumps({"error": err.get("error", "Access denied — your plan may not include this tool.")})
+            return json.dumps({"error": f"API error {e.code}: {err.get('error', body[:200])}"})
+        except Exception as e:
+            return json.dumps({"error": f"Could not reach FiveClaw API: {str(e)}"})

fiveclaw_agent-1.0.0/fiveclaw_agent/server.py

@@ -0,0 +1,302 @@
+"""
+FiveClaw Agent — local MCP server.
+
+Users run this on their machine and add it to their Claude Desktop config:
+  { "fiveclaw": { "url": "http://localhost:5200/mcp" } }
+
+Local tools (file I/O, SSH, MySQL, txAdmin) run on the user's machine.
+Intelligence tools (analysis, AI review, docs, patterns) relay to the FiveClaw VPS.
+The VPS logic is never distributed — only results come back.
+"""
+
+import os
+from typing import Optional
+from fastmcp import FastMCP
+
+from .config import Config
+from .local import RepoMapTool, FileTool, MySQLTool, TxAdminTool, DeployTool, ContextTool, collect_resource_files
+from .remote import RemoteClient
+
+# ─── Boot ─────────────────────────────────────────────────────────────────────
+
+try:
+    config = Config()
+except RuntimeError as e:
+    import sys
+    print(f"[FiveClaw Agent] Configuration error:\n{e}", file=sys.stderr)
+    sys.exit(1)
+
+remote  = RemoteClient(config.api_key, config.api_url)
+repomap = RepoMapTool(config)
+files   = FileTool(config)
+mysql   = MySQLTool(config)
+txadmin = TxAdminTool(config)
+deploy  = DeployTool(config)
+context = ContextTool(config)
+
+server = FastMCP("fiveclaw-agent")
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+def _resource_files(resource: Optional[str] = None) -> dict:
+    """Collect local source files to send to the VPS for analysis."""
+    return collect_resource_files(config.resources_dir, resource)
+
+# =============================================================================
+# LOCAL TOOLS — run on the user's machine
+# =============================================================================
+
+@server.tool()
+async def repomap_generate() -> str:
+    """Scan your FiveM resources directory and build a map of all resources,
+    their files, exports, and event handlers. Run this first."""
+    return await repomap.generate()
+
+@server.tool()
+async def repomap_query(query_type: str, filter: Optional[str] = None) -> str:
+    """Query the resource map. query_type: 'exports', 'events', 'files', or 'all'."""
+    return await repomap.query(query_type, filter)
+
+@server.tool()
+async def repomap_show() -> str:
+    """Show the full resource map JSON."""
+    return await repomap.show()
+
+@server.tool()
+async def tool_search(pattern: str, path: Optional[str] = None) -> str:
+    """Search for a regex pattern across all Lua/JS files in your resources."""
+    return await files.search(pattern, path)
+
+@server.tool()
+async def tool_file_info(file_path: str) -> str:
+    """Get file size, line count, and last modified time."""
+    return await files.file_info(file_path)
+
+@server.tool()
+async def tool_syntax_check(file_path: str) -> str:
+    """Check Lua syntax using luac. Requires luac installed locally."""
+    return await files.syntax_check(file_path)
+
+@server.tool()
+async def read_latest_logs(lines: int = 100, pattern: Optional[str] = None) -> str:
+    """Read the latest FiveM server log file."""
+    return await files.read_logs(lines, pattern)
+
+@server.tool()
+async def tool_mysql_query(query: str) -> str:
+    """Execute a SQL query against your locally configured MySQL database."""
+    return await mysql.query(query)
+
+@server.tool()
+async def tool_server_status() -> str:
+    """Check FiveM server status via your txAdmin panel."""
+    return await txadmin.server_status()
+
+@server.tool()
+async def tool_resource_control(action: str, resource_name: str) -> str:
+    """Start, stop, or restart a resource via txAdmin. action: 'start'|'stop'|'restart'."""
+    return await txadmin.resource_control(action, resource_name)
+
+@server.tool()
+async def tool_server_console(command: str) -> str:
+    """Send a raw command to the FiveM server console via txAdmin."""
+    return await txadmin.server_console(command)
+
+@server.tool()
+async def deploy_resource(resource_name: str, target: str = "production") -> str:
+    """Deploy a resource to your FiveM server.
+    Uses SSH if FIVEM_SSH_HOST is configured, otherwise local file copy.
+    target: 'production' or an absolute path."""
+    return await deploy.deploy(resource_name, target)
+
+@server.tool()
+async def backup_resource(resource_name: str) -> str:
+    """Create a timestamped backup of a resource in your project's backups/ folder."""
+    return await deploy.backup(resource_name)
+
+# Context memory
+@server.tool()
+async def context_remember(key: str, value: str, category: str = "general") -> str:
+    """Save a fact to persistent local memory."""
+    return await context.remember(key, value, category)
+
+@server.tool()
+async def context_recall(key: Optional[str] = None) -> str:
+    """Recall a saved fact, or list all facts if no key given."""
+    return await context.recall(key)
+
+@server.tool()
+async def context_search(query: str) -> str:
+    """Search your saved facts."""
+    return await context.search(query)
+
+@server.tool()
+async def context_forget(key: str) -> str:
+    """Delete a saved fact."""
+    return await context.forget(key)
+
+@server.tool()
+async def context_record(summary: str, tags: str) -> str:
+    """Record a session note (comma-separated tags)."""
+    return await context.record(summary, tags)
+
+@server.tool()
+async def context_history(limit: int = 10) -> str:
+    """Show recent session history."""
+    return await context.history(limit)
+
+# =============================================================================
+# REMOTE TOOLS — relay to FiveClaw VPS (your logic stays server-side)
+# =============================================================================
+
+@server.tool()
+async def tool_validate_resource(resource_name: str) -> str:
+    """Validate a FiveM resource — checks manifest, syntax, structure, and best practices."""
+    return remote.call("validate_resource", {"resource_name": resource_name},
+                       files=_resource_files(resource_name))
+
+@server.tool()
+async def resource_health_check(resource_name: str) -> str:
+    """Comprehensive health check: manifest, syntax, NUI build, TODOs, dependencies."""
+    return remote.call("resource_health_check", {"resource_name": resource_name},
+                       files=_resource_files(resource_name))
+
+@server.tool()
+async def detect_anti_patterns(resource: Optional[str] = None) -> str:
+    """Detect common FiveM anti-patterns: busy waits, missing locals, performance issues."""
+    return remote.call("detect_anti_patterns", {"resource": resource},
+                       files=_resource_files(resource))
+
+@server.tool()
+async def detect_duplicate_code(min_lines: int = 10, resource: Optional[str] = None) -> str:
+    """Find duplicate or copy-pasted code blocks across your resources."""
+    return remote.call("detect_duplicate_code", {"min_lines": min_lines, "resource": resource},
+                       files=_resource_files(resource))
+
+@server.tool()
+async def find_exports(export_name: Optional[str] = None, resource: Optional[str] = None) -> str:
+    """Find where exports are defined and called across your resources."""
+    return remote.call("find_exports", {"export_name": export_name, "resource": resource},
+                       files=_resource_files(resource))
+
+@server.tool()
+async def find_event_handlers(event_name: Optional[str] = None, resource: Optional[str] = None) -> str:
+    """Find RegisterNetEvent and AddEventHandler calls."""
+    return remote.call("find_event_handlers", {"event_name": event_name, "resource": resource},
+                       files=_resource_files(resource))
+
+@server.tool()
+async def find_triggers(pattern: Optional[str] = None, resource: Optional[str] = None) -> str:
+    """Find TriggerServerEvent and TriggerClientEvent calls."""
+    return remote.call("find_triggers", {"pattern": pattern, "resource": resource},
+                       files=_resource_files(resource))
+
+@server.tool()
+async def nui_build_check(resource_name: str) -> str:
+    """Check if a NUI resource needs to be rebuilt."""
+    return remote.call("nui_build_check", {"resource_name": resource_name},
+                       files=_resource_files(resource_name))
+
+@server.tool()
+async def test_resource(resource_name: str, mode: str = "auto") -> str:
+    """Test a FiveM resource using the FiveClaw test engine. mode: 'auto' or 'analyze'."""
+    return remote.call("test_resource", {"resource_name": resource_name, "mode": mode},
+                       files=_resource_files(resource_name))
+
+@server.tool()
+async def test_generate(resource_name: str) -> str:
+    """Generate test cases for a resource without running them."""
+    return remote.call("test_generate", {"resource_name": resource_name},
+                       files=_resource_files(resource_name))
+
+@server.tool()
+async def trace_event_flow(event_name: str, max_depth: int = 3) -> str:
+    """Trace how an event flows through your resources."""
+    return remote.call("trace_event_flow", {"event_name": event_name, "max_depth": max_depth},
+                       files=_resource_files())
+
+@server.tool()
+async def analyze_export_usage(caller: str, target: str, export_name: Optional[str] = None) -> str:
+    """Analyze how a resource uses another resource's exports."""
+    return remote.call("analyze_export_usage",
+                       {"caller": caller, "target": target, "export_name": export_name},
+                       files=_resource_files())
+
+@server.tool()
+async def mysql_visualize_schema() -> str:
+    """Visualize your database schema as an ASCII diagram."""
+    return remote.call("mysql_visualize_schema", {})
+
+@server.tool()
+async def pattern_list() -> str:
+    """List all available FiveM code patterns in the FiveClaw pattern library."""
+    return remote.call("pattern_list", {})
+
+@server.tool()
+async def pattern_show(pattern_name: str) -> str:
+    """Show the full code for a pattern from the FiveClaw library."""
+    return remote.call("pattern_show", {"pattern_name": pattern_name})
+
+@server.tool()
+async def pattern_apply(pattern_name: str, variables_json: str,
+                        output_dir: Optional[str] = None, dry_run: bool = False) -> str:
+    """Apply a FiveClaw code pattern to scaffold a new resource or feature."""
+    return remote.call("pattern_apply",
+                       {"pattern_name": pattern_name, "variables_json": variables_json,
+                        "output_dir": output_dir, "dry_run": dry_run})
+
+@server.tool()
+async def fivem_docs(query: str) -> str:
+    """Search the FiveM native documentation, scripting guides, and framework references."""
+    return remote.call("fivem_docs", {"query": query})
+
+@server.tool()
+async def fivem_native(native_name: str) -> str:
+    """Get detailed information about a FiveM native function."""
+    return remote.call("fivem_native", {"native_name": native_name})
+
+@server.tool()
+async def mcp_health() -> str:
+    """Check agent status and verify your FiveClaw API key is valid."""
+    import json as _json
+    result = remote.call("mcp_health", {})
+    try:
+        data = _json.loads(result)
+        data["agent_version"] = "1.0.0"
+        data["project_root"] = str(config.project_root)
+        data["resources_dir"] = str(config.resources_dir)
+        data["ssh_configured"] = config.has_ssh()
+        data["mysql_configured"] = config.has_mysql()
+        return _json.dumps(data, indent=2)
+    except Exception:
+        return result
+
+# =============================================================================
+# Entry point
+# =============================================================================
+
+def main():
+    import signal, sys
+
+    def _stop(sig, frame):
+        print("\n[FiveClaw Agent] Shutting down.", file=sys.stderr)
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _stop)
+    signal.signal(signal.SIGTERM, _stop)
+
+    transport = os.getenv("TRANSPORT", "streamable-http")
+    host = os.getenv("HOST", "127.0.0.1")   # localhost only by default
+    port = int(os.getenv("PORT", "5200"))
+
+    print(f"[FiveClaw Agent] Starting on {transport}://{host}:{port}/mcp", file=sys.stderr)
+    print(f"[FiveClaw Agent] Project root: {config.project_root}", file=sys.stderr)
+
+    if transport == "streamable-http":
+        server.run(transport="streamable-http", host=host, port=port)
+    else:
+        server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

fiveclaw_agent-1.0.0/fiveclaw_agent.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: fiveclaw-agent
+Version: 1.0.0
+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.com) — 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):
+- Resource validation and health checks
+- Anti-pattern and duplicate code detection
+- Export/event flow tracing
+- AI code review and test generation
+- FiveM native docs search
+- Pattern library (scaffold new resources/features)
+
+## Requirements
+
+- Python 3.10+
+- A [FiveClaw](https://fiveclaw.com) account with an active subscription
+- A FiveClaw API key (generate one at [fiveclaw.com/dashboard/keys](https://fiveclaw.com/dashboard/keys))
+
+## Installation
+
+```bash
+pip install fiveclaw-agent
+
+# With SSH deployment support
+pip install fiveclaw-agent[ssh]
+```
+
+## Setup
+
+1. **Create a `.env` file** in your FiveM project root:
+
+```env
+FIVECLAW_API_KEY=fc_live_your_key_here
+
+# Optional — auto-detected if not set
+# FIVEM_PROJECT_ROOT=/path/to/your/server
+
+# Optional SSH deployment
+# FIVEM_SSH_HOST=1.2.3.4
+# FIVEM_SSH_USER=root
+# FIVEM_SSH_KEY_PATH=~/.ssh/id_rsa
+# FIVEM_REMOTE_RESOURCES=/server-data/resources
+```
+
+2. **Add to your Claude config** (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "fiveclaw": {
+      "url": "http://localhost:5200/mcp"
+    }
+  }
+}
+```
+
+3. **Start the agent** in your project directory:
+
+```bash
+fiveclaw
+```
+
+The agent runs on `http://localhost:5200/mcp` and stays running while you work. Restart it anytime without restarting Claude.
+
+4. **Verify** by asking Claude: *"Run mcp_health to check my FiveClaw connection."*
+
+## Configuration
+
+SSH, txAdmin, and MySQL settings can also be configured on the [FiveClaw dashboard](https://fiveclaw.com/dashboard/server) — the agent fetches them automatically using your API key, so you don't need to duplicate them in `.env`.
+
+## Links
+
+- [FiveClaw Dashboard](https://fiveclaw.com/dashboard)
+- [Setup Guide](https://fiveclaw.com/dashboard/download)
+- [Pricing](https://fiveclaw.com/pricing)

fiveclaw_agent-1.0.0/fiveclaw_agent.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+fiveclaw_agent/__init__.py
+fiveclaw_agent/config.py
+fiveclaw_agent/local.py
+fiveclaw_agent/remote.py
+fiveclaw_agent/server.py
+fiveclaw_agent.egg-info/PKG-INFO
+fiveclaw_agent.egg-info/SOURCES.txt
+fiveclaw_agent.egg-info/dependency_links.txt
+fiveclaw_agent.egg-info/entry_points.txt
+fiveclaw_agent.egg-info/requires.txt
+fiveclaw_agent.egg-info/top_level.txt

fiveclaw_agent-1.0.0/fiveclaw_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fiveclaw_agent-1.0.0/fiveclaw_agent.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fiveclaw = fiveclaw_agent.server:main

fiveclaw_agent-1.0.0/fiveclaw_agent.egg-info/requires.txt

@@ -0,0 +1,4 @@
+fastmcp>=3.0
+
+[ssh]
+paramiko>=3.0

fiveclaw_agent-1.0.0/fiveclaw_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+fiveclaw_agent

fiveclaw_agent-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fiveclaw-agent"
+version = "1.0.0"
+description = "Local MCP agent for FiveClaw — FiveM AI development tools"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=3.0",
+]
+
+[project.optional-dependencies]
+ssh = ["paramiko>=3.0"]
+
+[project.scripts]
+fiveclaw = "fiveclaw_agent.server:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["fiveclaw_agent*"]

fiveclaw_agent-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+