mcp: Instructions file for Codex

AGENTS.md - StealthSurf MCP Server

Project Context

This is a stateless MCP proxy server that maps StealthSurf VPN API endpoints to MCP tools. It allows AI agents to manage VPN configurations, cloud servers, paid options, and user profiles through natural language.

Architecture

• Runtime: Node.js 22+, TypeScript, ES modules
• MCP SDK: @modelcontextprotocol/sdk with Streamable HTTP transport
• Transport: Stateless — each POST creates fresh McpServer + transport
• Auth: stlth_* API key from Authorization: Bearer header, forwarded to backend API
• No framework: Raw http.createServer + MCP SDK transport

Repository Structure

src/
├── index.ts              # HTTP server entry point
├── server.ts             # McpServer factory (registers tools, resources, prompts)
├── api-client.ts         # Fetch wrapper for StealthSurf API
├── schemas/
│   └── shared.ts         # Reusable zod schemas + toolResult/toolError helpers
├── resources/            # 4 MCP resources
│   ├── guide.ts              # Full docs (fetched from docs.stealthsurf.app)
│   ├── errors.ts             # API error codes reference (static)
│   ├── updates.ts            # Changelog (fetched from updates.stealthsurf.app)
│   └── protocols.ts          # VPN protocol comparison + compatibility (static)
├── prompts/              # 11 MCP prompt templates
│   ├── index.ts              # Registers all prompts
│   ├── setup-vpn.ts          # Interactive VPN config creation wizard
│   ├── troubleshoot.ts       # Connection issue diagnostics
│   ├── optimize-for-region.ts # Protocol recommendations by region
│   ├── account-overview.ts   # Full account status report
│   ├── bulk-renew.ts         # Batch renewal of expiring configs
│   ├── setup-family.ts       # Custom subscription for sharing
│   ├── setup-cloud-server.ts # VPS setup wizard
│   ├── switch-protocol.ts    # Bulk protocol migration
│   ├── setup-bridge.ts       # Dual-hop bridge creation
│   ├── device-audit.ts       # Device security audit
│   └── xray-config.ts        # Custom XRay configuration guide
└── tools/                # 13 files, 92 MCP tools total
    ├── configs.ts            # VPN configs (15 tools)
    ├── cloud-servers.ts      # Cloud servers (6 tools)
    ├── cloud-configs.ts      # Cloud server configs (6 tools)
    ├── cloud-proxies.ts      # Cloud server proxies (5 tools)
    ├── paid-options.ts       # Paid options core (12 tools)
    ├── paid-option-configs.ts # Paid option configs (10 tools)
    ├── profile.ts            # Profile + telegram (8 tools)
    ├── profile-devices.ts    # Devices (6 tools)
    ├── profile-balance.ts    # Balance (2 tools)
    ├── profile-referral.ts   # Referral program (4 tools)
    ├── profile-history.ts    # Payments + promocodes (2 tools)
    ├── custom-subscriptions.ts # Custom subscriptions (14 tools)
    └── utility.ts            # Locations + XRay keys (2 tools)