feat(dev): Add sentry local workflows

.env.example

@@ -19,9 +19,10 @@ OPENROUTER_API_KEY=sk-or-generate-this
 # SENTRY_ACCESS_TOKEN=your_sentry_access_token
 
 # Sentry Spotlight - development environment tool for local debugging
-# Set to 1 to enable Spotlight integration (recommended for development)
-# Learn more: https://spotlightjs.com
-SENTRY_SPOTLIGHT=1
+# `pnpm dev:local` and `pnpm dev:stdio:local` set this automatically via
+# `sentry local run`. Set it manually only when running Spotlight separately.
+# Learn more: https://github.com/getsentry/cli/blob/main/docs/src/fragments/commands/local.md
+# SENTRY_SPOTLIGHT=1
 
 # IMPORTANT: For local development, you also need to create:
 # - packages/mcp-cloudflare/.env - OAuth configuration (required for authentication)

README.md

@@ -197,23 +197,31 @@
      - `SENTRY_CLIENT_SECRET=your_development_sentry_client_secret`
      - `COOKIE_SECRET=my-super-secret-cookie`
 
-4. **Start the development server:**
+4. **Start the development server with local Sentry telemetry:**
 
    ```shell
-   pnpm dev
+   # Cloudflare HTTP server and React client
+   pnpm dev:local
+
+   # Node.js stdio transport (requires SENTRY_ACCESS_TOKEN)
+   pnpm dev:stdio:local
    ```
 
+   These scripts use [`sentry local run`](https://github.com/getsentry/cli/blob/main/docs/src/fragments/commands/local.md) to start a local telemetry server and inject `SENTRY_SPOTLIGHT` into the server process. The Cloudflare script also receives `VITE_SENTRY_SPOTLIGHT` for the browser client. Use `pnpm dev` or `pnpm dev:stdio` when you do not need local telemetry.
+
 ### Verify
 
-Run the server locally to make it available at `http://localhost:5173`
+Run the Cloudflare server locally to make it available at `http://localhost:5173`:
 
 ```shell
-pnpm dev
+pnpm dev:local
 ```
 
 To test the local server, enter `http://localhost:5173/mcp` into Inspector and hit connect. Once you follow the prompts, you'll be able to "List Tools".
 
+For stdio, set `SENTRY_ACCESS_TOKEN`, run `pnpm dev:stdio:local`, and connect an MCP client to the stdio process. Events from either transport appear in the `sentry local` output.
+
 ### Tests
 
 There are three test suites included: unit tests, evaluations, and manual testing.
 

package.json

@@ -22,7 +22,9 @@
   "scripts": {
     "docs:check": "node scripts/check-doc-links.mjs",
     "dev": "dotenv -e .env -e .env.local -- turbo dev --filter=!@sentry/mcp-server",
+    "dev:local": "sentry local run -- pnpm dev",
     "dev:stdio": "dotenv -e .env -e .env.local -- turbo dev --filter=!@sentry/mcp-cloudflare",
+    "dev:stdio:local": "sentry local run -- pnpm dev:stdio",
     "build": "turbo build after-build",
     "check:generated": "pnpm --filter @sentry/mcp-core generate-definitions && git diff --exit-code -- packages/mcp-core/src/toolDefinitions.json packages/mcp-core/src/skillDefinitions.json plugins/sentry-mcp/agents/sentry-mcp.md plugins/sentry-mcp-experimental/agents/sentry-mcp.md",
     "deploy": "turbo deploy",
@@ -70,6 +72,7 @@
     ]
   },
   "devDependencies": {
-    "@types/json-schema": "^7.0.15"
+    "@types/json-schema": "^7.0.15",
+    "sentry": "^0.38.0"
   }
 }

packages/mcp-cloudflare/src/client/instrument.ts

@@ -4,6 +4,7 @@ import { resolveAttribution } from "./utils";
 
 Sentry.init({
   dsn: import.meta.env.VITE_SENTRY_DSN,
+  spotlight: import.meta.env.VITE_SENTRY_SPOTLIGHT,
   sendDefaultPii: true,
   tracesSampleRate: 1,
   beforeSend: sentryBeforeSend,

packages/mcp-cloudflare/src/server/sentry.config.test.ts

@@ -39,4 +39,12 @@ describe("getSentryConfig", () => {
 
     expect(config.release).toBeUndefined();
   });
+
+  it("forwards the Spotlight URL from the Worker environment", () => {
+    const config = getSentryConfig(
+      createEnv({ SENTRY_SPOTLIGHT: "http://localhost:8969/stream" }),
+    );
+
+    expect(config.spotlight).toBe("http://localhost:8969/stream");
+  });
 });

packages/mcp-cloudflare/src/server/sentry.config.ts

@@ -9,6 +9,7 @@ export default function getSentryConfig(env: Env): CloudflareOptions {
 
   return {
     dsn: env.SENTRY_DSN,
+    spotlight: env.SENTRY_SPOTLIGHT,
     tracesSampleRate: 1,
     sendDefaultPii: true,
     beforeSend: sentryBeforeSend,

packages/mcp-cloudflare/src/server/types.ts

@@ -59,6 +59,7 @@ export interface Env {
   SENTRY_CLIENT_SECRET: string;
   SENTRY_ENVIRONMENT?: string;
   SENTRY_DSN?: string;
+  SENTRY_SPOTLIGHT?: string;
   SENTRY_HOST?: string;
   OPENAI_API_KEY: string;
   MCP_URL?: string;

turbo.json

@@ -104,6 +104,7 @@
     "SENTRY_AUTH_TOKEN",
     "SENTRY_ACCESS_TOKEN",
     "SENTRY_SPOTLIGHT",
+    "VITE_SENTRY_SPOTLIGHT",
     "VITE_SENTRY_DSN",
     "VITE_SENTRY_ENVIRONMENT"
   ]