feat: add txAdmin integration tools and skill

Add four MCP tools that drive a running txAdmin panel over HTTP:
txadmin_server_control, txadmin_resource_control, txadmin_player_search,
and txadmin_kick_player. A dependency-free client (urllib + cookiejar)
authenticates via POST /auth/password, stores the session cookie, and
echoes the csrfToken in the x-txadmin-csrftoken header. Credentials are
read only from TXADMIN_URL / TXADMIN_USERNAME / TXADMIN_PASSWORD.

Add the txadmin-integration skill and update README, CLAUDE.md, docs
(index, getting-started, architecture), and ROADMAP counts and tables
(10 skills, 10 MCP tools). Extend the CI py_compile list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -29,7 +29,8 @@
     "skills/performance-optimization/SKILL.md",
     "skills/nui-development/SKILL.md",
     "skills/database-integration/SKILL.md",
-    "skills/state-bags/SKILL.md"
+    "skills/state-bags/SKILL.md",
+    "skills/txadmin-integration/SKILL.md"
   ],
   "rules": [
     "rules/cfx-lua-conventions.mdc",

.github/workflows/validate.yml

@@ -256,3 +256,5 @@ jobs:
           python3 -m py_compile mcp-server/tools/event_search.py
           python3 -m py_compile mcp-server/tools/docs_search.py
           python3 -m py_compile mcp-server/tools/detect_framework.py
+          python3 -m py_compile mcp-server/tools/txadmin_client.py
+          python3 -m py_compile mcp-server/tools/txadmin.py

CLAUDE.md

@@ -6,7 +6,7 @@ Project documentation for Claude Code and AI assistants working on this reposito
 
 ## Project Overview
 
-CFX Developer Tools is a Cursor IDE plugin for FiveM and RedM (CFX) resource development. It includes 9 skills, 6 rules, 24 code snippets, 11 starter templates, and a companion Python MCP server with 6 tools for resource scaffolding, native lookup, manifest generation, framework detection, and live doc and event search.
+CFX Developer Tools is a Cursor IDE plugin for FiveM and RedM (CFX) resource development. It includes 10 skills, 6 rules, 24 code snippets, 11 starter templates, and a companion Python MCP server with 10 tools for resource scaffolding, native lookup, manifest generation, framework detection, live doc and event search, and txAdmin server control.
 
 **Works with:** Cursor (plugin), Claude Code (terminal and in-editor), and any MCP-compatible client.
 
@@ -40,7 +40,7 @@ CFX-Developer-Tools/
     workflows/               # CI / release / native-update / docs-index automation
 ```
 
-## Skills (9)
+## Skills (10)
 
 | Skill | Description |
 |-------|-------------|
@@ -53,6 +53,7 @@ CFX-Developer-Tools/
 | `nui-development` | NUI lifecycle, message routing, asset loading, callbacks, and Vite / Svelte integration |
 | `database-integration` | oxmysql, ghmattimysql, MariaDB connection patterns, prepared statements, migration flow |
 | `state-bags` | StateBag CRUD, replicated vs local, change handlers, and replacement of legacy SetX patterns |
+| `txadmin-integration` | Control a running server, manage resources, search players, and kick players through the txAdmin API |
 
 ## Rules (6)
 
@@ -65,9 +66,9 @@ CFX-Developer-Tools/
 | `security-best-practices.mdc` | Global | Flag hardcoded API keys, server-trust violations, unsafe NUI callbacks, missing input validation |
 | `performance-rules.mdc` | CFX resource files | Flag thread blockers, unbounded loops, missing `Wait()` in `CreateThread`, expensive natives in tight loops |
 
-## MCP Server (6 tools)
+## MCP Server (10 tools)
 
-The companion MCP server is Python-based (FastMCP). It exposes CFX-aware tools that read from local data files (`mcp-server/data/`) and the working tree.
+The companion MCP server is Python-based (FastMCP). It exposes CFX-aware tools that read from local data files (`mcp-server/data/`) and the working tree. The txAdmin tools additionally talk to a running txAdmin panel over HTTP, using credentials from the `TXADMIN_URL` / `TXADMIN_USERNAME` / `TXADMIN_PASSWORD` environment variables.
 
 | Tool | Description |
 |------|-------------|
@@ -77,6 +78,10 @@ The companion MCP server is Python-based (FastMCP). It exposes CFX-aware tools t
 | `search_events_tool` | Search the indexed CFX events database for canonical net-event and exports usage patterns |
 | `detect_framework_tool` | Detect ESX / QBCore / Qbox / ox_core / VORP / RSG / standalone from a workspace path |
 | `search_docs_tool` | Search the indexed `docs.fivem.net` snapshot for parameters, gotchas, and code samples |
+| `txadmin_server_control_tool` | Start, stop, or restart the FXServer through a running txAdmin panel |
+| `txadmin_resource_control_tool` | Start, stop, restart, or ensure a single resource through txAdmin |
+| `txadmin_player_search_tool` | Search players known to the server by name, notes, or identifier through txAdmin |
+| `txadmin_kick_player_tool` | Kick an online player by netid through txAdmin |
 
 ## Development Workflow
 

README.md

@@ -21,15 +21,15 @@
   <a href="#features">Features</a> &bull;
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#mcp-server">MCP Server</a> &bull;
-  <a href="#skills-9">Skills</a> &bull;
+  <a href="#skills-10">Skills</a> &bull;
   <a href="#rules-6">Rules</a> &bull;
   <a href="#roadmap">Roadmap</a>
 </p>
 
 ---
 
 <p align="center">
-  9 skills &nbsp;&bull;&nbsp; 6 rules &nbsp;&bull;&nbsp; 6 MCP tools &nbsp;&bull;&nbsp; 12,000+ natives &nbsp;&bull;&nbsp; 101 events &nbsp;&bull;&nbsp; 24 snippets &nbsp;&bull;&nbsp; 11 templates
+  10 skills &nbsp;&bull;&nbsp; 6 rules &nbsp;&bull;&nbsp; 10 MCP tools &nbsp;&bull;&nbsp; 12,000+ natives &nbsp;&bull;&nbsp; 101 events &nbsp;&bull;&nbsp; 24 snippets &nbsp;&bull;&nbsp; 11 templates
 </p>
 
 Scaffold complete FiveM/RedM resources, look up native functions, generate manifests, detect frameworks, search documentation, and write optimized scripts in Lua, JavaScript, and C# -- all from within Cursor's AI chat. Covers the full CFX development lifecycle from project setup to database integration.
@@ -46,7 +46,7 @@ Scaffold complete FiveM/RedM resources, look up native functions, generate manif
 flowchart LR
     A["You ask Cursor\na CFX question"] --> B["Cursor loads\na Skill"]
     B -->     C{"MCP server\navailable?"}
-    C -- Yes --> D["CFX MCP Server\n(6 tools)"]
+    C -- Yes --> D["CFX MCP Server\n(10 tools)"]
     C -- No --> E["Skill guidance\nonly"]
     D --> F["Scaffold, lookup,\ngenerate, search,\ndetect, docs"]
     E --> G["AI-assisted answer\nin Cursor chat"]
@@ -124,7 +124,7 @@ Then ask the AI agent to scaffold a resource, look up a native, or generate a ma
 
 </details>
 
-## Skills (9)
+## Skills (10)
 
 | Skill | What it does |
 |:------|:-------------|
@@ -137,6 +137,7 @@ Then ask the AI agent to scaffold a resource, look up a native, or generate a ma
 | **NUI Development** | Build in-game web UIs with proper message passing and devtools setup |
 | **Database Integration** | oxmysql queries, schema design, migrations, and connection pooling |
 | **State Bags** | Modern data sync with Entity/Player/Global state bags, change handlers, and security |
+| **txAdmin Integration** | Control a running server, manage resources, search players, and kick players through the txAdmin API |
 
 ## Rules (6)
 
@@ -235,7 +236,7 @@ pip install -r requirements.txt
 The server starts automatically when Cursor invokes an MCP tool.
 
 <details>
-<summary><strong>Available Tools (6)</strong></summary>
+<summary><strong>Available Tools (10)</strong></summary>
 
 &nbsp;
 
@@ -247,6 +248,10 @@ The server starts automatically when Cursor invokes an MCP tool.
 | `search_events_tool` | Search 101 events by name, side, game, or framework (cfx, esx, qbcore, qbox, oxcore, vorp, rsg, baseevents, chat) |
 | `detect_framework_tool` | Scan workspace files to detect ESX, QBCore, Qbox, ox_core, VORP, RSG, or standalone with confidence score |
 | `search_docs_tool` | Search the FiveM/RedM documentation index by keyword or section |
+| `txadmin_server_control_tool` | Start, stop, or restart the FXServer through txAdmin (requires txAdmin credentials) |
+| `txadmin_resource_control_tool` | Start, stop, restart, or ensure a single resource through txAdmin |
+| `txadmin_player_search_tool` | Search players by name, notes, or identifier through txAdmin |
+| `txadmin_kick_player_tool` | Kick an online player by netid through txAdmin |
 
 </details>
 
@@ -293,11 +298,11 @@ What framework does this resource use?
 CFX-Developer-Tools/
   .cursor-plugin/      Plugin manifest
   .cursor/             MCP server configuration
-  skills/              AI skill files (9 skills)
+  skills/              AI skill files (10 skills)
   rules/               Coding convention rules (6 rules)
   snippets/            Code snippets -- Lua, JS, C# (24 files)
   templates/           Resource starter templates (11 sets)
-  mcp-server/          Python MCP server (6 tools) and data files
+  mcp-server/          Python MCP server (10 tools) and data files
   docs/                Architecture, roadmap, contributing guide, docs site landing page
   assets/              Logo and images
   .github/             CI/CD workflows (validate, release, update-natives, update-docs-index, stale, deploy-docs)

docs/ARCHITECTURE.md

@@ -66,6 +66,12 @@ Cursor AI Agent  --(MCP protocol)-->  MCP Server  --(reads)-->  Data Files
 | `search_events_tool` | Searches 101 events by name, side, game, or framework |
 | `detect_framework_tool` | Scans workspace files to detect ESX, QBCore, Qbox, ox_core, VORP, RSG, or standalone |
 | `search_docs_tool` | Searches the FiveM/RedM documentation index by keyword or section |
+| `txadmin_server_control_tool` | Starts, stops, or restarts the FXServer through a running txAdmin panel |
+| `txadmin_resource_control_tool` | Starts, stops, restarts, or ensures a single resource through txAdmin |
+| `txadmin_player_search_tool` | Searches players by name, notes, or identifier through txAdmin |
+| `txadmin_kick_player_tool` | Kicks an online player by netid through txAdmin |
+
+The four txAdmin tools talk to a running txAdmin panel over HTTP, authenticating with credentials from the `TXADMIN_URL` / `TXADMIN_USERNAME` / `TXADMIN_PASSWORD` environment variables.
 
 ### Data files
 

docs/GETTING-STARTED.md

@@ -26,7 +26,7 @@ This guide takes you from zero to building FiveM/RedM resources with AI assistan
 - Generate a correct `fxmanifest.lua` with all the right directives
 - Write code that follows FiveM/RedM best practices automatically
 
-The plugin includes **9 skills**, **6 rules**, **24 code snippets**, **11 starter templates**, and **6 MCP tools** (including a searchable database of 12,000+ native functions, 101 events, and documentation search).
+The plugin includes **10 skills**, **6 rules**, **24 code snippets**, **11 starter templates**, and **10 MCP tools** (including a searchable database of 12,000+ native functions, 101 events, documentation search, and txAdmin server control).
 
 <details>
 <summary><strong>What is Cursor?</strong></summary>
@@ -203,7 +203,7 @@ You may see a prompt asking you to **trust the workspace**. Click **Yes, I trust
 When you open the folder, Cursor:
 
 - Reads `.cursor-plugin/plugin.json` and registers the plugin
-- Makes the 9 skills available to the AI assistant
+- Makes the 10 skills available to the AI assistant
 - Activates the 6 coding rules based on file types you open
 - Loads the MCP server configuration from `.cursor/mcp.json`
 

docs/ROADMAP.md

@@ -129,12 +129,12 @@ Connect the plugin to live FiveM/RedM server infrastructure for real-time develo
 
 txAdmin exposes a REST API on port 40120 (default) with session cookie authentication.
 
-- [ ] Add MCP tool: `txadmin_server_control` (start, stop, restart FXServer)
-- [ ] Add MCP tool: `txadmin_resource_control` (start, stop, restart, refresh individual resources)
-- [ ] Add MCP tool: `txadmin_player_search` (search connected players by name or identifier)
-- [ ] Add MCP tool: `txadmin_kick_player` (kick with reason)
-- [ ] Add connection configuration (host, port, session token via environment variable)
-- [ ] Add skill for txAdmin setup and authentication
+- [x] Add MCP tool: `txadmin_server_control` (start, stop, restart FXServer)
+- [x] Add MCP tool: `txadmin_resource_control` (start, stop, restart, ensure individual resources)
+- [x] Add MCP tool: `txadmin_player_search` (search players by name, notes, or identifier)
+- [x] Add MCP tool: `txadmin_kick_player` (kick with reason)
+- [x] Add connection configuration (URL, username, password via environment variables)
+- [x] Add skill for txAdmin setup and authentication
 
 ### RCON and server commands
 

docs/index.md

@@ -2,7 +2,7 @@
 
 **AI-powered development toolkit for FiveM and RedM resource development in Cursor IDE.**
 
-9 skills -- 6 rules -- 6 MCP tools -- 12,000+ natives -- 101 events -- 24 snippets -- 11 templates
+10 skills -- 6 rules -- 10 MCP tools -- 12,000+ natives -- 101 events -- 24 snippets -- 11 templates
 
 ---
 
@@ -15,6 +15,7 @@ CFX Developer Tools is a plugin for [Cursor](https://www.cursor.com/) that teach
 - Generate a correct `fxmanifest.lua` with all the right directives
 - Detect which framework your project uses (ESX, QBCore, Qbox, ox_core, VORP, RSG)
 - Search the FiveM/RedM documentation index
+- Control a running server through txAdmin (start/stop/restart, manage resources, search and kick players)
 - Write code that follows FiveM/RedM best practices automatically
 
 ## Quick start
@@ -35,6 +36,7 @@ For a detailed walkthrough, see the [Getting Started guide](GETTING-STARTED.md).
 - **Native function lookup** -- Search 12,000+ GTA5/RDR3 native functions by name, hash, or description
 - **Event reference** -- Searchable database of 101 events across CFX, ESX, QBCore, Qbox, ox_core, VORP, and RSG
 - **Documentation search** -- Query the FiveM/RedM docs index by keyword or section
+- **txAdmin integration** -- Control the FXServer, manage resources, and search or kick players through a running txAdmin panel
 - **Performance-aware coding rules** -- Catch common mistakes like `Wait(0)` in loops, runtime hashing, and more
 - **Snippet library** -- 24 copy-paste-ready code patterns across Lua, JavaScript, and C#
 - **NUI development** -- Skills and templates for building in-game web UIs with React or Svelte 5
@@ -58,9 +60,9 @@ For a detailed walkthrough, see the [Getting Started guide](GETTING-STARTED.md).
 flowchart LR
     A["You ask Cursor\na CFX question"] --> B["Cursor loads\na Skill"]
     B --> C{"MCP server\navailable?"}
-    C -- Yes --> D["CFX MCP Server\n(6 tools)"]
+    C -- Yes --> D["CFX MCP Server\n(10 tools)"]
     C -- No --> E["Skill guidance\nonly"]
-    D --> F["Scaffold, lookup,\ngenerate, search,\ndetect, docs"]
+    D --> F["Scaffold, lookup,\ngenerate, search,\ndetect, docs, txAdmin"]
     E --> G["AI-assisted answer\nin Cursor chat"]
     F --> G
 ```

mcp-server/server.py

@@ -16,6 +16,12 @@
 from tools.event_search import search_events
 from tools.docs_search import search_docs
 from tools.detect_framework import detect_framework
+from tools.txadmin import (
+    txadmin_server_control,
+    txadmin_resource_control,
+    txadmin_player_search,
+    txadmin_kick_player,
+)
 
 mcp = FastMCP("cfx-dev-tools")
 
@@ -130,5 +136,69 @@ def search_docs_tool(
     return search_docs(query, section, NATIVES_PATH)
 
 
+@mcp.tool()
+def txadmin_server_control_tool(action: str) -> str:
+    """Start, stop, or restart the FXServer through txAdmin.
+
+    Requires the TXADMIN_USERNAME, TXADMIN_PASSWORD, and optionally TXADMIN_URL
+    environment variables to be set. See the txadmin-integration skill.
+
+    Args:
+        action: One of start, stop, or restart.
+    """
+    return txadmin_server_control(action)
+
+
+@mcp.tool()
+def txadmin_resource_control_tool(action: str, resource: str) -> str:
+    """Start, stop, restart, or ensure a single server resource through txAdmin.
+
+    Requires txAdmin credentials in the environment (see txadmin-integration skill).
+
+    Args:
+        action: One of start, stop, restart, or ensure.
+        resource: The resource name (folder name) to act on.
+    """
+    return txadmin_resource_control(action, resource)
+
+
+@mcp.tool()
+def txadmin_player_search_tool(
+    search_value: str = "",
+    search_type: str = "playerName",
+    filters: str | None = None,
+    limit: int = 25,
+) -> str:
+    """Search players known to the server by name, notes, or identifier.
+
+    Requires txAdmin credentials in the environment (see txadmin-integration skill).
+
+    Args:
+        search_value: Text to search for.
+        search_type: Search mode - playerName, playerNotes, or playerIds.
+        filters: Comma-separated filters - isAdmin, isOnline, isWhitelisted, hasNote (optional).
+        limit: Maximum number of players to display (server caps at 100).
+    """
+    return txadmin_player_search(search_value, search_type, filters, limit)
+
+
+@mcp.tool()
+def txadmin_kick_player_tool(
+    netid: int,
+    reason: str = "",
+    mutex: str = "current",
+) -> str:
+    """Kick an online player by their server network id (netid) through txAdmin.
+
+    Requires txAdmin credentials in the environment (see txadmin-integration skill).
+
+    Args:
+        netid: The player's server id (netid) from the player list.
+        reason: Optional kick reason shown to the player.
+        mutex: Server instance mutex; 'current' (default) targets the running server.
+    """
+    return txadmin_kick_player(netid, reason, mutex)
+
+
 if __name__ == "__main__":
     mcp.run()