v0.1.1: diagnostic env-var errors, 403 scope-detail parsing, README link cleanup - #1

Summary

Addresses 4 UX issues raised by an early reviewer on v0.1.0 setup. All four bundled into one v0.1.1 patch release.

Reviewer feedback (1-by-1)

1. Misleading error when RISEUP_PAT is missing

Previously the code only distinguished "falsy" from "wrong prefix" — a RISEUP_PAT="" (or any other falsy state) triggered the "is required" message, but if the env var was set to anything else that didn't start with riseup_pat_, you got "token looks malformed". Easy to misdiagnose "I haven't configured the env var" as "I have the wrong format".

Fix: three distinct error messages now, one per failure mode:

• RISEUP_PAT environment variable is not set. Add it to your MCP client config (e.g. claude_desktop_config.json under mcpServers.<name>.env.RISEUP_PAT). Create a token at https://input.riseup.co.il/developer/tokens
• RISEUP_PAT environment variable is empty. Set it to the actual token value, not an empty string. ...
• RISEUP_PAT doesn't look like a RiseUp token — expected prefix "riseup_pat_", got "sk-someother…". Each token is shown only once at ... — make sure you copied the full value.

The wrong-format variant includes a 12-char snippet of what was actually received so users can spot copy-paste mistakes (truncated to avoid leaking what might be a valid token of another shape).

2. 403 without scope detail

Previously the MCP threw a generic RiseUp PAT lacks the required scope (403) regardless of what the API actually said in the response body. The companion olaf PR will start returning structured { required, availableOnToken } in the 403 body — this change makes the MCP read and surface those fields.

Fix: new _parse403Detail helper:

if (response.status === 403) {
  const detail = await _parse403Detail(response);
  throw new Error(`RiseUp PAT lacks the required scope (403).${detail} Recreate the token with the right scopes at ${TOKENS_URL}`);
}

When the API responds with { "required": "budget:read", "availableOnToken": ["transactions:read"] }, the user sees:

RiseUp PAT lacks the required scope (403). Missing scope: budget:read. Your token has: transactions:read. Recreate the token with the right scopes at https://input.riseup.co.il/developer/tokens

When the body is empty or not JSON, falls back to the previous generic message — so this change is forward-compatible with whatever olaf does or doesn't include in the response body.

3. README link confusion (app.riseup.co.il vs input.riseup.co.il)

Reviewer said the README pointed to app.riseup.co.il. It didn't — but the previous wording was:

Log into the RiseUp web app and visit the developer tokens page.

The link text "RiseUp web app" naturally suggests the URL is app.riseup.co.il to a skimming reader, even though it's actually input.riseup.co.il. So readers were typing app.riseup.co.il into their browsers based on the mental model the link text created.

Fix: drop the redundant first link entirely. Now:

Visit RiseUp's developer tokens page, create a token, pick the budget:read scope, and copy it. It is shown only once.

Same cleanup applied to docs/quickstart.md (which had the same the RiseUp web app at https://input.riseup.co.il pattern, replaced with a direct URL).

4. Config changes don't take effect without a full restart

Claude Desktop reads claude_desktop_config.json only at startup. Changing RISEUP_PAT (e.g. after creating a new token) and just closing the window doesn't pick up the new value — you have to Cmd+Q and reopen. Reviewer wasted time on this; the README didn't flag it.

Fix: previous one-liner Restart Claude Desktop. The get_budget tool should appear. replaced with:

Fully quit Claude Desktop (Cmd+Q on macOS) and reopen — closing the window isn't enough. Claude Desktop reads claude_desktop_config.json only at startup, so any change to RISEUP_PAT or other env values needs a full restart to take effect. After restart, the get_budget tool should appear.

What's also in this PR

• CHANGELOG.md — new file. v0.1.1 entries above + v0.1.0 backfilled. Going forward every release gets an entry per the runbook.
• Tests: 21 → 25 (4 new). Cover empty-string PAT, the wrong-prefix detail in the error, 403-JSON-body parsing, 403-non-JSON fallback.

Version

package.json: 0.1.0 → 0.1.1. Patch release per semver (bug fixes only, no API changes for tool consumers).

What's NOT in this PR (intentionally deferred)

• olaf-side 403 body change (Batch B in the plan) — separate PR on olaf. MCP changes here are forward-compatible: when olaf starts returning structured 403 bodies, this MCP picks up the detail automatically. Until then, generic-message fallback.
• GET /api/me token-introspection endpoint (Batch C / future feature) — needs design work with security team, not a same-day fix.

Test plan

• Build clean: npm run build
• All 25 tests pass: npm test
• After merge: bump to v0.1.1 on npm (npm publish --access public), update Claude Desktop config to use the published version, re-trigger the failure cases from the reviewer to verify the new messages

🤖 Generated with Claude Code