ai-gaming-agent-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AI Gaming Agent is a distributed automation system where a Master Claude instance controls multiple remote gaming PCs through MCP (Model Context Protocol) servers. The primary use case is autonomous game account leveling across multiple machines simultaneously.

Current State: Core implementation complete with MCP server, HTTP/SSE transport, CLI, and 24 tools including workflow automation.

Architecture

Master Claude (Orchestrator)
    ↓ MCP Protocol (JSON-RPC over HTTP/SSE + Bearer Token Auth)
    ├─→ PC #1 (HTTP Server :8765) ─→ PyAutoGUI + Optional Local VLM + Workflow Engine
    ├─→ PC #2 (HTTP Server :8765) ─→ PyAutoGUI + Optional Local VLM + Workflow Engine
    └─→ PC #N (HTTP Server :8765) ─→ PyAutoGUI + Optional Local VLM + Workflow Engine

Three Deployment Options:

• Option A (Simplest): Claude analyzes all screenshots, gaming PCs are simple executors
• Option B (Recommended): Hybrid - Claude for high-level decisions, local VLM for fast visual processing
• Option C (Privacy): Fully local orchestrator (e.g., Qwen3-72B), no cloud APIs

Project Structure

src/ai_gaming_agent/
├── __init__.py              # Package version
├── cli.py                   # CLI commands (serve, init, config)
├── config.py                # Configuration management (JSON file)
├── server.py                # MCP server implementation (stdio transport)
├── http_server.py           # FastAPI + SSE HTTP server with Bearer token auth
└── tools/                   # 24 MCP tools
    ├── screen.py            # screenshot, get_screen_size
    ├── mouse.py             # click, move_to, drag_to, scroll
    ├── keyboard.py          # type_text, press_key, hotkey
    ├── files.py             # read/write/list/upload/download
    ├── system.py            # execute_command, focus_window
    ├── workflow.py          # run_workflow, demo_terminal_workflow
    └── vlm.py               # analyze_screen (optional Ollama integration)

tests/
├── test_config.py           # Unit tests for config
├── test_tools.py            # Unit tests for tools
├── test_http_server.py      # Unit tests for HTTP/SSE server
├── test_workflow.py         # Unit tests for workflow tools
├── test_vlm.py              # Unit tests for VLM tool
├── test_cli.py              # Unit tests for CLI
└── integration/             # Integration tests (LOCAL ONLY)
    ├── test_gui_automation.py
    ├── test_demo_workflow.py
    └── test_full_workflow.py