feat: add compact mode to strip null/empty values from responses

Adds stripEmpty() utility that recursively removes null and "" values
from all MCP tool responses by default, reducing token usage ~15-20%.
false is preserved (semantic meaning). Agents can pass compact=false
for raw data on 7 data-heavy GET tools.

- Extract stripEmpty() to src/utils/compact.js
- Apply via wrapHandler() on all 28 tools
- Add compact parameter to list/get tools for forms, entries, feeds
- Add 17 unit tests for compact utility
- Update AGENTS.md, CLAUDE.md with compact documentation

Author: zackkatz

AGENTS.md

@@ -39,6 +39,7 @@ gravitymcp/
 │   │   ├── field-validation.js  # FieldAwareValidator for field-specific rules
 │   │   └── test-config.js    # Dual test/live environment config, TestFormManager
 │   ├── utils/
+│   │   ├── compact.js        # stripEmpty() — recursive null/empty/false stripping for token optimization
 │   │   ├── logger.js         # MCP-safe logger (stderr in MCP mode, console in test)
 │   │   └── sanitize.js       # Credential masking for safe logging
 │   └── tests/
@@ -59,6 +60,7 @@ gravitymcp/
 │       ├── field-registry.test.js       # Field registry tests
 │       ├── field-operations-e2e.test.js # Field operations E2E
 │       ├── field-operations-integration.test.js # Field ops integration
+│       ├── compact.test.js             # stripEmpty compact utility tests
 │       └── sanitize.test.js            # Sanitization tests
 ├── scripts/
 │   ├── check-env.js          # Environment validation script
@@ -121,6 +123,7 @@ Responses are optimized for minimal token usage:
 - **Compact JSON**: `JSON.stringify(result)` — no pretty-printing (no `null, 2`) — `src/index.js:114`
 - **Minimal payloads**: No redundant `message`, `created`/`updated` booleans, or echo-back of input IDs. GET methods return `{ resource: data }`, mutations return only what can't be inferred (e.g., delete returns `{ deleted: true, id, permanently }`)
 - **Summary/detail modes**: `gf_list_field_types` defaults to summary mode (`type`, `label`, `category` only). Pass `detail=true` for full metadata (supports, storage, validation, icon). Pass `include_variants=true` with `detail=true` for variant data.
+- **Compact mode (default on)**: `stripEmpty()` (`utils/compact.js`) recursively removes `null` and `""` values from all responses via `wrapHandler()`. `false` is preserved (semantic meaning, e.g. `is_active: false`). `"0"`/`"1"` strings are preserved (GF boolean pattern). Data-heavy GET tools expose a `compact` parameter — pass `compact=false` for raw unstripped data.
 - **Concise tool descriptions**: All 28 tool descriptions and property descriptions are terse to reduce tool-list overhead
 
 ### Tool Categories

CLAUDE.md

@@ -4,7 +4,7 @@ You MUST fully ingest @AGENTS.md first.
 
 ## Project Identity
 
-- **Package:** `@gravitykit/gravitymcp` v1.1.0
+- **Package:** `@gravitykit/gravitymcp` v1.2.0
 - **Type:** Node.js MCP server (ESM)
 - **Purpose:** Full Gravity Forms REST API v2 coverage via 28 MCP tools
 - **Repo:** https://github.com/GravityKit/GravityMCP
@@ -35,3 +35,4 @@ Required env vars (see `.env.example` for full list):
 5. **Update operations fetch-then-merge** — always GET existing data first to avoid data loss
 6. **Minimize response tokens** — no pretty-print (`JSON.stringify(result)` not `null, 2`), no redundant `message` strings, no echo-back of input IDs, no `created`/`updated` booleans. Return only essential data.
 7. **Keep tool descriptions terse** — every token in tool schemas is sent on every `tools/list` call
+8. **Compact mode strips null and empty strings** — `stripEmpty()` in `utils/compact.js` runs on all responses by default. `false` is preserved (semantic meaning). Agents pass `compact=false` for raw data.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitykit/gravitymcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Full-featured MCP server for Gravity Forms",
   "main": "src/index.js",
   "type": "module",
@@ -23,6 +23,7 @@
     "test:validation": "node src/tests/validation.test.js",
     "test:field-validation": "node src/tests/field-validation.test.js",
     "test:tools": "node src/tests/server-tools.test.js",
+    "test:compact": "node src/tests/compact.test.js",
     "test:all": "npm run test:unit && npm run test:auth && npm run test:forms && npm run test:entries && npm run test:feeds && npm run test:submissions && npm run test:validation && npm run test:field-validation && npm run test:tools && npm test",
     "test:coverage": "echo 'Running all tests with coverage analysis' && npm run test:all"
   },

src/index.js

@@ -21,6 +21,7 @@ import fieldRegistry from './field-definitions/field-registry.js';
 import FieldAwareValidator from './config/field-validation.js';
 import logger from './utils/logger.js';
 import { sanitize } from './utils/sanitize.js';
+import { stripEmpty } from './utils/compact.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -78,6 +79,10 @@ async function initializeClient() {
   }
 }
 
+/**
+ * Recursively strip null, empty string, and false values from objects/arrays.
+ * Reduces token usage by removing noise like empty field values and absent meta keys.
+ */
 /**
  * Create standard error response
  */
@@ -94,29 +99,29 @@ function createErrorResponse(message, details = null) {
 }
 
 /**
- * Wrap async handler with error handling
+ * Wrap async handler with error handling and response compaction.
+ * @param {Function} handler - async function returning result object
+ * @param {object} params - tool params; if compact !== false, strips null/empty/false values
  */
-function wrapHandler(handler) {
-  return async (params) => {
+function wrapHandler(handler, params = {}) {
+  return async () => {
     if (!gravityFormsClient) {
       return createErrorResponse('Gravity Forms client not initialized');
     }
 
     try {
-      const result = await handler(params);
+      const result = await handler();
+      const output = params.compact !== false ? stripEmpty(result) : result;
 
-      // MCP expects content to be an array of content blocks
-      // Each block should have a type (usually "text") and the actual content
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(result)
+            text: JSON.stringify(output)
           }
         ]
       };
     } catch (error) {
-      // Sanitize error details to prevent logging sensitive data
       const safeDetails = error.details ? sanitize(error.details) : undefined;
       console.error(`Tool error: ${error.message}`);
       return createErrorResponse(error.message, safeDetails);
@@ -134,25 +139,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       // Forms Management (6 tools)
       {
         name: 'gf_list_forms',
-        description: 'List all forms',
+        description: 'List all forms. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
             include: {
               type: 'array',
               items: { type: 'number' },
               description: 'Form IDs to include'
-            }
+            },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           }
         }
       },
       {
         name: 'gf_get_form',
-        description: 'Get a form by ID',
+        description: 'Get a form by ID. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
-            id: { type: 'number', description: 'Form ID' }
+            id: { type: 'number', description: 'Form ID' },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           },
           required: ['id']
         }
@@ -228,7 +235,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       // Entries Management (6 tools)
       {
         name: 'gf_list_entries',
-        description: 'List/search entries with filtering',
+        description: 'List/search entries. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -292,17 +299,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 page_size: { type: 'number' },
                 current_page: { type: 'number' }
               }
-            }
+            },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           }
         }
       },
       {
         name: 'gf_get_entry',
-        description: 'Get an entry by ID',
+        description: 'Get an entry by ID. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
-            id: { type: 'number', description: 'Entry ID' }
+            id: { type: 'number', description: 'Entry ID' },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           },
           required: ['id']
         }
@@ -404,33 +413,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       // Add-on Feeds (7 tools)
       {
         name: 'gf_list_feeds',
-        description: 'List feeds',
+        description: 'List feeds. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
             addon: { type: 'string', description: 'Addon slug' },
-            form_id: { type: 'number', description: 'Form ID' }
+            form_id: { type: 'number', description: 'Form ID' },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           }
         }
       },
       {
         name: 'gf_get_feed',
-        description: 'Get a feed by ID',
+        description: 'Get a feed by ID. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
-            id: { type: 'number', description: 'Feed ID' }
+            id: { type: 'number', description: 'Feed ID' },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           },
           required: ['id']
         }
       },
       {
         name: 'gf_list_form_feeds',
-        description: 'List feeds for a form',
+        description: 'List feeds for a form. Omits null/empty values by default; pass compact=false for raw data.',
         inputSchema: {
           type: 'object',
           properties: {
-            form_id: { type: 'number', description: 'Form ID' }
+            form_id: { type: 'number', description: 'Form ID' },
+            compact: { type: 'boolean', description: 'Strip null/empty values (default true)', default: true }
           },
           required: ['form_id']
         }
@@ -537,61 +549,61 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   switch (name) {
     // Forms Management
     case 'gf_list_forms':
-      return wrapHandler(() => gravityFormsClient.listForms(params))();
+      return wrapHandler(() => gravityFormsClient.listForms(params), params)();
     case 'gf_get_form':
-      return wrapHandler(() => gravityFormsClient.getForm(params))();
+      return wrapHandler(() => gravityFormsClient.getForm(params), params)();
     case 'gf_create_form':
-      return wrapHandler(() => gravityFormsClient.createForm(params))();
+      return wrapHandler(() => gravityFormsClient.createForm(params), params)();
     case 'gf_update_form':
-      return wrapHandler(() => gravityFormsClient.updateForm(params))();
+      return wrapHandler(() => gravityFormsClient.updateForm(params), params)();
     case 'gf_delete_form':
-      return wrapHandler(() => gravityFormsClient.deleteForm(params))();
+      return wrapHandler(() => gravityFormsClient.deleteForm(params), params)();
     case 'gf_validate_form':
-      return wrapHandler(() => gravityFormsClient.validateForm(params))();
+      return wrapHandler(() => gravityFormsClient.validateForm(params), params)();
 
     // Entries Management
     case 'gf_list_entries':
-      return wrapHandler(() => gravityFormsClient.listEntries(params))();
+      return wrapHandler(() => gravityFormsClient.listEntries(params), params)();
     case 'gf_get_entry':
-      return wrapHandler(() => gravityFormsClient.getEntry(params))();
+      return wrapHandler(() => gravityFormsClient.getEntry(params), params)();
     case 'gf_create_entry':
-      return wrapHandler(() => gravityFormsClient.createEntry(params))();
+      return wrapHandler(() => gravityFormsClient.createEntry(params), params)();
     case 'gf_update_entry':
-      return wrapHandler(() => gravityFormsClient.updateEntry(params))();
+      return wrapHandler(() => gravityFormsClient.updateEntry(params), params)();
     case 'gf_delete_entry':
-      return wrapHandler(() => gravityFormsClient.deleteEntry(params))();
+      return wrapHandler(() => gravityFormsClient.deleteEntry(params), params)();
 
     // Form Submissions
     case 'gf_submit_form_data':
-      return wrapHandler(() => gravityFormsClient.submitFormData(params))();
+      return wrapHandler(() => gravityFormsClient.submitFormData(params), params)();
     case 'gf_validate_submission':
-      return wrapHandler(() => gravityFormsClient.validateSubmission(params))();
+      return wrapHandler(() => gravityFormsClient.validateSubmission(params), params)();
 
     // Notifications
     case 'gf_send_notifications':
-      return wrapHandler(() => gravityFormsClient.sendNotifications(params))();
+      return wrapHandler(() => gravityFormsClient.sendNotifications(params), params)();
 
     // Add-on Feeds
     case 'gf_list_feeds':
-      return wrapHandler(() => gravityFormsClient.listFeeds(params))();
+      return wrapHandler(() => gravityFormsClient.listFeeds(params), params)();
     case 'gf_get_feed':
-      return wrapHandler(() => gravityFormsClient.getFeed(params))();
+      return wrapHandler(() => gravityFormsClient.getFeed(params), params)();
     case 'gf_list_form_feeds':
-      return wrapHandler(() => gravityFormsClient.listFormFeeds(params))();
+      return wrapHandler(() => gravityFormsClient.listFormFeeds(params), params)();
     case 'gf_create_feed':
-      return wrapHandler(() => gravityFormsClient.createFeed(params))();
+      return wrapHandler(() => gravityFormsClient.createFeed(params), params)();
     case 'gf_update_feed':
-      return wrapHandler(() => gravityFormsClient.updateFeed(params))();
+      return wrapHandler(() => gravityFormsClient.updateFeed(params), params)();
     case 'gf_patch_feed':
-      return wrapHandler(() => gravityFormsClient.patchFeed(params))();
+      return wrapHandler(() => gravityFormsClient.patchFeed(params), params)();
     case 'gf_delete_feed':
-      return wrapHandler(() => gravityFormsClient.deleteFeed(params))();
+      return wrapHandler(() => gravityFormsClient.deleteFeed(params), params)();
 
     // Utilities
     case 'gf_get_field_filters':
-      return wrapHandler(() => gravityFormsClient.getFieldFilters(params))();
+      return wrapHandler(() => gravityFormsClient.getFieldFilters(params), params)();
     case 'gf_get_results':
-      return wrapHandler(() => gravityFormsClient.getResults(params))();
+      return wrapHandler(() => gravityFormsClient.getResults(params), params)();
 
     // Field Operations - Intelligent field management
     case 'gf_add_field':
@@ -600,28 +612,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           throw new Error('Field operations not initialized');
         }
         return await fieldOperationHandlers.gf_add_field(params, fieldOperations);
-      })();
+      }, params)();
     case 'gf_update_field':
       return wrapHandler(async () => {
         if (!fieldOperations) {
           throw new Error('Field operations not initialized');
         }
         return await fieldOperationHandlers.gf_update_field(params, fieldOperations);
-      })();
+      }, params)();
     case 'gf_delete_field':
       return wrapHandler(async () => {
         if (!fieldOperations) {
           throw new Error('Field operations not initialized');
         }
         return await fieldOperationHandlers.gf_delete_field(params, fieldOperations);
-      })();
+      }, params)();
     case 'gf_list_field_types':
       return wrapHandler(async () => {
         if (!fieldOperations) {
           throw new Error('Field operations not initialized');
         }
         return await fieldOperationHandlers.gf_list_field_types(params, fieldOperations);
-      })();
+      }, params)();
 
     default:
       return createErrorResponse(`Unknown tool: ${name}`);