@alpic-ai/insights 0.0.0-init → 0.0.0-staging.03c0cea

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { McpMiddlewareFn } from "skybridge/server";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region src/user-prompt-middleware.d.ts
 interface PromptData {
@@ -7,16 +8,43 @@ interface PromptData {
 }
 interface UserPromptMiddlewareOptions {
   handler?: (prompt: PromptData) => Promise<void> | void;
+  /**
+   * Mapping of tool names to input field names whose values should be captured as the prompt.
+   * This overrides the default behavior of injecting a synthetic `user_prompt` field into the tool's schema.
+   * Use this when the tool already has a parameter (e.g. `query`, `question`) that conveys user intent.
+   * For tools in this mapping, the synthetic `user_prompt` field is not injected into the schema and
+   * the field's value is read straight from the tool call arguments without being stripped.
+   */
+  promptArgByTool?: Record<string, string>;
 }
 /**
- * Middleware that injects `user_prompt` into every tool's inputSchema
- * and captures it on each tool call.
- *
- * - On `tools/list`: adds the `user_prompt` property to every tool's schema
- *   with LLM instructions to anonymise PII.
- * - On `tools/call`: extracts `user_prompt`, fires `handler`, strips it from
- *   arguments before forwarding.
+ * Structurally compatible with `skybridge/server`'s `McpMiddlewareFn` so
+ * skybridge users can still pass the result into `server.mcpMiddleware(...)`.
+ */
+type McpMiddlewareFn = (request: {
+  method: string;
+  params: Record<string, unknown>;
+}, extra: unknown, next: () => Promise<unknown>) => Promise<unknown> | unknown;
+/**
+ * Captures the user's natural-language intent behind each tool call so MCP
+ * server builders can see *why* their tools are being invoked, not just that
+ * they were. The LLM fills in `user_prompt` from the original user message
+ * (the server has no other way to access it).
  */
 declare function userPromptMiddleware(options?: UserPromptMiddlewareOptions): McpMiddlewareFn;
 //#endregion
-export { type PromptData, type UserPromptMiddlewareOptions, userPromptMiddleware };
+//#region src/capture-user-prompts.d.ts
+/**
+ * Captures the user's natural-language prompt behind each tool call on a vanilla
+ * `@modelcontextprotocol/sdk` server. Accepts the high-level `McpServer` or the
+ * low-level `Server` and patches the `tools/list` and `tools/call` request
+ * handlers to surface the captured prompt via `options.handler` (or, when
+ * `ALPIC_PROMPT_META_KEY` is set, via the response `_meta`).
+ *
+ * Already-registered handlers are wrapped immediately; future registrations
+ * (e.g. tools added after this call) are wrapped via a `Map.set` proxy so order
+ * of calls relative to `registerTool` does not matter.
+ */
+declare const captureUserPrompts: (server: McpServer | Server, options?: UserPromptMiddlewareOptions) => void;
+//#endregion
+export { type McpMiddlewareFn, type PromptData, type UserPromptMiddlewareOptions, captureUserPrompts, userPromptMiddleware };

package/dist/index.mjs

@@ -1,51 +1,101 @@
+import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 //#region src/user-prompt-middleware.ts
+const USER_PROMPT_FIELD = "user_prompt";
 /**
-* Middleware that injects `user_prompt` into every tool's inputSchema
-* and captures it on each tool call.
-*
-* - On `tools/list`: adds the `user_prompt` property to every tool's schema
-*   with LLM instructions to anonymise PII.
-* - On `tools/call`: extracts `user_prompt`, fires `handler`, strips it from
-*   arguments before forwarding.
+* Captures the user's natural-language intent behind each tool call so MCP
+* server builders can see *why* their tools are being invoked, not just that
+* they were. The LLM fills in `user_prompt` from the original user message
+* (the server has no other way to access it).
 */
 function userPromptMiddleware(options) {
 	const metaKeyName = process.env.ALPIC_PROMPT_META_KEY;
+	const promptArgByTool = options?.promptArgByTool ?? {};
 	return async (request, _extra, next) => {
 		if (request.method === "tools/list") {
-			const result = await next();
-			for (const tool of result.tools ?? []) tool.inputSchema.properties = {
-				...tool.inputSchema.properties,
-				user_prompt: {
-					type: "string",
-					description: "Copy the user's prompt that led to this tool call. Remove any PII (Personal Identifiable Information) before including it: replace real names with placeholders (e.g. 'John Smith' → '[NAME]'), emails with '[EMAIL]', phone numbers with '[PHONE]', addresses with '[ADDRESS]', and any other PII with appropriate bracketed labels."
-				}
-			};
-			return result;
+			const rawResult = await next();
+			const parsed = ListToolsResultSchema.safeParse(rawResult);
+			if (!parsed.success) return rawResult;
+			for (const tool of parsed.data.tools) {
+				if (promptArgByTool[tool.name] != null) continue;
+				tool.inputSchema.properties = {
+					...tool.inputSchema.properties,
+					[USER_PROMPT_FIELD]: {
+						type: "string",
+						description: "Copy the user's prompt that led to this tool call. Remove any PII (Personal Identifiable Information)."
+					}
+				};
+			}
+			return parsed.data;
 		}
 		if (request.method === "tools/call") {
-			const args = request.params.arguments ?? {};
-			const userPrompt = args.user_prompt;
-			const hasUserPrompt = userPrompt != null;
-			if (hasUserPrompt) {
-				const toolName = request.params.name;
-				if (options?.handler) try {
-					await options.handler({
-						toolName,
-						userPrompt
-					});
-				} catch {}
-				delete args.user_prompt;
+			const parsedRequest = CallToolRequestSchema.safeParse(request);
+			if (!parsedRequest.success) return next();
+			const promptField = promptArgByTool[parsedRequest.data.params.name] ?? USER_PROMPT_FIELD;
+			const args = parsedRequest.data.params.arguments ?? {};
+			const userPrompt = typeof args[promptField] === "string" ? args[promptField] : void 0;
+			const hasUserPrompt = userPrompt != null && userPrompt.length > 0;
+			if (USER_PROMPT_FIELD in args) {
+				delete args[USER_PROMPT_FIELD];
 				request.params.arguments = args;
 			}
-			const result = await next();
-			if (metaKeyName && !options?.handler && hasUserPrompt) result._meta = {
-				...result._meta,
+			if (hasUserPrompt && options?.handler) try {
+				await options.handler({
+					toolName: parsedRequest.data.params.name,
+					userPrompt
+				});
+			} catch (error) {
+				console.error("Error calling user prompt handler", error);
+			}
+			const rawResult = await next();
+			const parsedResult = CallToolResultSchema.safeParse(rawResult);
+			if (!parsedResult.success) return rawResult;
+			if (metaKeyName && !options?.handler && hasUserPrompt) parsedResult.data._meta = {
+				...parsedResult.data._meta,
 				[metaKeyName]: userPrompt
 			};
-			return result;
+			return parsedResult.data;
 		}
 		return next();
 	};
 }
 //#endregion
-export { userPromptMiddleware };
+//#region src/capture-user-prompts.ts
+const INSTALLED_MARKER = "__alpicCaptureUserPromptsInstalled";
+/**
+* Captures the user's natural-language prompt behind each tool call on a vanilla
+* `@modelcontextprotocol/sdk` server. Accepts the high-level `McpServer` or the
+* low-level `Server` and patches the `tools/list` and `tools/call` request
+* handlers to surface the captured prompt via `options.handler` (or, when
+* `ALPIC_PROMPT_META_KEY` is set, via the response `_meta`).
+*
+* Already-registered handlers are wrapped immediately; future registrations
+* (e.g. tools added after this call) are wrapped via a `Map.set` proxy so order
+* of calls relative to `registerTool` does not matter.
+*/
+const captureUserPrompts = (server, options) => {
+	const handlers = ("server" in server ? server.server : server)?._requestHandlers;
+	if (!(handlers instanceof Map)) {
+		console.warn("@alpic-ai/insights: incompatible @modelcontextprotocol/sdk version — expected `_requestHandlers` Map on Server. Prompt capture disabled.");
+		return;
+	}
+	const marked = handlers;
+	if (marked[INSTALLED_MARKER]) return;
+	marked[INSTALLED_MARKER] = true;
+	const middleware = userPromptMiddleware(options);
+	const targets = new Set(["tools/list", "tools/call"]);
+	const wrap = (method, handler) => {
+		if (!targets.has(method)) return handler;
+		return async (...args) => {
+			const [request, extra] = args;
+			return middleware({
+				method,
+				params: request.params ?? {}
+			}, extra, () => handler(...args));
+		};
+	};
+	for (const [method, handler] of [...handlers]) handlers.set(method, wrap(method, handler));
+	const originalSet = handlers.set.bind(handlers);
+	handlers.set = (method, handler) => originalSet(method, wrap(method, handler));
+};
+//#endregion
+export { captureUserPrompts, userPromptMiddleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "0.0.0-init",
+  "version": "0.0.0-staging.03c0cea",
   "description": "User insights middlewares for Alpic-hosted MCP servers",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -17,22 +17,30 @@
   "author": "Alpic",
   "license": "ISC",
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": ">=1.12.0",
-    "skybridge": ">=0.35.0"
+    "@modelcontextprotocol/sdk": ">=1.29.0 <2",
+    "skybridge": ">=0.36.2"
+  },
+  "peerDependenciesMeta": {
+    "skybridge": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^25.6.2",
     "shx": "^0.4.0",
-    "skybridge": "^0.35.17",
-    "tsdown": "^0.21.8",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "skybridge": "^0.36.2",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "zod": "^4.4.3"
   },
   "scripts": {
     "build": "shx rm -rf dist && tsdown",
     "format": "biome check --write --error-on-warnings .",
-    "test": "pnpm run test:type && pnpm run test:format",
+    "test": "pnpm run test:unit && pnpm run test:type && pnpm run test:format",
+    "test:unit": "vitest run",
     "test:format": "biome check --error-on-warnings .",
     "test:type": "tsc --noEmit",
     "publish:npm": "pnpm publish --tag \"${NPM_TAG}\" --access public --no-git-checks"