@posthog/mcp 0.11.0 → 0.11.2

package/README.md

@@ -67,6 +67,45 @@ if (body?.method === 'initialize' && !req.headers[MCP_SESSION_HEADER]) {
 
 Details: [docs/ARCHITECTURE.md §4](./docs/ARCHITECTURE.md).
 
+## MCP TypeScript SDK v2
+
+`instrument()` works on both SDK majors — `@modelcontextprotocol/sdk` v1 and
+`@modelcontextprotocol/{core,server,client}` v2 — and on both the high-level `McpServer` and the
+low-level `Server`. Shapes are detected at runtime, so neither major is a dependency here.
+
+### Reading request headers in a callback
+
+If your `identify`, `intentFallback`, `eventProperties` or `beforeSend` reads HTTP headers, it has
+to change. The two majors put the request in different places and in different shapes: v1 attaches
+a plain object at `extra.requestInfo.headers`, v2 attaches the WHATWG `Request` at `extra.http.req`,
+whose `headers` only answers to `.get()`. A v1-shaped read returns `undefined` on v2 — an
+`identify()` written that way returns `null` and every event goes anonymous.
+
+The SDK hands your callback whatever the MCP SDK handed it, unchanged; it does **not** fake a v1
+shape on v2, because a partially synthesised `requestInfo` is a more convincing lie than an absent
+one. Read headers through the exported helper instead, which handles both majors, lowercases keys,
+and duck-types `Headers` so it also works on edge runtimes:
+
+```ts
+import { getRequestHeaders } from '@posthog/mcp'
+
+identify: async (request, extra) => {
+  const auth = getRequestHeaders(extra)?.['authorization'] // v1 and v2
+  // ...
+}
+```
+
+### If you switched to `instrument(server.server)`
+
+Before v2 support landed, the compatibility gate rejected high-level v2 servers, and the usual
+workaround was to instrument the underlying low-level server. `instrument(server)` now works, so
+you can go back to the documented call.
+
+Whether the workaround costs you anything depends on your stack: instrumenting the low-level server
+skips the high-level tool registry, so tool descriptions and callback-level wrapping come only from
+what is advertised over `tools/list`. If your framework never calls `registerTool()` — `@rekog/mcp-nest`
+does not — the registry is empty and the two calls behave the same.
+
 ## Developing locally
 
 To test local changes in a consumer app (e.g. a dummy MCP server), symlink **both**

package/dist/extensions/client-identity.d.ts

@@ -1,13 +1,24 @@
-import type { McpEvent, MCPRequestLike } from '../types';
+import type { CompatibleRequestHandlerExtra, McpEvent, MCPRequestLike, MCPServerLike } from '../types';
 /**
- * Client identity under the MCP 2026-07-28 (stateless) revision.
+ * Client identity — who is calling, and which spec revision they speak.
  *
- * That revision removes the `initialize` handshake and the `Mcp-Session-Id`
- * header (SEP-2575 / SEP-2567). Client name/version and the protocol version no
- * longer arrive once at `initialize` — they travel in every request's
- * `params._meta` under these reverse-DNS keys. We mirror the literal key strings
- * here rather than depend on the (still beta) v2 SDK, which is not a dependency
- * of this package.
+ * Where it lives depends on the revision the *request* declares, so this is a
+ * fallback chain and never a branch: one server serves both eras, request by
+ * request.
+ *
+ *   1. `ctx.mcpReq.envelope` — MCP SDK v2 lifts the reserved
+ *      `io.modelcontextprotocol/*` keys out of `_meta` before dispatch, so by
+ *      the time a handler runs they are here and `params._meta` is empty.
+ *   2. `request.params._meta` — where 2026-07-28 puts them on the wire, and
+ *      where they still are on any server that does not lift them.
+ *   3. the server's own accessors — `getClientVersion()` from a legacy
+ *      `initialize` handshake, `getNegotiatedProtocolVersion()` on v2.
+ *
+ * The 2026-07-28 revision removed the `initialize` handshake and the
+ * `Mcp-Session-Id` header (SEP-2575 / SEP-2567), so client name/version and the
+ * protocol version no longer arrive once per connection — they travel with
+ * every request. The key strings are mirrored here rather than imported,
+ * because no `@modelcontextprotocol/*` package is a dependency of this one.
  */
 export declare const META_CLIENT_INFO_KEY = "io.modelcontextprotocol/clientInfo";
 export declare const META_PROTOCOL_VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
@@ -16,6 +27,18 @@ export interface MetaClientInfo {
     clientVersion?: string;
     protocolVersion?: string;
 }
+/** Everything a request can be asked about who is calling. */
+export interface ClientIdentitySources {
+    request: MCPRequestLike;
+    extra?: CompatibleRequestHandlerExtra;
+    /**
+     * Typed `unknown` on purpose: every accessor on it is reached through a
+     * structural probe, never a declared type, because the two SDK majors expose
+     * different ones. Call sites pass a real `MCPServerLike`; the shape checks
+     * here are what decide whether it can answer.
+     */
+    server?: unknown;
+}
 /**
  * Reads the client name/version and protocol version a modern client puts in
  * `params._meta`. Returns `undefined` when the request carries none (e.g. a
@@ -23,17 +46,49 @@ export interface MetaClientInfo {
  */
 export declare function readMetaClientInfo(request: MCPRequestLike): MetaClientInfo | undefined;
 /**
- * Stamps any client identity found in `params._meta` directly onto the event
- * being built for *this* request, so it carries `$mcp_client_name`,
- * `$mcp_client_version`, and `$mcp_protocol_version` even when there was no
- * `initialize` to learn them from (the modern stateless case).
+ * Reads the same keys from MCP SDK v2's request envelope. v2 strips the reserved
+ * `io.modelcontextprotocol/*` keys from `_meta` while parsing, so on exactly the
+ * traffic this matters for, `readMetaClientInfo` finds nothing and this finds
+ * everything.
+ */
+export declare function readEnvelopeClientInfo(extra: CompatibleRequestHandlerExtra | undefined): MetaClientInfo | undefined;
+/**
+ * Asks the server itself. `getClientVersion()` answers on any server that
+ * handled an `initialize` (and v2 hosts such as `createMcpHandler` backfill it
+ * from the envelope); `getNegotiatedProtocolVersion()` exists on v2 only, which
+ * is why it is a link in the chain rather than a branch. Never throws — a
+ * server that dislikes being asked must not fail the tool call.
+ */
+export declare function readServerClientIdentity(server: unknown): MetaClientInfo | undefined;
+/**
+ * Resolves client identity through the whole chain, field by field: the first
+ * source that answers a field wins, and a source that answers nothing simply
+ * does not participate. Field-by-field rather than source-by-source because a
+ * request may carry its protocol version in the envelope while the client's
+ * name is only known to the server from a handshake.
+ *
+ * The first three links are **per request**, so they cannot describe anyone but
+ * the caller. Only the last — the server's own accessors — is connection-scoped,
+ * and on a server that multiplexes several clients through one connection it
+ * answers for whichever client completed the handshake. That is the best answer
+ * available on that connection, and it is the same scope `capture.ts` has always
+ * fallen back to (`eventInput.clientName ?? sessionInfo.clientName`), so the
+ * chain neither introduces that sharing nor widens it. Ordering it last is what
+ * keeps it a fallback: any request that identifies itself wins outright.
+ */
+export declare function resolveClientIdentity({ request, extra, server }: ClientIdentitySources): MetaClientInfo | undefined;
+/**
+ * Stamps whatever the chain resolved onto the event being built for *this*
+ * request, so it carries `$mcp_client_name`, `$mcp_client_version` and
+ * `$mcp_protocol_version` even when there was no `initialize` to learn them
+ * from (the modern stateless case).
  *
  * Writing to the event — a per-request object — rather than the server-wide
  * `sessionInfo` keeps identity correct when one instrumented server multiplexes
  * concurrent requests from different clients (which the stateless spec allows):
  * a sibling request can't clobber this event's attribution between now and when
- * it's captured. Only fields the request actually carries are set, so a request
- * without `_meta` leaves the event's existing values untouched.
+ * it's captured. Only fields actually resolved are set, so a request that
+ * carries nothing leaves the event's existing values untouched.
  */
-export declare function stampMetaClientInfo(event: McpEvent, request: MCPRequestLike): void;
+export declare function stampClientIdentity(event: McpEvent, request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra, server?: MCPServerLike): void;
 //# sourceMappingURL=client-identity.d.ts.map

package/dist/extensions/client-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-identity.d.ts","sourceRoot":"","sources":["../../src/extensions/client-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,uCAAuC,CAAA;AACxE,eAAO,MAAM,yBAAyB,4CAA4C,CAAA;AAElF,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAyBtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAclF"}
+{"version":3,"file":"client-identity.d.ts","sourceRoot":"","sources":["../../src/extensions/client-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGtG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,uCAAuC,CAAA;AACxE,eAAO,MAAM,yBAAyB,4CAA4C,CAAA;AAElF,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAA;IACvB,KAAK,CAAC,EAAE,6BAA6B,CAAA;IACrC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAuCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,6BAA6B,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAEnH;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAsBpF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,qBAAqB,GAAG,cAAc,GAAG,SAAS,CAYnH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,EACrC,MAAM,CAAC,EAAE,aAAa,GACrB,IAAI,CAcN"}

package/dist/extensions/client-identity.js

@@ -24,30 +24,79 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    META_CLIENT_INFO_KEY: ()=>META_CLIENT_INFO_KEY,
-    META_PROTOCOL_VERSION_KEY: ()=>META_PROTOCOL_VERSION_KEY,
+    resolveClientIdentity: ()=>resolveClientIdentity,
     readMetaClientInfo: ()=>readMetaClientInfo,
-    stampMetaClientInfo: ()=>stampMetaClientInfo
+    readServerClientIdentity: ()=>readServerClientIdentity,
+    readEnvelopeClientInfo: ()=>readEnvelopeClientInfo,
+    META_PROTOCOL_VERSION_KEY: ()=>META_PROTOCOL_VERSION_KEY,
+    stampClientIdentity: ()=>stampClientIdentity,
+    META_CLIENT_INFO_KEY: ()=>META_CLIENT_INFO_KEY
 });
+const external_detect_js_namespaceObject = require("./detect.js");
 const META_CLIENT_INFO_KEY = 'io.modelcontextprotocol/clientInfo';
 const META_PROTOCOL_VERSION_KEY = 'io.modelcontextprotocol/protocolVersion';
+function nonEmptyString(value) {
+    return 'string' == typeof value && value.length > 0 ? value : void 0;
+}
+function readClientInfoValue(value) {
+    if (!value || 'object' != typeof value) return;
+    const { name, version } = value;
+    const result = {};
+    const clientName = nonEmptyString(name);
+    const clientVersion = nonEmptyString(version);
+    if (clientName) result.clientName = clientName;
+    if (clientVersion) result.clientVersion = clientVersion;
+    return result.clientName || result.clientVersion ? result : void 0;
+}
+function readReservedKeys(bag) {
+    if (!bag || 'object' != typeof bag) return;
+    const record = bag;
+    const result = {
+        ...readClientInfoValue(record[META_CLIENT_INFO_KEY])
+    };
+    const protocolVersion = nonEmptyString(record[META_PROTOCOL_VERSION_KEY]);
+    if (protocolVersion) result.protocolVersion = protocolVersion;
+    return result.clientName || result.clientVersion || result.protocolVersion ? result : void 0;
+}
 function readMetaClientInfo(request) {
-    const meta = request.params?._meta;
-    if (!meta || 'object' != typeof meta) return;
-    const record = meta;
+    return readReservedKeys(request.params?._meta);
+}
+function readEnvelopeClientInfo(extra) {
+    return readReservedKeys(extra?.mcpReq?.envelope);
+}
+function readServerClientIdentity(server) {
+    if (!server) return;
+    const result = {};
+    try {
+        if ((0, external_detect_js_namespaceObject.hasClientVersionAccessor)(server)) Object.assign(result, readClientInfoValue(server.getClientVersion()));
+        if ((0, external_detect_js_namespaceObject.hasNegotiatedProtocolVersionAccessor)(server)) {
+            const negotiated = server.getNegotiatedProtocolVersion();
+            const protocolVersion = nonEmptyString(negotiated);
+            if (protocolVersion) result.protocolVersion = protocolVersion;
+        }
+    } catch  {}
+    return result.clientName || result.clientVersion || result.protocolVersion ? result : void 0;
+}
+function resolveClientIdentity({ request, extra, server }) {
+    const chain = [
+        readEnvelopeClientInfo(extra),
+        readMetaClientInfo(request),
+        readServerClientIdentity(server)
+    ];
     const result = {};
-    const clientInfo = record[META_CLIENT_INFO_KEY];
-    if (clientInfo && 'object' == typeof clientInfo) {
-        const { name, version } = clientInfo;
-        if ('string' == typeof name && name.length > 0) result.clientName = name;
-        if ('string' == typeof version && version.length > 0) result.clientVersion = version;
+    for (const source of chain)if (source) {
+        result.clientName ??= source.clientName;
+        result.clientVersion ??= source.clientVersion;
+        result.protocolVersion ??= source.protocolVersion;
     }
-    const protocolVersion = record[META_PROTOCOL_VERSION_KEY];
-    if ('string' == typeof protocolVersion && protocolVersion.length > 0) result.protocolVersion = protocolVersion;
     return result.clientName || result.clientVersion || result.protocolVersion ? result : void 0;
 }
-function stampMetaClientInfo(event, request) {
-    const info = readMetaClientInfo(request);
+function stampClientIdentity(event, request, extra, server) {
+    const info = resolveClientIdentity({
+        request,
+        extra,
+        server
+    });
     if (!info) return;
     if (info.clientName) event.clientName = info.clientName;
     if (info.clientVersion) event.clientVersion = info.clientVersion;
@@ -55,13 +104,19 @@ function stampMetaClientInfo(event, request) {
 }
 exports.META_CLIENT_INFO_KEY = __webpack_exports__.META_CLIENT_INFO_KEY;
 exports.META_PROTOCOL_VERSION_KEY = __webpack_exports__.META_PROTOCOL_VERSION_KEY;
+exports.readEnvelopeClientInfo = __webpack_exports__.readEnvelopeClientInfo;
 exports.readMetaClientInfo = __webpack_exports__.readMetaClientInfo;
-exports.stampMetaClientInfo = __webpack_exports__.stampMetaClientInfo;
+exports.readServerClientIdentity = __webpack_exports__.readServerClientIdentity;
+exports.resolveClientIdentity = __webpack_exports__.resolveClientIdentity;
+exports.stampClientIdentity = __webpack_exports__.stampClientIdentity;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "META_CLIENT_INFO_KEY",
     "META_PROTOCOL_VERSION_KEY",
+    "readEnvelopeClientInfo",
     "readMetaClientInfo",
-    "stampMetaClientInfo"
+    "readServerClientIdentity",
+    "resolveClientIdentity",
+    "stampClientIdentity"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/extensions/client-identity.mjs

@@ -1,25 +1,71 @@
+import { hasClientVersionAccessor, hasNegotiatedProtocolVersionAccessor } from "./detect.mjs";
 const META_CLIENT_INFO_KEY = 'io.modelcontextprotocol/clientInfo';
 const META_PROTOCOL_VERSION_KEY = 'io.modelcontextprotocol/protocolVersion';
+function nonEmptyString(value) {
+    return 'string' == typeof value && value.length > 0 ? value : void 0;
+}
+function readClientInfoValue(value) {
+    if (!value || 'object' != typeof value) return;
+    const { name, version } = value;
+    const result = {};
+    const clientName = nonEmptyString(name);
+    const clientVersion = nonEmptyString(version);
+    if (clientName) result.clientName = clientName;
+    if (clientVersion) result.clientVersion = clientVersion;
+    return result.clientName || result.clientVersion ? result : void 0;
+}
+function readReservedKeys(bag) {
+    if (!bag || 'object' != typeof bag) return;
+    const record = bag;
+    const result = {
+        ...readClientInfoValue(record[META_CLIENT_INFO_KEY])
+    };
+    const protocolVersion = nonEmptyString(record[META_PROTOCOL_VERSION_KEY]);
+    if (protocolVersion) result.protocolVersion = protocolVersion;
+    return result.clientName || result.clientVersion || result.protocolVersion ? result : void 0;
+}
 function readMetaClientInfo(request) {
-    const meta = request.params?._meta;
-    if (!meta || 'object' != typeof meta) return;
-    const record = meta;
+    return readReservedKeys(request.params?._meta);
+}
+function readEnvelopeClientInfo(extra) {
+    return readReservedKeys(extra?.mcpReq?.envelope);
+}
+function readServerClientIdentity(server) {
+    if (!server) return;
+    const result = {};
+    try {
+        if (hasClientVersionAccessor(server)) Object.assign(result, readClientInfoValue(server.getClientVersion()));
+        if (hasNegotiatedProtocolVersionAccessor(server)) {
+            const negotiated = server.getNegotiatedProtocolVersion();
+            const protocolVersion = nonEmptyString(negotiated);
+            if (protocolVersion) result.protocolVersion = protocolVersion;
+        }
+    } catch  {}
+    return result.clientName || result.clientVersion || result.protocolVersion ? result : void 0;
+}
+function resolveClientIdentity({ request, extra, server }) {
+    const chain = [
+        readEnvelopeClientInfo(extra),
+        readMetaClientInfo(request),
+        readServerClientIdentity(server)
+    ];
     const result = {};
-    const clientInfo = record[META_CLIENT_INFO_KEY];
-    if (clientInfo && 'object' == typeof clientInfo) {
-        const { name, version } = clientInfo;
-        if ('string' == typeof name && name.length > 0) result.clientName = name;
-        if ('string' == typeof version && version.length > 0) result.clientVersion = version;
+    for (const source of chain)if (source) {
+        result.clientName ??= source.clientName;
+        result.clientVersion ??= source.clientVersion;
+        result.protocolVersion ??= source.protocolVersion;
     }
-    const protocolVersion = record[META_PROTOCOL_VERSION_KEY];
-    if ('string' == typeof protocolVersion && protocolVersion.length > 0) result.protocolVersion = protocolVersion;
     return result.clientName || result.clientVersion || result.protocolVersion ? result : void 0;
 }
-function stampMetaClientInfo(event, request) {
-    const info = readMetaClientInfo(request);
+function stampClientIdentity(event, request, extra, server) {
+    const info = resolveClientIdentity({
+        request,
+        extra,
+        server
+    });
     if (!info) return;
     if (info.clientName) event.clientName = info.clientName;
     if (info.clientVersion) event.clientVersion = info.clientVersion;
     if (info.protocolVersion) event.protocolVersion = info.protocolVersion;
 }
-export { META_CLIENT_INFO_KEY, META_PROTOCOL_VERSION_KEY, readMetaClientInfo, stampMetaClientInfo };
+export { META_CLIENT_INFO_KEY, META_PROTOCOL_VERSION_KEY, readEnvelopeClientInfo, readMetaClientInfo, readServerClientIdentity, resolveClientIdentity, stampClientIdentity };

package/dist/extensions/compatibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../src/extensions/compatibility.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE3C;;;;;;;;;;;GAWG;AAEH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAI9D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY,GAAG;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CAIpG;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY,CAExE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAG,aAAa,GAAG,sBAAsB,CA6BhH;AAoDD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAanE"}
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../src/extensions/compatibility.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAWrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE3C;;;;;;;;;;;GAWG;AAEH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAI9D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY,GAAG;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CAEpG;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY,CAExE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAG,aAAa,GAAG,sBAAsB,CAiChH;AAyCD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAanE"}

package/dist/extensions/compatibility.js

@@ -24,20 +24,21 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    getMCPCompatibleErrorMessage: ()=>getMCPCompatibleErrorMessage,
-    isCompatibleServerType: ()=>isCompatibleServerType,
-    isHighLevelServer: ()=>isHighLevelServer,
     isLowLevelServer: ()=>isLowLevelServer,
-    logCompatibilityWarning: ()=>logCompatibilityWarning
+    isHighLevelServer: ()=>isHighLevelServer,
+    logCompatibilityWarning: ()=>logCompatibilityWarning,
+    isCompatibleServerType: ()=>isCompatibleServerType,
+    getMCPCompatibleErrorMessage: ()=>getMCPCompatibleErrorMessage
 });
+const external_detect_js_namespaceObject = require("./detect.js");
 function logCompatibilityWarning(logger) {
     logger('PostHog MCP analytics SDK Compatibility: This version only supports Model Context Protocol TypeScript SDK v1.11 and above. Please upgrade if using an older version.');
 }
 function isHighLevelServer(server) {
-    return !!server && 'object' == typeof server && 'server' in server && !!server.server && 'object' == typeof server.server;
+    return (0, external_detect_js_namespaceObject.hasNestedLowLevelServer)(server);
 }
 function isLowLevelServer(server) {
-    return !!server && 'object' == typeof server && !('server' in server);
+    return (0, external_detect_js_namespaceObject.isBareServerShape)(server);
 }
 function isCompatibleServerType(server, logger) {
     if (!server || 'object' != typeof server) {
@@ -45,13 +46,13 @@ function isCompatibleServerType(server, logger) {
         throw new Error("PostHog MCP analytics SDK compatibility error: Server must be an object. Ensure you're using MCP SDK v1.11 or higher.");
     }
     if (isHighLevelServer(server)) {
-        if (!server._registeredTools || 'object' != typeof server._registeredTools) {
+        if (!(0, external_detect_js_namespaceObject.hasToolRegistry)(server)) {
             logCompatibilityWarning(logger);
             throw new Error('PostHog MCP analytics SDK compatibility error: High-level server must have _registeredTools object. This requires MCP SDK v1.11 or higher.');
         }
-        if ('function' != typeof server.tool) {
+        if (!(0, external_detect_js_namespaceObject.canRegisterTools)(server)) {
             logCompatibilityWarning(logger);
-            throw new Error('PostHog MCP analytics SDK compatibility error: High-level server must have tool() method. This requires MCP SDK v1.11 or higher.');
+            throw new Error('PostHog MCP analytics SDK compatibility error: High-level server must have a registerTool() or tool() method. This requires MCP SDK v1.11 or higher.');
         }
         const targetServer = server.server;
         validateLowLevelServer(targetServer, logger);
@@ -65,24 +66,19 @@ function validateLowLevelServer(server, logger) {
         logCompatibilityWarning(logger);
         throw new Error("PostHog MCP analytics SDK compatibility error: Server must be an object. Ensure you're using MCP SDK v1.11 or higher.");
     }
-    const serverRecord = server;
-    if ('function' != typeof serverRecord.setRequestHandler) {
+    if (!(0, external_detect_js_namespaceObject.canSetRequestHandler)(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server must have a setRequestHandler method. This requires MCP SDK v1.11 or higher.');
     }
-    if (!(serverRecord._requestHandlers && serverRecord._requestHandlers instanceof Map)) {
+    if (!(0, external_detect_js_namespaceObject.hasRequestHandlerMap)(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server._requestHandlers is not accessible. This requires MCP SDK v1.11 or higher.');
     }
-    if ('function' != typeof serverRecord._requestHandlers.get) {
-        logCompatibilityWarning(logger);
-        throw new Error('PostHog MCP analytics SDK compatibility error: Server._requestHandlers must be a Map with a get method. This requires MCP SDK v1.11 or higher.');
-    }
-    if ('function' != typeof serverRecord.getClientVersion) {
+    if (!(0, external_detect_js_namespaceObject.hasClientVersionAccessor)(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server.getClientVersion must be a function. This requires MCP SDK v1.11 or higher.');
     }
-    if (!serverRecord._serverInfo || 'object' != typeof serverRecord._serverInfo || !('name' in serverRecord._serverInfo)) {
+    if (!(0, external_detect_js_namespaceObject.hasServerInfo)(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server._serverInfo is not accessible or missing name. This requires MCP SDK v1.11 or higher.');
     }

package/dist/extensions/compatibility.mjs

@@ -1,11 +1,12 @@
+import { canRegisterTools, canSetRequestHandler, hasClientVersionAccessor, hasNestedLowLevelServer, hasRequestHandlerMap, hasServerInfo, hasToolRegistry, isBareServerShape } from "./detect.mjs";
 function logCompatibilityWarning(logger) {
     logger('PostHog MCP analytics SDK Compatibility: This version only supports Model Context Protocol TypeScript SDK v1.11 and above. Please upgrade if using an older version.');
 }
 function isHighLevelServer(server) {
-    return !!server && 'object' == typeof server && 'server' in server && !!server.server && 'object' == typeof server.server;
+    return hasNestedLowLevelServer(server);
 }
 function isLowLevelServer(server) {
-    return !!server && 'object' == typeof server && !('server' in server);
+    return isBareServerShape(server);
 }
 function isCompatibleServerType(server, logger) {
     if (!server || 'object' != typeof server) {
@@ -13,13 +14,13 @@ function isCompatibleServerType(server, logger) {
         throw new Error("PostHog MCP analytics SDK compatibility error: Server must be an object. Ensure you're using MCP SDK v1.11 or higher.");
     }
     if (isHighLevelServer(server)) {
-        if (!server._registeredTools || 'object' != typeof server._registeredTools) {
+        if (!hasToolRegistry(server)) {
             logCompatibilityWarning(logger);
             throw new Error('PostHog MCP analytics SDK compatibility error: High-level server must have _registeredTools object. This requires MCP SDK v1.11 or higher.');
         }
-        if ('function' != typeof server.tool) {
+        if (!canRegisterTools(server)) {
             logCompatibilityWarning(logger);
-            throw new Error('PostHog MCP analytics SDK compatibility error: High-level server must have tool() method. This requires MCP SDK v1.11 or higher.');
+            throw new Error('PostHog MCP analytics SDK compatibility error: High-level server must have a registerTool() or tool() method. This requires MCP SDK v1.11 or higher.');
         }
         const targetServer = server.server;
         validateLowLevelServer(targetServer, logger);
@@ -33,24 +34,19 @@ function validateLowLevelServer(server, logger) {
         logCompatibilityWarning(logger);
         throw new Error("PostHog MCP analytics SDK compatibility error: Server must be an object. Ensure you're using MCP SDK v1.11 or higher.");
     }
-    const serverRecord = server;
-    if ('function' != typeof serverRecord.setRequestHandler) {
+    if (!canSetRequestHandler(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server must have a setRequestHandler method. This requires MCP SDK v1.11 or higher.');
     }
-    if (!(serverRecord._requestHandlers && serverRecord._requestHandlers instanceof Map)) {
+    if (!hasRequestHandlerMap(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server._requestHandlers is not accessible. This requires MCP SDK v1.11 or higher.');
     }
-    if ('function' != typeof serverRecord._requestHandlers.get) {
-        logCompatibilityWarning(logger);
-        throw new Error('PostHog MCP analytics SDK compatibility error: Server._requestHandlers must be a Map with a get method. This requires MCP SDK v1.11 or higher.');
-    }
-    if ('function' != typeof serverRecord.getClientVersion) {
+    if (!hasClientVersionAccessor(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server.getClientVersion must be a function. This requires MCP SDK v1.11 or higher.');
     }
-    if (!serverRecord._serverInfo || 'object' != typeof serverRecord._serverInfo || !('name' in serverRecord._serverInfo)) {
+    if (!hasServerInfo(server)) {
         logCompatibilityWarning(logger);
         throw new Error('PostHog MCP analytics SDK compatibility error: Server._serverInfo is not accessible or missing name. This requires MCP SDK v1.11 or higher.');
     }

package/dist/extensions/detect.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Structural feature probes.
+ *
+ * Every question about the shape of a server object is answered here, by
+ * duck-typing the object in front of us — never by reading a package version or
+ * a protocol constant. Two reasons this is a rule and not a preference:
+ *
+ * - The two SDK majors expose the same capability under different names (v1's
+ *   `.tool()` vs v2's `.registerTool()`), so "which SDK is installed" answers a
+ *   different question than "can this object register a tool".
+ * - A single v2 server serves both protocol eras, request by request, so no
+ *   module-level constant describes it. v2's exported `LATEST_PROTOCOL_VERSION`
+ *   is `2025-11-25`.
+ *
+ * Nothing here imports `@modelcontextprotocol/*`; that boundary is pinned by
+ * `sdk-import-boundary.test.ts`.
+ */
+type UnknownRecord = Record<string, unknown>;
+/** A high-level `McpServer` wrapper: it holds the low-level server on `.server`. */
+export declare function hasNestedLowLevelServer(server: unknown): server is UnknownRecord & {
+    server: UnknownRecord;
+};
+/** No `.server` property, so the object is itself the low-level `Server`. */
+export declare function isBareServerShape(server: unknown): boolean;
+/** The high-level registry we read tool metadata from and wrap callbacks in. */
+export declare function hasToolRegistry(server: unknown): boolean;
+/**
+ * The object can register a tool.
+ *
+ * v1 offers both `tool()` and `registerTool()`; v2 dropped the deprecated
+ * `tool()` and keeps only `registerTool()`. Requiring `tool()` specifically is
+ * what made `instrument()` reject every v2 high-level server — and, because
+ * `instrument()` swallows compatibility errors, reject it silently.
+ */
+export declare function canRegisterTools(server: unknown): boolean;
+/** Handler registration, which we patch to wrap late registrations. */
+export declare function canSetRequestHandler(server: unknown): boolean;
+/** The live handler map we read and write directly. A real `Map` on both majors. */
+export declare function hasRequestHandlerMap(server: unknown): boolean;
+/** `getClientVersion()` — still present on v2, and a link in B1's identity chain. */
+export declare function hasClientVersionAccessor(server: unknown): boolean;
+/**
+ * `getNegotiatedProtocolVersion()` — v2 only, and the last link in the protocol
+ * version chain. A v1 server does not have it, which is why the chain probes for
+ * it instead of branching on which SDK is installed.
+ */
+export declare function hasNegotiatedProtocolVersionAccessor(server: unknown): boolean;
+/** `_serverInfo`, which names the server on every event. */
+export declare function hasServerInfo(server: unknown): boolean;
+export {};
+//# sourceMappingURL=detect.d.ts.map

package/dist/extensions/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/extensions/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAU5C,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,aAAa,GAAG;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,CAG5G;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAG1D;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAG7D;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAE7E;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAGtD"}