feat: strip plugin entry meta from responses by default

Entry tools now strip plugin-added meta keys (gv_revision_*,
helpscout_conversation_id, conversion_bridge_session, etc.) by default,
keeping only core GF properties and numbered field values. Pass
compact=false for full raw data including all entry meta.

- Add stripEntryMeta() and stripEntryMetaFromResponse() to compact.js
- Apply to gf_list_entries, gf_get_entry, gf_create_entry, gf_update_entry
- Add 6 new tests (23 compact tests total)
- Bump to v1.2.0

Author: zackkatz

AGENTS.md

@@ -123,7 +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.
+- **Compact mode (default on)**: `stripEmpty()` (`utils/compact.js`) recursively removes `null` and `""` values from all responses via `wrapHandler()`. `false` is preserved (semantic meaning). Entry tools also strip plugin-added meta keys (e.g., `gv_revision_*`, `helpscout_conversation_id`) via `stripEntryMeta()`, keeping only core properties and numbered field values. Pass `compact=false` for full raw data.
 - **Concise tool descriptions**: All 28 tool descriptions and property descriptions are terse to reduce tool-list overhead
 
 ### Tool Categories

CLAUDE.md

@@ -35,4 +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.
+8. **Compact mode strips null, empty strings, and entry meta** — `stripEmpty()` in `utils/compact.js` runs on all responses. Entry tools also strip plugin-added meta keys via `stripEntryMeta()`, keeping only core properties and field values. `false` is preserved. Pass `compact=false` for full raw data.

src/index.js

@@ -21,7 +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';
+import { stripEmpty, stripEntryMetaFromResponse } from './utils/compact.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -235,7 +235,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       // Entries Management (6 tools)
       {
         name: 'gf_list_entries',
-        description: 'List/search entries. Omits null/empty values by default; pass compact=false for raw data.',
+        description: 'List/search entries. Strips null/empty values and plugin entry meta by default; pass compact=false for full raw data.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -306,7 +306,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'gf_get_entry',
-        description: 'Get an entry by ID. Omits null/empty values by default; pass compact=false for raw data.',
+        description: 'Get an entry by ID. Strips null/empty values and plugin entry meta by default; pass compact=false for full raw data.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -563,13 +563,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     // Entries Management
     case 'gf_list_entries':
-      return wrapHandler(() => gravityFormsClient.listEntries(params), params)();
+      return wrapHandler(async () => {
+        const result = await gravityFormsClient.listEntries(params);
+        return params.compact !== false ? stripEntryMetaFromResponse(result) : result;
+      }, params)();
     case 'gf_get_entry':
-      return wrapHandler(() => gravityFormsClient.getEntry(params), params)();
+      return wrapHandler(async () => {
+        const result = await gravityFormsClient.getEntry(params);
+        return params.compact !== false ? stripEntryMetaFromResponse(result) : result;
+      }, params)();
     case 'gf_create_entry':
-      return wrapHandler(() => gravityFormsClient.createEntry(params), params)();
+      return wrapHandler(async () => {
+        const result = await gravityFormsClient.createEntry(params);
+        return params.compact !== false ? stripEntryMetaFromResponse(result) : result;
+      }, params)();
     case 'gf_update_entry':
-      return wrapHandler(() => gravityFormsClient.updateEntry(params), params)();
+      return wrapHandler(async () => {
+        const result = await gravityFormsClient.updateEntry(params);
+        return params.compact !== false ? stripEntryMetaFromResponse(result) : result;
+      }, params)();
     case 'gf_delete_entry':
       return wrapHandler(() => gravityFormsClient.deleteEntry(params), params)();
 

src/tests/compact.test.js

@@ -7,7 +7,7 @@
  * Preserves: false, 0, "0"
  */
 
-import { stripEmpty } from '../utils/compact.js';
+import { stripEmpty, stripEntryMeta, stripEntryMetaFromResponse } from '../utils/compact.js';
 import { TestRunner, TestAssert } from './helpers.js';
 
 const runner = new TestRunner('Compact Utility Tests');
@@ -220,6 +220,123 @@ runner.test('stripEmpty: does not mutate original object', () => {
   TestAssert.equal(Object.keys(input).length, 3, 'original key count unchanged');
 });
 
+// --- stripEntryMeta ---
+
+runner.test('stripEntryMeta: keeps core properties and field values', () => {
+  const entry = {
+    id: '123',
+    form_id: '29',
+    status: 'active',
+    date_created: '2024-01-15',
+    date_updated: '2024-01-15',
+    is_starred: '0',
+    is_read: '0',
+    ip: '127.0.0.1',
+    source_url: 'https://example.com',
+    user_agent: 'node',
+    currency: 'USD',
+    created_by: '1',
+    '2': 'test@example.com',
+    '3': 'some survey value',
+    '6': '21621',
+    gv_revision_parent_id: false,
+    gv_revision_date: false,
+    gv_revision_date_gmt: false,
+    gv_revision_user_id: false,
+    gv_revision_changed: false,
+    helpscout_conversation_id: false,
+    conversion_bridge_session: false
+  };
+  const result = stripEntryMeta(entry);
+
+  // Core properties kept
+  TestAssert.equal(result.id, '123', 'id kept');
+  TestAssert.equal(result.form_id, '29', 'form_id kept');
+  TestAssert.equal(result.status, 'active', 'status kept');
+  TestAssert.equal(result.created_by, '1', 'created_by kept');
+  TestAssert.equal(result.currency, 'USD', 'currency kept');
+
+  // Field values kept
+  TestAssert.equal(result['2'], 'test@example.com', 'field 2 kept');
+  TestAssert.equal(result['3'], 'some survey value', 'field 3 kept');
+  TestAssert.equal(result['6'], '21621', 'field 6 kept');
+
+  // Plugin meta stripped
+  TestAssert.equal(result.gv_revision_parent_id, undefined, 'gv_revision_parent_id stripped');
+  TestAssert.equal(result.gv_revision_date, undefined, 'gv_revision_date stripped');
+  TestAssert.equal(result.helpscout_conversation_id, undefined, 'helpscout_conversation_id stripped');
+  TestAssert.equal(result.conversion_bridge_session, undefined, 'conversion_bridge_session stripped');
+});
+
+runner.test('stripEntryMeta: keeps compound field keys (dot notation)', () => {
+  const entry = {
+    id: '456',
+    form_id: '5',
+    status: 'active',
+    '5.1': '123 Main St',
+    '5.2': 'Apt 4',
+    '5.3': 'Springfield',
+    '5.4': 'IL',
+    '5.5': '62701',
+    some_plugin_meta: 'value'
+  };
+  const result = stripEntryMeta(entry);
+  TestAssert.equal(result['5.1'], '123 Main St', 'compound field 5.1 kept');
+  TestAssert.equal(result['5.3'], 'Springfield', 'compound field 5.3 kept');
+  TestAssert.equal(result.some_plugin_meta, undefined, 'plugin meta stripped');
+});
+
+runner.test('stripEntryMeta: keeps payment fields when present', () => {
+  const entry = {
+    id: '789',
+    form_id: '10',
+    status: 'active',
+    payment_status: 'Paid',
+    payment_amount: '49.99',
+    payment_method: 'stripe',
+    transaction_id: 'txn_123',
+    custom_addon_field: 'noise'
+  };
+  const result = stripEntryMeta(entry);
+  TestAssert.equal(result.payment_status, 'Paid', 'payment_status kept');
+  TestAssert.equal(result.payment_amount, '49.99', 'payment_amount kept');
+  TestAssert.equal(result.transaction_id, 'txn_123', 'transaction_id kept');
+  TestAssert.equal(result.custom_addon_field, undefined, 'custom addon stripped');
+});
+
+// --- stripEntryMetaFromResponse ---
+
+runner.test('stripEntryMetaFromResponse: handles entries array', () => {
+  const response = {
+    entries: [
+      { id: '1', form_id: '5', status: 'active', '2': 'val', plugin_meta: 'x' },
+      { id: '2', form_id: '5', status: 'active', '3': 'val', plugin_meta: 'y' }
+    ],
+    total_count: 2
+  };
+  const result = stripEntryMetaFromResponse(response);
+  TestAssert.equal(result.entries.length, 2, 'array length preserved');
+  TestAssert.equal(result.total_count, 2, 'total_count preserved');
+  TestAssert.equal(result.entries[0].plugin_meta, undefined, 'meta stripped from first');
+  TestAssert.equal(result.entries[1].plugin_meta, undefined, 'meta stripped from second');
+  TestAssert.equal(result.entries[0]['2'], 'val', 'field value kept in first');
+});
+
+runner.test('stripEntryMetaFromResponse: handles single entry', () => {
+  const response = {
+    entry: { id: '1', form_id: '5', status: 'active', '2': 'val', plugin_meta: 'x' }
+  };
+  const result = stripEntryMetaFromResponse(response);
+  TestAssert.equal(result.entry.plugin_meta, undefined, 'meta stripped');
+  TestAssert.equal(result.entry['2'], 'val', 'field value kept');
+});
+
+runner.test('stripEntryMetaFromResponse: passes through non-entry responses', () => {
+  const response = { forms: [{ id: 1 }] };
+  const result = stripEntryMetaFromResponse(response);
+  TestAssert.equal(result.forms[0].id, 1, 'non-entry response unchanged');
+});
+
 // Run tests
 runner.run().then(results => {
   process.exit(results.failed > 0 ? 1 : 0);

src/utils/compact.js

@@ -27,4 +27,55 @@ export function stripEmpty(obj) {
   return obj;
 }
 
-export default { stripEmpty };
+/**
+ * Core entry properties returned by the GF REST API.
+ * Everything else is plugin-added entry meta (stripped by default).
+ */
+const CORE_ENTRY_KEYS = new Set([
+  'id', 'form_id', 'post_id', 'date_created', 'date_updated',
+  'is_starred', 'is_read', 'ip', 'source_url', 'user_agent',
+  'currency', 'payment_status', 'payment_date', 'payment_amount',
+  'payment_method', 'transaction_id', 'is_fulfilled', 'created_by',
+  'transaction_type', 'status', 'source_id'
+]);
+
+/**
+ * Test if a key is a field value (numeric or dot-notation like "5.1").
+ */
+function isFieldKey(key) {
+  return /^\d+(\.\d+)?$/.test(key);
+}
+
+/**
+ * Strip plugin-added entry meta from an entry object.
+ * Keeps core properties and numbered field values.
+ * @param {object} entry - Single entry object
+ * @returns {object} Entry with only core + field keys
+ */
+export function stripEntryMeta(entry) {
+  const result = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if (CORE_ENTRY_KEYS.has(key) || isFieldKey(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Strip entry meta from a response containing entries.
+ * Handles both { entries: [...] } and { entry: {...} } shapes.
+ * @param {object} response - Tool response object
+ * @returns {object} Response with entry meta stripped
+ */
+export function stripEntryMetaFromResponse(response) {
+  if (response.entries && Array.isArray(response.entries)) {
+    return { ...response, entries: response.entries.map(stripEntryMeta) };
+  }
+  if (response.entry && typeof response.entry === 'object') {
+    return { ...response, entry: stripEntryMeta(response.entry) };
+  }
+  return response;
+}
+
+export default { stripEmpty, stripEntryMeta, stripEntryMetaFromResponse };