proteworks 0.1.3__tar.gz → 0.1.4__tar.gz

proteworks-0.1.4/PKG-INFO

@@ -0,0 +1,116 @@
+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.

proteworks-0.1.4/README.md

@@ -0,0 +1,102 @@
+# 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.

{proteworks-0.1.3 → proteworks-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proteworks"
-version = "0.1.3"
+version = "0.1.4"
 description = "Sync files with Proteworks using file-browser paths."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -11,9 +11,11 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest>=8"]
+mcp = ["mcp>=1.2", "pyarrow>=14"]
 
 [project.scripts]
 proteworks = "proteworks.cli:main"
+proteworks-mcp = "proteworks.mcp.server:main"
 
 [build-system]
 requires = ["setuptools>=68"]

{proteworks-0.1.3 → proteworks-0.1.4}/src/proteworks/api.py

@@ -2,14 +2,29 @@
 
 from __future__ import annotations
 
+import os
 import time
 from typing import Any, Optional
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlparse
 
 import httpx
 
 from proteworks.redact import redact
 
+# Host suffixes allowed for signed download/upload URLs (comma-separated env override).
+_DEFAULT_STORAGE_HOST_SUFFIXES = (
+    "storage.googleapis.com",
+    "googleapis.com",
+    "googleusercontent.com",
+)
+
+
+def allowed_storage_host_suffixes() -> tuple[str, ...]:
+    raw = (os.environ.get("PROTEWORKS_STORAGE_HOST_ALLOWLIST") or "").strip()
+    if raw:
+        return tuple(part.strip().lower() for part in raw.split(",") if part.strip())
+    return _DEFAULT_STORAGE_HOST_SUFFIXES
+
 
 class ApiError(Exception):
     """Sanitized API failure. The message never includes a storage URL."""
@@ -19,6 +34,20 @@ class ApiError(Exception):
         self.status_code = status_code
 
 
+def assert_allowed_storage_url(url: str) -> None:
+    """Reject signed URLs whose host is outside the storage allowlist (SSRF defense)."""
+    parsed = urlparse(str(url or ""))
+    if parsed.scheme not in {"https", "http"}:
+        raise ApiError("Storage URL must use http(s)", 400)
+    host = (parsed.hostname or "").lower()
+    if not host:
+        raise ApiError("Storage URL missing host", 400)
+    suffixes = allowed_storage_host_suffixes()
+    if any(host == suffix or host.endswith("." + suffix) for suffix in suffixes):
+        return
+    raise ApiError("Storage URL host is not allowlisted", 400)
+
+
 def public_detail(response: httpx.Response) -> str:
     """User-facing error from a JSON body, without echoing storage fields."""
     try:
@@ -192,6 +221,7 @@ class ApiClient:
 
     def download_to(self, url: str, path) -> None:
         """Stream bytes to a file. The URL is not logged."""
+        assert_allowed_storage_url(url)
         with self._client.stream("GET", url) as response:
             response.raise_for_status()
             with open(path, "wb") as handle:
@@ -200,7 +230,103 @@ class ApiClient:
 
     def put_file(self, url: str, path, headers: Optional[dict] = None) -> None:
         """Upload a file. The URL is not logged."""
+        assert_allowed_storage_url(url)
         with open(path, "rb") as handle:
             response = self._client.put(url, content=handle, headers=headers or {})
         if response.status_code >= 400:
             raise ApiError(f"Upload to storage failed ({response.status_code})", response.status_code)
+
+    def list_agent_schemas(self) -> dict:
+        return self.request("GET", "/api/v1/workflows/agent-schemas")
+
+    def get_agent_schema(self, workflow_name: str) -> dict:
+        return self.request("GET", f"/api/v1/workflows/agent-schemas/{workflow_name}")
+
+    def submit_workflow(self, body: dict) -> dict:
+        return self.request("POST", "/api/v1/workflows/submit", json_body=body)
+
+    def get_execution(self, execution_id: str) -> dict:
+        return self.request("GET", f"/api/v1/workflows/executions/{execution_id}")
+
+    def list_execution_results(self, execution_id: str) -> list:
+        payload = self.request("GET", f"/api/v1/workflows/executions/{execution_id}/results")
+        return list(payload or [])
+
+    def cancel_execution(self, execution_id: str) -> dict:
+        return self.request("POST", f"/api/v1/workflows/executions/{execution_id}/cancel")
+
+    def estimate_workflow_cost(self, body: dict) -> dict:
+        return self.request("POST", "/api/v1/workflows/estimate-cost", json_body=body)
+
+    def upload_bytes(
+        self,
+        filename: str,
+        folder_id: str,
+        data: bytes,
+        content_type: str = "application/octet-stream",
+    ) -> dict:
+        """Upload bytes via upload-init / PUT / upload-complete."""
+        init = self.upload_init(filename, folder_id, len(data), content_type)
+        if init.get("skipped"):
+            return {"id": init.get("file_id") or init.get("id")}
+        upload_url = init.get("upload_url")
+        session_id = init.get("session_id")
+        if not upload_url or not session_id:
+            raise ApiError("Upload init missing upload_url or session_id", 500)
+        assert_allowed_storage_url(str(upload_url))
+        response = self._client.put(
+            upload_url,
+            content=data,
+            headers={"Content-Type": content_type},
+        )
+        if response.status_code >= 400:
+            raise ApiError(f"Upload to storage failed ({response.status_code})", response.status_code)
+        return self.upload_complete(session_id, len(data))
+
+    def upload_json_bytes(
+        self,
+        filename: str,
+        folder_id: str,
+        data: bytes,
+        content_type: str = "application/json",
+    ) -> dict:
+        """Upload small JSON (e.g. SA handoff) via upload-init / PUT / upload-complete."""
+        return self.upload_bytes(filename, folder_id, data, content_type=content_type)
+
+    def save_selected_studio(
+        self,
+        file_id: str,
+        route_slug: str,
+        design_ids: list[str],
+    ) -> bytes:
+        """POST ``/files/{id}/{route_slug}-save-selected``; return subset .studio bytes."""
+        slug = str(route_slug or "").strip().strip("/")
+        if not slug:
+            raise ApiError("route_slug is required for save-selected", 400)
+        path = f"/api/v1/files/{file_id}/{slug}-save-selected"
+        query: dict[str, str] = {}
+        if self.organization_id:
+            query["organization_id"] = self.organization_id
+        url = self.base_url + path
+        if query:
+            url = url + "?" + urlencode(query)
+        headers = self._headers()
+        headers["Accept"] = "application/zip, application/octet-stream, */*"
+        response = self._client.post(
+            url,
+            headers=headers,
+            json={"design_ids": list(design_ids)},
+        )
+        if response.status_code >= 400:
+            raise ApiError(public_detail(response), response.status_code)
+        return response.content
+
+    def finalize_studio_bundle_retention(self, file_id: str, route_slug: str) -> dict:
+        """POST ``/files/{id}/{route_slug}-bundle-finalize-retention``."""
+        slug = str(route_slug or "").strip().strip("/")
+        if not slug:
+            raise ApiError("route_slug is required for finalize-retention", 400)
+        return self.request(
+            "POST",
+            f"/api/v1/files/{file_id}/{slug}-bundle-finalize-retention",
+        )

proteworks-0.1.4/src/proteworks/browse.py

@@ -0,0 +1,49 @@
+"""List remote file-browser paths without transferring bytes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from proteworks.api import ApiClient, ApiError
+
+
+def list_remote(api: ApiClient, path: str, *, limit: int = 200) -> dict[str, Any]:
+    """
+    List files under a file-browser path.
+
+    Returns agent-safe fields only (includes file_id for future cloud submit).
+    Caps the item list at ``limit`` and sets truncated=true when more remain.
+    """
+    if limit < 1:
+        raise ValueError("limit must be at least 1")
+    try:
+        page = api.manifest_all(path)
+    except ApiError as exc:
+        return {
+            "ok": False,
+            "error": str(exc),
+            "items": [],
+            "total": 0,
+            "root_folder_id": None,
+            "truncated": False,
+        }
+    raw_items = list(page.get("items") or [])
+    total = int(page.get("total") or len(raw_items))
+    truncated = len(raw_items) > limit
+    items = [_normalize_item(item) for item in raw_items[:limit]]
+    return {
+        "ok": True,
+        "items": items,
+        "total": total,
+        "root_folder_id": page.get("root_folder_id"),
+        "truncated": truncated,
+    }
+
+
+def _normalize_item(item: dict) -> dict[str, Any]:
+    return {
+        "file_id": item.get("file_id"),
+        "relative_path": item.get("relative_path"),
+        "size": item.get("size"),
+        "sha256": item.get("sha256"),
+    }

{proteworks-0.1.3 → proteworks-0.1.4}/src/proteworks/cli.py

@@ -19,6 +19,7 @@ from proteworks.orgs import (
 from proteworks.pull import export_organization, pull_path
 from proteworks.push import push_directory
 from proteworks.redact import install_redacting_logs
+from proteworks.session import SessionError, authenticated_client, open_session
 
 _PULL_EXAMPLES = """\
 examples:
@@ -127,35 +128,47 @@ def main(argv: list[str] | None = None, *, settings: Settings | None = None, tok
         data["api_url"] = settings.api_url
         config.write(data)
         return 0
-    token = token_store.get()
-    if not token:
-        print("Run proteworks login.", file=sys.stderr)
-        return 2
-    config = ConfigStore(settings.config_dir / "config.json")
-    bound = config.bound_api_url()
-    if bound and bound.rstrip("/") != settings.api_url.rstrip("/"):
-        print("API URL changed. Run proteworks login again.", file=sys.stderr)
-        return 2
-    api = ApiClient(settings.api_url, token)
-    try:
-        if args.command == "organization" and args.org_command == "list":
+    if args.command == "organization" and args.org_command == "list":
+        auth = authenticated_client(settings=settings, token_store=token_store)
+        if isinstance(auth, SessionError):
+            print(auth.message, file=sys.stderr)
+            return 2
+        api, config = auth
+        try:
             return _organization_list(api, config, sys.stdout)
-        if args.command == "organization" and args.org_command == "set":
-            return _organization_set(api, config, settings, args.name, sys.stderr)
-        org = _require_organization(api, config, sys.stderr)
-        if org is None:
+        finally:
+            api.close()
+    if args.command == "organization" and args.org_command == "set":
+        auth = authenticated_client(settings=settings, token_store=token_store)
+        if isinstance(auth, SessionError):
+            print(auth.message, file=sys.stderr)
             return 2
-        api.organization_id = org["id"]
+        api, config = auth
+        try:
+            return _organization_set(api, config, settings, args.name, sys.stderr)
+        finally:
+            api.close()
+    session = open_session(settings=settings, token_store=token_store)
+    if isinstance(session, SessionError):
+        print(session.message, file=sys.stderr)
+        return 2
+    try:
         if args.command == "pull":
-            return pull_path(api, args.remote, Path(args.dest), dry_run=args.dry_run, stderr=sys.stderr)
+            return pull_path(
+                session.api, args.remote, Path(args.dest), dry_run=args.dry_run, stderr=sys.stderr
+            ).exit_code
         if args.command == "export":
-            return export_organization(api, Path(args.dest), dry_run=args.dry_run, stderr=sys.stderr)
+            return export_organization(
+                session.api, Path(args.dest), dry_run=args.dry_run, stderr=sys.stderr
+            ).exit_code
         if args.command == "push":
-            return push_directory(api, Path(args.local_dir), args.remote, dry_run=args.dry_run, stderr=sys.stderr)
+            return push_directory(
+                session.api, Path(args.local_dir), args.remote, dry_run=args.dry_run, stderr=sys.stderr
+            ).exit_code
         parser.print_help(sys.stderr)
         return 2
     finally:
-        api.close()
+        session.api.close()
 
 
 def _organization_list(api: ApiClient, config: ConfigStore, stdout) -> int:
@@ -181,13 +194,5 @@ def _organization_set(api: ApiClient, config: ConfigStore, settings: Settings, n
     return 0
 
 
-def _require_organization(api: ApiClient, config: ConfigStore, stderr):
-    try:
-        return select_organization(api.list_organizations(), config.organization_id())
-    except OrgSelectionError as exc:
-        print(str(exc), file=stderr)
-        return None
-
-
 if __name__ == "__main__":
     raise SystemExit(main())

{proteworks-0.1.3 → proteworks-0.1.4}/src/proteworks/index.py

@@ -76,11 +76,21 @@ def local_relative(remote: str, relative_path: str) -> str:
 
 
 def destination_for(dest: Path, remote: str, relative_path: str, *, single_file: bool) -> Path:
-    """Place a downloaded file under dest without keeping the ~/ prefix."""
+    """Place a downloaded file under dest without keeping the ~/ prefix.
+
+    Rejects ``..`` / absolute segments so a malicious manifest cannot escape ``dest``.
+    """
     name = local_relative(remote, relative_path)
     if single_file and not _dest_is_directory(dest):
         return dest
-    return dest / name
+    rel = Path(name)
+    if rel.is_absolute() or any(part in {".", ".."} for part in rel.parts):
+        raise ValueError(f"Unsafe relative_path escapes destination: {relative_path!r}")
+    target = (dest / rel).resolve()
+    root = dest.resolve()
+    if root != target and root not in target.parents:
+        raise ValueError(f"Unsafe relative_path escapes destination: {relative_path!r}")
+    return dest / rel
 
 
 def _dest_is_directory(dest: Path) -> bool:

proteworks-0.1.4/src/proteworks/mcp/__init__.py

@@ -0,0 +1,13 @@
+"""Local MCP server for Proteworks (stdio). Domain tools register on the shared server."""
+
+from __future__ import annotations
+
+__all__ = ["create_server", "main"]
+
+
+def __getattr__(name: str):
+    if name in {"create_server", "main"}:
+        from proteworks.mcp import server as _server
+
+        return getattr(_server, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

proteworks-0.1.4/src/proteworks/mcp/errors.py

@@ -0,0 +1,32 @@
+"""Stable MCP tool error messages (no raw exception / URL leakage)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from proteworks.api import ApiError
+from proteworks.redact import redact
+
+
+def tool_error_message(exc: BaseException) -> str:
+    """Map an exception to a short, redacted user-facing message."""
+    if isinstance(exc, ApiError):
+        cleaned = redact(str(exc))
+        return cleaned if isinstance(cleaned, str) else "Request failed"
+    if isinstance(exc, (ValueError, RuntimeError, OSError, TypeError)):
+        cleaned = redact(str(exc))
+        if isinstance(cleaned, str) and cleaned.strip():
+            # Drop long path dumps / URL-like fragments.
+            text = cleaned.strip()
+            if len(text) > 240:
+                text = text[:237] + "..."
+            return text
+    return "Request failed"
+
+
+def tool_failure(error: str, message: str, **extra: Any) -> dict[str, Any]:
+    """Build a standard MCP failure payload."""
+    payload: dict[str, Any] = {"ok": False, "error": error, "message": message}
+    payload.update(extra)
+    cleaned = redact(payload)
+    return cleaned if isinstance(cleaned, dict) else {"ok": False, "error": error, "message": message}

proteworks-0.1.4/src/proteworks/mcp/paths.py

@@ -0,0 +1,47 @@
+"""Local path sandbox for MCP pull/push (workspace root containment)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_ENV_ROOT = "PROTEWORKS_MCP_ROOT"
+
+
+def mcp_workspace_root() -> Path:
+    """Return the allowlisted local root for MCP file transfers."""
+    raw = (os.environ.get(_ENV_ROOT) or "").strip()
+    if raw:
+        return Path(raw).expanduser().resolve()
+    return Path.cwd().resolve()
+
+
+def resolve_under_workspace(user_path: str, *, root: Path | None = None) -> Path:
+    """Resolve a user path under the MCP workspace; reject escapes.
+
+    Relative paths are resolved against the workspace root. Absolute paths are
+    allowed only when they resolve inside the root.
+    """
+    workspace = (root or mcp_workspace_root()).resolve()
+    raw = str(user_path or "").strip()
+    if not raw:
+        raise ValueError("Path is required.")
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        candidate = workspace / candidate
+    resolved = candidate.resolve()
+    if workspace != resolved and workspace not in resolved.parents:
+        raise ValueError(
+            f"Path escapes MCP workspace root ({workspace}). "
+            f"Set {_ENV_ROOT} or use a path under the workspace."
+        )
+    return resolved
+
+
+def assert_relative_under(dest: Path, target: Path) -> Path:
+    """Ensure ``target`` resolves under ``dest`` (pull path containment)."""
+    root = dest.resolve()
+    resolved = target.resolve()
+    if root != resolved and root not in resolved.parents:
+        raise ValueError("Download path escapes the destination directory.")
+    return resolved