From 99da782a7bcc432d8dd75163f3fabbbfe719406a Mon Sep 17 00:00:00 2001 From: David Cramer Date: Sun, 29 Jun 2025 10:39:42 -0700 Subject: [PATCH] docs: add tool count limits and documentation maintenance guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear 45-tool limit constraints for AI agents - Target ~20 tools, max 25 to avoid consuming all available slots - Add documentation maintenance guidelines to avoid redundancy - Update CLAUDE.md, cursor.mdc, and tool/architecture docs - Add MCP config files for Cursor and generic MCP clients 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .cursor/mcp.json | 8 ++ .mcp.json | 8 ++ CLAUDE.md | 14 ++ Dockerfile | 22 --- README.md | 1 - docs/README.md | 2 +- ...ing-new-prompts.mdc => adding-prompts.mdc} | 0 docs/adding-resources.mdc | 125 +++++++++++------ ...{adding-new-tools.mdc => adding-tools.mdc} | 12 ++ docs/architecture.mdc | 6 + docs/cursor.mdc | 14 ++ .../documentation-optimization-summary.mdc | 52 ------- docs/llms/documentation-todos.mdc | 131 ------------------ packages/mcp-cloudflare/package.json | 2 +- packages/mcp-server/package.json | 2 +- smithery.yaml | 31 ----- 16 files changed, 145 insertions(+), 285 deletions(-) create mode 100644 .cursor/mcp.json create mode 100644 .mcp.json delete mode 100644 Dockerfile rename docs/{adding-new-prompts.mdc => adding-prompts.mdc} (100%) rename docs/{adding-new-tools.mdc => adding-tools.mdc} (92%) delete mode 100644 docs/llms/documentation-optimization-summary.mdc delete mode 100644 docs/llms/documentation-todos.mdc delete mode 100644 smithery.yaml diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 00000000..9918d4c7 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "sentry": { + "type": "http", + "url": "https://mcp.sentry.dev/mcp" + } + } +} diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 00000000..9918d4c7 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "sentry": { + "type": "http", + "url": "https://mcp.sentry.dev/mcp" + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md index ec284c5f..a04e9ca9 100644 --- a/CLAUDE.md +++ b/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:** diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index a22c2633..00000000 --- a/Dockerfile +++ /dev/null @@ -1,22 +0,0 @@ -FROM node:lts-alpine AS base -ENV PNPM_HOME="/pnpm" -ENV PATH="$PNPM_HOME:$PATH" -RUN corepack enable - -FROM base AS build -COPY . /app -WORKDIR /app -# ensure latest corepack otherwise we could hit cert issues -RUN npm i -g corepack@latest -RUN --mount=type=cache,id=pnpm,target=/pnpm/store \ - pnpm install --frozen-lockfile -RUN pnpm run -r build -RUN pnpm deploy --filter=sentry-mcp --prod /prod/sentry-mcp - -FROM base AS app -COPY --from=build /prod/sentry-mcp /app -WORKDIR /app -# Expose port if needed (though stdio doesn't need it, but may be used in dev) -EXPOSE 8788 -# Run the MCP server via stdio transport -CMD ["npm", "run", "start", "--"] diff --git a/README.md b/README.md index c82e204b..84f1a903 100644 --- a/README.md +++ b/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. diff --git a/docs/README.md b/docs/README.md index d22fe722..730a3180 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/adding-new-prompts.mdc b/docs/adding-prompts.mdc similarity index 100% rename from docs/adding-new-prompts.mdc rename to docs/adding-prompts.mdc diff --git a/docs/adding-resources.mdc b/docs/adding-resources.mdc index a90ec2fb..c993c61d 100644 --- a/docs/adding-resources.mdc +++ b/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 { @@ -88,7 +105,28 @@ async function yourResourceHandler(url: URL): Promise { } ``` -### 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 { } ``` -### 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 \ No newline at end of file +- Common patterns: `docs/common-patterns.mdc` +- MCP spec: https://modelcontextprotocol.io/docs/concepts/resources \ No newline at end of file diff --git a/docs/adding-new-tools.mdc b/docs/adding-tools.mdc similarity index 92% rename from docs/adding-new-tools.mdc rename to docs/adding-tools.mdc index 4b906d26..508e55ae 100644 --- a/docs/adding-new-tools.mdc +++ b/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: diff --git a/docs/architecture.mdc b/docs/architecture.mdc index b8012f5a..184f7f1a 100644 --- a/docs/architecture.mdc +++ b/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: diff --git a/docs/cursor.mdc b/docs/cursor.mdc index e69a481a..cc395a1e 100644 --- a/docs/cursor.mdc +++ b/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:** diff --git a/docs/llms/documentation-optimization-summary.mdc b/docs/llms/documentation-optimization-summary.mdc deleted file mode 100644 index f44d68e8..00000000 --- a/docs/llms/documentation-optimization-summary.mdc +++ /dev/null @@ -1,52 +0,0 @@ -# Documentation Optimization Summary - -## Overview - -Completed comprehensive documentation optimization for the Sentry MCP project, reducing redundancy and improving clarity for LLM consumption. - -## Results - -### Total Reduction -- **Original**: ~5,120 lines across all docs -- **Optimized**: 2,407 lines -- **Reduction**: 53% (2,713 lines removed) - -### Key Changes - -1. **Created Consolidated Documents**: - - `common-patterns.mdc` (274 lines) - Shared patterns across all docs - - `api-patterns.mdc` (217 lines) - API client and mocking patterns - - `architecture.mdc` (227 lines) - System design extracted from CLAUDE.md - -2. **Simplified Entry Points**: - - CLAUDE.md: 267 → 85 lines (68% reduction) - - cursor.mdc: Synced with CLAUDE.md - -3. **Optimized Guide Documents**: - - `adding-resources.mdc`: 765 → 212 lines (72% reduction) - - `security.mdc`: 604 → 167 lines (72% reduction) - - `monitoring.mdc`: 559 → 233 lines (58% reduction) - - `deployment.mdc`: 574 → 219 lines (62% reduction) - - `testing.mdc`: Refactored to 238 lines - - `coding-guidelines.mdc`: 306 → 143 lines (53% reduction) - - `adding-new-tools.mdc`: 415 → 206 lines (50% reduction) - - `adding-new-prompts.mdc`: 276 → 186 lines (33% reduction) - -4. **Removed Obsolete Files**: - - `observability-and-monitoring.mdc` (replaced by `monitoring.mdc`) - -## Optimization Strategies - -1. **Extract Common Patterns**: Moved shared code patterns to `common-patterns.mdc` -2. **Show Don't Tell**: Replaced verbose explanations with code examples -3. **Reference Don't Repeat**: Used cross-references instead of duplicating content -4. **Focus on Essentials**: Removed obvious information (LLMs understand common sense) -5. **Structure for Context Windows**: Each doc is now reasonably sized for LLM consumption - -## Benefits - -- **Reduced Context Usage**: 53% less content to process -- **Better Organization**: Clear separation of concerns -- **Easier Maintenance**: Single source of truth for patterns -- **LLM-Optimized**: Focused on what LLMs need to know -- **Preserved Information**: All essential information retained \ No newline at end of file diff --git a/docs/llms/documentation-todos.mdc b/docs/llms/documentation-todos.mdc deleted file mode 100644 index c4bd8c33..00000000 --- a/docs/llms/documentation-todos.mdc +++ /dev/null @@ -1,131 +0,0 @@ -# Documentation Improvement TODOs - -Based on our style guide and scope definitions, here are the specific tasks for each document. - -## High Priority - Core Structure - -### 1. CLAUDE.md (268 → 150 lines) -- [ ] Remove all content that belongs in other docs -- [ ] Keep only: brief description, doc references, critical checks, Claude-specific notes -- [ ] Move project overview → architecture.mdc -- [ ] Move development setup → appropriate guides -- [ ] Move integration details → keep minimal - -### 2. cursor.mdc (76 → 75 lines) -- [ ] Already concise, just ensure consistency with CLAUDE.md structure -- [ ] Verify MDC header is correct -- [ ] Remove any redundant content - -### 3. architecture.mdc (NEW - 250 lines) -- [ ] Extract architecture content from CLAUDE.md -- [ ] Add package interaction diagram (text-based) -- [ ] Document key architectural decisions -- [ ] Explain MCP concept mappings -- [ ] Reference actual implementation files - -### 4. common-patterns.mdc (NEW - 350 lines) -- [ ] Extract shared patterns from all docs: - - Error handling (UserInputError, ApiError) - - Zod schema patterns - - Response formatting - - Parameter validation - - TypeScript helpers -- [ ] Add code references for each pattern -- [ ] Create clear section anchors for linking - -## High Priority - Feature Guides - -### 5. adding-tools.mdc (414 → 300 lines) -- [ ] Remove duplicate testing patterns → link to testing.mdc -- [ ] Remove verbose examples → reference real tools -- [ ] Focus on tool-specific patterns only -- [ ] Add more references to actual implementations -- [ ] Condense the workflow steps - -### 6. adding-prompts.mdc (275 → 225 lines) -- [ ] Remove overlap with adding-tools.mdc -- [ ] Focus on prompt-specific patterns -- [ ] Reference the 2 existing prompts as examples -- [ ] Remove generic prompt engineering advice -- [ ] Link to common patterns - -### 7. adding-resources.mdc (765 → 250 lines) - BIGGEST REDUCTION -- [ ] Remove ALL verbose examples (currently has 500+ lines of examples) -- [ ] Keep only unique resource patterns -- [ ] Reference actual implementations in resources.ts -- [ ] Remove duplicate handler patterns -- [ ] Focus on resource-specific concepts only - -## Medium Priority - Technical Guides - -### 8. testing.mdc (from using-api-mocks.mdc - 405 → 300 lines) -- [ ] Rename from using-api-mocks.mdc -- [ ] Consolidate all testing patterns -- [ ] Remove MSW documentation → link to MSW docs -- [ ] Focus on project-specific test patterns -- [ ] Add snapshot update guidance - -### 9. api-patterns.mdc (576 → 250 lines) -- [ ] Merge with api-client-patterns.mdc content -- [ ] Remove Zod documentation -- [ ] Remove duplicate error handling → link to common-patterns -- [ ] Focus on Sentry API specifics -- [ ] Condense mock examples - -### 10. quality-checks.mdc (from coding-guidelines.mdc - 305 → 125 lines) -- [ ] Extract just the quality check commands -- [ ] Add when to run each check -- [ ] Add common failure fixes -- [ ] Remove all other content → other docs - -## Low Priority - Operations - -### 11. deployment.mdc (574 → 225 lines) -- [ ] Remove Cloudflare concepts explanation -- [ ] Focus on configuration only -- [ ] Remove duplicate OAuth content → link to security.mdc -- [ ] Condense to essential deployment steps - -### 12. monitoring.mdc (559 → 175 lines) -- [ ] Remove Sentry product documentation -- [ ] Focus on integration patterns only -- [ ] Remove duplicate error handling -- [ ] Keep only project-specific telemetry - -### 13. security.mdc (604 → 225 lines) -- [ ] Remove OAuth protocol explanation -- [ ] Focus on implementation only -- [ ] Remove general security advice -- [ ] Condense to project-specific patterns - -## New Documents - -### 14. README.md (Update existing) -- [ ] Create proper index with one-line descriptions -- [ ] Add quick navigation -- [ ] Reference style guide -- [ ] Keep under 150 lines - -### 15. Remove these files: -- [ ] coding-guidelines.mdc (split into common-patterns + quality-checks) -- [ ] coding-practices.mdc (already renamed to cursor.mdc) -- [ ] package-management.mdc (already removed - common sense) - -## Summary - -**Total line reduction target**: ~4,600 → ~2,800 lines (40% reduction) - -**Key strategies**: -1. Extract common patterns to single location -2. Reference code instead of recreating examples -3. Remove external tool documentation -4. Focus on project-specific patterns only -5. Use cross-references instead of duplication - -**Order of execution**: -1. Create common-patterns.mdc first (extract from all docs) -2. Create architecture.mdc (extract from CLAUDE.md) -3. Simplify CLAUDE.md and cursor.mdc -4. Reduce feature guides (tools, prompts, resources) -5. Consolidate technical guides -6. Trim operations guides \ No newline at end of file diff --git a/packages/mcp-cloudflare/package.json b/packages/mcp-cloudflare/package.json index b5549605..9c42a20c 100644 --- a/packages/mcp-cloudflare/package.json +++ b/packages/mcp-cloudflare/package.json @@ -14,7 +14,7 @@ "scripts": { "build": "tsc -b && vite build", "dev": "vite", - "deploy": "npm exec wrangler deploy", + "deploy": "pnpm exec wrangler deploy", "cf:versions:upload": "npx wrangler versions upload", "preview": "vite preview", "cf-typegen": "wrangler types", diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json index 82497f35..8f44cbec 100644 --- a/packages/mcp-server/package.json +++ b/packages/mcp-server/package.json @@ -75,7 +75,7 @@ "build": "tsdown", "dev": "tsc -w", "start": "tsx src/index.ts", - "prepare": "npm run build", + "prepare": "pnpm run build", "test": "vitest", "test:ci": "vitest run --coverage --reporter=junit --outputFile=tests.junit.xml", "test:watch": "vitest watch" diff --git a/smithery.yaml b/smithery.yaml deleted file mode 100644 index 03479d8e..00000000 --- a/smithery.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml - -startCommand: - type: stdio - configSchema: - # JSON Schema defining the configuration options for the MCP. - type: object - required: - - sentryAccessToken - properties: - sentryAccessToken: - type: string - description: Sentry authentication token with proper scopes. - sentryHost: - type: string - default: https://sentry.io - description: Optional override for the Sentry host URL. - commandFunction: - # A JS function that produces the CLI command based on the given config to start the MCP on stdio. - |- - (config) => ({ - command: 'npm', - args: ['run', 'start:stdio'], - env: { - SENTRY_ACCESS_TOKEN: config.sentryAccessToken, - SENTRY_HOST: config.sentryHost - } - }) - exampleConfig: - sentryAuthToken: your_sentry_user_access_token_here - sentryHost: https://sentry.io