Sentry MCP

--- description: Cursor IDE instructions for working with Sentry MCP codebase globs: alwaysApply: true --- # Cursor IDE Instructions for Sentry MCP This file provides instructions for Cursor IDE when working with the Sentry MCP codebase. ## Project Overview Sentry MCP is a Model Context Protocol server that provides access to Sentry's functionality through tools, prompts, and resources. ## 🔴 CRITICAL: Pre-Development Requirements **MANDATORY READING before code changes:** ### Tool Development - MUST read `docs/adding-tools.mdc` before creating/modifying any tool - MUST read `docs/testing.mdc` for testing requirements - MUST verify tool count limits (target ~20, max 25) ### Code Changes - MUST read `docs/common-patterns.mdc` for established patterns - MUST read `docs/api-patterns.mdc` for API usage ## Documentation Maintenance Requirements **MANDATORY: Documentation MUST be updated when making code changes** ### When Documentation MUST Be Updated - **Adding new tools**: Update `docs/adding-tools.mdc` if new patterns emerge - **Changing testing approaches**: Update `docs/testing.mdc` immediately - **Modifying API patterns**: Update `docs/api-patterns.mdc` with new patterns - **Adding common patterns**: Update `docs/common-patterns.mdc` immediately - **Changing architecture**: Update `docs/architecture.mdc` ### Critical Sync Requirements - **AGENTS.md ↔ cursor.mdc**: These files MUST stay synchronized - **When updating AGENTS.md**: Also update `cursor.mdc` with equivalent guidance - **When updating cursor.mdc**: Also update `AGENTS.md` with equivalent guidance - Both files serve the same purpose for different tools (Claude Code vs Cursor IDE) ### Documentation Update Process 1. **Identify affected docs** while implementing changes 2. **Update documentation in the same session** as code changes 3. **Verify cross-references** remain accurate 4. **Ensure AGENTS.md ↔ cursor.mdc sync** is maintained 5. **Add examples** for new patterns introduced **Documentation updates are not optional - they are part of completing any task.** ## Documentation All documentation is in the `docs/` directory: ### Core References - `architecture.mdc` - System design and package structure - `common-patterns.mdc` - Reusable code patterns - `quality-checks.mdc` - Required quality checks ### Implementation Guides - `adding-tools.mdc` - Adding new MCP tools - `adding-prompts.mdc` - Adding new MCP prompts - `adding-resources.mdc` - Adding new MCP resources ### Technical References - `api-patterns.mdc` - Sentry API client usage - `testing.mdc` - Testing strategies - `deployment.mdc` - Cloudflare deployment - `monitoring.mdc` - Observability patterns - `security.mdc` - Authentication and security You should ALWAYS update docs when they are inaccurate or you have learned new relevant information which would add clarity that is otherwise missing. ## Documentation Maintenance - **Keep AGENTS.md and cursor.mdc concise**: These files are navigation aids, not comprehensive docs - **Reference, don't duplicate**: Point to `docs/` files instead of repeating content - **Update referenced docs first**: When making changes, update the actual documentation before updating references - **Avoid redundancy**: Check existing docs before creating new ones (see `docs/llms/documentation-style-guide.mdc`) ## Tool Count Limits **IMPORTANT**: AI agents have a hard cap of 45 total tools. Sentry MCP must: - Target ~20 tools (current best practice) - Never exceed 25 tools (absolute maximum) - This limit exists in Cursor and possibly other tools ## Code Validation Requirements **MANDATORY after ANY code changes:** - Run `pnpm run tsc` to verify type safety - Run `pnpm run lint` to check code style - Run `pnpm run test` for affected components - See `docs/quality-checks.mdc` for complete checklist **Commands to run:** ```bash pnpm -w run lint:fix # Fix linting issues pnpm tsc --noEmit # Check TypeScript types pnpm test # Run all tests ``` **DO NOT proceed if any check fails.** ## Tool Testing Requirements **ALL tools MUST have comprehensive tests that verify:** - **Input validation** - Required/optional parameters, type checking, edge cases - **Output formatting** - Markdown structure, content accuracy, error messages - **API integration** - Mock server responses, error handling, parameter passing - **Snapshot testing** - Use inline snapshots to verify formatted output **Required test patterns:** - Unit tests in individual `{tool-name}.test.ts` files using Vitest and MSW mocks - Input/output validation with inline snapshots - Error case testing (API failures, invalid params) - Mock server setup in `packages/mcp-server-mocks` See `docs/testing.mdc` for detailed testing patterns and `docs/adding-tools.mdc` for the testing workflow. ## Essential Commands ```bash # Development pnpm dev # Start all dev servers pnpm build # Build all packages pnpm inspector # Test tools interactively # Testing pnpm test # Unit tests pnpm eval # Evaluation tests (needs OPENAI_API_KEY) # Deployment pnpm deploy # Deploy to Cloudflare ``` ## Quick Start 1. Install dependencies: `pnpm install` 2. For local testing: `pnpm start:stdio --access-token=<token>` 3. For development: `pnpm dev` ## Cursor-Specific Notes When using Cursor's MCP integration: - The server runs via stdio transport - Authentication uses access tokens (not OAuth) - Follow the patterns in existing code ## Environment Variables See specific guides for required environment variables: - Cloudflare: `deployment.mdc` - Evaluation tests: `.env.example` - Local development: Use command-line args ## Repository Structure ``` sentry-mcp/ ├── packages/ │ ├── mcp-server/ # Main MCP server (tools, prompts, resources) │ │ ├── src/ │ │ │ ├── tools/ # 19 individual tool modules + utils │ │ │ ├── prompts.ts # MCP prompts │ │ │ ├── resources.ts # MCP resources │ │ │ ├── server.ts # MCP server configuration │ │ │ ├── api-client/ # Sentry API client │ │ │ └── internal/ # Shared utilities │ │ └── scripts/ # Build scripts (tool definitions generation) │ ├── mcp-cloudflare/ # Cloudflare Worker chat application │ │ ├── src/ │ │ │ ├── client/ # React frontend │ │ │ └── server/ # Worker API routes │ │ └── components.json # Shadcn/ui config │ ├── mcp-server-evals/ # AI evaluation tests │ ├── mcp-server-mocks/ # MSW mocks for testing │ ├── mcp-server-tsconfig/ # Shared TypeScript configs │ └── mcp-test-client/ # MCP client for testing └── docs/ # All documentation ├── cloudflare/ # Web app docs └── llms/ # LLM-specific docs ``` ## Core Components Impact Analysis When making changes, consider these component interactions: ### MCP Server (`packages/mcp-server/`) - **Tools** (19 modules): Query, create, update Sentry resources - **Prompts**: Help text and guidance for LLMs - **Resources**: Static documentation and references - **API Client**: Sentry API integration layer - **Server**: MCP protocol handler and error formatting ### Cloudflare Web App (`packages/mcp-cloudflare/`) - **Client**: React-based chat interface with UI components - **Server**: Worker API routes for search, auth, MCP communication - **Integration**: Uses MCP server for tool execution ### Testing Infrastructure - **Unit Tests**: Co-located with each component - **Mocks**: Realistic API responses in `mcp-server-mocks/` - **Evaluations**: AI-driven integration tests in `mcp-server-evals/` - **Test Client**: Interactive MCP testing in `mcp-test-client/` ### Build & Deployment - **Tool Definitions**: Auto-generated JSON schemas for client consumption - **TypeScript Config**: Shared configurations in `mcp-server-tsconfig/` - **Packaging**: Multiple package coordination ## References - MCP Protocol: https://modelcontextprotocol.io - Sentry API: https://docs.sentry.io/api/