@alpic-ai/insights 0.0.0-dev.ad3076e → 0.0.0-dev.ae87f1b

package/dist/index.d.mts

@@ -51,4 +51,25 @@ declare function intentMiddleware(options?: IntentMiddlewareOptions): McpMiddlew
  */
 declare const captureIntents: (server: McpServer | Server, options?: IntentMiddlewareOptions) => void;
 //#endregion
-export { type IntentMiddlewareOptions, type McpMiddlewareFn, type PromptData, captureIntents, intentMiddleware };
+//#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 FeedbackData, type FeedbackMiddlewareOptions, type IntentMiddlewareOptions, type McpMiddlewareFn, type PromptData, captureIntents, feedbackMiddleware, intentMiddleware };

package/dist/index.mjs

@@ -1,4 +1,80 @@
 import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
+//#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";
 /**
@@ -8,16 +84,17 @@ const USER_INTENT_FIELD = "user_intent";
 * (the server has no other way to access it).
 */
 function intentMiddleware(options) {
-	const metaKeyName = process.env.ALPIC_INTENT_META_KEY;
 	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) {
 				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,
@@ -67,7 +144,7 @@ Examples:
 			const parsedRequest = CallToolRequestSchema.safeParse(request);
 			if (!parsedRequest.success) return next();
 			const toolName = parsedRequest.data.params.name;
-			if (toolsFilter && !toolsFilter.has(toolName)) {
+			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];
@@ -143,4 +220,4 @@ const captureIntents = (server, options) => {
 	handlers.set = (method, handler) => originalSet(method, wrap(method, handler));
 };
 //#endregion
-export { captureIntents, intentMiddleware };
+export { captureIntents, feedbackMiddleware, intentMiddleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "0.0.0-dev.ad3076e",
+  "version": "0.0.0-dev.ae87f1b",
   "description": "User insights middlewares for Alpic-hosted MCP servers",
   "type": "module",
   "main": "./dist/index.mjs",