TinyPyMCP

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. 50 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.

Related MCP server: Coding MCP Server

Environment variables

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 (37)

• 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

• Memory (SQLite): memory_get_state, memory_set_state, memory_save, memory_search, memory_create_task, memory_get_tasks

• VPS channel: vps_status, vps_request

• 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

Security model

• Sandbox: every file tool resolves paths through path_guard.ensure_within — confined to C:\Work (../symlink escapes blocked). Network is unrestricted.

• 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        # 34 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.