@alpic-ai/insights 0.0.0-dev.be6e8e4 → 0.0.0-dev.bf144c2

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,7 +8,23 @@ 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>;
 }
+/**
+ * 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
@@ -16,4 +33,41 @@ interface UserPromptMiddlewareOptions {
  */
 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
+//#region src/feedback-middleware.d.ts
+interface FeedbackData {
+  toolName?: string;
+  message: string;
+}
+interface FeedbackMiddlewareOptions {
+  /** Tool name to register. Defaults to `send_feedback`. */
+  toolName?: string;
+  /**
+   * Custom handler invoked with the user's feedback. When provided, the middleware does NOT
+   * attach data to the response `_meta`. The handler takes full ownership of delivery.
+   */
+  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 FeedbackData, type FeedbackMiddlewareOptions, type McpMiddlewareFn, type PromptData, type UserPromptMiddlewareOptions, captureUserPrompts, feedbackMiddleware, userPromptMiddleware };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 //#region src/user-prompt-middleware.ts
+const USER_PROMPT_FIELD = "user_prompt";
 /**
 * 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
@@ -8,28 +9,33 @@ import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } fr
 */
 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 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 (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 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.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_PROMPT_FIELD in args) {
+				delete args[USER_PROMPT_FIELD];
 				request.params.arguments = args;
 			}
 			if (hasUserPrompt && options?.handler) try {
@@ -53,4 +59,126 @@ function userPromptMiddleware(options) {
 	};
 }
 //#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
+//#region src/feedback-middleware.ts
+const DEFAULT_FEEDBACK_TOOL_NAME = "send_feedback";
+const FEEDBACK_TOOL_DESCRIPTION = "Send the user's 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 MUST ask the user for explicit consent before calling this tool. You can proactively suggest sending feedback when something didn't work well, but never call without consent. ";
+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) {
+	const feedbackToolName = options?.toolName ?? DEFAULT_FEEDBACK_TOOL_NAME;
+	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 === feedbackToolName)) return parsed.data;
+			parsed.data.tools.push({
+				name: feedbackToolName,
+				description: FEEDBACK_TOOL_DESCRIPTION,
+				inputSchema: {
+					type: "object",
+					properties: {
+						tool_name: {
+							type: "string",
+							description: "Name of the tool the feedback is about, when applicable."
+						},
+						message: {
+							type: "string",
+							description: "The user's feedback content. Remove any PII (Personal Identifiable Information)."
+						}
+					},
+					required: ["message"]
+				}
+			});
+			return parsed.data;
+		}
+		if (request.method !== "tools/call") return next();
+		const parsedRequest = CallToolRequestSchema.safeParse(request);
+		if (!parsedRequest.success || parsedRequest.data.params.name !== feedbackToolName) return next();
+		const args = parsedRequest.data.params.arguments ?? {};
+		const message = typeof args.message === "string" ? args.message.trim() : void 0;
+		const rawToolName = typeof args.tool_name === "string" ? args.tool_name.trim() : "";
+		const toolName = rawToolName.length > 0 ? rawToolName : void 0;
+		if (message === void 0 || message.length === 0) return {
+			content: [{
+				type: "text",
+				text: "Feedback ignored — `message` is required."
+			}],
+			isError: true
+		};
+		const feedback = toolName !== void 0 ? {
+			toolName,
+			message
+		} : { message };
+		if (options?.handler) {
+			try {
+				await options.handler(feedback);
+			} catch (error) {
+				console.error("Error calling feedback handler", error);
+			}
+			return { content: [{
+				type: "text",
+				text: FEEDBACK_RESPONSE_TEXT
+			}] };
+		}
+		if (metaKeyName) return {
+			content: [{
+				type: "text",
+				text: FEEDBACK_RESPONSE_TEXT
+			}],
+			_meta: { [metaKeyName]: feedback }
+		};
+		return { content: [{
+			type: "text",
+			text: FEEDBACK_RESPONSE_TEXT
+		}] };
+	};
+}
+//#endregion
+export { captureUserPrompts, feedbackMiddleware, userPromptMiddleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "0.0.0-dev.be6e8e4",
+  "version": "0.0.0-dev.bf144c2",
   "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",
+    "@modelcontextprotocol/sdk": ">=1.29.0 <2",
     "skybridge": ">=0.35.21"
   },
+  "peerDependenciesMeta": {
+    "skybridge": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^25.6.0",
     "shx": "^0.4.0",
     "skybridge": "^0.35.21",
     "tsdown": "^0.21.10",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "zod": "^4.4.1"
   },
   "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"