Correct the CI claims and the agent tooling's honesty about itself

I asserted that the MySQL migration job "was a comment, not a job" and that
nothing had ever run a fresh install on MySQL. Both wrong. The job existed, hit
this org's ARC runners, and was deliberately moved to internal CI in ffe9fa1cc
because Kubernetes runners without docker-in-docker cannot host service
containers - a fact written at the bottom of the very file I was editing. The
job I added would have failed at container setup on its first push.

Removed it. The leftover was the HEADER, which listed a job that had moved, and
that is now corrected in place with a note not to re-add the entry without
re-adding a job to a runner that can host it. Coverage stays on internal CI.

The api-contract job was green by accident. gen_openapi.py refuses to run while
a bundled plugin is disabled, instance/plugins.json is gitignored, and the step
only worked because the earlier pytest step writes that file at import time and
leaves it. Reordering the steps would have produced a failure about disabled
plugins that had nothing to do with the spec. It now seeds its own registry.
Confirmed against a clean archive of HEAD, where the generator does refuse.

shopdb_whoami claimed to report "what the token is scoped to" and reported the
ACCOUNT's permissions. A read-scoped token on an admin account printed
roles=[admin] and the full permission count, so a model would try a write, take
a 403, and have no tool that explained it. The field is now account_permissions
and carries a note saying a scoped token may allow fewer. Fixing this properly
means /api/auth/me publishing the patscopes claim, which is a separate change.

The MCP client caught only urllib's two error types, so an ordinary mistake
escaped as a raw exception with no cause reaching the caller: a space in a path
raises InvalidURL, a non-ASCII path raises UnicodeEncodeError, a slow read
raises TimeoutError. Paths are now percent-encoded and those escapes are
contained; both cases return the API's own 404 envelope instead.

The operation index collapsed optional authentication. Fourteen routes work
signed out and return more when authenticated, and the index printed them as
requiring a bearer token. They now read bearerAuth,optional.

Also: the generator's own hint told the reader to run "flask plugins enable";
the CLI group is "plugin".

tools/mcp/shopdb_mcp/client.py

@@ -16,6 +16,7 @@ import threading
 import time
 from dataclasses import dataclass
 from typing import Any
+import http.client as http_client
 from urllib import error, parse, request
 
 # How long a fetched index or spec stays usable before it is re-read. Long
@@ -86,7 +87,11 @@ class ShopdbClient:
     def request(self, method: str, path: str, params: dict | None = None,
                 body: Any = None) -> tuple[int, Any]:
         """One HTTP call. Returns (status, parsed-body-or-text)."""
-        url = self.base_url + '/' + path.lstrip('/')
+        # Encode what a caller typed. A model filling an id into a templated
+        # path can easily produce a space or an accent; leaving those raw turns
+        # a legitimate request into an exception rather than a 404. '/' and the
+        # query delimiters stay literal so an already-formed path still works.
+        url = self.base_url + '/' + parse.quote(path.lstrip('/'), safe='/?=&%+,')
         if params:
             # Drop empty values rather than sending key= , which several list
             # endpoints treat as a filter on the empty string.
@@ -102,8 +107,9 @@ class ShopdbClient:
             data = json.dumps(body).encode('utf-8')
             headers['Content-Type'] = 'application/json'
 
-        req = request.Request(url, data=data, headers=headers, method=method.upper())
         try:
+            req = request.Request(url, data=data, headers=headers,
+                                  method=method.upper())
             with self._opener().open(req, timeout=self.timeout) as response:
                 return response.status, _decode(response.read(),
                                                 response.headers.get('Content-Type'))
@@ -113,6 +119,15 @@ class ShopdbClient:
             return exc.code, _decode(exc.read(), exc.headers.get('Content-Type'))
         except error.URLError as exc:
             raise ShopdbError(f'could not reach {self.base_url}: {exc.reason}') from exc
+        except (OSError, ValueError, http_client.HTTPException) as exc:
+            # Catching only the two urllib errors let ordinary mistakes escape
+            # as raw exceptions: a space in a path raises InvalidURL, a non
+            # ASCII path raises UnicodeEncodeError, a read that outruns the
+            # timeout raises TimeoutError. The caller then saw a bare "error
+            # executing tool" with no cause and nothing to try differently.
+            raise ShopdbError(
+                f'{method.upper()} {path} could not be sent: '
+                f'{type(exc).__name__}: {exc}') from exc
 
     def _cached(self, key: str, fetch):
         with self._lock:

tools/mcp/shopdb_mcp/server.py

@@ -54,11 +54,16 @@ def _fail(message: str) -> str:
 
 @mcp.tool()
 def shopdb_whoami() -> str:
-    """Check which ShopDB instance this server targets and what the token can do.
+    """Check which ShopDB instance this server targets and who the token is.
 
-    Call this first. It confirms the instance is reachable, the credential is
-    valid, and - importantly - what the token is scoped to, which determines
-    which other calls will succeed.
+    Call this first: it confirms the instance is reachable and the credential is
+    valid.
+
+    IMPORTANT: the permissions reported are the ACCOUNT's, not the token's. A
+    scoped personal access token carries its own narrower scope list, which the
+    server enforces but does not publish, so a call can still be refused with
+    403 even though the account shown here holds the permission. Treat this as
+    "who am I", not "what may I do".
     """
     try:
         c = client()
@@ -81,7 +86,14 @@ def shopdb_whoami() -> str:
         'instance': c.base_url,
         'username': user.get('username'),
         'roles': user.get('roles'),
-        'permissions': len(user.get('permissions') or []),
+        # Named account_permissions, not permissions, because that is what it
+        # is. Calling it "permissions" next to a token invited exactly the
+        # wrong reading: that an admin account means every call will succeed,
+        # when a read-scoped token on that same account is refused a write.
+        'account_permissions': len(user.get('permissions') or []),
+        'note': ('permissions shown are the account\'s; a scoped token may '
+                 'allow fewer, and a 403 from shopdb_call means the TOKEN '
+                 'lacks the scope even if the account holds the permission'),
         'operations_published': count,
         'tls_verified': c.verify_tls,
     }, indent=2)