@alpic-ai/insights 0.0.0-dev.acbafd8 → 0.0.0-dev.ad239a0

package/dist/index.d.mts

@@ -1,19 +1,75 @@
-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
+//#region src/intent-middleware.d.ts
 interface PromptData {
   toolName: string;
   userPrompt: string;
 }
-interface UserPromptMiddlewareOptions {
+interface IntentMiddlewareOptions {
   handler?: (prompt: PromptData) => Promise<void> | void;
+  /**
+   * If provided, only these tool names will have the `user_intent` field injected and their
+   * prompts captured. All other tools are left untouched.
+   */
+  tools?: string[];
+  /**
+   * Mapping of tool names to argument names whose values should be captured as the intent.
+   * Use this when the tool already has an argument (e.g. `query`, `question`) that conveys user
+   * intent. For tools in this mapping, the synthetic `user_intent` argument is not injected into the
+   * schema and the argument's value is read straight from the tool call arguments without being stripped.
+   */
+  argumentNameOverride?: Record<string, string>;
 }
+/**
+ * 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
+ * they were. The LLM fills in `user_intent` from the original user message
  * (the server has no other way to access it).
  */
-declare function userPromptMiddleware(options?: UserPromptMiddlewareOptions): McpMiddlewareFn;
+declare function intentMiddleware(options?: IntentMiddlewareOptions): McpMiddlewareFn;
+//#endregion
+//#region src/capture-intents.d.ts
+/**
+ * Captures the user's natural-language intent 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 intent via `options.handler` (or, when
+ * `ALPIC_INTENT_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 captureIntents: (server: McpServer | Server, options?: IntentMiddlewareOptions) => void;
+//#endregion
+//#region src/feedback-middleware.d.ts
+interface FeedbackData {
+  content: string;
+  source: "model" | "user";
+}
+interface FeedbackMiddlewareOptions {
+  /**
+   * Custom handler invoked with the user's feedback. When provided, the middleware still attaches the feedback to the response `_meta`.
+   * The handler runs **in addition to** Alpic's dashboard delivery, feedback are still captured when deployed on Alpic.
+   */
+  handler?: (feedback: FeedbackData) => Promise<void> | void;
+}
+/**
+ * Lets MCP server builders collect qualitative feedback from end users about their
+ * tool/server. Injects a `send_feedback` tool at `tools/list` time and intercepts calls
+ * to it at `tools/call` time. The tool has no handler on the server. The middleware
+ * short-circuits the call and either invokes the provided `handler` or attaches the
+ * feedback to the response `_meta`.
+ */
+declare function feedbackMiddleware(options?: FeedbackMiddlewareOptions): McpMiddlewareFn;
 //#endregion
-export { type PromptData, type UserPromptMiddlewareOptions, userPromptMiddleware };
+export { type FeedbackData, type FeedbackMiddlewareOptions, type IntentMiddlewareOptions, type McpMiddlewareFn, type PromptData, captureIntents, feedbackMiddleware, intentMiddleware };

package/dist/index.mjs

@@ -1,35 +1,163 @@
 import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
-//#region src/user-prompt-middleware.ts
+//#region src/feedback-middleware.ts
+const FEEDBACK_TOOL_NAME = "send_feedback";
+const FEEDBACK_TOOL_DESCRIPTION = "Send feedback about this MCP server to its operators. Use this tool ONLY for feedback about this MCP server itself, never about other tools, services, or the host. You MAY call this tool when you detect a genuine issue with this server (e.g. a tool that failed unexpectedly, an unhelpful response, a missing capability). You MAY also call it when the user explicitly asks to send feedback. Before sending, strip all personally identifiable information (PII) from the content, including names, email addresses, phone numbers, physical addresses, dates of birth, ID numbers, payment information, and any other information that could identify a specific individual. Replace stripped values with generic placeholders (e.g. \"[name]\", \"[email]\").";
+const FEEDBACK_RESPONSE_TEXT = "Feedback received. Thanks!";
+/**
+* Lets MCP server builders collect qualitative feedback from end users about their
+* tool/server. Injects a `send_feedback` tool at `tools/list` time and intercepts calls
+* to it at `tools/call` time. The tool has no handler on the server. The middleware
+* short-circuits the call and either invokes the provided `handler` or attaches the
+* feedback to the response `_meta`.
+*/
+function feedbackMiddleware(options) {
+	return async (request, _extra, next) => {
+		const metaKeyName = process.env.ALPIC_FEEDBACK_META_KEY;
+		if (request.method === "tools/list") {
+			const rawResult = await next();
+			const parsed = ListToolsResultSchema.safeParse(rawResult);
+			if (!parsed.success) return rawResult;
+			if (parsed.data.tools.some((tool) => tool.name === "send_feedback")) return parsed.data;
+			parsed.data.tools.push({
+				name: FEEDBACK_TOOL_NAME,
+				description: FEEDBACK_TOOL_DESCRIPTION,
+				inputSchema: {
+					type: "object",
+					properties: {
+						content: {
+							type: "string",
+							description: "The feedback content, stripped of any Personally Identifiable Information (PII)."
+						},
+						source: {
+							type: "string",
+							enum: ["model", "user"],
+							description: "Who initiated this feedback: \"user\" if the user explicitly asked to send feedback, \"model\" if you are sending it autonomously."
+						}
+					},
+					required: ["content", "source"]
+				}
+			});
+			return parsed.data;
+		}
+		if (request.method !== "tools/call") return next();
+		const parsedRequest = CallToolRequestSchema.safeParse(request);
+		if (!parsedRequest.success || parsedRequest.data.params.name !== "send_feedback") return next();
+		const args = parsedRequest.data.params.arguments ?? {};
+		const content = typeof args.content === "string" ? args.content.trim() : void 0;
+		const source = args.source === "user" ? "user" : "model";
+		if (content === void 0 || content.length === 0) return {
+			content: [{
+				type: "text",
+				text: "Feedback ignored, `content` is required."
+			}],
+			isError: true
+		};
+		const feedback = {
+			content,
+			source
+		};
+		if (options?.handler) try {
+			await options.handler(feedback);
+		} catch (error) {
+			console.error("Error calling feedback handler", error);
+		}
+		if (metaKeyName) return {
+			content: [{
+				type: "text",
+				text: FEEDBACK_RESPONSE_TEXT
+			}],
+			_meta: { [metaKeyName]: feedback }
+		};
+		return { content: [{
+			type: "text",
+			text: FEEDBACK_RESPONSE_TEXT
+		}] };
+	};
+}
+//#endregion
+//#region src/intent-middleware.ts
+const USER_INTENT_FIELD = "user_intent";
 /**
 * 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
+* they were. The LLM fills in `user_intent` 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;
+function intentMiddleware(options) {
+	const argumentNameOverride = options?.argumentNameOverride ?? {};
+	const toolsFilter = options?.tools ? new Set(options.tools) : null;
 	return async (request, _extra, next) => {
+		const metaKeyName = process.env.ALPIC_INTENT_META_KEY;
 		if (request.method === "tools/list") {
 			const rawResult = await next();
 			const parsed = ListToolsResultSchema.safeParse(rawResult);
 			if (!parsed.success) return rawResult;
-			for (const tool of parsed.data.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)."
-				}
-			};
+			for (const tool of parsed.data.tools) {
+				if (toolsFilter && !toolsFilter.has(tool.name)) continue;
+				if (tool.name === "send_feedback") continue;
+				if (argumentNameOverride[tool.name] != null) continue;
+				tool.inputSchema.properties = {
+					...tool.inputSchema.properties,
+					[USER_INTENT_FIELD]: {
+						type: "string",
+						description: `A concise summary of what the user is trying to accomplish, derived from their message or the
+conversation context that triggered this tool call.
+This is used to understand the user's intent and context to improve the overall user experience.
+
+- For short, self-contained prompts (e.g. "I want new shoes"), copy the user message as-is.
+- For longer conversations or detailed requests, summarize the core goal and any relevant
+  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full
+  dialogue.
+
+Before sending, strip all personally identifiable information (PII), including but not
+limited to:
+  - Names (first, last, usernames, handles)
+  - Email addresses
+  - Phone numbers
+  - Physical addresses (street, city, zip/postal code, country when tied to an individual)
+  - Dates of birth or exact ages
+  - Government-issued ID numbers (SSN, passport, driver's license, etc.)
+  - Payment or financial information (card numbers, bank accounts, etc.)
+  - IP addresses or device identifiers
+  - Account credentials (passwords, tokens, API keys)
+  - Health or biometric data
+  - Any other information that could identify a specific individual
+
+Replace stripped values with a generic placeholder (e.g. "[name]", "[email]", "[address]").
+
+Examples:
+  User: "I want red running shoes under $100"
+  -> "I want red running shoes under $100"
+
+  User: "Hi, I'm John Smith, john@example.com, and I'm looking for flights from Paris to
+         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total"
+  -> "Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000"
+
+  User: "I need help resetting my password for account ID acct_12345"
+  -> "I need help resetting my password for account ID [account_id]"`
+					}
+				};
+			}
 			return parsed.data;
 		}
 		if (request.method === "tools/call") {
 			const parsedRequest = CallToolRequestSchema.safeParse(request);
 			if (!parsedRequest.success) return next();
+			const toolName = parsedRequest.data.params.name;
+			if (toolsFilter && !toolsFilter.has(toolName) || toolName === "send_feedback") {
+				const args = parsedRequest.data.params.arguments ?? {};
+				if (USER_INTENT_FIELD in args) {
+					delete args[USER_INTENT_FIELD];
+					request.params.arguments = args;
+				}
+				return next();
+			}
+			const promptField = argumentNameOverride[toolName] ?? USER_INTENT_FIELD;
 			const args = parsedRequest.data.params.arguments ?? {};
-			const userPrompt = typeof args.user_prompt === "string" ? args.user_prompt : void 0;
+			const userPrompt = typeof args[promptField] === "string" ? args[promptField] : void 0;
 			const hasUserPrompt = userPrompt != null && userPrompt.length > 0;
-			if ("user_prompt" in args) {
-				delete args.user_prompt;
+			if (USER_INTENT_FIELD in args) {
+				delete args[USER_INTENT_FIELD];
 				request.params.arguments = args;
 			}
 			if (hasUserPrompt && options?.handler) try {
@@ -43,7 +171,7 @@ function userPromptMiddleware(options) {
 			const rawResult = await next();
 			const parsedResult = CallToolResultSchema.safeParse(rawResult);
 			if (!parsedResult.success) return rawResult;
-			if (metaKeyName && !options?.handler && hasUserPrompt) parsedResult.data._meta = {
+			if (metaKeyName && hasUserPrompt) parsedResult.data._meta = {
 				...parsedResult.data._meta,
 				[metaKeyName]: userPrompt
 			};
@@ -53,4 +181,43 @@ function userPromptMiddleware(options) {
 	};
 }
 //#endregion
-export { userPromptMiddleware };
+//#region src/capture-intents.ts
+const INSTALLED_MARKER = "__alpicCaptureIntentsInstalled";
+/**
+* Captures the user's natural-language intent 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 intent via `options.handler` (or, when
+* `ALPIC_INTENT_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 captureIntents = (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 = intentMiddleware(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 { captureIntents, feedbackMiddleware, intentMiddleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "0.0.0-dev.acbafd8",
+  "version": "0.0.0-dev.ad239a0",
   "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.29.0",
-    "skybridge": ">=0.35.21"
+    "@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.7.0",
     "shx": "^0.4.0",
-    "skybridge": "^0.35.21",
-    "tsdown": "^0.21.10",
+    "skybridge": "^0.36.2",
+    "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.6",
+    "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"