TinyPyMCP

⚠️ OPERATOR-ONLY / AUTHENTICATED ADMIN SERVER. TinyPyMCP exposes run_command (allowlisted local code execution) and Cloudflare cloud-admin tools. The in-process path_guard is not an OS security boundary — a compromised or prompt-injected authenticated caller can run code with the server process's privileges. Run it only behind auth (bearer/OAuth), only for a trusted operator, never as an open/multi-tenant public connector. Before any exposure, harden at the OS level: low-privilege user, filesystem ACLs, and ideally a container (see DEVNOTES "Hardening Tier 2"). Audit: 2026-06-20.

A Python MCP server: a sandboxed workshop for an agent — file read/edit, code intelligence, search index, local command execution, package lookups, persistent memory, and a client for bounded VPS channels. All filesystem access is confined to C:\Work. 104 tools.

For development/maintenance notes and the roadmap, see DEVNOTES.md.

---

Run

Local clients (Claude Desktop, Cursor) — stdio, no auth:

python -m src.server

Remote / hosted connectors — HTTP (Streamable HTTP), auth required:

# Bearer mode (token from file): bearer_token.json = {"token": "<secret>"}
python -m src.server --auth bearer --token-file C:\Users\mczyz\.romion\bearer_token.json --transport http --port 8765
# OAuth 2.1 mode (recommended for hosted connectors): see below.

Auth is selected by --auth bearer|oauth|none (default bearer). Secrets come from --token-file / --secret-file (JSON, kept outside C:\Work) or env. none runs open — never on a public tunnel. Endpoint: http://127.0.0.1:8765/mcp/v5 (public via Cloudflare Tunnel at https://tiny-py-mcp.romionologic.dev/mcp/v5).

The HTTP transport refuses to start without MCP_AUTH_TOKEN (fail-closed), because the tunnel exposes tools like run_command. For trusted localhost-only dev you may set MCP_AUTH_DISABLE=1 — never on port 8765 while the tunnel runs.

How clients authenticate

• Header clients: send Authorization: Bearer <secret>.
• ChatGPT connector (can't send custom headers): set the URL to https://tiny-py-mcp.romionologic.dev/mcp/v5?token=<secret> and Authentication to "No authorization". The token in the URL is redacted from logs.

Environment variables

Var	Purpose
MCP_AUTH_TOKEN	Bearer/query token for HTTP. Required unless MCP_AUTH_DISABLE=1.
MCP_AUTH_DISABLE=1	Run HTTP without auth (trusted local only).
MCP_PUBLIC_HOST	Public host for the DNS-rebinding allowlist (default tiny-py-mcp.romionologic.dev).
MCP_MEMORY_DB	SQLite memory path (default data/memory.db).
MCP_WORKSPACE_ROOT	Where clone_repo/indexes live (default workspaces/).
MCP_AUDIT_LOG	Audit JSONL path (default logs/.tinypymcp-audit.jsonl).
MCP_VPS_CONFIG	VPS-channel creds JSON (default ~/.romion/vps-channel.json, kept OUTSIDE C:\Work).
MCP_AUTH_MODE	bearer (default) or oauth. Selects HTTP auth.
MCP_OAUTH_OPERATOR_SECRET	OAuth mode: the secret you type on the authorization page (the human gate). Required for oauth mode.
MCP_OAUTH_ISSUER	OAuth mode: public issuer URL (default https://<MCP_PUBLIC_HOST>).
MCP_OAUTH_DB	OAuth store path (default data/oauth.db).
MCP_EXEC_ALLOWLIST	Comma/space-separated exec allowlist override (e.g. "git" drops interpreters). Default: git/node/npm/python/pytest/...
MCP_CF_PROTECTED	Override the protected-CF-host denylist (delete/remove of these needs force=true).
MCP_RATE_LIMIT_PER_MIN	Per-IP request cap (0 = off, default). Anti-runaway; set generous to not break connector bursts.

OAuth 2.1 mode (standard, for hosted connectors)

python -m src.server --auth oauth --secret-file C:\Users\mczyz\.romion\oauth_secret.json --transport http --port 8765

oauth_secret.json (keep OUTSIDE C:\Work):

{ "operator_secret": "<the secret you type at login>", "issuer": "https://tiny-py-mcp.romionologic.dev" }

The server becomes its own OAuth authorization server (DCR + PKCE; no external IdP). Connectors discover it automatically; during each connector's login you enter the operator secret on the TinyPyMCP page. See CONNECTORS.md.

(Env-var form also works: MCP_AUTH_MODE=oauth, MCP_OAUTH_OPERATOR_SECRET, MCP_OAUTH_ISSUER. Flags take precedence.)

Tools (81)

Grouped by domain. The authorization boundary is which profiles are enabled at launch (read_only / operator_admin / cloud_admin — see src/profiles.py); confirm=true on a tool is an accidental-mutation guard, not authorization.

• Read/inspect: read_file, read_file_chunk, get_info, list_files, get_project_structure, find_phrase_occurrences, search_codebase
• Edit/write: write_file, create_file, append_file, safe_replace_in_line, edit_code_block, edit_file_patch
• Manage: copy_path, move_path, delete_path (soft → .trash), restore_path, list_trash
• Code intelligence: code_dependencies, code_impact, code_symbols, build_index, search_index, index_status
• Exec/acquire: run_command (allowlisted), clone_repo
• Network: http_probe, check_npm_package, check_pypi_package
• Research / security: check_cve (OSV.dev, no key — id/CVE/severity/CWE/fixed, slimmed), check_github_advisory (GitHub global advisory DB via the gh token)
• Memory (SQLite + sqlite-vec): memory_get_state, memory_set_state, memory_save, memory_search (semantic KNN via bge-m3 embeddings, lexical fallback), memory_reindex, memory_create_task, memory_get_tasks
• VPS channel: vps_status, vps_request
• VPS filesystem (read-only, whole host) via the /hostfs ro bind-mount, NOT path_guard-confined: vps_fs_list, vps_fs_stat, vps_fs_read. Read any path on the VPS. Secret-file bytes are withheld unless MCP_FS_SECRET_MODE=allow (an air-gapped, no-egress instance).
• SIM job governance (stage 1, read-only) — MCP as a typed governance interface, never the compute engine (compute-plane ADR): sim_validate_job_manifest, sim_submit_job_dry_run, sim_experiment_catalog. Pure validation + dry-run planning; no submit/exec.
• VPS docker (host control) via the mounted docker.sock (uid 10001 in host group docker): vps_docker. Read subcommands (ps/logs/inspect/...) ungated; mutating ones (run/exec/rm/stop/restart/build/compose/...) require confirm=true and are audited.
• Cloudflare admin (token from ~/.romion/cloudflare.json; writes need confirm=true): cf_verify_token, cf_list_dns, cf_create_dns_record, cf_delete_dns_record, cf_list_tunnels, cf_get_tunnel_config, cf_add_tunnel_route, cf_remove_tunnel_route, cf_create_access_app, cf_delete_access_app, cf_add_access_service_policy, cf_create_service_token, cf_delete_service_token
• OVH host (consumer key from ~/.romion/ovh.json; writes need confirm=true): ovh_vps_info, ovh_snapshot_status, ovh_automated_backup_status, ovh_images_available, ovh_create_snapshot, ovh_revert_snapshot, ovh_abort_snapshot, ovh_automated_backup_restore, ovh_reboot
• OVH AI Endpoints (OpenAI-compatible Bearer key from ~/.romion/ovh-ai.json; read-only, clean-IP VPS path; key never surfaced): ovh_ai_embeddings, ovh_ai_chat
• Uptime Kuma (socket.io from ~/.romion/kuma.json; writes need confirm=true): kuma_list_monitors, kuma_monitor_status, kuma_add_monitor, kuma_pause_monitor, kuma_resume_monitor
• GitHub (token from ~/.romion/github.json; mutations need confirm=true): gh_repo_info, gh_list_prs, gh_get_pr, gh_create_repo, gh_create_pr, gh_merge_pr

Security model

• Sandbox: every C:\Work file tool resolves paths through path_guard.ensure_within — confined to C:\Work (../symlink escapes blocked). Network is unrestricted.
• Whole-VPS read plane (vps_fs_*) is deliberately NOT confined: it reads the host root via a read-only bind-mount. Read-only is the boundary (no write/exec). Secret-file CONTENTS are withheld per MCP_FS_SECRET_MODE (default redact); an air-gapped instance with no internet egress can set allow to read/manage secrets safely.
• Exec: run_command runs only allowlisted binaries (git/node/npm/python/ pytest/...), no shell, child env stripped to a safe allowlist (secrets don't leak), timeout + output caps, cwd confined to C:\Work.
• Auth: bearer header or ?token= query, fail-closed; redacted from logs.
• Deletes are soft (move to .trash, reversible via restore_path).
• Secrets (VPS channel tokens) live OUTSIDE C:\Work so the agent's own file tools can't read them.
• All mutations and command runs are recorded in the audit log.

Tests

python tests/smoke.py        # 57 offline checks over the whole tool surface

VPS deploy channel

Heavy deploy (docker on the VPS) is handled by the separate romion-deploy service (C:\Work\romion-deploy), reached via vps_request. See its README.