sftp-manager: Instructions file for Codex

AGENTS.md

Instructions for an AI agent that has been handed this repository.

This file follows the AGENTS.md convention and is read automatically by Codex, Cursor, Jules, Copilot, Zed and others. Claude Code reads CLAUDE.md, which points here.

---

What this repo is

sftp-manager is a stdio MCP server. It gives an AI agent sandboxed SFTP access to game servers (Pterodactyl / TaroHosting panels and any plain SFTP host) so configs can be read and edited, addons installed, backups restored and the server restarted — without a shell.

It is not a library to import and not a service to deploy. The deliverable is a process launched over stdio by an MCP client:

<python> <repo>/mcp_server.py

Everything else in this file exists to get that command running correctly.

---

Installing it (do this in order)

install_mcp.py is the install and diagnosis surface. It uses only the standard library, so it runs before any dependency is installed, and every subcommand prints JSON so you can branch on the result instead of parsing prose.

Step 1 — Diagnose

python install_mcp.py check

Returns Python version, missing dependencies, whether config exists, the exact command/args to register, and a siguiente_paso field telling you what to do next. Read siguiente_paso and follow it. If listo is true, skip to step 4.

Step 2 — Dependencies

python install_mcp.py deps

Requires Python 3.10+. If the environment is externally managed (PEP 668) this fails; create a virtualenv and use its interpreter for every later step:

python -m venv .venv
.venv/bin/python install_mcp.py deps        # Windows: .venv\Scripts\python.exe

Only paramiko, python-dotenv and mcp are needed to run the server. nbtlib unlocks the two level.dat tools; anthropic is only for the optional standalone CLI.

Step 3 — Credentials

python install_mcp.py init

This copies servers.example.json → servers.json and .env.example → .env. Both are git-ignored. It never overwrites an existing file.