# YandexGamesMCP

**Model Context Protocol (MCP) server for the Yandex Games Console.**  
Built specifically for terminal AI coding agents: **Claude Code**, **Codex CLI**, **OpenCode**, and **Antigravity CLI**.

[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E1.6.1-blue)](https://github.com/modelcontextprotocol/typescript-sdk)

---

## Highlights

- **Zero-Config Auto-Authentication**: Reads credentials from `~/.yagames/credentials.json` (chmod 600) so you never need to hardcode sensitive tokens in agent config files.
- **Auto CSRF Token Fetch & Recovery**: Automatically fetches fresh CSRF tokens from `/console/api/csrf-token` using your `Session_id` and auto-recovers from `403` / `EBADCSRFTOKEN` expiration in the background.
- **Interactive In-Chat Credential Setup**: Just tell your AI agent *"here is my Yandex session cookie/cURL"* — the agent invokes `yagames-set-credentials` to extract, verify, and store it.
- **Dedicated CLI Integration**: Native setup and verified support for **Claude Code**, **Codex CLI**, **OpenCode**, and **Antigravity CLI**.

---

## Supported Tools

### 🔑 Authentication & Status
| Tool | Description |
|------|-------------|
| `yagames-browser-login` | Opens a real browser window to Yandex Games Console. Once you log in, it captures `Session_id` and `CSRF` token automatically and saves them. |
| `yagames-set-credentials` | Paste a DevTools cURL, raw Cookie header, or Session_id. Auto-fetches CSRF, validates, and saves securely. |
| `yagames-auth-status` | Inspect current developer login, studio name, and connection state. |

### 🎮 Developer Console (Authenticated)
| Tool | Description |
|------|-------------|
| `yagames-list-my-games` | List all games uploaded to your developer account with IDs and live status. |
| `yagames-status` | Check the current status of a specific game (draft, moderation, published). |
| `yagames-create-draft` | Register a new game in the Yandex Games Console. |
| `yagames-update-draft` | Update draft metadata, titles, descriptions, orientations, and categories. |
| `yagames-upload-build` | Upload a ZIP game build archive as a new version. |

> **Safety Notice:** Submitting for moderation and publishing have been deliberately omitted from automated tool execution. These final actions must always be reviewed and performed manually by the developer in the [Yandex Games Console](https://games.yandex.ru/console) to avoid accidental submissions.

### 🌐 Public Catalog (No Auth Required)
| Tool | Description |
|------|-------------|
| `yagames-search` | Search games in the Yandex Games catalog by keyword. |
| `yagames-popular` | Browse popular games, optionally filtered by genre/category. |
| `yagames-categories` | List all available genres and categories. |

---

## Installation & Build

```bash
git clone https://github.com/Z3r01n/YandexGamesMCP.git ~/Documents/full_data/apps/OpenSource/YandexGamesMCP
cd ~/Documents/full_data/apps/OpenSource/YandexGamesMCP
npm install
npm run build
```

---

## Agent Setup Guide

### 1. Claude Code
Register globally to your user config with a single command:

```bash
claude mcp add --scope user yagames-mcp -- node ~/Documents/full_data/apps/OpenSource/YandexGamesMCP/build/index.js
```

Verify connection:
```bash
claude mcp get yagames-mcp
```

---

### 2. OpenAI Codex CLI
Register as a global MCP server:

```bash
codex mcp add yagames-mcp -- node ~/Documents/full_data/apps/OpenSource/YandexGamesMCP/build/index.js
```

Verify connection:
```bash
codex mcp list
```

---

### 3. OpenCode CLI
Add to `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yagames-mcp": {
      "type": "local",
      "command": [
        "node",
        "/Users/z3r01n/Documents/full_data/apps/OpenSource/YandexGamesMCP/build/index.js"
      ],
      "enabled": true
    }
  }
}
```

---

### 4. Antigravity CLI
Add to your `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "yagames-mcp": {
      "command": "node",
      "args": [
        "/Users/z3r01n/Documents/full_data/apps/OpenSource/YandexGamesMCP/build/index.js"
      ]
    }
  }
}
```

---

## Authentication Workflow

### Method A: One-Click Browser Login (Automatic)
Tell your AI agent:
> *"Open the browser so I can log in to Yandex Games"*

Or run directly from your terminal:
```bash
cd ~/Documents/full_data/apps/OpenSource/YandexGamesMCP
npm run login
```
* A browser window opens to `https://games.yandex.ru/console`.
* Log in with your Yandex account.
* The script automatically grabs the `Session_id` cookie, fetches a fresh CSRF token, verifies your developer account, saves everything to `~/.yagames/credentials.json`, and closes the browser!

### Method B: Directly via Chat (cURL or Cookie)
In Claude Code, Codex, OpenCode, or Antigravity, simply tell the agent:
> *"Here is my Yandex session: `Session_id=3:...`"*  
> *(or paste a raw DevTools cURL command)*

The agent will run `yagames-set-credentials`, which:
1. Extracts the `Session_id`.
2. Automatically calls `/console/api/csrf-token` to acquire a valid CSRF token.
3. Tests the connection against Yandex Developer Console.
4. Saves credentials to `~/.yagames/credentials.json`.

### Method B: Via Terminal CLI
```bash
# Save and test credentials directly:
npm run auth "<paste_session_id_or_curl_here>"

# Check status:
npm run status
```

### Method C: Environment Variable (Optional)
```bash
export YAGAMES_SESSION_COOKIE="your_session_id_value"
# YAGAMES_CSRF_TOKEN is optional (auto-fetched if omitted)
```

---

## Security

* **Local Storage**: Credentials are saved strictly to your machine at `~/.yagames/credentials.json` with `0600` permissions (readable only by your user account).
* **Direct Communication**: Network traffic only communicates with official Yandex endpoints (`https://games.yandex.ru/console` and `https://yandex.ru/games`).
* **Zero Telemetry**: No third-party servers, tracking, analytics, or external logging exist in this MCP server.

---

## License

[MIT](LICENSE) © [Z3r01n](https://github.com/Z3r01n)