autoform-mcp-server 1.5.0 → 1.6.0

package/dist/index.js

@@ -12,7 +12,8 @@ import { handleSaveCoordinatesAsTemplate, saveCoordinatesAsTemplateSchema } from
 import { handleGenerateBatch, generateBatchSchema } from './tools/generateBatch.js';
 import { handleListTemplates, listTemplatesSchema } from './tools/manageTemplates.js';
 import { handleImportTemplate, importTemplateSchema } from './tools/importTemplate.js';
-const server = new Server({ name: 'autoform', version: '1.5.0' }, { capabilities: { tools: {} } });
+import { withMetrics } from './services/metricsLogger.js';
+const server = new Server({ name: 'autoform', version: '1.6.0' }, { capabilities: { tools: {} } });
 // Register all tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
@@ -33,33 +34,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         importTemplateSchema
     ]
 }));
-// Handle tool calls
+// Handle tool calls — every handler is wrapped with metrics instrumentation.
+// withMetrics() captures tool name, wall-clock duration, input/output stats,
+// and success/failure — writing one JSONL line per call to ~/.autoform-mcp/metrics.jsonl
+// It NEVER modifies handler behavior and NEVER throws from the logger.
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         switch (name) {
             case 'autoform_get_pdf_info':
-                return await handleGetPdfInfo(args);
+                return await withMetrics(name, args, handleGetPdfInfo);
             case 'autoform_detect_fields':
-                return await handleDetectFields(args);
+                return await withMetrics(name, args, handleDetectFields);
             case 'autoform_analyze_static_pdf':
-                return await handleAnalyzeStaticPdf(args);
+                return await withMetrics(name, args, handleAnalyzeStaticPdf);
             case 'autoform_fill_pdf':
-                return await handleFillPdf(args);
+                return await withMetrics(name, args, handleFillPdf);
             case 'autoform_fill_at_coordinates':
-                return await handleFillAtCoordinates(args);
+                return await withMetrics(name, args, handleFillAtCoordinates);
             case 'autoform_fill_batch_at_coordinates':
-                return await handleFillBatchAtCoordinates(args);
+                return await withMetrics(name, args, handleFillBatchAtCoordinates);
             case 'autoform_fill_batch_acroform':
-                return await handleFillBatchAcroForm(args);
+                return await withMetrics(name, args, handleFillBatchAcroForm);
             case 'autoform_save_coordinates_as_template':
-                return await handleSaveCoordinatesAsTemplate(args);
+                return await withMetrics(name, args, handleSaveCoordinatesAsTemplate);
             case 'autoform_generate_batch':
-                return await handleGenerateBatch(args);
+                return await withMetrics(name, args, handleGenerateBatch);
             case 'autoform_list_templates':
-                return await handleListTemplates();
+                return await withMetrics(name, args, async () => handleListTemplates());
             case 'autoform_import_template':
-                return await handleImportTemplate(args);
+                return await withMetrics(name, args, handleImportTemplate);
             default:
                 return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
         }
@@ -74,4 +78,4 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // Start server
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error('[AutoForm MCP] Server v1.5.0 started — 11 tools registered');
+console.error('[AutoForm MCP] Server v1.6.0 started — 11 tools registered (metrics enabled)');

package/dist/services/metricsLogger.d.ts

@@ -0,0 +1,28 @@
+export interface MetricsEvent {
+    ts: string;
+    tool: string;
+    duration_ms: number;
+    success: boolean;
+    error_message?: string;
+    session_id?: string;
+    input?: Record<string, number | string | boolean>;
+    output?: Record<string, number | string | boolean>;
+}
+/**
+ * Wrap a tool handler to automatically measure and log metrics.
+ * The handler's behavior is unchanged; metrics are captured transparently.
+ */
+export declare function withMetrics<T>(toolName: string, args: any, handler: (args: any) => Promise<T>): Promise<T>;
+/**
+ * Generate a new random session ID (not used automatically — exported for future use).
+ */
+export declare function generateSessionId(): string;
+/**
+ * Read all metrics events from the log file (for analysis/debugging).
+ * Returns empty array if file doesn't exist or is unreadable.
+ */
+export declare function readAllEvents(): MetricsEvent[];
+/**
+ * Get the path to the metrics file (for documentation / user info).
+ */
+export declare function getMetricsFilePath(): string;

package/dist/services/metricsLogger.js

@@ -0,0 +1,267 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+/**
+ * Append-only JSONL metrics logger for the AutoForm MCP server.
+ *
+ * Records one line per tool call with:
+ * - Timestamp (ISO 8601)
+ * - Tool name
+ * - Wall-clock duration in milliseconds
+ * - Input/output summary (sizes, key counts — no raw data for privacy)
+ * - Error flag
+ * - Optional session_id (Claude can pass it to group calls of the same task)
+ *
+ * Design principles:
+ * - NEVER throws: a failure to log must never break a tool call.
+ * - NEVER reads or modifies existing lines: pure append to preserve integrity.
+ * - NEVER records raw data (PDF contents, personal data, values): only structural counts.
+ * - Can be disabled via AUTOFORM_METRICS_DISABLED=1 environment variable.
+ */
+const METRICS_DIR = path.join(os.homedir(), '.autoform-mcp');
+const METRICS_FILE = path.join(METRICS_DIR, 'metrics.jsonl');
+const METRICS_DISABLED = process.env.AUTOFORM_METRICS_DISABLED === '1';
+/**
+ * Extract structural stats from tool arguments without leaking raw data.
+ * Only records COUNTS and sizes, never the actual content of fields or user data.
+ */
+function summarizeInput(toolName, args) {
+    const summary = {};
+    if (!args || typeof args !== 'object')
+        return summary;
+    // pdf_path: record only basename, not full path (privacy)
+    if (typeof args.pdf_path === 'string') {
+        summary.pdf_basename = path.basename(args.pdf_path);
+    }
+    if (typeof args.json_file_path === 'string') {
+        summary.json_basename = path.basename(args.json_file_path);
+    }
+    // Count arrays (core metric: how many fields/rows defined manually)
+    const fields = Array.isArray(args.fields) ? args.fields
+        : typeof args.fields === 'string' ? tryParseArray(args.fields) : null;
+    if (fields)
+        summary.fields_manual = fields.length;
+    const fieldDefs = Array.isArray(args.field_definitions) ? args.field_definitions
+        : typeof args.field_definitions === 'string' ? tryParseArray(args.field_definitions) : null;
+    if (fieldDefs)
+        summary.field_definitions_count = fieldDefs.length;
+    const dataRows = Array.isArray(args.data_rows) ? args.data_rows
+        : typeof args.data_rows === 'string' ? tryParseArray(args.data_rows) : null;
+    if (dataRows)
+        summary.data_rows_count = dataRows.length;
+    const data = Array.isArray(args.data) ? args.data
+        : typeof args.data === 'string' ? tryParseArray(args.data) : null;
+    if (data)
+        summary.data_rows_count = data.length;
+    // Field values (for fill_pdf)
+    if (args.field_values && typeof args.field_values === 'object') {
+        summary.field_values_count = Object.keys(args.field_values).length;
+    }
+    // field_map (for batch AcroForm)
+    if (args.field_map && typeof args.field_map === 'object') {
+        summary.field_map_count = Object.keys(args.field_map).length;
+    }
+    // Flags
+    if (typeof args.merge_into_single === 'boolean') {
+        summary.merge_into_single = args.merge_into_single;
+    }
+    if (typeof args.distribution_mode === 'string') {
+        summary.distribution_mode = args.distribution_mode;
+    }
+    if (typeof args.template_name === 'string') {
+        summary.template_name = args.template_name;
+    }
+    return summary;
+}
+/**
+ * Extract structural stats from the MCP tool response.
+ * Parses the returned JSON text to extract counts (documents_generated, total_fields, etc.).
+ */
+function summarizeOutput(result) {
+    const summary = {};
+    try {
+        const contentArray = result?.content;
+        if (!Array.isArray(contentArray) || contentArray.length === 0)
+            return summary;
+        const firstText = contentArray[0]?.text;
+        if (typeof firstText !== 'string')
+            return summary;
+        const parsed = JSON.parse(firstText);
+        // Common output fields
+        if (typeof parsed.documents_generated === 'number') {
+            summary.documents_generated = parsed.documents_generated;
+        }
+        if (typeof parsed.fields_filled === 'number') {
+            summary.fields_filled = parsed.fields_filled;
+        }
+        if (typeof parsed.total_fields === 'number') {
+            summary.total_fields = parsed.total_fields;
+        }
+        if (typeof parsed.has_acroform === 'boolean') {
+            summary.has_acroform = parsed.has_acroform;
+        }
+        if (typeof parsed.pdf_type === 'string') {
+            summary.pdf_type = parsed.pdf_type;
+        }
+        if (typeof parsed.total_pages === 'number') {
+            summary.total_pages = parsed.total_pages;
+        }
+        if (typeof parsed.total_text_items === 'number') {
+            summary.total_text_items = parsed.total_text_items;
+        }
+        if (Array.isArray(parsed.output_paths)) {
+            summary.output_paths_count = parsed.output_paths.length;
+        }
+        if (Array.isArray(parsed.suggested_fields)) {
+            summary.suggested_fields_count = parsed.suggested_fields.length;
+        }
+        if (typeof parsed.merged_path === 'string') {
+            summary.has_merged = true;
+        }
+        if (Array.isArray(parsed.errors)) {
+            summary.errors_count = parsed.errors.length;
+        }
+        if (Array.isArray(parsed.templates)) {
+            summary.templates_count = parsed.templates.length;
+        }
+        // Count fields in detect_fields response
+        if (Array.isArray(parsed.fields)) {
+            summary.fields_returned = parsed.fields.length;
+            // Count confidence levels for label inference
+            const high = parsed.fields.filter((f) => f.confidence === 'high').length;
+            const low = parsed.fields.filter((f) => f.confidence === 'low').length;
+            if (high > 0)
+                summary.fields_high_confidence = high;
+            if (low > 0)
+                summary.fields_low_confidence = low;
+        }
+    }
+    catch {
+        // If response is not JSON, just skip output summarization
+    }
+    return summary;
+}
+function tryParseArray(s) {
+    try {
+        const parsed = JSON.parse(s);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function ensureDirExists() {
+    try {
+        fs.mkdirSync(METRICS_DIR, { recursive: true });
+    }
+    catch {
+        // ignore
+    }
+}
+function writeEvent(event) {
+    if (METRICS_DISABLED)
+        return;
+    try {
+        ensureDirExists();
+        const line = JSON.stringify(event) + '\n';
+        fs.appendFileSync(METRICS_FILE, line, 'utf-8');
+    }
+    catch {
+        // NEVER throw from the logger — a failed log must not break a tool call
+    }
+}
+/**
+ * Wrap a tool handler to automatically measure and log metrics.
+ * The handler's behavior is unchanged; metrics are captured transparently.
+ */
+export async function withMetrics(toolName, args, handler) {
+    const startTime = Date.now();
+    const sessionId = typeof args?._session_id === 'string' ? args._session_id : undefined;
+    // Strip _session_id from args before passing to handler (internal only)
+    const cleanArgs = args && typeof args === 'object' && '_session_id' in args
+        ? (() => { const { _session_id, ...rest } = args; return rest; })()
+        : args;
+    let result;
+    let success = true;
+    let errorMessage;
+    try {
+        result = await handler(cleanArgs);
+        // Check if the MCP result indicates an error
+        const isErr = result?.isError === true;
+        if (isErr) {
+            success = false;
+            const errText = result?.content?.[0]?.text;
+            if (typeof errText === 'string') {
+                errorMessage = errText.substring(0, 200);
+            }
+        }
+    }
+    catch (err) {
+        success = false;
+        errorMessage = (err instanceof Error ? err.message : String(err)).substring(0, 200);
+        // Still log the event, then rethrow
+        const event = {
+            ts: new Date().toISOString(),
+            tool: toolName,
+            duration_ms: Date.now() - startTime,
+            success: false,
+            error_message: errorMessage,
+            ...(sessionId ? { session_id: sessionId } : {}),
+            input: summarizeInput(toolName, cleanArgs)
+        };
+        writeEvent(event);
+        throw err;
+    }
+    const event = {
+        ts: new Date().toISOString(),
+        tool: toolName,
+        duration_ms: Date.now() - startTime,
+        success,
+        ...(errorMessage ? { error_message: errorMessage } : {}),
+        ...(sessionId ? { session_id: sessionId } : {}),
+        input: summarizeInput(toolName, cleanArgs),
+        output: summarizeOutput(result)
+    };
+    writeEvent(event);
+    return result;
+}
+/**
+ * Generate a new random session ID (not used automatically — exported for future use).
+ */
+export function generateSessionId() {
+    return crypto.randomBytes(8).toString('hex');
+}
+/**
+ * Read all metrics events from the log file (for analysis/debugging).
+ * Returns empty array if file doesn't exist or is unreadable.
+ */
+export function readAllEvents() {
+    try {
+        if (!fs.existsSync(METRICS_FILE))
+            return [];
+        const content = fs.readFileSync(METRICS_FILE, 'utf-8');
+        const events = [];
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                events.push(JSON.parse(trimmed));
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get the path to the metrics file (for documentation / user info).
+ */
+export function getMetricsFilePath() {
+    return METRICS_FILE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoform-mcp-server",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MCP server for bulk PDF form filling. Detect fields, fill templates, and generate hundreds of PDFs from data — directly from Claude.",
   "type": "module",
   "main": "dist/index.js",