refactor(docs): various cleanup to documentation (#674)

- Rename all .mdc files to standard .md extension for broader
compatibility
- Remove Cursor-specific cursor.mdc file (no longer needed)
- Delete PACKAGE_REFACTORING_PLAN.md (refactoring complete)
- Simplify AGENTS.md with cleaner structure and essential info only
- Update all documentation cross-references to use .md extensions

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: dcramer

AGENTS.md

@@ -1,140 +1,76 @@
-# CLAUDE.md
+# AGENTS.md
 
-## 🔴 CRITICAL Requirements
+Sentry MCP is a Model Context Protocol server that exposes Sentry's error tracking and performance monitoring to AI assistants through 19 tools.
 
-**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)
+## Principles
 
-**MANDATORY reads:**
-- Start here: CLAUDE.md — Contributor doc map
-- Tools → @docs/adding-tools.mdc
-- Testing → @docs/testing.mdc
-- PRs → @docs/pr-management.mdc
+- **Type Safety**: Prefer strict types over `any` - they catch bugs and improve tooling. Use `unknown` for truly unknown types.
+- **Security**: Never log secrets. Validate external input. See @docs/security.md.
+- **Simplicity**: Follow existing patterns. Check neighboring files before inventing new approaches.
 
-## 🟡 MANDATORY Workflow
+## Constraints
 
-```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
-```
+- **Tool count**: Target ≤20, hard limit 25 (AI agents have limited tool slots).
+- **Quality gate**: `pnpm run tsc && pnpm run lint && pnpm run test` must pass before committing.
 
-## Repository Map
+## Repository Structure
 
 ```
 sentry-mcp/
 ├── packages/
-│   ├── mcp-core/            # Core MCP implementation (private package)
-│   │   ├── src/
-│   │   │   ├── tools/       # 19 tool modules
-│   │   │   ├── server.ts    # buildServer() function
-│   │   │   ├── api-client/  # Sentry API
-│   │   │   └── internal/    # Shared utils
-│   │   └── scripts/         # Build scripts
-│   ├── mcp-server/          # stdio transport (published as @sentry/mcp-server)
+│   ├── mcp-core/            # Core MCP implementation (private)
 │   │   └── src/
-│   │       ├── cli/         # CLI argument parsing
-│   │       ├── transports/  # stdio transport
-│   │       └── index.ts     # Main entry point
-│   ├── mcp-cloudflare/      # Web app
-│   ├── mcp-server-evals/    # AI tests
+│   │       ├── tools/       # 19 tool modules
+│   │       ├── server.ts    # buildServer()
+│   │       ├── api-client/  # Sentry API
+│   │       └── internal/    # Shared utils
+│   ├── mcp-server/          # stdio transport (@sentry/mcp-server on npm)
+│   ├── mcp-cloudflare/      # Web app + OAuth
+│   ├── mcp-server-evals/    # AI evaluation tests
 │   ├── mcp-server-mocks/    # MSW mocks
-│   └── mcp-test-client/     # Test client
-└── docs/                    # All docs
+│   └── mcp-test-client/     # CLI test client
+└── docs/                    # All documentation
 ```
 
-## AI-Powered Search Tools
+## Essential Documentation
 
-**search_events** (`packages/mcp-core/src/tools/search-events/`):
-- Natural language → DiscoverQL queries
-- GPT-4o agent with structured outputs
-- Tools: `datasetAttributes`, `otelSemantics`, `whoami`
-- Requires: `OPENAI_API_KEY`
+**Read before making changes:**
+- @docs/adding-tools.md — Tool implementation guide
+- @docs/testing.md — Testing requirements
+- @docs/common-patterns.md — Error handling, Zod schemas, response formatting
+- @docs/error-handling.md — Error types and propagation
 
-**search_issues** (`packages/mcp-core/src/tools/search-issues/`):
-- Natural language → issue search syntax
-- GPT-4o agent with structured outputs
-- Tools: `issueFields`, `whoami`
-- Requires: `OPENAI_API_KEY`
+**Reference:**
+- @docs/architecture.md — System design
+- @docs/api-patterns.md — Sentry API client usage
+- @docs/quality-checks.md — Pre-commit checklist
+- @docs/pr-management.md — Commit/PR guidelines
+- @docs/security.md — Authentication patterns
+- @docs/releases/stdio.md — npm package release
+- @docs/releases/cloudflare.md — Cloudflare deployment
 
-## 🟢 Key Commands
+## Commands
 
 ```bash
 # Development
-pnpm run dev               # Start development
-pnpm run build             # Build all packages
-pnpm run generate-otel-namespaces  # Update OpenTelemetry docs
+pnpm run dev                              # Start dev server
+pnpm run build                            # Build all packages
 
-# Manual Testing (preferred for testing MCP changes)
-pnpm -w run cli "who am I?"                    # Test with local dev server (default)
-pnpm -w run cli --agent "who am I?"            # Test agent mode (use_sentry tool) - approximately 2x slower
-pnpm -w run cli --mcp-host=https://mcp.sentry.dev "query"  # Test against production
-pnpm -w run cli --access-token=TOKEN "query"   # Test with local stdio mode
+# Testing
+pnpm -w run cli "who am I?"               # Test local dev server
+pnpm -w run cli --access-token=TOKEN "q"  # Test stdio transport
+pnpm -w run cli --agent "query"           # Test agent mode (~2x slower)
 
-# Quality checks (combine for speed)
+# Quality (run before committing)
 pnpm run tsc && pnpm run lint && pnpm run test
 
-# Token cost monitoring
-pnpm run measure-tokens  # Check tool definition overhead
-
-# Common workflows
-pnpm run build && pnpm run test  # Before PR
-grep -r "TODO\|FIXME" src/     # Find tech debt
+# Token overhead
+pnpm run measure-tokens                   # Check tool definition size
 ```
 
-## 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/api-patterns.mdc — Sentry API usage
-  - @docs/search-events-api-patterns.md — search_events specifics
-
-- Infrastructure and Operations
-  - @docs/architecture.mdc — System design
-  - @docs/releases/cloudflare.mdc — Cloudflare Workers release
-  - @docs/releases/stdio.mdc — npm package release
-  - @docs/monitoring.mdc — Monitoring/telemetry
-  - @docs/security.mdc — Security and authentication
-  - @docs/token-cost-tracking.mdc — Track MCP tool definition overhead
-  - @docs/cursor.mdc — Cursor IDE integration
-
-- Testing
-  - @docs/testing.mdc — Testing strategies and patterns
-  - @docs/testing-stdio.md — Stdio testing playbook (build, run, test)
-  - @docs/testing-remote.md — Remote testing playbook (OAuth, web UI, CLI)
-
-- 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*
+## Workflow
+
+1. Check neighboring files for existing patterns before writing new code.
+2. Update relevant docs when changing functionality.
+3. Follow @docs/error-handling.md for error types.
+4. Follow @docs/pr-management.md for commits and PRs.