Add OAuth permission scopes system for fine-grained access control (#535)

## Summary

Implements an OAuth-style permission scopes system that allows users to
choose their access level when authenticating with Sentry. Users can
select from three permission levels during the OAuth flow: Read-Only
(default), Issue Triage, or Project Management.

## Key Changes

- **Permission System**: Added hierarchical scope system in
`packages/mcp-server/src/permissions.ts` with scope expansion and
validation
- **OAuth Flow**: Enhanced approval dialog to present permission options
with clear descriptions of what each level allows
- **Tool Access Control**: All MCP tools now declare required scopes and
are filtered based on granted permissions
- **User Experience**: Permission selection UI shows required vs
optional permissions with visual distinction
- **Documentation**: Added comprehensive guide in
`docs/permissions-and-scopes.md` covering usage, scope hierarchy, and
tool requirements

The system is NOT backward compatible - if no scopes are specified,
read-only access is granted. Scopes can also be configured via CLI with
`--scopes` flag or `MCP_SCOPES` environment variable.

Fixes #525

---
*Generated with Claude Code*

---------

Co-authored-by: Codex CLI Agent <noreply@openai.com>

Author: dcramer

AGENTS.md

@@ -0,0 +1,125 @@
+# CLAUDE.md
+
+## 🔴 CRITICAL Requirements
+
+**MANDATORY before ANY code:**
+1. TypeScript: NEVER use `any`. Use `unknown` or proper types
+2. Security: NO API keys in logs. NO vulnerabilities
+3. Validation: `pnpm run tsc && pnpm run lint && pnpm run test`
+4. Tools limit: ≤20 (hard limit: 25)
+
+**MANDATORY reads:**
+- Start here: CLAUDE.md — Contributor doc map
+- Tools → @docs/adding-tools.mdc
+- Prompts → @docs/adding-prompts.mdc
+- Resources → @docs/adding-resources.mdc
+- Testing → @docs/testing.mdc
+- PRs → @docs/pr-management.mdc
+
+## 🟡 MANDATORY Workflow
+
+```bash
+# BEFORE coding (parallel execution)
+cat docs/[component].mdc & ls -la neighboring-files & git status
+
+# AFTER coding (sequential - fail fast)
+pnpm run tsc && pnpm run lint && pnpm run test  # ALL must pass
+```
+
+## Repository Map
+
+```
+sentry-mcp/
+├── packages/
+│   ├── mcp-server/          # Main MCP server
+│   │   ├── src/
+│   │   │   ├── tools/       # 19 tool modules
+│   │   │   ├── prompts.ts   # MCP prompts
+│   │   │   ├── resources.ts # MCP resources
+│   │   │   ├── server.ts    # MCP protocol
+│   │   │   ├── api-client/  # Sentry API
+│   │   │   └── internal/    # Shared utils
+│   │   └── scripts/         # Build scripts
+│   ├── mcp-cloudflare/      # Web app
+│   ├── mcp-server-evals/    # AI tests
+│   ├── mcp-server-mocks/    # MSW mocks
+│   └── mcp-test-client/     # Test client
+└── docs/                    # All docs
+```
+
+## AI-Powered Search Tools
+
+**search_events** (`packages/mcp-server/src/tools/search-events/`):
+- Natural language → DiscoverQL queries
+- GPT-4o agent with structured outputs
+- Tools: `datasetAttributes`, `otelSemantics`, `whoami`
+- Requires: `OPENAI_API_KEY`
+
+**search_issues** (`packages/mcp-server/src/tools/search-issues/`):
+- Natural language → issue search syntax
+- GPT-4o agent with structured outputs
+- Tools: `issueFields`, `whoami`
+- Requires: `OPENAI_API_KEY`
+
+## 🟢 Key Commands
+
+```bash
+# Development
+pnpm run dev               # Start development
+pnpm run build             # Build all packages
+pnpm run generate-otel-namespaces  # Update OpenTelemetry docs
+
+# Quality checks (combine for speed)
+pnpm run tsc && pnpm run lint && pnpm run test
+
+# Common workflows
+pnpm run build && pnpm run test  # Before PR
+grep -r "TODO\|FIXME" src/     # Find tech debt
+```
+
+## Quick Reference
+
+**Defaults:**
+- Organization: `sentry`
+- Project: `mcp-server`
+- Transport: stdio
+- Auth: access tokens (NOT OAuth)
+
+**Doc Index:**
+
+- Core Guidelines
+  - @docs/coding-guidelines.mdc — Code standards and patterns
+  - @docs/common-patterns.mdc — Reusable patterns and conventions
+  - @docs/quality-checks.mdc — Required checks before changes
+  - @docs/error-handling.mdc — Error handling patterns
+
+- API and Tools
+  - @docs/adding-tools.mdc — Add new MCP tools
+  - @docs/adding-prompts.mdc — Add prompts
+  - @docs/adding-resources.mdc — Add resources
+  - @docs/api-patterns.mdc — Sentry API usage
+  - @docs/search-events-api-patterns.md — search_events specifics
+
+- Infrastructure and Operations
+  - @docs/architecture.mdc — System design
+  - @docs/deployment.mdc — Deploy (Cloudflare)
+  - @docs/monitoring.mdc — Monitoring/telemetry
+  - @docs/security.mdc — Security and authentication
+  - @docs/cursor.mdc — Cursor IDE integration
+
+- LLM-Specific
+  - @docs/llms/documentation-style-guide.mdc — How to write LLM docs
+  - @docs/llms/document-scopes.mdc — Doc scopes and purposes
+
+## Rules
+
+1. **Code**: Follow existing patterns. Check adjacent files
+2. **Errors**: Try/catch all async. Log: `console.error('[ERROR]', error.message, error.stack)`
+   - Sentry API 429: Retry with exponential backoff
+   - Sentry API 401/403: Check token permissions
+3. **Docs**: Update when changing functionality
+4. **PR**: Follow `docs/pr-management.mdc` for commit/PR guidelines (includes AI attribution)
+5. **Tasks**: Use TodoWrite for 3+ steps. Batch tool calls when possible
+
+---
+*Optimized for Codex CLI (OpenAI) and Claude Code*

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -82,6 +82,7 @@ To contribute changes, you'll need to set up your local environment:
      - `COOKIE_SECRET=my-super-secret-cookie`
 
 4. **Start the development server:**
+
    ```shell
    pnpm dev
    ```
@@ -135,3 +136,7 @@ The automated reviews should be treated as:
 - ❌ **Not replacements** for human code review
 
 When addressing automated feedback, focus on the underlying concerns rather than strictly following every suggestion.
+
+### Contributor Documentation
+
+Looking to contribute or explore the full documentation map? See `CLAUDE.md` (also available as `AGENTS.md`) for contributor workflows and the complete docs index. The `docs/` folder contains the per-topic guides and tool-integrated `.mdc` files.

README.md

@@ -4,7 +4,11 @@
     "enabled": true
   },
   "files": {
-    "ignore": ["worker-configuration.d.ts", "tsconfig*.json"]
+    "ignore": [
+      "worker-configuration.d.ts",
+      "tsconfig*.json",
+      "packages/mcp-server-mocks/src/fixtures/**"
+    ]
   },
   "vcs": {
     "enabled": true,
@@ -15,6 +19,9 @@
     "enabled": true,
     "rules": {
       "recommended": true,
+      "correctness": {
+        "noUnusedImports": "warn"
+      },
       "suspicious": {
         "noExplicitAny": "off",
         "noDebugger": "off",

biome.json

@@ -1,68 +1,26 @@
-# Documentation for Contributors
+# Contributor Docs
 
-This directory contains documentation to help LLMs (Language Learning Models) and human contributors work more effectively with the Sentry MCP codebase.
+This directory contains contributor documentation used by humans and LLMs. To avoid duplication, the canonical documentation map and contributor workflow live in `CLAUDE.md` (also available as `AGENTS.md`).
 
 ## Purpose
 
-These documents provide structured guidance to ensure consistent, high-quality contributions that align with the project's standards and patterns. All documentation files use the `.mdc` format for better AI tool compatibility.
+- Central home for all contributor-focused docs (.mdc files)
+- Consumed by tools (e.g., Cursor) via direct file references
 
-## Directory Structure
+## Start Here
 
-This directory serves a dual purpose:
-1. Central documentation repository for all contributors
-2. Source for `.cursor/rules/` via symlink (for Cursor IDE integration)
+- Doc map and workflow: see `CLAUDE.md` / `AGENTS.md`
+- Per-topic guides live in this folder (e.g., `adding-tools.mdc`)
 
-## Contents
+## Integration with Tools
 
-### Core Guidelines
-- `coding-guidelines.mdc` - Coding standards, patterns, and best practices
-- `coding-practices.mdc` - General coding practices and conventions
-- `package-management.mdc` - Package and dependency management
+- Cursor IDE: this folder is referenced directly as contextual rules
+- Other AI tools: reference specific `.mdc` files as needed
 
-### API and Tools
-- `adding-new-tools.mdc` - How to add new MCP tools
-- `adding-prompts.mdc` - Guidelines for adding new prompts
-- `adding-new-resources.mdc` - How to add new MCP resources
-- `api-client-patterns.mdc` - Working with the Sentry API client
-- `search-events-api-patterns.md` - Comprehensive guide to search_events API patterns
-- `using-api-mocks.mdc` - Testing with API mocks
+## LLM-Specific
 
-### Infrastructure and Operations
-- `deployment-and-infrastructure.mdc` - Deployment processes and infrastructure
-- `observability-and-monitoring.mdc` - Monitoring and telemetry practices
-- `security-and-authentication.mdc` - Security best practices
-
-## For LLMs
-
-When working with this codebase:
-1. Always read relevant `.mdc` files before making changes
-2. Follow the patterns and conventions outlined in these guides
-3. Run all quality checks as specified in the guidelines
-4. Maintain consistency with existing code
-
-## Integration with Development Tools
-
-### Cursor IDE
-The `.cursor/rules/` directory is symlinked to this `docs/` folder, ensuring that Cursor IDE automatically picks up all documentation as contextual rules.
-
-### Other AI Tools
-These `.mdc` files are designed to be easily consumed by various AI development assistants and can be referenced directly when needed.
-
-## LLM-Specific Guidelines
-
-The `llms/` subdirectory contains meta-documentation for LLMs:
-- `documentation-style-guide.mdc` - How to write effective LLM documentation
-- `document-scopes.mdc` - Purpose and content for each doc
-- `documentation-todos.mdc` - Tasks for documentation improvement
+- Meta-docs live under `llms/` (e.g., `llms/document-scopes.mdc`)
 
 ## Maintenance
 
-These documents should be updated when:
-- New patterns or conventions are adopted
-- Common issues arise that need documentation
-- The architecture or tooling changes significantly
-- New tools, resources, or features are added
-
-## Note
-
-This documentation supplements but does not replace the root-level CLAUDE.md file, which remains the primary instruction set for Claude Code when working with this repository. The CLAUDE.md file will be refactored into multiple focused documents within this directory.
+Update docs when patterns change, new tools are added, or common issues arise. Keep the index in `CLAUDE.md` authoritative; avoid mirroring it here.

docs/README.md

@@ -303,7 +303,7 @@ try {
 
 ### Implementation Guidelines
 
-1. **Create a CLAUDE.md file** in the tool directory documenting:
+1. **Create an AGENTS.md file** in the tool directory documenting:
    - The embedded agent's prompt and behavior
    - Common translation patterns
    - Known limitations

docs/adding-tools.mdc

@@ -56,7 +56,7 @@ A separate web chat application that uses the MCP server.
 
 **Note**: This is NOT part of the MCP server itself - it's a demonstration of how to build a chat interface that consumes MCP.
 
-See [Cloudflare Web App Documentation](./cloudflare/overview.md) for details.
+See "Overview" in @docs/cloudflare/overview.md for details.
 
 ### packages/mcp-server-evals
 

docs/architecture.mdc

@@ -183,7 +183,7 @@ SENTRY_CLIENT_SECRET = "..." # OAuth app secret
 
 ## Related Documentation
 
-- [Authentication Flow](./authentication.md)
-- [Chat Interface Features](./chat-interface.md)
-- [Deployment Guide](./deployment.md)
-- [Core MCP Server](../architecture.mdc)
+- See "OAuth Architecture" in @docs/cloudflare/oauth-architecture.md
+- See "Chat Interface" in @docs/cloudflare/architecture.md
+- See "Deployment" in @docs/cloudflare/deployment.md
+- See "Architecture" in @docs/architecture.mdc