Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Changelog

## Unreleased

- `apple_reply_review` is now two-step: the default call validates and returns a preview without sending; it sends only with the `confirm_token` from that preview, a hash of the exact text, attachments and submission, so nothing can change between preview and send, and a token sends only once (#12). Suggested by u/QuanTradin on r/mcp.
- Tools marked "External action" now carry MCP tool annotations (`destructiveHint`, `openWorldHint`) so clients can gate them.

## 0.2.0

- Toolsets: `SHIPSTORES_TOOLSETS` (or `[server] toolsets` in `config.toml`) exposes only the tool groups you need: `apple`, `play` and/or `eas`. Core diagnostics stay on, and the default is still all 60 tools. Thanks @berkay-byte for the first community contribution (#11).
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ uvx --from shipstores python -m shipstores.browser login # opens a window; sig

**Apple: listing & app setup** — `apple_update_listing`, `apple_upload_screenshots`, `apple_set_app_info` (subtitle, URLs, categories, copyright, content rights), `apple_set_age_rating`, `apple_set_free_price`, `apple_set_availability`, `apple_set_app_privacy`, `apple_review_details`, `apple_set_review_details`

**Apple: App Review** — `apple_review_messages` (read the rejection and its guideline), `apple_reply_review` (answer with text + attachments; iPhone HEVC videos are converted to H.264)
**Apple: App Review** — `apple_review_messages` (read the rejection and its guideline), `apple_reply_review` (answer with text + attachments; iPhone HEVC videos are converted to H.264; returns a preview and a `confirm_token` first; only sends when called again with that token)

**Apple: subscriptions** — `apple_create_subscription_group`, `apple_create_subscription`, `apple_list_price_points`, `apple_set_subscription_price`, `apple_set_subscription_availability`, `apple_create_intro_offer`, `apple_list_subscriptions`, `apple_upload_subscription_screenshot`

Expand All @@ -115,7 +115,7 @@ uvx --from shipstores python -m shipstores.browser login # opens a window; sig

**Expo / EAS** — `eas_build_list`, `eas_build_start`, `eas_build_status`, `eas_build_download`, `eas_submit`

Tools that publish or submit (`apple_submit_for_review`, `apple_resubmit_for_review`, `apple_reply_review`, `apple_cancel_submission`, `apple_set_*`, `apple_testflight_invite`, `play_upload_bundle`, `play_promote_release`, `play_upload_screenshots`) say so in their description, so the agent confirms with you first.
Tools that publish or submit (`apple_submit_for_review`, `apple_resubmit_for_review`, `apple_reply_review`, `apple_cancel_submission`, `apple_set_*`, `apple_testflight_invite`, `play_upload_bundle`, `play_promote_release`, `play_upload_screenshots`) say so in their description, so the agent confirms with you first. They also carry MCP tool annotations (`destructiveHint`), so clients that support them can ask for approval on their own. `apple_reply_review` goes further: the reply reaches a person at Apple, so the server only sends it on a second call carrying the `confirm_token` from the preview — a hash of the exact text, attachments and submission, usable once.

## Workflows

Expand Down
32 changes: 29 additions & 3 deletions src/shipstores/apple_review.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,15 @@

ASC = "https://appstoreconnect.apple.com"

# Printed by the harness script right after the Reply button is clicked. Without it
# in the output, the failure happened before anything could reach Apple.
CLICKED = "__SP__clicked"


class ReplyNotSent(browser.BrowserError):
"""The reply failed before the Reply button was clicked: nothing reached Apple."""


# Console UI labels, matched literally against the page text (pt-BR and en-US)
REPLY_OPEN = ("Responda à equipe de revisão de apps", "Reply to App Review")
REPLY_SEND = ("Responder", "Reply")
Expand Down Expand Up @@ -91,7 +100,11 @@ def prepare_attachment(path: Path) -> Path:


def reply(app_id: str, submission_id: str, text: str, attachments: list[Path]) -> str:
"""Reply to App Review through the console box and verify the message landed in the thread."""
"""Reply to App Review through the console box and verify the message landed in the thread.

Raises ReplyNotSent only when the failure provably happened before the click.
Any other error means the message may have reached Apple.
"""
script = f"""
import time, json
TEXT = {json.dumps(text)}
Expand Down Expand Up @@ -135,15 +148,28 @@ def reply(app_id: str, submission_id: str, text: str, attachments: list[Path]) -
sent = js("(()=>{{const b=[...document.querySelectorAll('[role=dialog] button')].filter(b=>%s.includes(b.innerText.trim())).pop(); if(!b) return 'no button'; if(b.disabled) return 'disabled'; b.click(); return 'sent'}})()" % json.dumps(SEND))
if sent != 'sent':
raise SystemExit('ERROR: not sent (' + sent + ')')
print({CLICKED!r}, flush=True)
for _ in range(15):
time.sleep(2)
if js(COUNT) > before: break
else:
raise SystemExit('ERROR: the message did not appear in the thread after sending')
print('__SP__ok')
"""
out = browser.run_harness(script, timeout=600)
try:
out = browser.run_harness(script, timeout=600)
except subprocess.TimeoutExpired as exc:
partial = exc.stdout.decode(errors="replace") if isinstance(exc.stdout, bytes) else (exc.stdout or "")
if partial and CLICKED not in partial:
raise ReplyNotSent("Timed out before clicking Reply; nothing was sent.") from exc
raise browser.BrowserError("Timed out after clicking Reply; the message may have been sent.") from exc
except browser.BrowserError as exc:
# Only a failed script run carries its output; anything else may come after the click.
if str(exc).startswith(("browser-harness failed", "browser-harness not found")) and CLICKED not in str(exc):
erro = next((l for l in str(exc).splitlines() if l.startswith("ERROR")), str(exc)[-500:])
raise ReplyNotSent(erro) from exc
raise
if "__SP__ok" not in out:
erro = next((l for l in out.splitlines() if l.startswith("ERROR")), out[-500:])
raise browser.BrowserError(erro)
raise (browser.BrowserError if CLICKED in out else ReplyNotSent)(erro)
return "sent"
85 changes: 80 additions & 5 deletions src/shipstores/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,15 @@

from __future__ import annotations

import hashlib
import tempfile
from collections.abc import Callable
from pathlib import Path
from typing import Any

import httpx
from fastmcp import FastMCP
from mcp.types import ToolAnnotations

from . import apple, apple_console, apple_review, browser, data_safety, eas, play, play_console, signing
from .config import (
Expand Down Expand Up @@ -51,6 +53,11 @@

_CORE_TOOLS = {"store_doctor", "store_audit_identity", "store_browser_session"}

# Tools whose docstring says "External action" change something in a store (or
# reach a person at Apple/Google). Clients that read MCP annotations can gate
# them without relying on the description text.
_EXTERNAL_ACTION = ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True)


def _register_tool(function: Callable[..., Any]) -> Any:
name = function.__name__
Expand All @@ -60,7 +67,8 @@ def _register_tool(function: Callable[..., Any]) -> Any:
toolset = name.partition("_")[0]
if toolset not in TOOLSETS - {"core"}:
raise ValueError(f"Tool {name!r} does not belong to a known toolset.")
return mcp.tool(tags={toolset})(function)
external = "External action" in (function.__doc__ or "")
return mcp.tool(tags={toolset}, annotations=_EXTERNAL_ACTION if external else None)(function)


# ---------------------------------------------------------------- diagnostics
Expand Down Expand Up @@ -697,29 +705,96 @@ def apple_review_messages(app_id: str) -> dict[str, Any]:
return {"app_id": app_id, "messages": messages, "total": len(messages)}


# Preview tokens already used to send a reply, so a repeated confirm cannot send twice.
_SENT_REPLY_TOKENS: set[str] = set()


def _reply_token(app_id: str, sub_id: str, text: str, files: list[Path]) -> str:
"""Hash of everything that would be sent: the submission, the exact text and each attachment's bytes."""
digest = hashlib.sha256()
for part in (app_id, sub_id, text):
digest.update(part.encode())
digest.update(b"\0")
for path in files:
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1 << 20), b""):
digest.update(chunk)
digest.update(b"\0")
return digest.hexdigest()[:16]


@_register_tool
def apple_reply_review(
app_id: str, text: str, attachments: list[str] | None = None
app_id: str, text: str, attachments: list[str] | None = None, confirm_token: str = ""
) -> dict[str, Any]:
"""Reply to App Review on a rejected submission, with attachments. External action.

Two steps, because the reply goes to a person at Apple and cannot be edited
or taken back:
1. Call without confirm_token. Nothing is sent: it validates the text and
attachments, converts videos, finds the rejected submission and returns a
preview plus a `confirm_token` (a hash of exactly what would be sent).
2. Show the preview to the user. Only after an explicit yes, call again with
the same arguments and that confirm_token. If the text, an attachment or
the submission changed since the preview, the token no longer matches and
nothing is sent. A token can only send once.

For a "Guideline 2.1 - Information Needed" request: send the answers in
`text` (up to 4000 characters) and the video recorded on the iPhone in
`attachments`. HEVC video is converted to H.264 at 1920px before upload. Copy
the same information into the review notes with apple_set_review_details, as
Apple asks. Replying is not enough: the version stays Rejected until you
resubmit it ("Update Review" on the version page, then resubmit).
"""
if not text.strip():
raise ValueError("The reply is empty.")
if len(text) > 4000:
raise ValueError(f"The reply has {len(text)} characters; the console limit is 4000.")
files = []
originals = []
for item in attachments or []:
path = Path(item).expanduser()
if not path.exists():
raise FileNotFoundError(f"Attachment not found: {path}")
files.append(apple_review.prepare_attachment(path))
originals.append(path)
sub_id = _active_submission(app_id, ("UNRESOLVED_ISSUES",))
apple_review.reply(app_id, sub_id, text, files)
token = _reply_token(app_id, sub_id, text, originals)
if not confirm_token:
files = [apple_review.prepare_attachment(path) for path in originals]
return {
"sent": False,
"preview": {
"review_submission_id": sub_id,
"text": text,
"characters": len(text),
"attachments": [str(f) for f in files],
},
"confirm_token": token,
"next_step": (
"Nothing was sent. Show this preview to the user; only after an explicit yes, "
"call apple_reply_review again with the same arguments and this confirm_token."
),
}
if confirm_token in _SENT_REPLY_TOKENS:
raise ValueError("This reply was already sent with this confirm_token; nothing was sent again.")
if confirm_token != token:
raise ValueError(
"confirm_token does not match: the text, an attachment or the submission changed since "
"the preview. Nothing was sent. Call again without confirm_token for a new preview."
)
files = [apple_review.prepare_attachment(path) for path in originals]
_SENT_REPLY_TOKENS.add(token)
try:
apple_review.reply(app_id, sub_id, text, files)
except apple_review.ReplyNotSent:
# Nothing reached Apple, so the same token may retry.
_SENT_REPLY_TOKENS.discard(token)
raise
except Exception as exc:
# Unknown outcome: keep the token burned so a retry cannot double-post.
raise RuntimeError(
f"{exc}\nThe reply may have reached Apple. Check with apple_review_messages "
"before sending anything again."
) from exc
return {
"review_submission_id": sub_id,
"sent": True,
Expand Down
145 changes: 145 additions & 0 deletions tests/test_reply_review.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
import asyncio
import subprocess
import tempfile
import unittest
from pathlib import Path
from unittest.mock import patch

from shipstores import server


class ReplyReviewConfirmTests(unittest.TestCase):
def setUp(self) -> None:
server._SENT_REPLY_TOKENS.clear()
self.submission = patch.object(server, "_active_submission", return_value="sub-1")
self.reply = patch.object(server.apple_review, "reply")
self.submission.start()
self.reply_mock = self.reply.start()

def tearDown(self) -> None:
self.reply.stop()
self.submission.stop()

def test_default_returns_preview_and_token_without_sending(self) -> None:
result = server.apple_reply_review("123", "Here is the demo video.")
self.reply_mock.assert_not_called()
self.assertFalse(result["sent"])
self.assertEqual(result["preview"]["text"], "Here is the demo video.")
self.assertTrue(result["confirm_token"])

def test_confirm_with_matching_token_sends(self) -> None:
token = server.apple_reply_review("123", "Here is the demo video.")["confirm_token"]
result = server.apple_reply_review("123", "Here is the demo video.", confirm_token=token)
self.reply_mock.assert_called_once_with("123", "sub-1", "Here is the demo video.", [])
self.assertTrue(result["sent"])

def test_changed_text_after_preview_is_rejected(self) -> None:
token = server.apple_reply_review("123", "Here is the demo video.")["confirm_token"]
with self.assertRaises(ValueError):
server.apple_reply_review("123", "Something else entirely.", confirm_token=token)
self.reply_mock.assert_not_called()

def test_changed_attachment_after_preview_is_rejected(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
note = Path(tmp) / "notes.pdf"
note.write_bytes(b"%PDF v1")
token = server.apple_reply_review("123", "See attached.", [str(note)])["confirm_token"]
note.write_bytes(b"%PDF v2")
with self.assertRaises(ValueError):
server.apple_reply_review("123", "See attached.", [str(note)], confirm_token=token)
self.reply_mock.assert_not_called()

def test_changed_submission_after_preview_is_rejected(self) -> None:
token = server.apple_reply_review("123", "Hi")["confirm_token"]
with patch.object(server, "_active_submission", return_value="sub-2"):
with self.assertRaises(ValueError):
server.apple_reply_review("123", "Hi", confirm_token=token)
self.reply_mock.assert_not_called()

def test_two_confirms_in_a_row_send_once(self) -> None:
token = server.apple_reply_review("123", "Hi")["confirm_token"]
server.apple_reply_review("123", "Hi", confirm_token=token)
with self.assertRaises(ValueError):
server.apple_reply_review("123", "Hi", confirm_token=token)
self.reply_mock.assert_called_once()

def test_failure_before_send_allows_retry(self) -> None:
token = server.apple_reply_review("123", "Hi")["confirm_token"]
self.reply_mock.side_effect = [server.apple_review.ReplyNotSent("ERROR: the reply box did not open"), "sent"]
with self.assertRaises(server.apple_review.ReplyNotSent):
server.apple_reply_review("123", "Hi", confirm_token=token)
server.apple_reply_review("123", "Hi", confirm_token=token)
self.assertEqual(self.reply_mock.call_count, 2)

def test_failure_after_send_keeps_token_burned(self) -> None:
token = server.apple_reply_review("123", "Hi")["confirm_token"]
self.reply_mock.side_effect = server.browser.BrowserError("ERROR: the message did not appear in the thread")
with self.assertRaises(RuntimeError):
server.apple_reply_review("123", "Hi", confirm_token=token)
with self.assertRaises(ValueError):
server.apple_reply_review("123", "Hi", confirm_token=token)
self.assertEqual(self.reply_mock.call_count, 1)

def test_validation_runs_before_preview(self) -> None:
with self.assertRaises(ValueError):
server.apple_reply_review("123", "x" * 4001)
with self.assertRaises(ValueError):
server.apple_reply_review("123", " ")
with self.assertRaises(FileNotFoundError):
server.apple_reply_review("123", "See attached.", ["/nonexistent/video.mov"])
self.reply_mock.assert_not_called()


class ReplyOutcomeTests(unittest.TestCase):
"""apple_review.reply says "not sent" only when the click provably did not happen."""

def _reply(self, **harness):
with patch.object(server.apple_review.browser, "run_harness", **harness):
return server.apple_review.reply("123", "sub-1", "Hi", [])

def test_script_error_before_click_is_not_sent(self) -> None:
error = server.browser.BrowserError("browser-harness failed (exit 1):\nERROR: the reply box did not open")
with self.assertRaises(server.apple_review.ReplyNotSent):
self._reply(side_effect=error)

def test_script_error_after_click_may_be_sent(self) -> None:
error = server.browser.BrowserError(
"browser-harness failed (exit 1):\n__SP__clicked\nERROR: the message did not appear in the thread"
)
with self.assertRaises(server.browser.BrowserError) as ctx:
self._reply(side_effect=error)
self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent)

def test_timeout_after_click_may_be_sent(self) -> None:
timeout = subprocess.TimeoutExpired("browser-harness", 600, output="__SP__clicked\n")
with self.assertRaises(server.browser.BrowserError) as ctx:
self._reply(side_effect=timeout)
self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent)

def test_timeout_without_output_may_be_sent(self) -> None:
with self.assertRaises(server.browser.BrowserError) as ctx:
self._reply(side_effect=subprocess.TimeoutExpired("browser-harness", 600))
self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent)

def test_other_errors_may_be_sent(self) -> None:
with self.assertRaises(server.browser.BrowserError) as ctx:
self._reply(side_effect=server.browser.BrowserError("Logged out of the Apple console"))
self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent)


class ToolAnnotationTests(unittest.TestCase):
def test_external_action_tools_are_annotated(self) -> None:
tools = {t.name: t for t in asyncio.run(server.mcp.list_tools())}
for name in ("apple_reply_review", "apple_submit_for_review", "play_promote_release", "eas_submit"):
annotations = tools[name].annotations
self.assertIsNotNone(annotations, name)
self.assertTrue(annotations.destructiveHint, name)
self.assertFalse(annotations.readOnlyHint, name)

def test_read_tools_are_not_flagged_destructive(self) -> None:
tools = {t.name: t for t in asyncio.run(server.mcp.list_tools())}
self.assertIsNone(tools["apple_review_messages"].annotations)


if __name__ == "__main__":
unittest.main()
Loading