@platless/axom-cli 0.1.0 → 0.5.9

package/dist/mcp.js

@@ -11,7 +11,7 @@ export async function callAxomTool(server, toolName, args) {
     }
     catch (error) {
         if (isInsufficientScope(error))
-            throw insufficientScopeError(normalizedServer);
+            throw insufficientScopeError(normalizedServer, toolName);
         if (!isUnauthorized(error))
             throw error;
         // An env token cannot be refreshed: `accessTokenFor` returns the same literal whatever
@@ -28,7 +28,7 @@ export async function callAxomTool(server, toolName, args) {
     }
     catch (error) {
         if (isInsufficientScope(error))
-            throw insufficientScopeError(normalizedServer);
+            throw insufficientScopeError(normalizedServer, toolName);
         if (isUnauthorized(error)) {
             throw new AuthError(`MCP authentication failed with ${normalizedServer}. Run: axom auth --server ${normalizedServer}`);
         }
@@ -45,7 +45,7 @@ async function callAxomToolOnce(server, token, toolName, args) {
     try {
         await client.connect(transport);
         const result = await client.callTool({ name: toolName, arguments: args });
-        return toToolOutcome(result);
+        return addPermissionAdvice(toolName, toToolOutcome(result));
     }
     finally {
         try {
@@ -89,12 +89,7 @@ function isUnauthorized(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /\b401\b/.test(message);
 }
-/**
- * `/mcp` returns 403 (not 401) when the bearer token is valid but lacks the `mcp` scope — this is
- * how a `workstation`-only access token (the default for a token minted without `--scope mcp`)
- * looks from the client. Retrying with a refreshed token would not help, since the new token would
- * carry the same scopes, so this is checked before the 401/refresh path, not folded into it.
- */
+/** A 403 is an authorization refusal, so refreshing the same grant cannot make it succeed. */
 export function isInsufficientScope(error) {
     const candidate = error;
     if (candidate.status === 403 || candidate.code === 403 || candidate.response?.status === 403)
@@ -102,11 +97,34 @@ export function isInsufficientScope(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /\b403\b/.test(message);
 }
-export function insufficientScopeError(server) {
-    const hint = usesEnvAccessToken()
-        ? ' Set AXOM_ACCESS_TOKEN to a token that includes the "mcp" scope, or run axom auth.'
-        : '';
-    return new AuthError(`MCP token is missing the "mcp" scope for ${server}.${hint}`);
+/** Abilities every credential has (Ability registry: BASELINE with the MCP surface). */
+const BASELINE_TOOL_SCOPES = new Set(['system', 'guide', 'app_struct']);
+const TOOL_SCOPE = /^axom__([a-z][a-z0-9]*(?:_[a-z0-9]+)*)__[a-z]/;
+const ADMIN_NOTE = ' Scopes marked "Requires an administrator account" on the consent page also need an administrator user.';
+/** An external tool's middle segment IS the OAuth scope that grants it (spec 2026-09-26 §3.5). */
+export function scopeForTool(toolName) {
+    const scope = toolName ? TOOL_SCOPE.exec(toolName)?.[1] : undefined;
+    return scope && !BASELINE_TOOL_SCOPES.has(scope) ? scope : undefined;
+}
+export function insufficientScopeError(server, toolName) {
+    const scope = scopeForTool(toolName);
+    if (!scope)
+        return new AuthError(`MCP authorization was denied by ${server}. Check this credential's approved scopes.`);
+    const remedy = usesEnvAccessToken()
+        ? ` Create or edit an access token under Settings → Security and grant ${scope}.`
+        : ` Run axom auth --server ${server} and select ${scope}.`;
+    return new AuthError(`MCP authorization was denied by ${server}. Required OAuth scope: ${scope}.${remedy}${ADMIN_NOTE}`);
+}
+function addPermissionAdvice(toolName, outcome) {
+    if (!outcome.isError || !isPermissionFailure(outcome.text))
+        return outcome;
+    const scope = scopeForTool(toolName);
+    if (!scope)
+        return outcome;
+    return { ...outcome, text: `${outcome.text}\nRequired OAuth scope: ${scope}.${ADMIN_NOTE}` };
+}
+function isPermissionFailure(message) {
+    return /permission denied|not authorized|forbidden|insufficient[_ ]scope|MCP grant is no longer valid/i.test(message);
 }
 /**
  * Is this process authenticating with `AXOM_ACCESS_TOKEN` rather than a stored login? Mirrors