spm-mcp 0.3.1 → 0.4.0

package/README.md

@@ -21,7 +21,7 @@ Not just PRDs. Every document in the PM lifecycle:
 - **Execution:** User Stories, Feature Spec, Sprint Planning, PRD to Jira, Release Notes, Test Cases
 - **Discovery:** Problem Statement, Persona, Jobs-to-be-Done, Opportunity Assessment
 
-30 built-in expert reviews. Or create your own with `spm_create_custom_nano_app`.
+30 built-in expert reviews. Or bring your own template with `spm_create_custom_nano_app` -- paste your favorite PRD or describe your sections, and SPM creates a personalized review in seconds.
 
 ## Quick start
 
@@ -60,12 +60,12 @@ For claude.ai web users, SPM is available as a remote MCP server:
 
 | Tool | What it does |
 |------|-------------|
-| `spm_list_nano_apps` | Discover available expert reviews (30 built-in + your custom ones) |
-| `spm_analyze` | Score a document against domain-specific expert expectations. Every gap scored 0-1.0 with evidence. |
-| `spm_clarify` | Get decision-forcing questions for the weakest gaps. Questions escalate when you give vague answers. |
+| `spm_create_custom_nano_app` | **Start here.** Paste your favorite PRD, describe your template sections, or pass evaluation criteria. Creates a personalized review that uses your terminology and covers your sections. |
+| `spm_list_nano_apps` | Browse 30 built-in expert reviews if you don't have your own template. |
+| `spm_analyze` | Score a document against expert expectations. Every gap scored 0-1.0 with evidence. |
+| `spm_clarify` | Decision-forcing questions for the weakest gaps. Questions escalate when you give vague answers. |
 | `spm_evaluate` | Re-score gaps after clarification rounds. Tracks progress. Use after every 3 rounds of `spm_clarify`. |
 | `spm_improve` | Generate paste-ready improvements grounded in your answers, not AI hallucination. |
-| `spm_create_custom_nano_app` | Create a custom expert review for any document type not covered by the built-in 30. |
 
 ## How it works
 
@@ -79,7 +79,24 @@ Your document
 
 The clarification questions are the product. They surface the assumptions you've been carrying without examining. When you dodge, they escalate: evidence first, then action directives, then assumptions made on your behalf. Like a principal PM review, not a chatbot.
 
-## Example workflow
+## Example: Bring your own template
+
+```
+You:    Here's my team's PRD template [pastes PRD]
+SPM:    Detected 9 sections. Created "PRD Review" with 5 expectations:
+
+        Expectation                  | Rules                          | Checks
+        Problem & Goal               | Problem, Goal                  | Data-backed problem, measurable goal
+        Users & Solution             | Target Users, Proposed Solution| Specific personas, buildable solution
+        Metrics & Timeline           | Success Metrics, Timeline      | Baselines, phased delivery
+        Technical & Risks            | Technical Approach, Risks      | Dependencies, mitigations
+        Out of Scope                 | Out of Scope                   | Explicit boundary list
+
+You:    Looks good. Analyze this PRD.
+SPM:    [scores against YOUR expectations, not generic ones]
+```
+
+## Example: Built-in review
 
 ```
 You:    Analyze this PRD with prd_critique

package/dist/src/index.js

@@ -19,18 +19,41 @@ import { handleClarify } from './tools/clarify.js';
 import { handleEvaluate } from './tools/evaluate.js';
 import { handleImprove } from './tools/improve.js';
 import { handleCreateCustomNanoApp } from './tools/create-custom-nano-app.js';
+import { handleWorkspace } from './tools/workspace.js';
 import { SpmApiError } from './client/spm-api.js';
+function logToolCall(tool, input) {
+    const summary = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (typeof v === 'string' && v.length > 100) {
+            summary[k] = `[${v.length} chars]`;
+        }
+        else if (Array.isArray(v)) {
+            summary[k] = `[${v.length} items]`;
+        }
+        else {
+            summary[k] = v ?? '(empty)';
+        }
+    }
+    console.log(`[MCP] ${tool}:`, JSON.stringify(summary));
+}
 export function createSpmMcpServer(options) {
     const server = new McpServer({
         name: 'Super Product Manager',
-        version: '0.1.0',
+        version: '0.3.1',
     });
     const apiKey = options?.apiKey;
     // Tool: spm_list_nano_apps
-    server.tool('spm_list_nano_apps', 'List all available SPM nano app templates for product document analysis. ' +
+    server.tool('spm_list_nano_apps', 'List available SPM nano app templates. ' +
+        'IMPORTANT: Do NOT call this as your first action. Instead:\n' +
+        '1. Ask the user what document or task they are working on.\n' +
+        '2. Check if they have an existing template, PRD, or evaluation criteria ' +
+        '(look in workspace files, Claude project instructions, or ask).\n' +
+        '3. If they have their own template or a favorite PRD, use spm_create_custom_nano_app instead.\n' +
+        '4. Only call this tool if the user explicitly wants to browse available templates.\n' +
         'Returns template keys, names, descriptions, and categories. ' +
-        'Use this to discover which analysis types are available before calling spm_analyze.', {}, async () => {
+        'DISPLAY: Show the top 5-6 most popular first. Only show the full list if the user asks for it.', {}, async () => {
         try {
+            logToolCall('spm_list_nano_apps', {});
             const result = await handleListNanoApps(apiKey);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -51,6 +74,7 @@ export function createSpmMcpServer(options) {
         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) => {
         try {
+            logToolCall('spm_analyze', input);
             const result = await handleAnalyze(input, apiKey);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -82,6 +106,7 @@ export function createSpmMcpServer(options) {
         about_company: z.string().optional().describe('Context about the company/product: stage, team size, market, existing users, business model.'),
     }, async (input) => {
         try {
+            logToolCall('spm_clarify', input);
             const result = await handleClarify(input, apiKey);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -108,6 +133,7 @@ export function createSpmMcpServer(options) {
         about_company: z.string().optional().describe('Context about the company/product: stage, team size, market, existing users, business model.'),
     }, async (input) => {
         try {
+            logToolCall('spm_evaluate', input);
             const result = await handleEvaluate(input, apiKey);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -136,6 +162,7 @@ export function createSpmMcpServer(options) {
         current_content: z.string().optional().describe('The current generated content (live_artifact) to improve upon. Empty for first generation.'),
     }, async (input) => {
         try {
+            logToolCall('spm_improve', input);
             const result = await handleImprove(input, apiKey);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -146,18 +173,31 @@ export function createSpmMcpServer(options) {
         }
     });
     // Tool: spm_create_custom_nano_app
-    server.tool('spm_create_custom_nano_app', 'Create a custom nano app when the user\'s document doesn\'t match any existing nano app ' +
-        '(call spm_list_nano_apps first to check).\n\n' +
-        'BEFORE calling this tool, gather preferences from the user:\n' +
-        '1. WHAT TO EVALUATE → expectations + rules\n' +
-        '2. DOMAIN LENS → domainContext\n' +
-        '3. GOOD vs BAD SIGNALS → reviewer examples\n' +
-        '4. CLARIFICATION STYLE → clarification examples + instructions\n' +
-        '5. IMPROVEMENT FORMAT → improviser instructions\n\n' +
-        'IMPORTANT: Do NOT run a rigid 5-question interview. Extract what you can from the user\'s ' +
-        'initial message. Only ask 1-2 clarifying questions for what\'s genuinely missing. ' +
-        'Bias toward ACTION over interrogation. The endpoint handles missing preferences gracefully.', {
-        description: z.string().describe('What kind of document this nano app analyzes and what it should evaluate'),
+    server.tool('spm_create_custom_nano_app', 'Create a personalized nano app from the user\'s own template, PRD, or evaluation criteria. ' +
+        'This is the PREFERRED path for new users who have their own standards.\n\n' +
+        'The endpoint accepts MULTIPLE input types — prepare the best input:\n\n' +
+        'BEST (structured description + preferences):\n' +
+        '  description: "Evaluate PRDs with 9 sections: Problem, Goal, Target Users, Solution, ' +
+        'Success Metrics, Timeline, Technical Approach, Risks, Out of Scope"\n' +
+        '  preferences: { domain_lens: "...", good_bad_signals: "..." }\n\n' +
+        'GOOD (raw PRD or document pasted as description):\n' +
+        '  description: <paste the user\'s actual PRD or template document here>\n' +
+        '  The endpoint will extract sections and create generic rules from the structure.\n\n' +
+        'OK (bare description):\n' +
+        '  description: "Evaluate product strategy for investment readiness"\n\n' +
+        'INPUT PREPARATION — How to build the best input:\n' +
+        '1. If the user has a template/PRD, read it and list its sections explicitly in the description ' +
+        '(e.g., "9 sections: Problem, Goal, Target Users..."). This produces the best results.\n' +
+        '2. Add preferences.domain_lens with who is reviewing and what matters.\n' +
+        '3. Add preferences.good_bad_signals with concrete examples of quality.\n' +
+        '4. If the user provides explicit evaluation criteria or rules, pass them in the description — ' +
+        'the endpoint will use them as-is, not reinterpret.\n\n' +
+        'DISPLAY: After creation, show a table: Expectation | Rules | What it checks. ' +
+        'Ask the user to confirm before proceeding to spm_analyze. Do NOT show the scoring rubric — ' +
+        'users see it in action when they analyze a document.', {
+        description: z.string().describe('BEST: List sections explicitly ("Evaluate PRDs with 9 sections: Problem, Goal, ..."). ' +
+            'ALSO WORKS: Paste a raw PRD/template document — sections will be auto-extracted. ' +
+            'ALSO WORKS: Short description ("Evaluate product strategy for investment readiness").'),
         name: z.string().optional().describe('Human-readable name for the nano app (auto-generated if omitted)'),
         preferences: z.object({
             domain_lens: z.string().optional().describe('Domain context and expertise lens'),
@@ -167,6 +207,7 @@ export function createSpmMcpServer(options) {
         }).optional().describe('Optional preferences to customize the nano app behavior'),
     }, async (input) => {
         try {
+            logToolCall('spm_create_custom_nano_app', input);
             const result = await handleCreateCustomNanoApp(input, apiKey);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -176,6 +217,27 @@ export function createSpmMcpServer(options) {
             return errorResponse(err);
         }
     });
+    // Tool: spm_read_workspace
+    server.tool('spm_read_workspace', 'Read or write files from the user\'s local workspace to gather project context or record decisions. ' +
+        'Three modes: (1) "scan" — auto-discover known config files (CLAUDE.md, SKILL.md, README.md)\n' +
+        '(2) "read" — read a specific .md file by relative path\n' +
+        '(3) "write" — write content to a .md file by relative path (e.g., to record a system-of-record decision summary)\n' +
+        'All paths are restricted to the project directory for security, and ONLY .md files are allowed.', {
+        mode: z.enum(['scan', 'read', 'write']).describe('"scan" to discover files, "read" to get contents, "write" to save contents'),
+        path: z.string().optional().describe('Relative path to the file (required when mode is "read" or "write"). Must be a .md file.'),
+        content: z.string().optional().describe('The markdown content to write to the file (required when mode is "write").'),
+    }, async (input) => {
+        try {
+            logToolCall('spm_read_workspace', input);
+            const result = await handleWorkspace(input);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
     return server;
 }
 function errorResponse(err) {

package/dist/src/stdio.js

@@ -94,13 +94,12 @@ if (wantsSetup || (isInteractive() && !hasApiKey())) {
     const ok = await runSetup();
     process.exit(ok ? 0 : 1);
 }
-else if (!hasApiKey() && isInteractive()) {
-    // No key and interactive — guide the user
-    process.stderr.write('\n  No SPM_API_KEY found. Run: npx spm-mcp --setup\n\n');
-    process.exit(1);
-}
 else {
     // MCP server mode (non-interactive, started by AI tool)
+    if (!hasApiKey()) {
+        process.stderr.write('[spm-mcp] Warning: No API key found. Tool calls will fail with 401.\n' +
+            '  Fix: run "npx spm-mcp --setup" or set SPM_API_KEY env var.\n');
+    }
     const server = createSpmMcpServer({ apiKey: config.apiKey });
     const transport = new StdioServerTransport();
     await server.connect(transport);

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

@@ -0,0 +1,18 @@
+/**
+ * spm_read_workspace — Local workspace file reader.
+ *
+ * Reads files from the user's workspace (cwd) to provide project context.
+ * Two modes:
+ *   - scan:  auto-discover known config/doc files and return a manifest
+ *   - read:  read a specific file by relative path
+ *
+ * Security:
+ *   - All paths resolved and validated to stay within cwd
+ *   - Only .md files are allowed (no .env, .json, source code, etc.)
+ */
+export interface WorkspaceInput {
+    mode: 'scan' | 'read' | 'write';
+    path?: string;
+    content?: string;
+}
+export declare function handleWorkspace(input: WorkspaceInput): Promise<unknown>;

package/dist/src/tools/workspace.js

@@ -0,0 +1,172 @@
+/**
+ * spm_read_workspace — Local workspace file reader.
+ *
+ * Reads files from the user's workspace (cwd) to provide project context.
+ * Two modes:
+ *   - scan:  auto-discover known config/doc files and return a manifest
+ *   - read:  read a specific file by relative path
+ *
+ * Security:
+ *   - All paths resolved and validated to stay within cwd
+ *   - Only .md files are allowed (no .env, .json, source code, etc.)
+ */
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, relative, join, extname, dirname } from 'path';
+const log = (msg) => process.stderr.write(`[spm-mcp:workspace] ${msg}\n`);
+/** Only markdown files are allowed */
+const ALLOWED_EXTENSIONS = ['.md'];
+/** Files to auto-discover in scan mode */
+const KNOWN_FILES = [
+    'CLAUDE.md',
+    'claude.md',
+    'README.md',
+    '.github/copilot-instructions.md',
+];
+/** Directories to scan for skill files */
+const SKILL_DIRS = [
+    '.claude/skills',
+    '.gemini/skills',
+];
+/** Max file size to read (100 KB) — skip huge files */
+const MAX_FILE_SIZE = 100 * 1024;
+// ─── Security ───────────────────────────────────────────────────────
+function safePath(relativePath) {
+    const cwd = process.cwd();
+    const resolved = resolve(cwd, relativePath);
+    const rel = relative(cwd, resolved);
+    if (rel.startsWith('..') || rel === resolved) {
+        log(`BLOCKED path traversal: ${relativePath}`);
+        return null;
+    }
+    return resolved;
+}
+function scanWorkspace() {
+    const cwd = process.cwd();
+    const found = [];
+    // Check known files
+    for (const file of KNOWN_FILES) {
+        const full = join(cwd, file);
+        if (existsSync(full)) {
+            const stat = statSync(full);
+            if (stat.isFile()) {
+                found.push({ path: file, size: stat.size, type: 'config' });
+            }
+        }
+    }
+    // Scan skill directories for SKILL.md files
+    for (const dir of SKILL_DIRS) {
+        const fullDir = join(cwd, dir);
+        if (existsSync(fullDir) && statSync(fullDir).isDirectory()) {
+            try {
+                const entries = readdirSync(fullDir);
+                for (const entry of entries) {
+                    const skillPath = join(fullDir, entry, 'SKILL.md');
+                    if (existsSync(skillPath)) {
+                        const stat = statSync(skillPath);
+                        found.push({
+                            path: join(dir, entry, 'SKILL.md'),
+                            size: stat.size,
+                            type: 'skill',
+                        });
+                    }
+                }
+            }
+            catch {
+                log(`Could not scan skill dir: ${dir}`);
+            }
+        }
+    }
+    log(`Scan complete: found ${found.length} files`);
+    return found;
+}
+function readWorkspaceFile(relativePath) {
+    // Only allow .md files
+    const ext = extname(relativePath).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.includes(ext)) {
+        log(`BLOCKED non-markdown file: ${relativePath}`);
+        throw new Error(`Only .md files are allowed. Got: "${relativePath}"`);
+    }
+    const fullPath = safePath(relativePath);
+    if (!fullPath) {
+        throw new Error(`Path not allowed: "${relativePath}" — must be within project directory`);
+    }
+    if (!existsSync(fullPath)) {
+        throw new Error(`File not found: "${relativePath}"`);
+    }
+    const stat = statSync(fullPath);
+    if (!stat.isFile()) {
+        throw new Error(`Not a file: "${relativePath}"`);
+    }
+    let content;
+    let truncated = false;
+    if (stat.size > MAX_FILE_SIZE) {
+        content = readFileSync(fullPath, 'utf-8').slice(0, MAX_FILE_SIZE);
+        truncated = true;
+        log(`Read ${relativePath} (${stat.size} bytes, truncated to ${MAX_FILE_SIZE})`);
+    }
+    else {
+        content = readFileSync(fullPath, 'utf-8');
+        log(`Read ${relativePath} (${stat.size} bytes)`);
+    }
+    return {
+        path: relativePath,
+        content,
+        size: stat.size,
+        truncated,
+    };
+}
+function writeWorkspaceFile(relativePath, content) {
+    // Only allow .md files
+    const ext = extname(relativePath).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.includes(ext)) {
+        log(`BLOCKED write to non-markdown file: ${relativePath}`);
+        throw new Error(`Only .md files are allowed to be written. Got: "${relativePath}"`);
+    }
+    const fullPath = safePath(relativePath);
+    if (!fullPath) {
+        throw new Error(`Path not allowed: "${relativePath}" — must be within project directory`);
+    }
+    // Ensure parent directory exists
+    const dir = dirname(fullPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // We allow creating new files or overwriting existing ones.
+    // In a production scenario, you might want to differentiate or append.
+    writeFileSync(fullPath, content, 'utf-8');
+    log(`Wrote ${relativePath} (${Buffer.byteLength(content, 'utf-8')} bytes)`);
+    return {
+        path: relativePath,
+        size: Buffer.byteLength(content, 'utf-8'),
+        message: `Successfully wrote to ${relativePath}`,
+    };
+}
+export async function handleWorkspace(input) {
+    if (input.mode === 'scan') {
+        const files = scanWorkspace();
+        return {
+            workspace: process.cwd(),
+            files,
+            hint: 'Use mode "read" with a path from this list to get file contents.',
+        };
+    }
+    if (input.mode === 'read') {
+        if (!input.path) {
+            throw new Error('path is required when mode is "read"');
+        }
+        const result = readWorkspaceFile(input.path);
+        return result;
+    }
+    if (input.mode === 'write') {
+        if (!input.path) {
+            throw new Error('path is required when mode is "write"');
+        }
+        if (input.content === undefined) {
+            throw new Error('content is required when mode is "write"');
+        }
+        const result = writeWorkspaceFile(input.path, input.content);
+        return result;
+    }
+    throw new Error(`Unknown mode: "${input.mode}". Use "scan", "read", or "write".`);
+}
+//# sourceMappingURL=workspace.js.map

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "spm-mcp",
-  "version": "0.3.1",
-  "description": "Super Product Manager MCP Server - AI-powered product document analysis for PRDs, roadmaps, and 30 PM document types",
+  "version": "0.4.0",
+  "description": "Super Product Manager MCP Server - AI-powered product document analysis. Bring your own template or use 30 built-in expert reviews for PRDs, roadmaps, and PM documents.",
   "author": "Super Product Manager <chiranjeevi.gunturi@superproductmanager.ai>",
   "homepage": "https://superproductmanager.ai",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/src/index.js",
   "bin": {
     "spm-mcp": "dist/src/stdio.js"
   },

package/src/index.ts

@@ -20,12 +20,27 @@ import { handleClarify } from './tools/clarify.js';
 import { handleEvaluate } from './tools/evaluate.js';
 import { handleImprove } from './tools/improve.js';
 import { handleCreateCustomNanoApp } from './tools/create-custom-nano-app.js';
+import { handleWorkspace } from './tools/workspace.js';
 import { SpmApiError } from './client/spm-api.js';
 
+function logToolCall(tool: string, input: Record<string, unknown>) {
+  const summary: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (typeof v === 'string' && v.length > 100) {
+      summary[k] = `[${v.length} chars]`;
+    } else if (Array.isArray(v)) {
+      summary[k] = `[${v.length} items]`;
+    } else {
+      summary[k] = v ?? '(empty)';
+    }
+  }
+  console.log(`[MCP] ${tool}:`, JSON.stringify(summary));
+}
+
 export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   const server = new McpServer({
     name: 'Super Product Manager',
-    version: '0.1.0',
+    version: '0.3.1',
   });
 
   const apiKey = options?.apiKey;
@@ -33,12 +48,19 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   // Tool: spm_list_nano_apps
   server.tool(
     'spm_list_nano_apps',
-    'List all available SPM nano app templates for product document analysis. ' +
-      'Returns template keys, names, descriptions, and categories. ' +
-      'Use this to discover which analysis types are available before calling spm_analyze.',
+    'List available SPM nano app templates. ' +
+    'IMPORTANT: Do NOT call this as your first action. Instead:\n' +
+    '1. Ask the user what document or task they are working on.\n' +
+    '2. Check if they have an existing template, PRD, or evaluation criteria ' +
+    '(look in workspace files, Claude project instructions, or ask).\n' +
+    '3. If they have their own template or a favorite PRD, use spm_create_custom_nano_app instead.\n' +
+    '4. Only call this tool if the user explicitly wants to browse available templates.\n' +
+    'Returns template keys, names, descriptions, and categories. ' +
+    'DISPLAY: Show the top 5-6 most popular first. Only show the full list if the user asks for it.',
     {},
     async () => {
       try {
+        logToolCall('spm_list_nano_apps', {});
         const result = await handleListNanoApps(apiKey);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -53,11 +75,11 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   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. ' +
-      '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.',
+    '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. ' +
+    '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(
@@ -66,6 +88,7 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     },
     async (input) => {
       try {
+        logToolCall('spm_analyze', input);
         const result = await handleAnalyze(input, apiKey);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -80,13 +103,13 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   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. ' +
-      '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.',
+    'Pass the original document, the expert analysis context, and a target gap. ' +
+    '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'),
@@ -112,6 +135,7 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     },
     async (input) => {
       try {
+        logToolCall('spm_clarify', input);
         const result = await handleClarify(input, apiKey);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -126,9 +150,9 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   server.tool(
     'spm_evaluate',
     'Re-score sub-expectations after clarification rounds. ' +
-      'Pass the original document, the expectations from spm_analyze, and all Q&A pairs from spm_clarify. ' +
-      'Returns updated scores showing which gaps are now covered (>=0.81) and which still need work. ' +
-      'Use after every 3 rounds of spm_clarify to measure progress.',
+    'Pass the original document, the expectations from spm_analyze, and all Q&A pairs from spm_clarify. ' +
+    'Returns updated scores showing which gaps are now covered (>=0.81) and which still need work. ' +
+    'Use after every 3 rounds of spm_clarify to measure progress.',
     {
       document: z.string().describe('The original product document text'),
       nano_app_id: z.string().describe('The nano app template key used in the analysis'),
@@ -151,6 +175,7 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     },
     async (input) => {
       try {
+        logToolCall('spm_evaluate', input);
         const result = await handleEvaluate(input, apiKey);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -165,11 +190,11 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   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. ' +
-      '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.',
+    '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. ' +
+    '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'),
@@ -190,6 +215,7 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     },
     async (input) => {
       try {
+        logToolCall('spm_improve', input);
         const result = await handleImprove(input, apiKey);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -203,20 +229,33 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
   // Tool: spm_create_custom_nano_app
   server.tool(
     'spm_create_custom_nano_app',
-    'Create a custom nano app when the user\'s document doesn\'t match any existing nano app ' +
-      '(call spm_list_nano_apps first to check).\n\n' +
-      'BEFORE calling this tool, gather preferences from the user:\n' +
-      '1. WHAT TO EVALUATE → expectations + rules\n' +
-      '2. DOMAIN LENS → domainContext\n' +
-      '3. GOOD vs BAD SIGNALS → reviewer examples\n' +
-      '4. CLARIFICATION STYLE → clarification examples + instructions\n' +
-      '5. IMPROVEMENT FORMAT → improviser instructions\n\n' +
-      'IMPORTANT: Do NOT run a rigid 5-question interview. Extract what you can from the user\'s ' +
-      'initial message. Only ask 1-2 clarifying questions for what\'s genuinely missing. ' +
-      'Bias toward ACTION over interrogation. The endpoint handles missing preferences gracefully.',
+    'Create a personalized nano app from the user\'s own template, PRD, or evaluation criteria. ' +
+    'This is the PREFERRED path for new users who have their own standards.\n\n' +
+    'The endpoint accepts MULTIPLE input types — prepare the best input:\n\n' +
+    'BEST (structured description + preferences):\n' +
+    '  description: "Evaluate PRDs with 9 sections: Problem, Goal, Target Users, Solution, ' +
+    'Success Metrics, Timeline, Technical Approach, Risks, Out of Scope"\n' +
+    '  preferences: { domain_lens: "...", good_bad_signals: "..." }\n\n' +
+    'GOOD (raw PRD or document pasted as description):\n' +
+    '  description: <paste the user\'s actual PRD or template document here>\n' +
+    '  The endpoint will extract sections and create generic rules from the structure.\n\n' +
+    'OK (bare description):\n' +
+    '  description: "Evaluate product strategy for investment readiness"\n\n' +
+    'INPUT PREPARATION — How to build the best input:\n' +
+    '1. If the user has a template/PRD, read it and list its sections explicitly in the description ' +
+    '(e.g., "9 sections: Problem, Goal, Target Users..."). This produces the best results.\n' +
+    '2. Add preferences.domain_lens with who is reviewing and what matters.\n' +
+    '3. Add preferences.good_bad_signals with concrete examples of quality.\n' +
+    '4. If the user provides explicit evaluation criteria or rules, pass them in the description — ' +
+    'the endpoint will use them as-is, not reinterpret.\n\n' +
+    'DISPLAY: After creation, show a table: Expectation | Rules | What it checks. ' +
+    'Ask the user to confirm before proceeding to spm_analyze. Do NOT show the scoring rubric — ' +
+    'users see it in action when they analyze a document.',
     {
       description: z.string().describe(
-        'What kind of document this nano app analyzes and what it should evaluate',
+        'BEST: List sections explicitly ("Evaluate PRDs with 9 sections: Problem, Goal, ..."). ' +
+        'ALSO WORKS: Paste a raw PRD/template document — sections will be auto-extracted. ' +
+        'ALSO WORKS: Short description ("Evaluate product strategy for investment readiness").',
       ),
       name: z.string().optional().describe(
         'Human-readable name for the nano app (auto-generated if omitted)',
@@ -230,6 +269,7 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     },
     async (input) => {
       try {
+        logToolCall('spm_create_custom_nano_app', input);
         const result = await handleCreateCustomNanoApp(input, apiKey);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -240,6 +280,38 @@ export function createSpmMcpServer(options?: { apiKey?: string }): McpServer {
     },
   );
 
+  // Tool: spm_read_workspace
+  server.tool(
+    'spm_read_workspace',
+    'Read or write files from the user\'s local workspace to gather project context or record decisions. ' +
+    'Three modes: (1) "scan" — auto-discover known config files (CLAUDE.md, SKILL.md, README.md)\n' +
+    '(2) "read" — read a specific .md file by relative path\n' +
+    '(3) "write" — write content to a .md file by relative path (e.g., to record a system-of-record decision summary)\n' +
+    'All paths are restricted to the project directory for security, and ONLY .md files are allowed.',
+    {
+      mode: z.enum(['scan', 'read', 'write']).describe(
+        '"scan" to discover files, "read" to get contents, "write" to save contents',
+      ),
+      path: z.string().optional().describe(
+        'Relative path to the file (required when mode is "read" or "write"). Must be a .md file.',
+      ),
+      content: z.string().optional().describe(
+        'The markdown content to write to the file (required when mode is "write").',
+      ),
+    },
+    async (input) => {
+      try {
+        logToolCall('spm_read_workspace', input);
+        const result = await handleWorkspace(input);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return errorResponse(err);
+      }
+    },
+  );
+
   return server;
 }
 

package/src/stdio.ts

@@ -107,12 +107,14 @@ if (wantsSetup || (isInteractive() && !hasApiKey())) {
   // Interactive setup mode
   const ok = await runSetup();
   process.exit(ok ? 0 : 1);
-} else if (!hasApiKey() && isInteractive()) {
-  // No key and interactive — guide the user
-  process.stderr.write('\n  No SPM_API_KEY found. Run: npx spm-mcp --setup\n\n');
-  process.exit(1);
 } else {
   // MCP server mode (non-interactive, started by AI tool)
+  if (!hasApiKey()) {
+    process.stderr.write(
+      '[spm-mcp] Warning: No API key found. Tool calls will fail with 401.\n' +
+      '  Fix: run "npx spm-mcp --setup" or set SPM_API_KEY env var.\n'
+    );
+  }
   const server = createSpmMcpServer({ apiKey: config.apiKey });
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/tools/workspace.ts

@@ -0,0 +1,231 @@
+/**
+ * spm_read_workspace — Local workspace file reader.
+ *
+ * Reads files from the user's workspace (cwd) to provide project context.
+ * Two modes:
+ *   - scan:  auto-discover known config/doc files and return a manifest
+ *   - read:  read a specific file by relative path
+ *
+ * Security:
+ *   - All paths resolved and validated to stay within cwd
+ *   - Only .md files are allowed (no .env, .json, source code, etc.)
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, relative, join, basename, extname, dirname } from 'path';
+
+const log = (msg: string) => process.stderr.write(`[spm-mcp:workspace] ${msg}\n`);
+
+/** Only markdown files are allowed */
+const ALLOWED_EXTENSIONS = ['.md'];
+
+/** Files to auto-discover in scan mode */
+const KNOWN_FILES = [
+  'CLAUDE.md',
+  'claude.md',
+  'README.md',
+  '.github/copilot-instructions.md',
+];
+
+/** Directories to scan for skill files */
+const SKILL_DIRS = [
+  '.claude/skills',
+  '.gemini/skills',
+];
+
+/** Max file size to read (100 KB) — skip huge files */
+const MAX_FILE_SIZE = 100 * 1024;
+
+// ─── Security ───────────────────────────────────────────────────────
+
+function safePath(relativePath: string): string | null {
+  const cwd = process.cwd();
+  const resolved = resolve(cwd, relativePath);
+  const rel = relative(cwd, resolved);
+  if (rel.startsWith('..') || rel === resolved) {
+    log(`BLOCKED path traversal: ${relativePath}`);
+    return null;
+  }
+  return resolved;
+}
+
+// ─── Scan Mode ──────────────────────────────────────────────────────
+
+interface FileEntry {
+  path: string;
+  size: number;
+  type: 'config' | 'skill' | 'doc';
+}
+
+function scanWorkspace(): FileEntry[] {
+  const cwd = process.cwd();
+  const found: FileEntry[] = [];
+
+  // Check known files
+  for (const file of KNOWN_FILES) {
+    const full = join(cwd, file);
+    if (existsSync(full)) {
+      const stat = statSync(full);
+      if (stat.isFile()) {
+        found.push({ path: file, size: stat.size, type: 'config' });
+      }
+    }
+  }
+
+  // Scan skill directories for SKILL.md files
+  for (const dir of SKILL_DIRS) {
+    const fullDir = join(cwd, dir);
+    if (existsSync(fullDir) && statSync(fullDir).isDirectory()) {
+      try {
+        const entries = readdirSync(fullDir);
+        for (const entry of entries) {
+          const skillPath = join(fullDir, entry, 'SKILL.md');
+          if (existsSync(skillPath)) {
+            const stat = statSync(skillPath);
+            found.push({
+              path: join(dir, entry, 'SKILL.md'),
+              size: stat.size,
+              type: 'skill',
+            });
+          }
+        }
+      } catch {
+        log(`Could not scan skill dir: ${dir}`);
+      }
+    }
+  }
+
+  log(`Scan complete: found ${found.length} files`);
+  return found;
+}
+
+// ─── Read Mode ──────────────────────────────────────────────────────
+
+interface ReadResult {
+  path: string;
+  content: string;
+  size: number;
+  truncated: boolean;
+}
+
+function readWorkspaceFile(relativePath: string): ReadResult {
+  // Only allow .md files
+  const ext = extname(relativePath).toLowerCase();
+  if (!ALLOWED_EXTENSIONS.includes(ext)) {
+    log(`BLOCKED non-markdown file: ${relativePath}`);
+    throw new Error(`Only .md files are allowed. Got: "${relativePath}"`);
+  }
+
+  const fullPath = safePath(relativePath);
+  if (!fullPath) {
+    throw new Error(`Path not allowed: "${relativePath}" — must be within project directory`);
+  }
+
+  if (!existsSync(fullPath)) {
+    throw new Error(`File not found: "${relativePath}"`);
+  }
+
+  const stat = statSync(fullPath);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: "${relativePath}"`);
+  }
+
+  let content: string;
+  let truncated = false;
+
+  if (stat.size > MAX_FILE_SIZE) {
+    content = readFileSync(fullPath, 'utf-8').slice(0, MAX_FILE_SIZE);
+    truncated = true;
+    log(`Read ${relativePath} (${stat.size} bytes, truncated to ${MAX_FILE_SIZE})`);
+  } else {
+    content = readFileSync(fullPath, 'utf-8');
+    log(`Read ${relativePath} (${stat.size} bytes)`);
+  }
+
+  return {
+    path: relativePath,
+    content,
+    size: stat.size,
+    truncated,
+  };
+}
+
+// ─── Write Mode ─────────────────────────────────────────────────────
+
+interface WriteResult {
+  path: string;
+  size: number;
+  message: string;
+}
+
+function writeWorkspaceFile(relativePath: string, content: string): WriteResult {
+  // Only allow .md files
+  const ext = extname(relativePath).toLowerCase();
+  if (!ALLOWED_EXTENSIONS.includes(ext)) {
+    log(`BLOCKED write to non-markdown file: ${relativePath}`);
+    throw new Error(`Only .md files are allowed to be written. Got: "${relativePath}"`);
+  }
+
+  const fullPath = safePath(relativePath);
+  if (!fullPath) {
+    throw new Error(`Path not allowed: "${relativePath}" — must be within project directory`);
+  }
+
+  // Ensure parent directory exists
+  const dir = dirname(fullPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // We allow creating new files or overwriting existing ones.
+  // In a production scenario, you might want to differentiate or append.
+  writeFileSync(fullPath, content, 'utf-8');
+
+  log(`Wrote ${relativePath} (${Buffer.byteLength(content, 'utf-8')} bytes)`);
+
+  return {
+    path: relativePath,
+    size: Buffer.byteLength(content, 'utf-8'),
+    message: `Successfully wrote to ${relativePath}`,
+  };
+}
+
+// ─── Exported Handler ───────────────────────────────────────────────
+
+export interface WorkspaceInput {
+  mode: 'scan' | 'read' | 'write';
+  path?: string;
+  content?: string;
+}
+
+export async function handleWorkspace(input: WorkspaceInput): Promise<unknown> {
+  if (input.mode === 'scan') {
+    const files = scanWorkspace();
+    return {
+      workspace: process.cwd(),
+      files,
+      hint: 'Use mode "read" with a path from this list to get file contents.',
+    };
+  }
+
+  if (input.mode === 'read') {
+    if (!input.path) {
+      throw new Error('path is required when mode is "read"');
+    }
+    const result = readWorkspaceFile(input.path);
+    return result;
+  }
+
+  if (input.mode === 'write') {
+    if (!input.path) {
+      throw new Error('path is required when mode is "write"');
+    }
+    if (input.content === undefined) {
+      throw new Error('content is required when mode is "write"');
+    }
+    const result = writeWorkspaceFile(input.path, input.content);
+    return result;
+  }
+
+  throw new Error(`Unknown mode: "${input.mode}". Use "scan", "read", or "write".`);
+}

package/test-mcp-client.mjs

@@ -0,0 +1,44 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { unlinkSync } from "fs";
+
+async function run() {
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: ["./dist/src/stdio.js"]
+  });
+
+  const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+  await client.connect(transport);
+
+  console.log("Connected to MCP Server via stdio!");
+
+  try {
+    console.log("\nCalling spm_read_workspace (mode: write)...");
+    const result = await client.callTool({
+      name: "spm_read_workspace",
+      arguments: {
+        mode: "write",
+        path: "mcp_protocol_test.md",
+        content: "# Real MCP Test\n\nThis was written via the actual MCP JSON-RPC protocol!"
+      }
+    });
+    console.log("Tool Result:", JSON.stringify(result, null, 2));
+
+    // read it back
+    console.log("\nCalling spm_read_workspace (mode: read)...");
+    const readResult = await client.callTool({
+      name: "spm_read_workspace",
+      arguments: { mode: "read", path: "mcp_protocol_test.md" }
+    });
+    console.log("Read Result text:\n" + readResult.content[0].text);
+
+  } catch (err) {
+    console.error("Error:", err);
+  } finally {
+    try { unlinkSync('mcp_protocol_test.md'); } catch (e) { }
+    console.log("\nCleanup done. Test complete.");
+    process.exit(0);
+  }
+}
+run();