fix(mcp-server): Add defensive patches for Transport edge cases

[codyde]

Problem

The Sentry MCP server instrumentation has several edge cases that can cause runtime errors when working with StreamableHTTPServerTransport and similar transport implementations. These issues occur during:

1. Transport initialization - when transport constructors are undefined/null
2. Session establishment - when sessionId is undefined during MCP initialization phases
3. Span correlation - when transport objects cannot be used as WeakMap keys
4. Type validation - when invalid transport objects are passed to correlation functions

Solution

This PR adds defensive patches to handle these edge cases gracefully while preserving existing functionality and maintaining backward compatibility.

Changes Made

1. Transport Constructor Null Checks (attributeExtraction.ts)

export function getTransportTypes(transport: MCPTransport): { mcpTransport: string; networkTransport: string } {
  // Handle undefined transport gracefully while preserving type detection
  if (\!transport || \!transport.constructor) {
    return { mcpTransport: 'unknown', networkTransport: 'unknown' };
  }
  const transportName = transport.constructor.name?.toLowerCase() || '';
  // ... rest of function
}

2. Graceful sessionId Handling (attributeExtraction.ts)

export function buildTransportAttributes(
  transport: MCPTransport,
  extra?: ExtraHandlerData,
): Record<string, string | number> {
  // Gracefully handle undefined sessionId during MCP initialization
  // Respects client-provided sessions and waits for proper session establishment
  const sessionId = transport && 'sessionId' in transport ? transport.sessionId : undefined;
  // ... rest of function
}

3. WeakMap Correlation Fallback System (correlation.ts)

const transportToSpanMap = new WeakMap<MCPTransport, Map<RequestId, RequestSpanMapValue>>();

/**
 * Fallback span map for invalid transport objects
 * @internal Used when transport objects cannot be used as WeakMap keys
 */
const fallbackSpanMap = new Map<RequestId, RequestSpanMapValue>();

function getOrCreateSpanMap(transport: MCPTransport): Map<RequestId, RequestSpanMapValue> {
  // Handle invalid transport values for WeakMap while preserving correlation
  if (\!transport || typeof transport \!== 'object') {
    // Return persistent fallback Map to maintain correlation across calls
    return fallbackSpanMap;
  }
  // ... rest of function
}

Testing

Added comprehensive test coverage for all edge cases:

• attributeExtraction.test.ts: Tests undefined/null transports, constructor edge cases, sessionId handling
• correlation.test.ts: Tests WeakMap fallback scenarios, invalid transport objects, correlation isolation

All tests pass and verify that the patches handle edge cases without breaking existing functionality.

Compatibility

• ✅ Backward compatible - No breaking changes to existing APIs
• ✅ Non-invasive - Only adds defensive checks, doesn't modify core logic
• ✅ Performance neutral - Minimal overhead with early returns for invalid cases
• ✅ Type safe - Maintains existing TypeScript contracts

Impact

This fix prevents runtime errors in production environments when:

• MCP transports are not fully initialized
• Session establishment is in progress
• Invalid transport objects are passed to instrumentation functions
• Edge case transport implementations are used

The patches ensure reliable instrumentation while maintaining full compatibility with existing MCP server implementations.

Testing Instructions

1. The existing test suite continues to pass
2. New edge case tests verify defensive behavior
3. Real-world StreamableHTTPServerTransport usage is now more robust

🤖 Generated with Claude Code

[betegon]

I've changed a couple of thing, mostly agreed with @codyde . The description in his PR lines 5 items:

1. Transport initialization - when transport constructors are undefined/null.
2. Session establishment - when sessionId is undefined during MCP initialization phases.

These two first items are the main addition in this PR. So I haven't touch them much, just did a small refactor so it was easier to follow.

Now about these:

4. Span correlation - when transport objects cannot be used as WeakMap keys
5. Type validation - when invalid transport objects are passed to correlation functions

i've remove them as there aren't any code path that could put us in those situation as we have 1.) and 2.) in place.

I also added better transport name handling following @codyde addition of using

const transportName = transport.constructor.name?.toLowerCase() || 'unknown';

So now we get the name of the transport object used, which is handy when there could be more than one http and people can add their own transport and will be instrumenting those too.

[mydea]

hmm, should we maybe no lower-case the transport? I suppose this would be easier to read in camel case? 😅

[betegon]

totally right. fixing it

[mydea]

approved, LGTM - only one idea (but feel free to ignore) left, which is maybe we should not lowercase the transport name? but will happily defer to your perspective on this! nice work!