spm-mcp 0.2.0 → 0.3.1

package/dist/src/client/cloud-functions.d.ts

@@ -2,4 +2,5 @@
  * Helper to call Cloud Functions that return plain JSON (not SSE).
  * Used for nano app CRUD and discovery endpoints.
  */
+export declare function setChannel(ch: string): void;
 export declare function callJsonEndpoint(endpoint: string, body?: Record<string, unknown>, apiKey?: string): Promise<unknown>;

package/dist/src/client/cloud-functions.js

@@ -3,11 +3,15 @@
  * Used for nano app CRUD and discovery endpoints.
  */
 import { config } from '../config.js';
+// Channel identifier — overridden by hosted/cloud-run.ts
+let _channel = 'mcp-npm';
+export function setChannel(ch) { _channel = ch; }
 export async function callJsonEndpoint(endpoint, body = {}, apiKey) {
     const url = `${config.cloudFunctionsBase}/${endpoint}`;
     const headers = {
         'Content-Type': 'application/json',
         'Origin': 'https://mcp.superproductmanager.ai',
+        'X-SPM-Channel': _channel,
     };
     if (apiKey) {
         headers['X-SPM-API-Key'] = apiKey;

package/dist/src/client/spm-api.d.ts

@@ -13,6 +13,7 @@ declare const ENDPOINTS: {
     readonly classifyIntent: "/classifyIntent";
 };
 type EndpointName = keyof typeof ENDPOINTS;
+export declare function setChannel(ch: string): void;
 /**
  * Call an SPM Cloud Function endpoint.
  * Handles SSE stream parsing automatically.

package/dist/src/client/spm-api.js

@@ -14,12 +14,16 @@ const ENDPOINTS = {
     extensionReviewAgainAgentV3: '/extensionReviewAgainAgentV3',
     classifyIntent: '/classifyIntent',
 };
+// Channel identifier — shared with cloud-functions.ts
+let _channel = 'mcp-npm';
+export function setChannel(ch) { _channel = ch; }
 function getHeaders(apiKey) {
     const key = apiKey || config.apiKey;
     const headers = {
         'Content-Type': 'application/json',
         'Accept': 'text/event-stream, application/json',
         'Origin': 'https://mcp.superproductmanager.ai',
+        'X-SPM-Channel': _channel,
     };
     if (key) {
         headers['X-SPM-API-Key'] = key;

package/dist/src/index.js

@@ -44,7 +44,9 @@ export function createSpmMcpServer(options) {
     server.tool('spm_analyze', 'Analyze a product document against SPM expert expectations. ' +
         'Pass a document and a nano_app_id (e.g., "prd_critique", "user_story", "growth_strategy") ' +
         'to get an expert analysis with expectations, sub-expectations, scores, and evidence. ' +
-        'Call spm_list_nano_apps first if you need to discover available templates.', {
+        'Call spm_list_nano_apps first if you need to discover available templates. ' +
+        'IMPORTANT: Present results as a clear scorecard table (Expectation | Score | Verdict). ' +
+        'Highlight critical gaps (score < 50%) and suggest running spm_clarify on the weakest gap next.', {
         document: z.string().describe('The product document text to analyze'),
         nano_app_id: z.string().describe('The nano app template key (e.g., "prd_critique"). Call spm_list_nano_apps to see available options.'),
     }, async (input) => {
@@ -61,7 +63,12 @@ export function createSpmMcpServer(options) {
     // Tool: spm_clarify
     server.tool('spm_clarify', 'Get clarification questions for gaps identified in an SPM analysis. ' +
         'Pass the original document, the expert analysis context, and a target gap. ' +
-        'Returns targeted questions with suggested answers to close document gaps.', {
+        'Returns targeted questions with suggested answers to close document gaps. ' +
+        'IMPORTANT: When presenting results to the user, minimize cognitive load. ' +
+        'Show the question prominently, then present each answer option as a clear ' +
+        'numbered choice the user can pick (1, 2, 3...). Mark the [recommended] option. ' +
+        'If you have native interactive UI (buttons, selectable options, AskUserQuestion), use it. ' +
+        'The user should be able to pick an option or type their own answer with minimal effort.', {
         document: z.string().describe('The original product document text'),
         nano_app_id: z.string().describe('The nano app template key used in the analysis'),
         main_expectation: z.string().describe('The main expectation name/text from the analysis result'),
@@ -71,6 +78,8 @@ export function createSpmMcpServer(options) {
             question: z.string(),
             answer: z.string(),
         })).optional().describe('Array of previous Q&A pairs from this clarification session. Empty for first question.'),
+        user_context: z.string().optional().describe('Context about the PM: role, experience level, company stage, research done, decisions made. Helps generate tailored questions.'),
+        about_company: z.string().optional().describe('Context about the company/product: stage, team size, market, existing users, business model.'),
     }, async (input) => {
         try {
             const result = await handleClarify(input, apiKey);
@@ -95,6 +104,8 @@ export function createSpmMcpServer(options) {
             question: z.string(),
             answer: z.string(),
         })).describe('All Q&A pairs accumulated from spm_clarify rounds. The evaluator uses these as evidence.'),
+        user_context: z.string().optional().describe('Context about the PM: role, experience level, company stage, research done, decisions made.'),
+        about_company: z.string().optional().describe('Context about the company/product: stage, team size, market, existing users, business model.'),
     }, async (input) => {
         try {
             const result = await handleEvaluate(input, apiKey);
@@ -110,7 +121,9 @@ export function createSpmMcpServer(options) {
     server.tool('spm_improve', 'Generate improved document content for a specific gap. ' +
         'Pass the document, the target sub-expectation, and all clarification Q&A pairs. ' +
         'Returns paste-ready content the PM can insert into their document. ' +
-        'Use after spm_evaluate confirms the gap is sufficiently covered by clarification answers.', {
+        'Use after spm_evaluate confirms the gap is sufficiently covered by clarification answers. ' +
+        'IMPORTANT: Present the generated content in clean markdown the user can copy-paste directly. ' +
+        'If there are [ACTION NEEDED] markers, highlight them so the user knows what to fill in.', {
         document: z.string().describe('The original product document text'),
         nano_app_id: z.string().describe('The nano app template key used in the analysis'),
         main_expectation: z.string().describe('The main expectation name/text from the analysis result'),

package/dist/src/tools/clarify.d.ts

@@ -47,6 +47,14 @@ export declare const clarifyDefinition: {
                 };
                 description: string;
             };
+            user_context: {
+                type: string;
+                description: string;
+            };
+            about_company: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
@@ -61,5 +69,7 @@ export interface ClarifyInput {
         question: string;
         answer: string;
     }>;
+    user_context?: string;
+    about_company?: string;
 }
 export declare function handleClarify(input: ClarifyInput, apiKey?: string): Promise<unknown>;

package/dist/src/tools/clarify.js

@@ -52,12 +52,23 @@ export const clarifyDefinition = {
                 description: 'Array of previous Q&A pairs from this clarification session. ' +
                     'Pass as [{question, answer}, ...]. Empty array for first question.',
             },
+            user_context: {
+                type: 'string',
+                description: 'Context about the PM: their role, experience level, company stage, ' +
+                    'what research they have done, what decisions they have already made. ' +
+                    'This helps generate questions tailored to the specific user rather than generic ones.',
+            },
+            about_company: {
+                type: 'string',
+                description: 'Context about the company/product: stage, team size, market, ' +
+                    'existing users, business model. Helps ground questions in reality.',
+            },
         },
         required: ['document', 'nano_app_id', 'main_expectation', 'all_sub_expectations', 'target_sub_expectation'],
     },
 };
 export async function handleClarify(input, apiKey) {
-    const { document, nano_app_id, main_expectation, all_sub_expectations, target_sub_expectation, previous_answers = [], } = input;
+    const { document, nano_app_id, main_expectation, all_sub_expectations, target_sub_expectation, previous_answers = [], user_context = '', about_company = '', } = input;
     if (!document?.trim()) {
         throw new SpmApiError('Document text is required', 'INVALID_INPUT');
     }
@@ -88,6 +99,8 @@ export async function handleClarify(input, apiKey) {
         recent_recommendation: '',
         latest_review: '',
         gap_coverage: '',
+        user_context,
+        about_company,
         nano_app_id,
     };
     const result = await callClarificationAgent(payload, apiKey);

package/dist/src/tools/evaluate.d.ts

@@ -17,5 +17,7 @@ export interface EvaluateInput {
         question: string;
         answer: string;
     }>;
+    user_context?: string;
+    about_company?: string;
 }
 export declare function handleEvaluate(input: EvaluateInput, apiKey?: string): Promise<unknown>;

package/dist/src/tools/evaluate.js

@@ -10,7 +10,7 @@
  */
 import { callEndpoint, SpmApiError } from '../client/spm-api.js';
 export async function handleEvaluate(input, apiKey) {
-    const { document, nano_app_id, main_expectation, all_sub_expectations, prior_clarifications = [], } = input;
+    const { document, nano_app_id, main_expectation, all_sub_expectations, prior_clarifications = [], user_context = '', about_company = '', } = input;
     if (!document?.trim()) {
         throw new SpmApiError('Document text is required', 'INVALID_INPUT');
     }
@@ -51,6 +51,8 @@ export async function handleEvaluate(input, apiKey) {
         all_sub_expectations: parsedSubExps,
         requirement_document: document,
         prior_clarifications: formattedClarifications,
+        user_context,
+        about_company,
         nano_app_id,
     };
     const result = await callEndpoint('extensionGapEvaluatorV3', payload, apiKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spm-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Super Product Manager MCP Server - AI-powered product document analysis for PRDs, roadmaps, and 30 PM document types",
   "author": "Super Product Manager <chiranjeevi.gunturi@superproductmanager.ai>",
   "homepage": "https://superproductmanager.ai",

package/src/client/cloud-functions.ts

@@ -5,6 +5,10 @@
 
 import { config } from '../config.js';
 
+// Channel identifier — overridden by hosted/cloud-run.ts
+let _channel = 'mcp-npm';
+export function setChannel(ch: string) { _channel = ch; }
+
 export async function callJsonEndpoint(
   endpoint: string,
   body: Record<string, unknown> = {},
@@ -14,6 +18,7 @@ export async function callJsonEndpoint(
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'Origin': 'https://mcp.superproductmanager.ai',
+    'X-SPM-Channel': _channel,
   };
   if (apiKey) {
     headers['X-SPM-API-Key'] = apiKey;

package/src/client/spm-api.ts

@@ -19,12 +19,17 @@ const ENDPOINTS = {
 
 type EndpointName = keyof typeof ENDPOINTS;
 
+// Channel identifier — shared with cloud-functions.ts
+let _channel = 'mcp-npm';
+export function setChannel(ch: string) { _channel = ch; }
+
 function getHeaders(apiKey?: string): Record<string, string> {
   const key = apiKey || config.apiKey;
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'Accept': 'text/event-stream, application/json',
     'Origin': 'https://mcp.superproductmanager.ai',
+    'X-SPM-Channel': _channel,
   };
   if (key) {
     headers['X-SPM-API-Key'] = key;

package/src/index.ts

@@ -55,7 +55,9 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     'Analyze a product document against SPM expert expectations. ' +
       'Pass a document and a nano_app_id (e.g., "prd_critique", "user_story", "growth_strategy") ' +
       'to get an expert analysis with expectations, sub-expectations, scores, and evidence. ' +
-      'Call spm_list_nano_apps first if you need to discover available templates.',
+      'Call spm_list_nano_apps first if you need to discover available templates. ' +
+      'IMPORTANT: Present results as a clear scorecard table (Expectation | Score | Verdict). ' +
+      'Highlight critical gaps (score < 50%) and suggest running spm_clarify on the weakest gap next.',
     {
       document: z.string().describe('The product document text to analyze'),
       nano_app_id: z.string().describe(
@@ -79,7 +81,12 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     'spm_clarify',
     'Get clarification questions for gaps identified in an SPM analysis. ' +
       'Pass the original document, the expert analysis context, and a target gap. ' +
-      'Returns targeted questions with suggested answers to close document gaps.',
+      'Returns targeted questions with suggested answers to close document gaps. ' +
+      'IMPORTANT: When presenting results to the user, minimize cognitive load. ' +
+      'Show the question prominently, then present each answer option as a clear ' +
+      'numbered choice the user can pick (1, 2, 3...). Mark the [recommended] option. ' +
+      'If you have native interactive UI (buttons, selectable options, AskUserQuestion), use it. ' +
+      'The user should be able to pick an option or type their own answer with minimal effort.',
     {
       document: z.string().describe('The original product document text'),
       nano_app_id: z.string().describe('The nano app template key used in the analysis'),
@@ -96,6 +103,12 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
       })).optional().describe(
         'Array of previous Q&A pairs from this clarification session. Empty for first question.',
       ),
+      user_context: z.string().optional().describe(
+        'Context about the PM: role, experience level, company stage, research done, decisions made. Helps generate tailored questions.',
+      ),
+      about_company: z.string().optional().describe(
+        'Context about the company/product: stage, team size, market, existing users, business model.',
+      ),
     },
     async (input) => {
       try {
@@ -129,6 +142,12 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
       })).describe(
         'All Q&A pairs accumulated from spm_clarify rounds. The evaluator uses these as evidence.',
       ),
+      user_context: z.string().optional().describe(
+        'Context about the PM: role, experience level, company stage, research done, decisions made.',
+      ),
+      about_company: z.string().optional().describe(
+        'Context about the company/product: stage, team size, market, existing users, business model.',
+      ),
     },
     async (input) => {
       try {
@@ -148,7 +167,9 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     'Generate improved document content for a specific gap. ' +
       'Pass the document, the target sub-expectation, and all clarification Q&A pairs. ' +
       'Returns paste-ready content the PM can insert into their document. ' +
-      'Use after spm_evaluate confirms the gap is sufficiently covered by clarification answers.',
+      'Use after spm_evaluate confirms the gap is sufficiently covered by clarification answers. ' +
+      'IMPORTANT: Present the generated content in clean markdown the user can copy-paste directly. ' +
+      'If there are [ACTION NEEDED] markers, highlight them so the user knows what to fill in.',
     {
       document: z.string().describe('The original product document text'),
       nano_app_id: z.string().describe('The nano app template key used in the analysis'),

package/src/tools/clarify.ts

@@ -58,6 +58,19 @@ export const clarifyDefinition = {
           'Array of previous Q&A pairs from this clarification session. ' +
           'Pass as [{question, answer}, ...]. Empty array for first question.',
       },
+      user_context: {
+        type: 'string',
+        description:
+          'Context about the PM: their role, experience level, company stage, ' +
+          'what research they have done, what decisions they have already made. ' +
+          'This helps generate questions tailored to the specific user rather than generic ones.',
+      },
+      about_company: {
+        type: 'string',
+        description:
+          'Context about the company/product: stage, team size, market, ' +
+          'existing users, business model. Helps ground questions in reality.',
+      },
     },
     required: ['document', 'nano_app_id', 'main_expectation', 'all_sub_expectations', 'target_sub_expectation'],
   },
@@ -70,6 +83,8 @@ export interface ClarifyInput {
   all_sub_expectations: string;
   target_sub_expectation: string;
   previous_answers?: Array<{ question: string; answer: string }>;
+  user_context?: string;
+  about_company?: string;
 }
 
 export async function handleClarify(input: ClarifyInput, apiKey?: string): Promise<unknown> {
@@ -80,6 +95,8 @@ export async function handleClarify(input: ClarifyInput, apiKey?: string): Promi
     all_sub_expectations,
     target_sub_expectation,
     previous_answers = [],
+    user_context = '',
+    about_company = '',
   } = input;
 
   if (!document?.trim()) {
@@ -117,6 +134,8 @@ export async function handleClarify(input: ClarifyInput, apiKey?: string): Promi
     recent_recommendation: '',
     latest_review: '',
     gap_coverage: '',
+    user_context,
+    about_company,
     nano_app_id,
   };
 

package/src/tools/evaluate.ts

@@ -17,6 +17,8 @@ export interface EvaluateInput {
   main_expectation: string;
   all_sub_expectations: string;
   prior_clarifications: Array<{ question: string; answer: string }>;
+  user_context?: string;
+  about_company?: string;
 }
 
 export async function handleEvaluate(input: EvaluateInput, apiKey?: string): Promise<unknown> {
@@ -26,6 +28,8 @@ export async function handleEvaluate(input: EvaluateInput, apiKey?: string): Pro
     main_expectation,
     all_sub_expectations,
     prior_clarifications = [],
+    user_context = '',
+    about_company = '',
   } = input;
 
   if (!document?.trim()) {
@@ -71,6 +75,8 @@ export async function handleEvaluate(input: EvaluateInput, apiKey?: string): Pro
     all_sub_expectations: parsedSubExps,
     requirement_document: document,
     prior_clarifications: formattedClarifications,
+    user_context,
+    about_company,
     nano_app_id,
   };