Metadata-Version: 2.4
Name: proteworks
Version: 0.1.9
Summary: Sync files with Proteworks using file-browser paths.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: keyring>=25
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Requires-Dist: pyarrow>=14; extra == "mcp"

# proteworks

Command line client and local MCP server for syncing Proteworks files and submitting allowlisted workflows. The default API is production. Set `PROTEWORKS_API_URL` only when testing against staging or a local stack.

## One install (CLI + Claude Science)

There is a **single supported install**:

| Path | Role |
| --- | --- |
| `/opt/proteworks` | Package + `proteworks-mcp` |
| `/usr/local/bin/proteworks` | CLI symlink |
| `/usr/local/bin/proteworks-mcp` | MCP symlink (Science **Command**) |
| `~/.config/proteworks/` | Login token file + org config |

Do **not** keep a second copy from `uv tool` / pipx / a repo `.venv` on your PATH for daily use. Those diverge and break Claude Science.

### Bootstrap once, then use only `/usr/local/bin`

```bash
# 1) Temporary bootstrap (any machine with uv)
uv tool install 'proteworks[mcp]'

# 2) Canonical install (needs sudo). Uses distro python3.12+ under /usr (not uv under $HOME).
sudo "$(which proteworks)" mcp install-system
# Developers working from a git checkout before publishing:
# sudo "$(which proteworks)" mcp install-system --package-spec "$PWD[mcp]"

# 3) Remove the bootstrap copy so PATH has one binary
uv tool uninstall proteworks
hash -r
which -a proteworks   # expect only /usr/local/bin/proteworks

# 4) Login + Science grants
proteworks login
proteworks organization set "My Org"
proteworks mcp setup-claude-science
proteworks mcp doctor
```

After any upgrade: run step 2 again (same `install-system` command), then `doctor`. Do not `uv tool install` again unless `/usr/local/bin/proteworks` is missing.

### Claude Science connector

`setup-claude-science` prints the fields. Always:

| Field | Value |
| --- | --- |
| **Name** | `proteworks` |
| **Command** | `/opt/proteworks/bin/proteworks-mcp` |
| **Arguments** | leave empty |
| **Env** (if shown) | `PROTEWORKS_CONFIG_DIR=$HOME/.config/proteworks` |

Paste **only** that Command path. Do not use `python -m …`, `uvx`, or a path under `~/.local`. Science’s one-field UI can drop `-m` and hang for 180s; sandboxed `HOME` also cannot see a second user-level install’s credentials unless you use the system layout above.

Fully quit and relaunch Claude Science after setup so it reloads `config.toml`.
Also add each host **by name** under Science **Settings → Domain Allowlist**
(Science rejects wildcards). `setup-claude-science` prints the list — typically
`api.studio.proteworks.com` plus virtual-hosted GCS hosts such as
`proteworks-production.storage.googleapis.com`. The connector’s `config.toml`
grants are necessary but Science’s UI allowlist often gates egress separately.
Bare `storage.googleapis.com` is hard-denylisted (path-style GCS). If pull still
fails for a custom org bucket, add `<bucket>.storage.googleapis.com`. Science may
set `ALL_PROXY` (SOCKS); `proteworks` depends on `httpx[socks]` so that works out
of the box. If a direct GCS PUT is still blocked, push falls back to uploading
through the Proteworks API host.

Allow Claude to push/pull from a real project (like the CLI — no staging copy):

```bash
proteworks mcp setup-claude-science --mcp-root ~/projects/my-campaign
```

That grants the Science sandbox **and** writes `~/.config/proteworks/mcp_roots`.
Restart the connector afterward. Absolute paths under that project then work with
MCP `push` / `pull`.

`proteworks --version` / `proteworks-mcp --version` print the installed version.

Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.

```bash
proteworks pull '~/My Files/campaigns/run/' ./run
proteworks push ./1UBQ.pdb '~/My Files/test/'
proteworks push '*.pdb' '~/My Files/pdbs/'
proteworks push designs.zip '~/My Files/dest/'   # auto-extracts
proteworks mkdir '~/My Files/campaigns/round6/'
```

MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).

Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs.

Example prompts: list `~/My Files/`, dry-run pull a folder, pull it, push results back.

Optional coaching skills (not required for the server):

- [`skills/proteworks-files/SKILL.md`](skills/proteworks-files/SKILL.md)
- [`skills/proteworks-workflows/SKILL.md`](skills/proteworks-workflows/SKILL.md)

Import via Settings → Skills → Import from GitHub (or upload the folder). Hosts without a Skills UI still get conventions from MCP tool descriptions and this README.

### Tools

| Tool | Purpose |
| --- | --- |
| `auth_status` | Login state, API URL, active org (never the token) |
| `organization_list` / `organization_set` | Choose organization (`organization_set` needs `confirm=true`) |
| `list_files` | Browse a remote path; returns `file_id` + `relative_path` |
| `pull` / `push` | Transfer with `dry_run` (default true); real transfers need `confirm_transfer=true` |
| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
| `get_workflow_schema` | Full schema with UI-matching defaults |
| `prepare_workflow_submission` | Merge defaults + overrides; **no submit** (draft body) |
| `submit_workflow` | Same merge, then submit |
| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / structure_prediction); normalized rows + scores |
| `save_selected_studio` | Same as Studio Save selected → subset `.studio` uploaded + retention finalized (not yet for structure_prediction) |
| `inspect_proteinmpnn_studio` | Legacy ProteinMPNN flat-row inspect (prefer `inspect_studio`) |
| `prepare_refolding_from_proteinmpnn_studio` | Build refolding payload + SA handoff from MPNN studio selection (**no submit**) |
| `get_execution` / `list_execution_results` / `cancel_execution` | Status / results / cancel (`cancel_execution` needs `confirm=true`) |
| `estimate_workflow_cost` | Cost estimate from merged params (same validation as prepare) |

Auth is shared with the CLI. The access token is stored in the OS keychain and mirrored to `~/.config/proteworks/credentials` (mode `0600`) so Claude Science’s sandbox can read it. There is no separate MCP login: run `proteworks login` in a terminal, then restart the connector.

### MCP safety env

| Variable | Purpose |
| --- | --- |
| `PROTEWORKS_MCP_ROOT` | Local workspace root for `pull`/`push` (default: process cwd) |
| `PROTEWORKS_MCP_READ_ONLY` | When `1`/`true`, disables submit/push/cancel/save-selected |
| `PROTEWORKS_STORAGE_HOST_ALLOWLIST` | Comma-separated host suffixes for signed URL follow (default: GCS hosts) |
| `PROTEWORKS_MAX_STUDIO_BYTES` | Max `.studio` download size (default 80 MiB) |
| `PROTEWORKS_STUDIO_INSPECT_LIMIT` | Default row page size for `inspect_studio` (default 50) |

**Staging smoke:** `auth_status` → `list_workflows` → `get_workflow_schema` → `prepare_workflow_submission` → `estimate_workflow_cost` → `submit_workflow` → `get_execution` → `cancel_execution` (with `confirm=true` if still running).

### Workflow submit

1. `list_files` → get `file_id` for any structure input.
2. `get_workflow_schema` for the workflow (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, or `msa-generation`).
3. `prepare_workflow_submission` to review the merged payload (defaults match a fresh Studio form).
4. `submit_workflow` when ready.

**Refolding** and **Structure Prediction** have no default predictor/MSA — agents must **ask the user** which methods and (when required) which MSA to use before prepare/submit. Structure Prediction also requires a user-provided complex (`structure-prediction-complex-json`). **MSA generation** has no default sequences — ask, then pass `generated-fasta-inputs` or `fasta_files`; use the run **output folder** as `msa_output_folder` downstream. From ProteinMPNN results: `inspect_studio` → ask → `prepare_refolding_from_proteinmpnn_studio` → `submit_workflow`.

**`.studio` results:** `inspect_studio` → filter by scores (e.g. pLDDT / Rg) → `save_selected_studio` to write a subset bundle (structure_prediction is inspect-only for now).

Payload shape matches Studio `POST /api/v1/workflows/submit` and is reserved for future shareable draft links (`/app?workflowDraft=<id>`) that open the form pre-filled without submitting.

### Adding another workflow to the allowlist

In **protein-studio**:

1. Extract `buildXDefaultParameters` + form init from that workflow’s UI.
2. Implement `buildXAgentSchema()`.
3. Run `npm run export-agent-schemas` in `frontend/`; commit JSON under `backend/app/data/agent_workflow_schemas/`.
4. Add the workflow id to allowlists (frontend export index, backend `AGENT_WORKFLOW_ALLOWLIST`, proteworks-cli `AGENT_WORKFLOW_ALLOWLIST`).
5. Add default/parity tests; extend the workflows skill if needed.

No new MCP tool names are required.
