Add MCPcat (#26)

* remove migration

* add mcpcat

* order fix

* fix mcpcat in tests

* Revert "fix mcpcat in tests"

This reverts commit b432c6e.

* update mcpcat

* recommendations

* fix inputs

* chore: update wrangler to version 4.51.0
refactor: formatting code
fix: use Number.isNaN for loss check in formatMeasurementSummary

* beta3

* beta4

* beta5

* feat: add isOAuth property to Props and update authentication logic, fix for incorrect user type detection

---------

Co-authored-by: eyepokes <[email protected]>

Author: jimaek

package-lock.json

@@ -27,14 +27,15 @@
 		"patch-package": "^8.0.1",
 		"typescript": "^5.9.3",
 		"vitest": "^3.2.4",
-		"wrangler": "^4.42.0"
+		"wrangler": "^4.51.0"
 	},
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "^0.1.0",
 		"@modelcontextprotocol/sdk": "^1.20.2",
 		"agents": "^0.2.21",
 		"globalping": "^0.2.0",
 		"hono": "^4.10.6",
+		"mcpcat": "^0.1.9-beta.5",
 		"zod": "^3.25.76"
 	}
 }

package.json

@@ -261,6 +261,7 @@ app.get("/auth/callback", async (c) => {
 				state,
 				userName: userData.username,
 				isAuthenticated: true,
+				isOAuth: true,
 			},
 		});
 

src/app.ts

@@ -133,3 +133,11 @@ export const CORS_CONFIG = {
 	EXPOSE_HEADERS: "Mcp-Session-Id",
 	MAX_AGE: 86400, // 24 hours
 };
+
+/**
+ * MCPcat configuration for analytics and telemetry
+ */
+export const MCPCAT_CONFIG = {
+	ENABLED: true, // Set to false to disable MCPcat in dev environments
+	PROJECT_ID_ENV_VAR: "MCPCAT_PROJECT_ID",
+} as const;

src/config/constants.ts

@@ -2,13 +2,14 @@ import { McpAgent } from "agents/mcp";
 import OAuthProvider from "@cloudflare/workers-oauth-provider";
 import { isAPITokenRequest, isValidAPIToken } from "./auth";
 import app from "./app";
-import { MCP_CONFIG, OAUTH_CONFIG } from "./config";
+import { MCP_CONFIG, OAUTH_CONFIG, MCPCAT_CONFIG } from "./config";
 import type { GlobalpingEnv, Props, State } from "./types";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { registerGlobalpingTools } from "./mcp";
 import { sanitizeToken } from "./auth";
 import { validateOrigin, validateHost, getCorsOptionsForRequest } from "./lib";
+import * as mcpcat from "mcpcat";
 
 export class GlobalpingMCP extends McpAgent<GlobalpingEnv, State, Props> {
 	server = new McpServer({
@@ -51,6 +52,24 @@ Key guidelines:
 	async init() {
 		console.log("Initializing Globalping MCP...");
 
+		// Initialize MCPcat tracking if project ID is configured
+		if (this.env.MCPCAT_PROJECT_ID && MCPCAT_CONFIG.ENABLED) {
+			try {
+				mcpcat.track(this.server, this.env.MCPCAT_PROJECT_ID, {
+					// Identify users with generic labels
+					identify: async () => {
+						return this.getUserIdentification();
+					},
+				});
+
+				console.log("✓ MCPcat tracking initialized");
+			} catch (error) {
+				console.warn("⚠ MCPcat tracking initialization failed (non-fatal):", error);
+			}
+		} else {
+			console.log("✗ MCPcat tracking disabled (no project ID or disabled in config)");
+		}
+
 		// Register all the Globalping tools
 		registerGlobalpingTools(this, () => {
 			const raw = this.getToken() ?? "";
@@ -114,7 +133,6 @@ Key guidelines:
 				annotations: {
 					readOnlyHint: true,
 				},
-				inputSchema: {},
 				outputSchema: {
 					guide: z.string(),
 				},
@@ -174,7 +192,6 @@ This approach allows for direct side-by-side comparisons of different targets us
 				annotations: {
 					readOnlyHint: true,
 				},
-				inputSchema: {},
 				outputSchema: {
 					helpText: z.string(),
 				},
@@ -277,7 +294,6 @@ For more information, visit: https://www.globalping.io
 				annotations: {
 					readOnlyHint: true,
 				},
-				inputSchema: {},
 				outputSchema: {
 					authenticated: z.boolean(),
 					status: z.string(),
@@ -359,6 +375,50 @@ For more information, visit: https://www.globalping.io
 		return this.props?.accessToken;
 	}
 
+	/**
+	 * Returns generic user identification for MCPcat analytics
+	 * Does not expose PII - uses generic labels only
+	 */
+	private getUserIdentification(): {
+		userId: string;
+		userName: string;
+		userData: Record<string, any>;
+	} {
+		const isAuth = this.props?.isAuthenticated;
+		const hasAPIToken = !this.props?.isOAuth;
+
+		// Check API token first (most specific) to prevent misclassification
+		// as OAuth when API token flow sets isAuthenticated and userName
+		if (hasAPIToken) {
+			return {
+				userId: "api_token_user",
+				userName: "API Token User",
+				userData: {
+					authMethod: "api_token",
+				},
+			};
+		}
+
+		if (isAuth && this.props?.userName) {
+			return {
+				userId: "oauth_user",
+				userName: "OAuth User",
+				userData: {
+					authMethod: "oauth",
+					clientId: this.props.clientId || "unknown",
+				},
+			};
+		}
+
+		return {
+			userId: "anonymous_user",
+			userName: "Anonymous User",
+			userData: {
+				authMethod: "none",
+			},
+		};
+	}
+
 	setIsAuthenticated(isAuthenticated: boolean): void {
 		if (!this.props) return;
 		this.props.isAuthenticated = isAuthenticated;
@@ -490,6 +550,7 @@ async function handleAPITokenRequest<
 		userName: "API Token User",
 		clientId: "",
 		isAuthenticated: true,
+		isOAuth: false,
 	} satisfies Props;
 
 	if (pathname === MCP_CONFIG.ROUTES.SSE || pathname === MCP_CONFIG.ROUTES.SSE_MESSAGE) {

src/index.ts

@@ -136,7 +136,8 @@ export function formatMeasurementSummary(measurement: any): string {
 					const avg = testResult.stats.avg !== undefined ? testResult.stats.avg : "N/A";
 					const max = testResult.stats.max !== undefined ? testResult.stats.max : "N/A";
 					const loss =
-						typeof testResult.stats.loss === "number" && !isNaN(testResult.stats.loss)
+						typeof testResult.stats.loss === "number" &&
+						!Number.isNaN(testResult.stats.loss)
 							? testResult.stats.loss.toFixed(2)
 							: "N/A";
 

src/mcp/helpers.ts

@@ -10,10 +10,7 @@ import { maskToken } from "../auth";
 /**
  * Helper to wrap tool execution with error handling
  */
-async function handleToolExecution(
-	operation: () => Promise<any>,
-	errorMessagePrefix: string
-) {
+async function handleToolExecution(operation: () => Promise<any>, errorMessagePrefix: string) {
 	try {
 		return await operation();
 	} catch (error: any) {
@@ -561,7 +558,6 @@ export function registerGlobalpingTools(agent: GlobalpingMCP, getToken: () => st
 			annotations: {
 				readOnlyHint: true,
 			},
-			inputSchema: {},
 			outputSchema: {
 				totalProbes: z.number(),
 				continents: z.array(
@@ -658,7 +654,6 @@ export function registerGlobalpingTools(agent: GlobalpingMCP, getToken: () => st
 			annotations: {
 				readOnlyHint: true,
 			},
-			inputSchema: {},
 			outputSchema: {
 				authenticated: z.boolean(),
 				rateLimit: z.object({

src/mcp/tools.ts

@@ -5,6 +5,7 @@ export type Props = {
 	userName: string;
 	clientId: string;
 	isAuthenticated: boolean;
+	isOAuth: boolean;
 };
 
 // Define custom state for storing previous measurements

src/types/app.ts

@@ -24,6 +24,7 @@ export interface GlobalpingEnv {
 	GLOBALPING_CLIENT_ID: string;
 	globalping_mcp_object: DurableObjectNamespace;
 	OAUTH_KV: KVNamespace;
+	MCPCAT_PROJECT_ID?: string;
 }
 
 /**

src/types/globalping.ts

@@ -18,10 +18,12 @@ export default defineWorkersConfig({
 				main: "./src/index.ts",
 				miniflare: {
 					compatibilityDate: "2025-03-10",
-					compatibilityFlags: ["nodejs_compat"],
+					compatibilityFlags: ["nodejs_compat_v2"],
 					kvNamespaces: ["OAUTH_KV"],
 					bindings: {
 						GLOBALPING_CLIENT_ID: "test-client-id",
+						// Disable MCPcat during tests - it adds a required 'context' parameter to all tools for agents to understand their use-cases
+						MCPCAT_PROJECT_ID: "",
 					},
 				},
 				isolatedStorage: false,