@kynver-app/mcp-estimator 0.1.1

package/dist/tools/stats-pdf-tools.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import * as client from "../lib/kynver-client.js";
+// --- estimator_get_stats ---
+const getStatsSchema = z.object({
+    from: z.string().optional(),
+    to: z.string().optional(),
+});
+export const getStats = {
+    name: "estimator_get_stats",
+    description: "Get aggregate statistics for the user's estimating business. Returns: total estimates count, estimates by status, total revenue (accepted estimates), average estimate value, estimates by type (replacement vs repair). Optionally filter by date range (from/to as ISO strings). Use this for dashboard data and business reporting.",
+    inputSchemaZod: getStatsSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const params = new URLSearchParams();
+        if (args.from)
+            params.set("from", args.from);
+        if (args.to)
+            params.set("to", args.to);
+        const q = params.toString();
+        const path = q ? `/estimator/stats?${q}` : "/estimator/stats";
+        const data = await client.get(path);
+        return JSON.stringify(data);
+    },
+};
+// --- estimator_export_pdf ---
+const exportPdfSchema = z.object({
+    estimateId: z.string(),
+});
+export const exportPdf = {
+    name: "estimator_export_pdf",
+    description: "Generate a PDF document for an estimate. Returns a download URL (not the binary file). The PDF layout is controlled by the estimate's output config — use estimator_update_output_config to customize which columns, sections, and details appear. The PDF includes company branding from estimator config.",
+    inputSchemaZod: exportPdfSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        // Trigger PDF generation on the server side
+        try {
+            await client.get(`/estimator/estimates/${args.estimateId}/pdf`);
+        }
+        catch {
+            // Even if the binary response fails to parse, the PDF was generated
+        }
+        return JSON.stringify({
+            message: "PDF generated successfully.",
+            downloadUrl: `/api/estimator/estimates/${args.estimateId}/pdf`,
+        });
+    },
+};
+// --- estimator_update_output_config ---
+const updateOutputConfigSchema = z.object({
+    estimateId: z.string(),
+    showMaterialCost: z.boolean().optional(),
+    showLaborCost: z.boolean().optional(),
+    showUnitPrice: z.boolean().optional(),
+    showQuantity: z.boolean().optional(),
+    showNotes: z.boolean().optional(),
+    headerText: z.string().optional(),
+    footerText: z.string().optional(),
+    template: z.string().optional(),
+});
+export const updateOutputConfig = {
+    name: "estimator_update_output_config",
+    description: "Configure what appears in an estimate's PDF output. Toggle visibility of: material costs, labor costs, unit prices, quantities, line item notes. Set custom header/footer text. Choose a template style. This controls the presentation layer — the underlying estimate data is not changed.",
+    inputSchemaZod: updateOutputConfigSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const { estimateId, ...body } = args;
+        const data = await client.patch(`/estimator/estimates/${estimateId}/output-config`, body);
+        return JSON.stringify(data);
+    },
+};

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

@@ -0,0 +1,96 @@
+import { z } from "zod";
+declare const saveTemplateSchema: z.ZodObject<{
+    estimateId: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    estimateId: string;
+}, {
+    name: string;
+    estimateId: string;
+}>;
+export declare const saveTemplate: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        estimateId: z.ZodString;
+        name: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        estimateId: string;
+    }, {
+        name: string;
+        estimateId: string;
+    }>;
+    execute: (args: z.infer<typeof saveTemplateSchema>) => Promise<string>;
+};
+declare const listTemplatesSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type?: string | undefined;
+}, {
+    type?: string | undefined;
+}>;
+export declare const listTemplates: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type?: string | undefined;
+    }, {
+        type?: string | undefined;
+    }>;
+    execute: (args: z.infer<typeof listTemplatesSchema>) => Promise<string>;
+};
+declare const deleteTemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export declare const deleteTemplate: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+    }, {
+        id: string;
+    }>;
+    execute: (args: z.infer<typeof deleteTemplateSchema>) => Promise<string>;
+};
+declare const createFromTemplateSchema: z.ZodObject<{
+    templateId: z.ZodString;
+    projectName: z.ZodString;
+    clientId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    templateId: string;
+    projectName: string;
+    clientId?: string | undefined;
+}, {
+    templateId: string;
+    projectName: string;
+    clientId?: string | undefined;
+}>;
+export declare const createFromTemplate: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        templateId: z.ZodString;
+        projectName: z.ZodString;
+        clientId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        templateId: string;
+        projectName: string;
+        clientId?: string | undefined;
+    }, {
+        templateId: string;
+        projectName: string;
+        clientId?: string | undefined;
+    }>;
+    execute: (args: z.infer<typeof createFromTemplateSchema>) => Promise<string>;
+};
+export {};

package/dist/tools/template-tools.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import * as client from "../lib/kynver-client.js";
+// --- estimator_save_template ---
+const saveTemplateSchema = z.object({
+    estimateId: z.string(),
+    name: z.string(),
+});
+export const saveTemplate = {
+    name: "estimator_save_template",
+    description: "Save an existing estimate as a reusable template. Templates capture the estimate's line items, quantities, and structure so you can quickly create similar estimates in the future. Requires the estimateId of the source estimate and a name for the template.",
+    inputSchemaZod: saveTemplateSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.post("/estimator/templates", args);
+        return JSON.stringify(data);
+    },
+};
+// --- estimator_list_templates ---
+const listTemplatesSchema = z.object({
+    type: z.string().optional(),
+});
+export const listTemplates = {
+    name: "estimator_list_templates",
+    description: "List all saved estimate templates. Optionally filter by type: 'replacement' or 'repair_service'. Returns template names, types, and IDs. Use template IDs with estimator_create_from_template to create new estimates.",
+    inputSchemaZod: listTemplatesSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const params = new URLSearchParams();
+        if (args.type)
+            params.set("type", args.type);
+        const q = params.toString();
+        const path = q ? `/estimator/templates?${q}` : "/estimator/templates";
+        const data = await client.get(path);
+        return JSON.stringify(data);
+    },
+};
+// --- estimator_delete_template ---
+const deleteTemplateSchema = z.object({
+    id: z.string(),
+});
+export const deleteTemplate = {
+    name: "estimator_delete_template",
+    description: "Delete a saved estimate template permanently. This does not affect any estimates that were previously created from this template.",
+    inputSchemaZod: deleteTemplateSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.del(`/estimator/templates/${args.id}`);
+        return JSON.stringify(data);
+    },
+};
+// --- estimator_create_from_template ---
+const createFromTemplateSchema = z.object({
+    templateId: z.string(),
+    projectName: z.string(),
+    clientId: z.string().optional(),
+});
+export const createFromTemplate = {
+    name: "estimator_create_from_template",
+    description: "Create a new estimate from a saved template. The new estimate gets all the template's line items and structure. Requires: templateId (from estimator_list_templates), projectName. Optionally link to a clientId. The new estimate is created as a draft.",
+    inputSchemaZod: createFromTemplateSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.post("/estimator/estimates", args);
+        return JSON.stringify(data);
+    },
+};

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

@@ -0,0 +1,46 @@
+import { z } from "zod";
+declare const listVersionsSchema: z.ZodObject<{
+    estimateId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    estimateId: string;
+}, {
+    estimateId: string;
+}>;
+export declare const listVersions: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        estimateId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        estimateId: string;
+    }, {
+        estimateId: string;
+    }>;
+    execute: (args: z.infer<typeof listVersionsSchema>) => Promise<string>;
+};
+declare const getVersionSchema: z.ZodObject<{
+    estimateId: z.ZodString;
+    versionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    estimateId: string;
+    versionId: string;
+}, {
+    estimateId: string;
+    versionId: string;
+}>;
+export declare const getVersion: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        estimateId: z.ZodString;
+        versionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        estimateId: string;
+        versionId: string;
+    }, {
+        estimateId: string;
+        versionId: string;
+    }>;
+    execute: (args: z.infer<typeof getVersionSchema>) => Promise<string>;
+};
+export {};

package/dist/tools/version-tools.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import * as client from "../lib/kynver-client.js";
+// --- estimator_list_versions ---
+const listVersionsSchema = z.object({
+    estimateId: z.string(),
+});
+export const listVersions = {
+    name: "estimator_list_versions",
+    description: "List all saved version snapshots of an estimate. Versions are created automatically when significant changes are made. Shows version numbers and timestamps. Use this to track the history of changes to an estimate.",
+    inputSchemaZod: listVersionsSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.get(`/estimator/estimates/${args.estimateId}/versions`);
+        return JSON.stringify(data);
+    },
+};
+// --- estimator_get_version ---
+const getVersionSchema = z.object({
+    estimateId: z.string(),
+    versionId: z.string(),
+});
+export const getVersion = {
+    name: "estimator_get_version",
+    description: "Get a specific historical version of an estimate. Returns the full estimate snapshot as it existed at that point in time — all line items, totals, and metadata. Useful for comparing current vs previous versions or reverting changes.",
+    inputSchemaZod: getVersionSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.get(`/estimator/estimates/${args.estimateId}/versions/${args.versionId}`);
+        return JSON.stringify(data);
+    },
+};

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

@@ -0,0 +1,52 @@
+import { z } from "zod";
+declare const analyzePhotosSchema: z.ZodObject<{
+    images: z.ZodArray<z.ZodString, "many">;
+    prompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    images: string[];
+    prompt?: string | undefined;
+}, {
+    images: string[];
+    prompt?: string | undefined;
+}>;
+export declare const analyzePhotos: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        images: z.ZodArray<z.ZodString, "many">;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        images: string[];
+        prompt?: string | undefined;
+    }, {
+        images: string[];
+        prompt?: string | undefined;
+    }>;
+    execute: (args: z.infer<typeof analyzePhotosSchema>) => Promise<string>;
+};
+declare const analyzeDocumentSchema: z.ZodObject<{
+    text: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    prompt?: string | undefined;
+}, {
+    text: string;
+    prompt?: string | undefined;
+}>;
+export declare const analyzeDocument: {
+    name: string;
+    description: string;
+    inputSchemaZod: z.ZodObject<{
+        text: z.ZodString;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        prompt?: string | undefined;
+    }, {
+        text: string;
+        prompt?: string | undefined;
+    }>;
+    execute: (args: z.infer<typeof analyzeDocumentSchema>) => Promise<string>;
+};
+export {};

package/dist/tools/vision-tools.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import * as client from "../lib/kynver-client.js";
+// --- estimator_analyze_photos ---
+const analyzePhotosSchema = z.object({
+    images: z.array(z.string()),
+    prompt: z.string().optional(),
+});
+export const analyzePhotos = {
+    name: "estimator_analyze_photos",
+    description: "Analyze roof photos using Claude's vision AI. Provide image URLs (can be multiple). The AI identifies: roofing materials, visible damage (missing shingles, cracks, moss, ponding), approximate measurements, and repair recommendations. Use the optional prompt parameter to ask specific questions about the photos. Results can inform estimate creation.",
+    inputSchemaZod: analyzePhotosSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.post("/estimator/analyze", {
+            type: "photos",
+            images: args.images,
+            prompt: args.prompt,
+        });
+        return JSON.stringify(data);
+    },
+};
+// --- estimator_analyze_document ---
+const analyzeDocumentSchema = z.object({
+    text: z.string(),
+    prompt: z.string().optional(),
+});
+export const analyzeDocument = {
+    name: "estimator_analyze_document",
+    description: "Analyze a text document (inspection report, insurance scope of work, contractor notes) and extract structured estimating data — identified services, quantities, materials, and damage descriptions. Pass the document text in the text field. Use the optional prompt parameter to focus the analysis. Results can be used to create estimates with accurate line items.",
+    inputSchemaZod: analyzeDocumentSchema,
+    execute: async (args) => {
+        if (!client.hasApiKey())
+            return client.noApiKeyMessage();
+        const data = await client.post("/estimator/analyze", {
+            type: "document",
+            text: args.text,
+            prompt: args.prompt,
+        });
+        return JSON.stringify(data);
+    },
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@kynver-app/mcp-estimator",
+  "version": "0.1.1",
+  "description": "Kynver Estimator MCP server — chat, estimate, and catalog tools",
+  "type": "module",
+  "bin": {
+    "kynver-mcp-estimator": "dist/index.js"
+  },
+  "scripts": {
+    "prebuild": "node ../../scripts/sync-mcp-sse-server.mjs",
+    "build": "node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc",
+    "dev": "node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc --watch",
+    "start": "node dist/index.js",
+    "start:sse": "node dist/sse.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Kynver Estimator MCP server — stdio entry point.
+ * Run: node dist/index.js
+ * Env: KYNVER_API_URL (default https://kynver.com), KYNVER_API_KEY (required for all tools)
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createEstimatorServer } from "./server.js";
+
+const server = createEstimatorServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/lib/kynver-client.ts

@@ -0,0 +1,136 @@
+/**
+ * Thin fetch wrapper for Kynver API. Base URL from KYNVER_API_URL; optional Bearer from KYNVER_API_KEY.
+ *
+ * Supports per-request user identity via AsyncLocalStorage. When a userId is
+ * set in the request context (e.g. from the SSE route), all API calls include
+ * X-Kynver-User-Id and X-Kynver-Service-Secret headers so the Kynver API
+ * executes operations on behalf of the correct user.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// ---------------------------------------------------------------------------
+// Request context — allows the SSE route to set userId per-connection
+// ---------------------------------------------------------------------------
+
+interface RequestContext {
+  userId?: string;
+}
+
+export const requestContext = new AsyncLocalStorage<RequestContext>();
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const baseUrl = process.env.KYNVER_API_URL ?? "https://kynver.com";
+const apiKey = process.env.KYNVER_API_KEY ?? "";
+
+function assertSafeApiPath(path: string): void {
+  const p = path.startsWith("/") ? path : `/${path}`;
+  if (p.includes("..") || p.includes("\0")) {
+    throw new Error("Invalid API path: path traversal is not allowed");
+  }
+}
+
+function url(path: string): string {
+  assertSafeApiPath(path);
+  const p = path.startsWith("/") ? path : `/${path}`;
+  const apiPath = p.startsWith("/api") ? p : `/api${p}`;
+  return `${baseUrl.replace(/\/$/, "")}${apiPath}`;
+}
+
+function getHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (apiKey) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  }
+
+  const ctx = requestContext.getStore();
+  const userId = ctx?.userId ?? process.env.KYNVER_USER_ID?.trim();
+  const serviceSecret = process.env.KYNVER_SERVICE_SECRET?.trim();
+
+  if (userId) {
+    if (!serviceSecret) {
+      throw new Error(
+        "X-Kynver-User-Id was set in context but KYNVER_SERVICE_SECRET is missing; refusing to send an unscoped request.",
+      );
+    }
+    headers["X-Kynver-User-Id"] = userId;
+    headers["X-Kynver-Service-Secret"] = serviceSecret;
+  }
+
+  return headers;
+}
+
+// ---------------------------------------------------------------------------
+// Response handling
+// ---------------------------------------------------------------------------
+
+async function handleResponse<T>(res: Response): Promise<T> {
+  const text = await res.text();
+  if (!res.ok) {
+    let msg = text;
+    try {
+      const j = JSON.parse(text) as { error?: string; message?: string };
+      msg = j.error ?? j.message ?? text;
+    } catch {
+      // use text as-is
+    }
+    throw new Error(msg || `HTTP ${res.status}`);
+  }
+  if (!text) return undefined as T;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return text as unknown as T;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP methods
+// ---------------------------------------------------------------------------
+
+export async function get<T = unknown>(path: string): Promise<T> {
+  const res = await fetch(url(path), {
+    method: "GET",
+    headers: getHeaders(),
+  });
+  return handleResponse<T>(res);
+}
+
+export async function post<T = unknown>(path: string, body: unknown): Promise<T> {
+  const res = await fetch(url(path), {
+    method: "POST",
+    headers: getHeaders(),
+    body: JSON.stringify(body),
+  });
+  return handleResponse<T>(res);
+}
+
+export async function patch<T = unknown>(path: string, body: unknown): Promise<T> {
+  const res = await fetch(url(path), {
+    method: "PATCH",
+    headers: getHeaders(),
+    body: JSON.stringify(body),
+  });
+  return handleResponse<T>(res);
+}
+
+export async function del<T = unknown>(path: string): Promise<T> {
+  const res = await fetch(url(path), {
+    method: "DELETE",
+    headers: getHeaders(),
+  });
+  return handleResponse<T>(res);
+}
+
+export function hasApiKey(): boolean {
+  return !!apiKey;
+}
+
+export function noApiKeyMessage(): string {
+  return "No API key configured. Set KYNVER_API_KEY in your MCP server config.";
+}