@nestpilot/mcp-app 1.0.0

package/dist/src/skills/skill-registry.js

@@ -0,0 +1,116 @@
+/**
+ * Skill Registry — FEAT-0057
+ *
+ * Loads, validates, and indexes v1 skill manifests.
+ * Performs compatibility checks against FEAT-0056 tool contracts
+ * to ensure required tool versions are available before execution.
+ *
+ * @feature FEAT-0057
+ * @design DES-0055
+ */
+import { validateManifest, } from "./skill-manifest-schema.js";
+import { lookupContract, } from "../contracts/tool-contract-registry.js";
+// ── Semver comparison ───────────────────────────────────────────────────
+function parseSemver(version) {
+    const parts = version.split(".").map(Number);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+/**
+ * Returns true if `actual` >= `required` (semver).
+ */
+export function semverSatisfies(actual, required) {
+    const [aMajor, aMinor, aPatch] = parseSemver(actual);
+    const [rMajor, rMinor, rPatch] = parseSemver(required);
+    if (aMajor !== rMajor)
+        return aMajor > rMajor;
+    if (aMinor !== rMinor)
+        return aMinor > rMinor;
+    return aPatch >= rPatch;
+}
+// ── Registry ────────────────────────────────────────────────────────────
+const skillMap = new Map();
+/**
+ * Registers a validated skill manifest in the registry.
+ * Returns validation result; rejects invalid manifests.
+ */
+export function registerSkill(raw) {
+    const result = validateManifest(raw);
+    if (result.valid) {
+        skillMap.set(result.manifest.skillId, result.manifest);
+    }
+    return result;
+}
+/**
+ * Look up a registered skill by ID.
+ */
+export function lookupSkill(skillId) {
+    const manifest = skillMap.get(skillId);
+    if (manifest) {
+        return { found: true, manifest };
+    }
+    return {
+        found: false,
+        skillId,
+        reason: `No skill registered with id '${skillId}'`,
+    };
+}
+/**
+ * Returns all registered skill manifests.
+ */
+export function getAllSkills() {
+    return Array.from(skillMap.values());
+}
+/**
+ * Checks whether all required tools for a skill are available
+ * in the contract registry with sufficient versions.
+ *
+ * This is the compatibility gate: execution MUST be blocked
+ * if any required tool contract is missing or below the
+ * minimum version.
+ */
+export function checkCompatibility(manifest) {
+    const failures = [];
+    const checkedTools = [];
+    for (const req of manifest.requiredTools) {
+        checkedTools.push(req.toolName);
+        const lookup = lookupContract(req.toolName);
+        if (!lookup.found) {
+            failures.push({
+                toolName: req.toolName,
+                requiredVersion: req.minContractVersion,
+                reason: `Tool contract not registered: ${req.toolName}`,
+            });
+            continue;
+        }
+        if (!semverSatisfies(lookup.contract.contractVersion, req.minContractVersion)) {
+            failures.push({
+                toolName: req.toolName,
+                requiredVersion: req.minContractVersion,
+                reason: `Contract version ${lookup.contract.contractVersion} < required ${req.minContractVersion}`,
+            });
+        }
+    }
+    if (failures.length > 0) {
+        return { compatible: false, skillId: manifest.skillId, failures };
+    }
+    return { compatible: true, skillId: manifest.skillId, checkedTools };
+}
+/**
+ * Checks compatibility and throws if requirements are not met.
+ */
+export function requireCompatibility(manifest) {
+    const result = checkCompatibility(manifest);
+    if (!result.compatible) {
+        const details = result.failures
+            .map((f) => `  ${f.toolName}: ${f.reason}`)
+            .join("\n");
+        throw new Error(`Compatibility check failed for skill '${manifest.skillId}':\n${details}`);
+    }
+    return result;
+}
+/**
+ * Clears all registered skills (for testing only).
+ */
+export function _resetSkillRegistry() {
+    skillMap.clear();
+}

package/dist/src/telemetry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OpenTelemetry tracing for the NestPilot MCP server.
+ *
+ * Ported from apps/mcp-edge to provide tool-level spans and observability.
+ * Initialized conditionally based on config.enableConsoleTracing.
+ */
+import { type Span } from "@opentelemetry/api";
+import type { AppConfig } from "./config.js";
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export declare function initializeTelemetry(config: AppConfig): void;
+export declare function shutdownTelemetry(): Promise<void>;
+export declare function withToolSpan<T>(spanName: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;

package/dist/src/telemetry.js

@@ -0,0 +1,59 @@
+/**
+ * OpenTelemetry tracing for the NestPilot MCP server.
+ *
+ * Ported from apps/mcp-edge to provide tool-level spans and observability.
+ * Initialized conditionally based on config.enableConsoleTracing.
+ */
+import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { Resource } from "@opentelemetry/resources";
+import { BatchSpanProcessor, ConsoleSpanExporter, } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+const SERVICE_NAME = "nestpilot-mcp-app";
+const SERVICE_VERSION = "1.0.0";
+let provider = null;
+let initialized = false;
+export const tracer = trace.getTracer(SERVICE_NAME, SERVICE_VERSION);
+export function initializeTelemetry(config) {
+    if (initialized || !config.enableConsoleTracing) {
+        return;
+    }
+    provider = new NodeTracerProvider({
+        resource: new Resource({
+            [SemanticResourceAttributes.SERVICE_NAME]: SERVICE_NAME,
+            [SemanticResourceAttributes.SERVICE_VERSION]: SERVICE_VERSION,
+        }),
+    });
+    provider.addSpanProcessor(new BatchSpanProcessor(new ConsoleSpanExporter()));
+    provider.register();
+    initialized = true;
+    process.once("beforeExit", () => {
+        void shutdownTelemetry();
+    });
+}
+export async function shutdownTelemetry() {
+    if (!provider) {
+        return;
+    }
+    await provider.shutdown().catch(() => { });
+}
+export async function withToolSpan(spanName, attributes, fn) {
+    return tracer.startActiveSpan(spanName, { kind: SpanKind.SERVER, attributes }, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}

package/dist/src/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared type definitions for the Medicare Guardian MCP App view.
+ */
+export interface Deadline {
+    type: string;
+    startDate: string;
+    endDate: string;
+    status: string;
+    daysRemaining?: number;
+}
+export interface PenaltyInfo {
+    monthly: number;
+    lifetime?: number;
+    notes?: string;
+}
+export interface ChecklistItem {
+    id?: string;
+    title: string;
+    description: string;
+}
+export interface Explanation {
+    topic: string;
+    reasoning: string;
+}
+export interface AnalysisResult {
+    status: string;
+    healthScore: number;
+    deadlines: Deadline[];
+    penalties: {
+        partBPenalty?: PenaltyInfo;
+        partDPenalty?: PenaltyInfo;
+    };
+    checklist: ChecklistItem[];
+    explanations: Explanation[];
+    error?: boolean;
+    message?: string;
+}
+export interface FormData {
+    dateOfBirth: string;
+    employmentStatus: string;
+    coverageType: string;
+    employerSize: string | null;
+    hsaContributor: boolean;
+    hasCreditableDrugCoverage: boolean;
+}
+export type ViewState = "input" | "results" | "subscribe" | "sep_check";

package/dist/src/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared type definitions for the Medicare Guardian MCP App view.
+ */
+export {};

package/dist/tools/agent-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Agent Runtime MCP tools — list_skills, run_skill, run_plan.
+ *
+ * These tools expose the NestPilot Agent Runtime's skill registry
+ * and orchestration capabilities through MCP, enabling any MCP host
+ * (Claude Desktop, ChatGPT, etc.) to access the agent platform.
+ *
+ * Communicates with the agent-runtime service via HTTP.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AuthContext } from "./mcp-helpers.js";
+export declare function registerAgentTools(server: McpServer, _authCtx?: AuthContext): void;

package/dist/tools/agent-tools.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { toCallToolResult } from "./mcp-helpers.js";
+const AGENT_RUNTIME_URL = process.env.AGENT_RUNTIME_URL ?? "http://localhost:3002";
+async function agentRuntimeGet(path) {
+    const url = `${AGENT_RUNTIME_URL}${path}`;
+    try {
+        const res = await fetch(url, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            return { error: true, code: res.status, message: await res.text() };
+        }
+        return await res.json();
+    }
+    catch (e) {
+        return {
+            error: true,
+            message: `Agent runtime connection failed: ${String(e)}`,
+        };
+    }
+}
+async function agentRuntimePost(path, body) {
+    const url = `${AGENT_RUNTIME_URL}${path}`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(180_000),
+        });
+        if (!res.ok) {
+            return { error: true, code: res.status, message: await res.text() };
+        }
+        return await res.json();
+    }
+    catch (e) {
+        return {
+            error: true,
+            message: `Agent runtime connection failed: ${String(e)}`,
+        };
+    }
+}
+export function registerAgentTools(server, _authCtx) {
+    // ── 1. nestpilot_list_skills ──────────────────────────────────────────
+    server.tool("nestpilot_list_skills", `Lists all available NestPilot agent skills with their names and descriptions.
+
+USE THIS TOOL WHEN THE USER:
+- Asks "what can you do?" or wants to know available capabilities
+- Needs to choose a skill before running it
+- Wants to understand the agent's capabilities`, {}, async () => {
+        const result = await agentRuntimeGet("/skills");
+        const data = result;
+        if (data.error) {
+            return toCallToolResult(data, true);
+        }
+        return toCallToolResult(data);
+    });
+    // ── 2. nestpilot_run_skill ────────────────────────────────────────────
+    server.tool("nestpilot_run_skill", `Runs a NestPilot agent skill by name within a session. Creates a new session if none provided. Returns the agent's streaming response events.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to run a specific skill (e.g., "retirement-readiness", "scenario-sweep")
+- Wants to interact with the agent runtime through a skill-specific workflow
+
+Call nestpilot_list_skills first to see available skills.`, {
+        skillName: z
+            .string()
+            .describe("Name of the skill to run (e.g., 'retirement-readiness', 'scenario-sweep')"),
+        message: z
+            .string()
+            .describe("User message to send to the skill (the skill will guide the conversation)"),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Existing session ID to continue a conversation. If omitted, a new session is created."),
+    }, async (args) => {
+        const { skillName, message, sessionId } = args;
+        let activeSessionId = sessionId;
+        // Create session if needed
+        if (!activeSessionId) {
+            const createResult = (await agentRuntimePost("/sessions", {
+                userId: "mcp-user",
+            }));
+            if (createResult.error) {
+                return toCallToolResult(createResult, true);
+            }
+            activeSessionId = createResult.id;
+        }
+        // Send message with skill context prefix
+        const content = `[skill:${skillName}] ${message}`;
+        const result = (await agentRuntimePost(`/sessions/${activeSessionId}/messages`, { content }));
+        if (result.error) {
+            return toCallToolResult(result, true);
+        }
+        return toCallToolResult({
+            sessionId: activeSessionId,
+            ...result,
+        });
+    });
+    // ── 3. nestpilot_run_plan ─────────────────────────────────────────────
+    server.tool("nestpilot_run_plan", `Runs a full retirement planning session through the agent runtime. This is a convenience tool that combines creating a session, running the retirement-readiness skill, and returning the results.
+
+USE THIS TOOL WHEN THE USER:
+- Wants a complete retirement readiness assessment
+- Says "check my retirement plan" or "am I on track?"
+- Provides age, savings, and contribution information and wants a full analysis`, {
+        message: z
+            .string()
+            .describe("User's retirement planning question or data (e.g., 'I'm 40, have $250k saved, contributing $2k/month')"),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Existing session ID to continue. If omitted, starts fresh."),
+    }, async (args) => {
+        const { message, sessionId } = args;
+        let activeSessionId = sessionId;
+        if (!activeSessionId) {
+            const createResult = (await agentRuntimePost("/sessions", {
+                userId: "mcp-user",
+            }));
+            if (createResult.error) {
+                return toCallToolResult(createResult, true);
+            }
+            activeSessionId = createResult.id;
+        }
+        const content = `[skill:retirement-readiness] ${message}`;
+        const result = (await agentRuntimePost(`/sessions/${activeSessionId}/messages`, { content }));
+        if (result.error) {
+            return toCallToolResult(result, true);
+        }
+        return toCallToolResult({
+            sessionId: activeSessionId,
+            skill: "retirement-readiness",
+            ...result,
+        });
+    });
+}

package/dist/tools/forecast-management-tools.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AuthContext } from "./mcp-helpers.js";
+export declare function usesActivePlanAlias(planId?: string): boolean;
+export declare function resolveSavedPlanId(planId: string | undefined, authCtx?: AuthContext): Promise<{
+    planId?: string;
+    errorResult?: CallToolResult;
+}>;
+export declare function registerForecastManagementTools(server: McpServer, authCtx?: AuthContext): void;

package/dist/tools/forecast-management-tools.js

@@ -0,0 +1,133 @@
+/**
+ * Forecast management MCP tools — saved forecast operations.
+ *
+ * Mirrors the forecast management API used by the web app (apps/web/hooks/useApi.ts):
+ *   run_saved_forecast, get_baseline_forecast.
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { nestpilotClient } from "../nestpilot-client.js";
+import { proxyGetTool, proxyPostTool, toCallToolResult, } from "./mcp-helpers.js";
+const ACTIVE_PLAN_ALIASES = new Set(["default", "active", "current"]);
+function buildAuthHeaders(authCtx) {
+    const headers = {};
+    if (authCtx?.bearerToken) {
+        headers.Authorization = `Bearer ${authCtx.bearerToken}`;
+    }
+    if (authCtx?.userId) {
+        headers["X-User-ID"] = authCtx.userId;
+    }
+    return headers;
+}
+export function usesActivePlanAlias(planId) {
+    const normalized = planId?.trim().toLowerCase();
+    if (!normalized)
+        return true;
+    return ACTIVE_PLAN_ALIASES.has(normalized);
+}
+function extractPlanId(payload) {
+    const candidate = payload.id ?? payload.planId;
+    if (typeof candidate !== "string")
+        return undefined;
+    const trimmed = candidate.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export async function resolveSavedPlanId(planId, authCtx) {
+    if (!usesActivePlanAlias(planId)) {
+        return { planId: planId?.trim() };
+    }
+    const activePlanResult = await nestpilotClient.get("/api/plans/active", undefined, { headers: buildAuthHeaders(authCtx) });
+    if (activePlanResult.error) {
+        return {
+            errorResult: toCallToolResult({
+                error: true,
+                code: activePlanResult.code ?? 404,
+                message: activePlanResult.message ??
+                    "Unable to resolve active plan for this user.",
+            }, true),
+        };
+    }
+    const activePlanId = extractPlanId(activePlanResult);
+    if (!activePlanId) {
+        return {
+            errorResult: toCallToolResult({
+                error: true,
+                code: 404,
+                message: "No active plan found. Create or activate a saved plan first.",
+            }, true),
+        };
+    }
+    return { planId: activePlanId };
+}
+export function registerForecastManagementTools(server, authCtx) {
+    // ── 1. run_saved_forecast ───────────────────────────────────────────────
+    registerAppTool(server, "run_saved_forecast", {
+        title: "Run Saved Forecast",
+        description: `Triggers a forecast run for a saved plan. Returns a forecastId and status.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to run a forecast on one of their saved plans
+- Says "run forecast on my plan" or "forecast plan X"
+- Needs to compute or refresh the baseline or scenario forecast for a persisted plan
+
+REQUIRES authentication — operates on saved plans.`,
+        inputSchema: {
+            planId: z
+                .string()
+                .describe("UUID of the saved plan. Alias values 'default', 'active', or 'current' use the active plan."),
+            runType: z
+                .enum(["baseline", "scenario"])
+                .describe("Type of forecast run: 'baseline' or 'scenario'"),
+            scenarioId: z
+                .string()
+                .optional()
+                .describe("UUID of the scenario to apply (required when runType is 'scenario')"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId, runType, scenarioId } = args;
+        const resolved = await resolveSavedPlanId(planId, authCtx);
+        if (resolved.errorResult)
+            return resolved.errorResult;
+        if (!resolved.planId) {
+            return toCallToolResult({
+                error: true,
+                code: 400,
+                message: "Missing planId after active plan resolution.",
+            }, true);
+        }
+        return proxyPostTool("/api/forecasts/run", { planId: resolved.planId, runType, scenarioId }, { toolName: "run_saved_forecast", authCtx });
+    });
+    // ── 2. get_baseline_forecast ────────────────────────────────────────────
+    registerAppTool(server, "get_baseline_forecast", {
+        title: "Get Baseline Forecast",
+        description: `Retrieves the most recent baseline forecast result for a saved plan.
+Returns the forecast JSON, derived metrics, and forecast ID.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to see the latest forecast results for a saved plan
+- Asks "show me my forecast" or "what's my baseline?"
+- Needs forecast data to display in charts or reports
+
+REQUIRES authentication — operates on saved plans.`,
+        inputSchema: {
+            planId: z
+                .string()
+                .describe("UUID of the saved plan. Alias values 'default', 'active', or 'current' use the active plan."),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId } = args;
+        const resolved = await resolveSavedPlanId(planId, authCtx);
+        if (resolved.errorResult)
+            return resolved.errorResult;
+        if (!resolved.planId) {
+            return toCallToolResult({
+                error: true,
+                code: 400,
+                message: "Missing planId after active plan resolution.",
+            }, true);
+        }
+        return proxyGetTool(`/api/forecasts/baseline`, { planId: resolved.planId }, { toolName: "get_baseline_forecast", authCtx });
+    });
+}

package/dist/tools/local-plan-tools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LocalPlanStore } from "../src/local/local-plan-store.js";
+import type { CloudComputeClient } from "../src/local/cloud-compute-client.js";
+/**
+ * Registers local-mode MCP tools on the server.
+ * These tools handle data locally and delegate compute to the cloud.
+ */
+export declare function registerLocalPlanTools(server: McpServer, store: LocalPlanStore, computeClient: CloudComputeClient): void;