fix: OAuth scope mismatch, runtime dep, and Claude Desktop setup docs

[joalves]

Summary

• OAuth scope fix: the redirect to the ABsmartly backend was hardcoded to api:read api:write, but the backend's discovery endpoint advertises only ["mcp:access","user:info"] and rejects anything else with invalid_scope. This blocked OAuth login entirely. Updated the outgoing scope, the MCP-advertised scopesSupported, and the approval-page descriptions to match.
• Runtime dep fix: @absmartly/cli was in devDependencies but is imported as a runtime value by the stdio entry (local-server.ts) and the worker (index.ts, cli-catalog.ts). Worker bundling masked the issue, but npx @absmartly/mcp would have failed for end users. Moved to dependencies.
• Docs: replaced the misleading "API key requires mcp-remote" framing for Claude Desktop with the URL-based form (?api_key=...) as the primary option, kept mcp-remote as a secondary header-based option, and added screenshots walking through Settings → Connectors → Add custom connector. Noted that absmartly-endpoint is optional for OAuth (form prompts when omitted).
• Regression test: documents the conditions under which the URL endpoint survives the OAuth redirect (per-client KV linkage via /register, or the RFC 8707 resource parameter).

Test plan

• npm run test — 3180/3180 pass
• npx tsc --noEmit — clean
• After deploy, verify OAuth flow reaches SAML login on demo-2 instead of failing at the backend
• After deploy, verify Claude Desktop "Add custom connector" flow with URL-based API key works end-to-end

Summary by CodeRabbit

Release Notes

• New Features

  • Made absmartly-endpoint optional in OAuth flow; omitting it now triggers a browser prompt requesting the ABsmartly instance URL
  • Added "With API Key" configuration option for Claude Desktop integration, allowing embedded API key in Remote MCP server URLs

• Documentation

  • Updated OAuth setup guides across Claude Desktop, Claude Code, Cursor, and VS Code with explicit navigation instructions and screenshots
  • Clarified API key configuration requirements and available options

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 113224e2-f5b2-45d2-ab4a-77fc0bd639e4

📥 Commits

Reviewing files that changed from the base of the PR and between 008b02d and a73eb9d.

⛔ Files ignored due to path filters (3)

• docs/images/claude-desktop-add-custom-connector.png is excluded by !**/*.png
• docs/images/claude-desktop-connectors.png is excluded by !**/*.png
• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (5)

• README.md
• package.json
• src/absmartly-oauth-handler.ts
• src/index.ts
• tests/unit/oauth-endpoint-survival.test.ts

---

Walkthrough

This pull request updates OAuth scope definitions across the codebase from api:read api:write to mcp:access user:info, reflecting a shift in permission model. The package.json moves @absmartly/cli from development to runtime dependencies. README documentation is expanded with explicit navigation instructions for Claude Desktop OAuth setup and clarifies that the absmartly-endpoint parameter is optional across multiple editor integrations. A new test file oauth-endpoint-survival.test.ts with 184 lines adds test coverage for OAuth endpoint persistence scenarios.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• feat: rewrite MCP to use full CLI core functions #1 — Modifies the same OAuth-related codepaths in src/absmartly-oauth-handler.ts and touches @absmartly/cli dependency handling in package.json

Poem

🐰 Scopes now dance from api to mcp,
One test hops in to fill the gap,
Dependencies climb to runtime's stage,
OAuth endpoints no longer astray—
A migration complete, hooray! 🎉

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/oauth-scopes-and-setup-docs

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}