Metadata-Version: 2.4
Name: proteworks
Version: 0.1.4
Summary: Sync files with Proteworks using file-browser paths.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=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.

```bash
uv tool install proteworks
proteworks login
proteworks organization list
proteworks organization set "My Org"
proteworks pull '~/My Files/campaigns/run/' ./run
proteworks push ./1UBQ.pdb '~/My Files/test/'
proteworks push ./run '~/My Files/campaigns/run/'
```

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

Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs. The same URL is used in development and production.

## MCP (Claude Science and other clients)

The same login and organization selection power a local MCP server. Install the MCP extra, sign in once with the CLI, then point your client at `proteworks-mcp`.

```bash
uv tool install 'proteworks[mcp]'
# or: pip install 'proteworks[mcp]'
proteworks login
proteworks organization set "My Org"
```

### Claude Science

1. Settings → Connectors → Add connector → **Local command**
2. Command: `proteworks-mcp`  
   (or `uvx --from 'proteworks[mcp]' proteworks-mcp`)
3. Approve tools as needed

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 (OS keychain + `~/.config/proteworks/`). There is no separate MCP login.

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