@nestpilot/mcp-app 1.0.0

package/README.md

@@ -0,0 +1,350 @@
+# NestPilot MCP App
+
+NestPilot retirement planning tools and interactive apps, distributed as an MCP server via the `@modelcontextprotocol/ext-apps` SDK. Runs in any MCP-compatible host (Claude Desktop, ChatGPT, GitHub Copilot, VS Code, MCPJam, basic-host).
+
+Migrated from `apps/chatgpt-app/` (Python FastApps / OpenAI Apps SDK).
+
+**Features**: FEAT-0052 (Medicare Guardian), FEAT-0001 (Plan Creation), FEAT-0002 (Forecast), FEAT-0003 (Scenarios), FEAT-0066 (Roth Conversion)
+
+## Tools
+
+### Planning Tools
+
+| Tool | Visibility | Backend Endpoint | Purpose |
+|------|-----------|------------------|---------|
+| `create_plan` | model | `POST /api/plan/calc` | Quick retirement projection (balance, withdrawal, readiness score) |
+| `run_forecast` | model | `POST /api/plan/forecast` | Comprehensive multi-account, multi-income forecast with yearly projections |
+| `run_scenario` | model | `POST /api/plan/scenario/run` | What-if scenario analysis with plan deltas, component overrides, stress tests |
+| `verify_forecast` | model | `POST /api/plan/forecast/verify` | Forecast verification with auditable calculation trace |
+| `coach` | model | `POST /api/spring_ai/coach` | AI-powered retirement coaching and concept explanations |
+
+### Roth Conversion Tools
+
+| Tool | Visibility | Backend Endpoint | Purpose |
+|------|-----------|------------------|---------|
+| `optimize_roth_conversion` | model | `POST /api/tax/roth/max-conversion` | Multi-year Roth conversion strategy with tax analysis, IRMAA warnings, RMD impact |
+
+**Note**: This tool is currently under development (FEAT-0066).
+
+### Medicare Tools
+
+| Tool | Visibility | Backend Endpoint | Purpose |
+|------|-----------|------------------|---------|
+| `medicare-guardian` | model + app | — (renders UI) | Launches the interactive Medicare Guardian UI |
+| `medicare-analyze` | app (internal) | `POST /api/medicare/guardian/analyze` | Proxies analysis to NestPilot backend API |
+| `email-subscribe` | app (internal) | `POST /api/medicare/subscribe` | Proxies email subscription to backend API |
+
+### Agent Runtime Tools
+
+| Tool | Visibility | Backend Endpoint | Purpose |
+|------|-----------|------------------|---------|
+| `nestpilot_list_skills` | model | `GET /skills` (agent-runtime) | Lists all available agent skills |
+| `nestpilot_run_skill` | model | `POST /sessions/:id/messages` | Runs a specific agent skill within a session |
+| `nestpilot_run_plan` | model | `POST /sessions/:id/messages` | Full retirement readiness assessment via retirement-readiness skill |
+
+### Interactive Views
+
+| View | Resource URI | Purpose |
+|------|-------------|---------|
+| `retirement-planner` | `ui://retirement-planner/planner-v2.html` | Interactive retirement planner with charts and scenario comparison |
+| `verification-packet` | `ui://verification-packet/verification-packet.html` | Verification packet display for forecast audit trails |
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+cp .env.example .env
+npm run serve:auth          # HTTP transport on port 3001 (auth enforced)
+# or
+npm run serve:auth:stdio    # stdio transport for Claude Desktop
+```
+
+## Testing the MCP Server
+
+### 1. Test with Custom Script
+
+```bash
+# Build the MCP app first
+npm run build
+
+# Start the MCP server (HTTP transport with auth)
+npm run serve:auth
+
+# In another terminal, run the test script
+node test-mcp-tools.mjs
+```
+
+The test script `test-mcp-tools.mjs` tests all major tools:
+- `optimize_roth_conversion` (Roth optimization)
+- `create_plan` (Quick projection)
+- `run_forecast` (Multi-account forecast)
+- `coach` (AI coaching)
+- `nestpilot_list_skills` (Agent skills)
+- `verify_forecast` (Verification)
+
+### 2.Test with GitHub Copilot (VS Code)
+
+Add to `.github/claude_desktop_config.json` or VS Code's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "nestpilot": {
+      "command": "npx",
+      "args": ["tsx", "C:\\git\\javapan\\nestpilot\\apps\\mcp-app\\main.ts", "--stdio"]
+    }
+  }
+}
+```
+
+Then in GitHub Copilot Chat:
+- "List available NestPilot tools"
+- "Create a retirement plan for someone who is 45, wants to retire at 65, has $300k saved"
+- "What's the 4% rule?" (tests coach tool)
+
+### 3. Test with basic-host
+
+```bash
+# Terminal 1: Run this server
+npm start
+
+# Terminal 2: Run basic-host from the ext-apps repo
+cd c:\git\ref\ext-apps\examples\basic-host
+npm install
+SERVERS='["http://localhost:3001/mcp"]' npm run start
+# Open http://localhost:8080
+```
+
+### 4. Test with Claude Desktop
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nestpilot": {
+      "command": "npx",
+      "args": ["tsx", "C:\\git\\javapan\\nestpilot\\apps\\mcp-app\\main.ts", "--stdio"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then test:
+- "What tools do you have from NestPilot?"
+- "Help me plan my retirement. I'm 40, have $250k saved, contributing $2k/month"
+
+### 5. Manual Testing with curl/PowerShell
+
+```powershell
+# List all tools
+$payload = @{
+    jsonrpc = "2.0"
+    id = "test1"
+    method = "tools/list"
+    params = @{}
+} | ConvertTo-Json
+
+Invoke-RestMethod -Uri "http://localhost:3001/mcp" `
+  -Method POST `
+  -ContentType "application/json" `
+  -Headers @{ Accept = "application/json, text/event-stream" } `
+  -Body $payload
+
+# Call create_plan tool
+$payload = @{
+    jsonrpc = "2.0"
+    id = "test2"
+    method = "tools/call"
+    params = @{
+        name = "create_plan"
+        arguments = @{
+            currentAge = 40
+            retireAge = 65
+            lifeExpectancy = 95
+            currentBalance = 250000
+            monthlyContribution = 2000
+            realReturnRate = 0.05
+            withdrawalRate = 0.04
+            targetAnnualSpending = 60000
+        }
+    }
+} | ConvertTo-Json -Depth 10
+
+Invoke-RestMethod -Uri "http://localhost:3001/mcp" `
+  -Method POST `
+  -ContentType "application/json" `
+  -Headers @{ Accept = "application/json, text/event-stream" } `
+  -Body $payload
+```
+
+## Testing in MCP Hosts
+
+### GitHub Copilot (Recommended for Development)
+
+1. **Setup**: Register the MCP server in VS Code settings or GitHub Copilot configuration
+2. **Verification**: Type `@nestpilot` in Copilot Chat to see available tools
+3. **Testing**: Use natural language queries that match tool descriptions
+4. **Debugging**: Check VS Code Output panel → "MCP" channel for errors
+
+### Claude Desktop
+
+1. **Setup**: Edit `claude_desktop_config.json` with server configuration
+2. **Verification**: Ask "What NestPilot tools are available?"
+3. **Testing**: Provide detailed retirement scenarios in conversation
+4. **Debugging**: Check Claude Desktop logs: `%APPDATA%\Claude\logs\`
+
+### MCPJam Inspector
+
+```bash
+npx @mcpjam/inspector@latest
+```
+
+1. Connect to `http://localhost:3001/mcp`
+2. Browse available tools in the inspector UI
+3. Test tools with custom JSON payloads
+4. View real-time request/response
+
+## Project Structure
+
+```
+apps/mcp-app/
+├── server.ts                     # MCP server orchestrator
+├── main.ts                       # Entry point: HTTP/stdio transport
+├── nestpilot-client.ts           # HTTP client for NestPilot backend API
+├── tools/
+│   ├── mcp-helpers.ts            # Shared: toCallToolResult(), proxyPostTool()
+│   ├── medicare-tools.ts         # Medicare tools (guardian, analyze, subscribe)
+│   ├── planning-tools.ts         # Planning tools (create_plan, run_forecast, run_scenario, verify_forecast, coach)
+│   ├── optimize-roth-tools.ts    # Roth conversion optimization (FEAT-0066) [IN DEVELOPMENT]
+│   └── agent-tools.ts            # Agent runtime tools (list_skills, run_skill, run_plan)
+├── mcp-app.html                  # Vite entry point for the Medicare Guardian view
+├── src/
+│   ├── planner/
+│   │   └── planner-app.tsx       # Retirement planner interactive view
+│   ├── mcp-app.tsx               # Medicare Guardian React app (useApp hook)
+│   ├── types.ts                  # Shared TypeScript types
+│   ├── styles.ts                 # CSS-in-JS styles with host variable fallbacks
+│   ├── global.css                # Global CSS with host variable fallbacks
+│   └── components/
+│       ├── TimelineChecker.tsx   # Input form for user data
+│       ├── ResultsPanel.tsx      # Results display (score, deadlines, penalties)
+│       ├── EmailCapture.tsx      # Email subscription form
+│       ├── CitationsDrawer.tsx   # Expandable citations section
+│       ├── SEPInterview.tsx      # Special Enrollment Period checker
+│       └── FunnelCTA.tsx         # Cross-sell to full NestPilot platform
+├── tests/
+│   ├── server.test.ts            # Server tool and client tests (vitest)
+│   └── contract-policy.test.ts   # Contract validation tests
+├── dist/                         # Build output (generated)
+│   ├── mcp-app.html              # Bundled Medicare Guardian single-file HTML
+│   ├── planner.html              # Bundled retirement planner single-file HTML
+│   └── views/
+│       └── verification-packet.html  # Bundled verification packet view
+├── test-mcp-tools.mjs             # Comprehensive MCP tools test script
+├── package.json
+├── vite.config.ts
+├── vite.planner.config.ts
+├── vite.verification.config.ts
+└──tsconfig.json
+```
+
+## Architecture
+
+```
+User in MCP Host (Claude / ChatGPT / GitHub Copilot / VS Code / MCPJam)
+    |
+    v
+MCP Protocol (stdio or HTTP)
+    |
+    v
+MCP Server (server.ts — orchestrator)
+    |
+    ├── tools/planning-tools.ts
+    │   ├── create_plan          --> POST /api/plan/calc
+    │   ├── run_forecast         --> POST /api/plan/forecast
+    │   ├── run_scenario         --> POST /api/plan/scenario/run
+    │   ├── verify_forecast      --> POST /api/plan/forecast/verify
+    │   └── coach                --> POST /api/spring_ai/coach
+    |
+    ├── tools/roth-tools.ts
+    │   └── optimize_roth_conversion  --> POST /api/tax/roth/max-conversion
+    |
+    ├── tools/medicare-tools.ts
+    │   ├── medicare-guardian         --> renders UI resource (mcp-app.html)
+    │   ├── medicare-analyze         --> POST /api/medicare/guardian/analyze
+    │   └── email-subscribe          --> POST /api/medicare/subscribe
+    |
+    ├── tools/agent-tools.ts
+    │   ├── nestpilot_list_skills    --> GET /skills (agent-runtime:3002)
+    │   ├── nestpilot_run_skill      --> POST /sessions/:id/messages
+    │   └── nestpilot_run_plan       --> POST /sessions/:id/messages
+    |
+    └── tools/mcp-helpers.ts
+        ├── toCallToolResult()   -- wraps payload into MCP CallToolResult
+        └── proxyPostTool()      -- POST to backend + error handling
+                                        |
+                                        v
+                                NestPilot Spring Boot API (port 8080)
+                                        |
+                                        v
+                                    PostgreSQL
+```
+
+Planning tools are thin facades — they validate input via Zod schemas and proxy to the Spring Boot API via `nestpilot-client.ts`. The Medicare Guardian view (React app in iframe) communicates with the server via `app.callServerTool()`.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NESTPILOT_BACKEND_URL` | `http://localhost:8080` | NestPilot Spring Boot API URL |
+| `AGENT_RUNTIME_URL` | `http://localhost:3002` | Agent Runtime service URL |
+| `PORT` | `3001` | HTTP transport port |
+| `MCP_REQUIRE_AUTH` | `true` | Require bearer authentication on HTTP `/mcp` |
+| `MCP_AUTH_MODE` | `token` | Auth mode: `token` or `jwt-passthrough` |
+| `MCP_AUTH_TOKENS` | (none) | Comma-separated bearer tokens (required in `token` mode when auth is enabled) |
+| `MCP_DEFAULT_USER_ID` | `anonymous` | Fallback user id when auth is disabled |
+| `MCP_RATE_LIMIT_WINDOW_MS` | `60000` | Rate limit window in milliseconds |
+| `MCP_RATE_LIMIT_MAX_REQUESTS` | `60` | Max requests per window |
+
+## Commands
+
+```bash
+npm run build                     # Vite build -> dist/*.html
+npm run serve                     # Start MCP server (HTTP transport)
+npm run serve:auth                # Start MCP server with auth validation + .env loading
+npm run serve:auth:stdio          # Start stdio mode with auth env validation
+npm run start                     # Build + serve
+npm test                          # Run vitest tests
+node test-mcp-tools.mjs           # Run comprehensive tool tests
+```
+
+## Known Issues
+
+- **optimize_roth_conversion** tool (FEAT-0066) is currently under development and may not be fully functional
+- Console.log output in tool registration appears suppressed in HTTP transport mode
+- Tool registration happens per-request for HTTP transport, not at server startup
+
+## Migration from chatgpt-app
+
+| chatgpt-app (Python) | mcp-app (TypeScript) |
+|----------------------|---------------------|
+| `FastApps` / `WidgetMCPServer` | `McpServer` + `registerAppTool` |
+| `BaseWidget` subclasses | `server.tool()` / `registerAppTool()` |
+| `window.openai.callTool()` | `app.callServerTool()` |
+| `useWidgetProps()` (FastApps) | `useApp()` (MCP Apps SDK) |
+| `structuredContent` / `_meta` | `CallToolResult.content` |
+| React JSX (JavaScript) | React TSX (TypeScript) |
+| Python httpx | Node.js fetch |
+| `fastapps.json` CSP | Single-file bundle (no CSP needed) |
+|----------------------|---------------------|
+| `FastApps` / `WidgetMCPServer` | `McpServer` + `registerAppTool` |
+| `BaseWidget` subclasses | `server.tool()` / `registerAppTool()` |
+| `window.openai.callTool()` | `app.callServerTool()` |
+| `useWidgetProps()` (FastApps) | `useApp()` (MCP Apps SDK) |
+| `structuredContent` / `_meta` | `CallToolResult.content` |
+| React JSX (JavaScript) | React TSX (TypeScript) |
+| Python httpx | Node.js fetch |
+| `fastapps.json` CSP | Single-file bundle (no CSP needed) |
+

package/dist/cli/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctorCommand(): Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,214 @@
+/**
+ * `nestpilot doctor` — diagnoses common issues with the local installation.
+ *
+ * Checks:
+ *   1. Data directory exists
+ *   2. Config file is valid JSON
+ *   3. API key is present (keychain or env)
+ *   4. Encryption key is in keychain
+ *   5. Cloud API is reachable
+ *   6. Node.js version ≥ 18
+ *   7. Plans directory is readable
+ *   8. Disk space is sufficient
+ *
+ * @feature FEAT-0088
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadLocalConfig, configFilePath, plansDir, } from "../src/local/local-config.js";
+import { createKeychainProvider } from "../src/local/keychain.js";
+// ── Doctor command ───────────────────────────────────────────────────────
+export async function doctorCommand() {
+    console.log("\n🩺 NestPilot Doctor");
+    console.log("═══════════════════\n");
+    const config = loadLocalConfig();
+    const keychain = createKeychainProvider(config.dataDir);
+    const checks = [
+        {
+            name: "Data directory exists",
+            check: async () => {
+                try {
+                    await fs.access(config.dataDir);
+                    return { ok: true, message: config.dataDir };
+                }
+                catch {
+                    return {
+                        ok: false,
+                        message: `${config.dataDir} not found. Run: nestpilot init`,
+                    };
+                }
+            },
+        },
+        {
+            name: "Config file valid",
+            check: async () => {
+                const cfgPath = configFilePath(config.dataDir);
+                try {
+                    const raw = await fs.readFile(cfgPath, "utf-8");
+                    JSON.parse(raw);
+                    return { ok: true, message: cfgPath };
+                }
+                catch (e) {
+                    return {
+                        ok: false,
+                        message: `${cfgPath} — ${e instanceof Error ? e.message : String(e)}`,
+                    };
+                }
+            },
+        },
+        {
+            name: "API key configured",
+            check: async () => {
+                if (config.apiKey) {
+                    return { ok: true, message: "Set via NESTPILOT_API_KEY env var" };
+                }
+                const key = await keychain.get("nestpilot", "api-key");
+                if (key) {
+                    return { ok: true, message: "Found in OS keychain" };
+                }
+                return {
+                    ok: false,
+                    message: "No API key found. Run: nestpilot init, or set NESTPILOT_API_KEY env var",
+                };
+            },
+        },
+        {
+            name: "Encryption key in keychain",
+            check: async () => {
+                const key = await keychain.get("nestpilot", "encryption-key");
+                if (key) {
+                    return { ok: true, message: "Found in OS keychain" };
+                }
+                return {
+                    ok: false,
+                    message: "No encryption key. Run: nestpilot init",
+                };
+            },
+        },
+        {
+            name: "Cloud API reachable",
+            check: async () => {
+                try {
+                    const response = await fetch(`${config.cloudApiUrl}/actuator/health`, {
+                        method: "GET",
+                        signal: AbortSignal.timeout(5_000),
+                    });
+                    if (response.ok) {
+                        return { ok: true, message: config.cloudApiUrl };
+                    }
+                    return {
+                        ok: false,
+                        message: `${config.cloudApiUrl} returned ${response.status}`,
+                    };
+                }
+                catch {
+                    return {
+                        ok: false,
+                        message: `Cannot reach ${config.cloudApiUrl} — check internet`,
+                    };
+                }
+            },
+        },
+        {
+            name: "Node.js version ≥ 18",
+            check: async () => {
+                const major = Number.parseInt(process.version.slice(1), 10);
+                if (major >= 18) {
+                    return { ok: true, message: process.version };
+                }
+                return {
+                    ok: false,
+                    message: `${process.version} — Node.js 18+ required`,
+                };
+            },
+        },
+        {
+            name: "Plans directory readable",
+            check: async () => {
+                const dir = plansDir(config.dataDir);
+                try {
+                    const files = await fs.readdir(dir);
+                    const planFiles = files.filter((f) => f.endsWith(".json"));
+                    return {
+                        ok: true,
+                        message: `${planFiles.length} plan(s) found in ${dir}`,
+                    };
+                }
+                catch {
+                    return {
+                        ok: false,
+                        message: `${dir} not accessible. Run: nestpilot init`,
+                    };
+                }
+            },
+        },
+        {
+            name: "Disk space sufficient",
+            check: async () => {
+                try {
+                    // Check total data dir size
+                    let totalSize = 0;
+                    const walkDir = async (dirPath) => {
+                        try {
+                            const entries = await fs.readdir(dirPath, {
+                                withFileTypes: true,
+                            });
+                            for (const entry of entries) {
+                                const entryPath = path.join(dirPath, entry.name);
+                                if (entry.isDirectory()) {
+                                    await walkDir(entryPath);
+                                }
+                                else {
+                                    const stat = await fs.stat(entryPath);
+                                    totalSize += stat.size;
+                                }
+                            }
+                        }
+                        catch {
+                            // Skip inaccessible directories
+                        }
+                    };
+                    await walkDir(config.dataDir);
+                    const sizeMb = (totalSize / (1024 * 1024)).toFixed(2);
+                    const ok = totalSize < 500 * 1024 * 1024; // 500 MB threshold
+                    return {
+                        ok,
+                        message: ok
+                            ? `${sizeMb} MB used (< 500 MB limit)`
+                            : `${sizeMb} MB used — consider pruning old plans`,
+                    };
+                }
+                catch {
+                    return { ok: true, message: "Could not check disk usage" };
+                }
+            },
+        },
+    ];
+    let passCount = 0;
+    let failCount = 0;
+    for (const { name, check } of checks) {
+        try {
+            const { ok, message } = await check();
+            if (ok) {
+                console.log(`  ✅ ${name}: ${message}`);
+                passCount++;
+            }
+            else {
+                console.log(`  ❌ ${name}: ${message}`);
+                failCount++;
+            }
+        }
+        catch (e) {
+            console.log(`  ❌ ${name}: Unexpected error — ${e instanceof Error ? e.message : String(e)}`);
+            failCount++;
+        }
+    }
+    console.log(`\n${passCount} passed, ${failCount} failed out of ${checks.length} checks.`);
+    if (failCount > 0) {
+        console.log("\nTip: Run `nestpilot init` to fix most issues.\n");
+        process.exit(1);
+    }
+    else {
+        console.log("\nAll checks passed! NestPilot is healthy. ✨\n");
+    }
+}

package/dist/cli/export-import.d.ts

@@ -0,0 +1,6 @@
+export declare function exportCommand(opts: {
+    plan?: string;
+    all?: boolean;
+    output?: string;
+}): Promise<void>;
+export declare function importCommand(file: string): Promise<void>;