docs: add tool count limits and documentation maintenance guidelines

.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sentry": {
+      "type": "http",
+      "url": "https://mcp.sentry.dev/mcp"
+    }
+  }
+}

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sentry": {
+      "type": "http",
+      "url": "https://mcp.sentry.dev/mcp"
+    }
+  }
+}

CLAUDE.md

@@ -34,6 +34,20 @@ All documentation is in the `docs/` directory:
 
 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 CLAUDE.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
+
 ## Critical Quality Checks
 
 **After ANY code changes, you MUST run:**

README.md

@@ -1,7 +1,6 @@
 # sentry-mcp
 
 [![codecov](https://codecov.io/gh/getsentry/sentry-mcp/graph/badge.svg?token=khVKvJP5Ig)](https://codecov.io/gh/getsentry/sentry-mcp)
-[![smithery badge](https://smithery.ai/badge/@getsentry/sentry-mcp)](https://smithery.ai/server/@getsentry/sentry-mcp)
 
 This is a prototype of a remote MCP sever, acting as a middleware to the upstream Sentry API provider.
 

docs/README.md

@@ -21,7 +21,7 @@ This directory serves a dual purpose:
 
 ### API and Tools
 - `adding-new-tools.mdc` - How to add new MCP tools
-- `adding-new-prompts.mdc` - Guidelines for adding new prompts
+- `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
 - `using-api-mocks.mdc` - Testing with API mocks

docs/adding-resources.mdc

@@ -1,11 +1,24 @@
-# Adding Resources
+---
+description: Guide for adding new resources that provide context, live data, and reference materials.
+globs: 
+alwaysApply: false
+---
+# Adding New Resources
 
-How to add new MCP resources to provide context, live data, and reference materials to LLMs.
+Guide for adding new resources that provide context, live data, and reference materials.
 
 ## What Are Resources?
 
 Resources are **application-controlled** content that clients provide to LLMs proactively, unlike tools which are **model-controlled** (LLM decides when to call).
 
+## Resource Structure
+
+Each resource consists of:
+1. **Definition** - Schema in `resources.ts`
+2. **Handler** - Logic in `resources.ts`
+3. **Tests** - Unit tests in `resources.test.ts`
+4. **Integration** - Referenced by prompts and tools
+
 ## Resource Types
 
 ### 1. Context Management
@@ -48,11 +61,9 @@ Reference guides, API docs:
 }
 ```
 
-## Implementation Pattern
-
-### 1. Add Resource Definition
+## Step 1: Define the Resource
 
-In `packages/mcp-server/src/resources.ts`:
+Add to `packages/mcp-server/src/resources.ts`:
 
 ```typescript
 const RESOURCE_HANDLERS: ResourceHandler[] = [
@@ -66,7 +77,13 @@ const RESOURCE_HANDLERS: ResourceHandler[] = [
 ];
 ```
 
-### 2. Implement Handler
+### Resource URI Design
+
+- Use semantic paths: `sentry://entity/identifier/aspect`
+- Support templates with `{variable}` placeholders
+- Keep URIs predictable and consistent
+
+## Step 2: Implement the Handler
 
 ```typescript
 async function yourResourceHandler(url: URL): Promise<ReadResourceResult> {
@@ -88,7 +105,28 @@ async function yourResourceHandler(url: URL): Promise<ReadResourceResult> {
 }
 ```
 
-### 3. Handle Binary Content
+## Step 3: Add Tests
+
+```typescript
+describe("resource: your-resource", () => {
+  it("returns expected content", async () => {
+    const handler = findHandler("sentry://your/path/123");
+    const result = await handler(new URL("sentry://your/path/123"));
+
+    expect(result.contents[0]).toMatchInlineSnapshot(`
+      {
+        "mimeType": "application/json",
+        "text": "{\"expected\": \"content\"}",
+        "uri": "sentry://your/path/123"
+      }
+    `);
+  });
+});
+```
+
+## Advanced Patterns
+
+### Handle Binary Content
 
 For images, PDFs, or other binary data:
 
@@ -106,7 +144,7 @@ async function binaryResourceHandler(url: URL): Promise<ReadResourceResult> {
 }
 ```
 
-### 4. Support Multiple Contents
+### Support Multiple Contents
 
 Resources can return multiple content items:
 
@@ -127,7 +165,7 @@ return {
 };
 ```
 
-## Resource Templates
+### Resource Templates
 
 Support dynamic URIs with placeholders:
 
@@ -146,68 +184,65 @@ The MCP server automatically generates:
 - `sentry://issue/123/context` → Specific instance
 - `sentry://issue/{issueId}/context` → Template for discovery
 
-## Testing Resources
-
-### Unit Test Pattern
-
-```typescript
-describe("resource: your-resource", () => {
-  it("returns expected content", async () => {
-    const handler = findHandler("sentry://your/path/123");
-    const result = await handler(new URL("sentry://your/path/123"));
-
-    expect(result.contents[0]).toMatchInlineSnapshot(`
-      {
-        "mimeType": "application/json",
-        "text": "{\\"expected\\": \\"content\\"}",
-        "uri": "sentry://your/path/123"
-      }
-    `);
-  });
-});
-```
-
-See: `packages/mcp-server/src/resources.test.ts`
-
 ## Best Practices
 
-### 1. Clear Naming
+### Clear Naming
 - Use descriptive resource names
 - Follow the pattern: `noun-context` (e.g., `issue-attachments`, `project-health`)
+- Match naming conventions from tools
 
-### 2. Efficient Data
+### Efficient Data
 - Don't overload with unnecessary data
 - Structure for LLM consumption
 - Use appropriate mimeTypes
+- Consider resource size limits
 
-### 3. Error Handling
+### Error Handling
 - Return empty contents for missing data
 - Use clear error messages
 - Don't throw unless critical
+- Log errors for debugging
 
-### 4. Security
+### Security
 - Validate access permissions
 - Sanitize user input in URIs
 - Don't expose sensitive data
+- Use the same auth as tools
 
 ## Common Patterns
 
-See `common-patterns.mdc#multi-content-resources` for:
+See `common-patterns.mdc` for:
 - Response formatting
 - Error handling
 - Parameter extraction
 - Binary content handling
+- Multi-content resources
+
+## Integration with Prompts
+
+Resources are often referenced in prompts:
+
+```typescript
+// In prompt handler
+const instructions = [
+  "Check available resources:",
+  "1. `user-session-context` for recent activity",
+  "2. `project-health` for current metrics",
+];
+```
 
-## Existing Resources
+## Checklist
 
-Current implementations in `packages/mcp-server/src/resources.ts`:
-- Platform documentation (`sentry://docs/{platform}`)
-- Framework guides (`sentry://docs/{platform}/{framework}`)
-- SDK references (`sentry://sdk/{platform}`)
-- Troubleshooting guides
+- [ ] Resource defined in `resources.ts`
+- [ ] Handler implemented with proper error handling
+- [ ] Unit tests with snapshots added
+- [ ] Resource documented in handler comments
+- [ ] Referenced in relevant prompts
+- [ ] Follows security best practices
 
 ## References
 
 - Implementation: `packages/mcp-server/src/resources.ts`
 - Tests: `packages/mcp-server/src/resources.test.ts`
-- MCP Resource spec: https://modelcontextprotocol.io/docs/concepts/resources
+- Common patterns: `docs/common-patterns.mdc`
+- MCP spec: https://modelcontextprotocol.io/docs/concepts/resources

docs/adding-new-tools.mdc → docs/adding-tools.mdc

@@ -7,6 +7,18 @@ alwaysApply: false
 
 Step-by-step guide for adding new tools to the Sentry MCP server.
 
+## Tool Count Limits
+
+**IMPORTANT**: AI agents have a hard cap of 45 total tools available. Since Sentry MCP cannot consume all available tool slots:
+- **Target**: Keep total tool count around 20
+- **Maximum**: Absolutely no more than 25 tools
+- **Constraint**: This limit exists in Cursor and possibly other tools
+
+Before adding a new tool, consider if it could be:
+1. Combined with an existing tool
+2. Implemented as a parameter variant
+3. Truly necessary for core functionality
+
 ## Tool Structure
 
 Each tool consists of:

docs/architecture.mdc

@@ -165,6 +165,12 @@ Each tool follows a consistent structure:
    - Mock API responses
    - Evaluation tests
 
+**Tool Count Constraints:**
+- AI agents have a 45 tool limit (Cursor, etc.)
+- Sentry MCP must stay under 25 tools (target: ~20)
+- Consolidate functionality where possible
+- Consider parameter variants over new tools
+
 ### 6. Error Handling Philosophy
 
 Two-tier error system:

docs/cursor.mdc

@@ -34,6 +34,20 @@ All documentation is in the `docs/` directory:
 
 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 CLAUDE.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
+
 ## Critical Quality Checks
 
 **After ANY code changes, you MUST run:**