@posthog/mcp 0.4.4 → 0.5.1

package/README.md

@@ -7,3 +7,32 @@ SDK usage examples and code snippets live in the official documentation so they
 ## Documentation
 
 - [MCP analytics docs](https://posthog.com/docs/mcp-analytics)
+
+## Developing locally
+
+To test local changes in a consumer app (e.g. a dummy MCP server), symlink **both**
+`@posthog/mcp` and its `posthog-node` peer from this monorepo into the app — run from the
+app's directory:
+
+```bash
+mkdir -p node_modules/@posthog   # in case the app has no other @posthog/-scoped deps yet
+ln -s /absolute/path/to/posthog-js/packages/mcp  node_modules/@posthog/mcp
+ln -s /absolute/path/to/posthog-js/packages/node node_modules/posthog-node
+```
+
+Then keep a watch build running and restart the app after each change:
+
+```bash
+cd /absolute/path/to/posthog-js/packages/mcp && pnpm dev   # rebuilds dist/ on save
+
+# in the app (e.g. dummy mcp), after each rebuild:
+npm start                                                  # Node caches dist/ at startup, so restart to pick it up
+```
+
+- **`npm install` in the app replaces both symlinks with published copies** — re-create them if you run it.
+
+## Run tests
+
+```bash
+cd packages/mcp && pnpm test:unit
+```

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/extensions/session.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,UAAU,CAAA;AAKjB,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,6BAA6B,GAAG,MAAM,CAoCvG;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CA8Bb"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/extensions/session.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,UAAU,CAAA;AAKjB,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,6BAA6B,GAAG,MAAM,CAoCvG;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CAgCb"}

package/dist/extensions/session.js

@@ -73,11 +73,11 @@ function setLastActivity(server) {
     (0, external_internal_js_namespaceObject.setServerTrackingData)(server, data);
 }
 function getSessionInfo(server, data, sessionId) {
-    let clientInfo = {
-        name: void 0,
-        version: void 0
-    };
-    if (!data?.sessionInfo.clientName) clientInfo = server.getClientVersion();
+    let clientInfo;
+    clientInfo = data?.sessionInfo.clientName ? {
+        name: data.sessionInfo.clientName,
+        version: data.sessionInfo.clientVersion
+    } : server.getClientVersion();
     const actorInfo = data?.identifiedSessions.get(sessionId ?? data.sessionId);
     const sessionInfo = {
         ipAddress: void 0,

package/dist/extensions/session.mjs

@@ -41,11 +41,11 @@ function setLastActivity(server) {
     setServerTrackingData(server, data);
 }
 function getSessionInfo(server, data, sessionId) {
-    let clientInfo = {
-        name: void 0,
-        version: void 0
-    };
-    if (!data?.sessionInfo.clientName) clientInfo = server.getClientVersion();
+    let clientInfo;
+    clientInfo = data?.sessionInfo.clientName ? {
+        name: data.sessionInfo.clientName,
+        version: data.sessionInfo.clientVersion
+    } : server.getClientVersion();
     const actorInfo = data?.identifiedSessions.get(sessionId ?? data.sessionId);
     const sessionInfo = {
         ipAddress: void 0,

package/dist/index.d.ts

@@ -28,6 +28,25 @@ import type { McpAnalytics, MCPAnalyticsOptions } from './types';
  * ```
  */
 declare function instrument(server: unknown, posthog: PostHog, options?: MCPAnalyticsOptions): McpAnalytics;
+/**
+ * A point-free `(server) => server` helper for framework server-mutation hooks (e.g.
+ * `@rekog/mcp-nest`'s `serverMutator`). It instruments the server and returns it, so you
+ * don't trip over {@link instrument} returning the analytics handle rather than the server —
+ * the bare `(s) => instrument(s, posthog)` would replace the server with the handle.
+ *
+ * @example
+ * ```ts
+ * McpModule.forRoot({ serverMutator: instrumentMutator(posthog) })
+ * ```
+ *
+ * Need the handle for custom events? Call {@link instrument} directly inside your own mutator
+ * and return the server. See https://posthog.com/docs/mcp-analytics/installation.
+ *
+ * @param posthog - A `posthog-node` client you construct and own.
+ * @param options - Optional configuration. See `MCPAnalyticsOptions`.
+ * @returns A `(server) => server` mutator that instruments the server and returns it.
+ */
+declare function instrumentMutator<TServer>(posthog: PostHog, options?: MCPAnalyticsOptions): (server: TServer) => TServer;
 export { deriveSessionIdFromMCPSession };
 export { POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, } from './extensions/constants';
 export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp';
@@ -36,5 +55,5 @@ export { setLogger } from './extensions/logger';
 export { PostHog, type PostHogOptions } from 'posthog-node';
 export type { BeforeSendFn, CaptureEventData, InitializeCaptureData, McpAnalytics, McpCaptureCommon, MCPAnalyticsContextOptions, MCPAnalyticsIntentSource, MCPAnalyticsOptions, MissingCapabilityCaptureData, PreparedToolCall, PrepareToolListOptions, ToolCallCaptureData, ToolsListCaptureData, UserIdentity, } from './types';
 export type IdentifyFunction = MCPAnalyticsOptions['identify'];
-export { instrument };
+export { instrument, instrumentMutator };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAO3C,OAAO,EAAE,6BAA6B,EAAgC,MAAM,sBAAsB,CAAA;AAGlG,OAAO,KAAK,EAGV,YAAY,EAEZ,mBAAmB,EAGpB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA6BtG;AAmFD,OAAO,EAAE,6BAA6B,EAAE,CAAA;AACxC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAI/C,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3D,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,GACb,MAAM,SAAS,CAAA;AAChB,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAO3C,OAAO,EAAE,6BAA6B,EAAgC,MAAM,sBAAsB,CAAA;AAGlG,OAAO,KAAK,EAGV,YAAY,EAEZ,mBAAmB,EAGpB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA6BtG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAKjH;AAmFD,OAAO,EAAE,6BAA6B,EAAE,CAAA;AACxC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAI/C,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3D,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,GACb,MAAM,SAAS,CAAA;AAChB,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/index.js

@@ -29,6 +29,7 @@ __webpack_require__.d(__webpack_exports__, {
     deriveSessionIdFromMCPSession: ()=>session_js_namespaceObject.deriveSessionIdFromMCPSession,
     POSTHOG_MCP_ANALYTICS_SOURCE: ()=>constants_js_namespaceObject.POSTHOG_MCP_ANALYTICS_SOURCE,
     instrument: ()=>instrument,
+    instrumentMutator: ()=>instrumentMutator,
     setLogger: ()=>logger_js_namespaceObject.setLogger,
     PostHogMCPAnalyticsEvent: ()=>constants_js_namespaceObject.PostHogMCPAnalyticsEvent,
     getMoreToolsResult: ()=>tools_js_namespaceObject.getMoreToolsResult,
@@ -69,6 +70,12 @@ function instrument(server, posthog, options = {}) {
         };
     }
 }
+function instrumentMutator(posthog, options) {
+    return (server)=>{
+        instrument(server, posthog, options);
+        return server;
+    };
+}
 function createAnalyticsHandle(lowLevelServer) {
     return {
         capture: (eventData)=>captureCustomEvent(lowLevelServer, eventData)
@@ -131,6 +138,7 @@ exports.PostHogMCPAnalyticsProperty = __webpack_exports__.PostHogMCPAnalyticsPro
 exports.deriveSessionIdFromMCPSession = __webpack_exports__.deriveSessionIdFromMCPSession;
 exports.getMoreToolsResult = __webpack_exports__.getMoreToolsResult;
 exports.instrument = __webpack_exports__.instrument;
+exports.instrumentMutator = __webpack_exports__.instrumentMutator;
 exports.setLogger = __webpack_exports__.setLogger;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "POSTHOG_MCP_ANALYTICS_SOURCE",
@@ -141,6 +149,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "deriveSessionIdFromMCPSession",
     "getMoreToolsResult",
     "instrument",
+    "instrumentMutator",
     "setLogger"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {

package/dist/index.mjs

@@ -33,6 +33,12 @@ function instrument(server, posthog, options = {}) {
         };
     }
 }
+function instrumentMutator(posthog, options) {
+    return (server)=>{
+        instrument(server, posthog, options);
+        return server;
+    };
+}
 function createAnalyticsHandle(lowLevelServer) {
     return {
         capture: (eventData)=>captureCustomEvent(lowLevelServer, eventData)
@@ -87,4 +93,4 @@ async function captureCustomEvent(lowLevelServer, eventData) {
     await captureEvent(lowLevelServer, event);
     log(`Captured event "${eventData.event}" for session ${trackingData.sessionId}`);
 }
-export { POSTHOG_MCP_ANALYTICS_SOURCE, PostHog, PostHogMCP, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, deriveSessionIdFromMCPSession, getMoreToolsResult, instrument, setLogger };
+export { POSTHOG_MCP_ANALYTICS_SOURCE, PostHog, PostHogMCP, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, deriveSessionIdFromMCPSession, getMoreToolsResult, instrument, instrumentMutator, setLogger };

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "0.4.4";
+export declare const version = "0.5.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     version: ()=>version
 });
-const version = '0.4.4';
+const version = '0.5.1';
 exports.version = __webpack_exports__.version;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "version"

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = '0.4.4';
+const version = '0.5.1';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/mcp",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -28,7 +28,7 @@
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@posthog/core": "^1.38.0"
+    "@posthog/core": "^1.38.1"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.27.1",
@@ -39,7 +39,7 @@
     "@types/node": "^20.0.0",
     "jest": "29.7.0",
     "zod": "^3.25.0",
-    "posthog-node": "^5.38.6",
+    "posthog-node": "^5.38.8",
     "@posthog-tooling/tsconfig-base": "1.1.1"
   },
   "peerDependencies": {

package/src/extensions/session.ts

@@ -89,11 +89,13 @@ export function getSessionInfo(
   data: MCPAnalyticsData | undefined,
   sessionId?: string
 ): SessionInfo {
-  let clientInfo: ServerClientInfoLike | undefined = {
-    name: undefined,
-    version: undefined,
-  }
-  if (!data?.sessionInfo.clientName) {
+  let clientInfo: ServerClientInfoLike | undefined
+  if (data?.sessionInfo.clientName) {
+    clientInfo = {
+      name: data.sessionInfo.clientName,
+      version: data.sessionInfo.clientVersion,
+    }
+  } else {
     clientInfo = server.getClientVersion()
   }
   const actorInfo = data?.identifiedSessions.get(sessionId ?? data.sessionId)

package/src/index.ts

@@ -79,6 +79,31 @@ function instrument(server: unknown, posthog: PostHog, options: MCPAnalyticsOpti
   }
 }
 
+/**
+ * A point-free `(server) => server` helper for framework server-mutation hooks (e.g.
+ * `@rekog/mcp-nest`'s `serverMutator`). It instruments the server and returns it, so you
+ * don't trip over {@link instrument} returning the analytics handle rather than the server —
+ * the bare `(s) => instrument(s, posthog)` would replace the server with the handle.
+ *
+ * @example
+ * ```ts
+ * McpModule.forRoot({ serverMutator: instrumentMutator(posthog) })
+ * ```
+ *
+ * Need the handle for custom events? Call {@link instrument} directly inside your own mutator
+ * and return the server. See https://posthog.com/docs/mcp-analytics/installation.
+ *
+ * @param posthog - A `posthog-node` client you construct and own.
+ * @param options - Optional configuration. See `MCPAnalyticsOptions`.
+ * @returns A `(server) => server` mutator that instruments the server and returns it.
+ */
+function instrumentMutator<TServer>(posthog: PostHog, options?: MCPAnalyticsOptions): (server: TServer) => TServer {
+  return (server: TServer): TServer => {
+    instrument(server, posthog, options)
+    return server
+  }
+}
+
 function createAnalyticsHandle(lowLevelServer: MCPServerLike): McpAnalytics {
   return {
     capture: (eventData) => captureCustomEvent(lowLevelServer, eventData),
@@ -190,4 +215,4 @@ export type {
   UserIdentity,
 } from './types'
 export type IdentifyFunction = MCPAnalyticsOptions['identify']
-export { instrument }
+export { instrument, instrumentMutator }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.4.4'
+export const version = '0.5.1'