fix(fields): accept custom and third-party field types in gf_add_field

gf_add_field threw "Unknown field type" for any type not in the static 46-key registry, rejecting third-party fields (Gravity Perks, Gravity Wiz, etc.) that Gravity Forms itself accepts. The registry is now an enhancement, not a gate: unknown types are created with graceful degradation plus a warning. Also stop leaking the internal _unknown flag to Gravity Forms on form create/update, and align validateFieldConfig to tolerate unknown types. Convert the orphan field-operations-integration harness to exercise the real field-operations layer.

Bump 2.4.0 -> 2.4.1.

Claude-Session: https://claude.ai/code/session_01LJHfTpQknHFs1j5ayj7fpo

Author: zackkatz

AGENTS.md

@@ -6,7 +6,7 @@ This is the single canonical doc for the project (agents and humans). `CLAUDE.md
 
 ## Project Identity
 
-- **Package:** `@gravitykit/mcp` v2.4.0
+- **Package:** `@gravitykit/mcp` v2.4.1
 - **Type:** Node.js MCP server (ESM)
 - **Purpose:** Full Gravity Forms REST API v2 coverage (26 Gravity Forms tools), plus dynamic GravityKit product tools (GravityView so far) via the WordPress Abilities API
 - **Repo:** https://github.com/GravityKit/MCP

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to GravityKit MCP (formerly GravityMCP) will be documented i
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.1] - 2026-06-25
+
+This release lets the field tools work with custom and third-party field types, not just the ones built into Gravity Forms.
+
+### 🐛 Fixed
+- **`gf_add_field` now accepts custom and third-party field types.** Field types added by other plugins (Gravity Perks, Gravity Wiz, and similar add-ons) were previously rejected because they aren't in the built-in registry. They are now created normally, with a note when type-specific defaults or sub-inputs aren't available; pass `inputs`/`choices` explicitly for custom compound or choice fields.
+- **Unrecognized field types no longer leave an internal marker in saved forms** when creating or updating a form.
+
 ## [2.4.0] - 2026-06-19
 
 This update adds additional guards to make sure Gravity Forms entries save correctly for every field type, so an AI assistant gets the entry format right the first time. Adds explicit support for the `password` field type and Gravity Wiz Nested Forms, plus a benchmark suite that ensures the MCP works well with small models.
@@ -236,6 +244,7 @@ A correctness pass on the Gravity Forms (`gf_*`) plane, verified against Gravity
 - Field filters (1 tool)
 - Results/Analytics (1 tool)
 
+[2.4.1]: https://github.com/GravityKit/MCP/releases/tag/v2.4.1
 [2.4.0]: https://github.com/GravityKit/MCP/releases/tag/v2.4.0
 [2.3.0]: https://github.com/GravityKit/MCP/releases/tag/v2.3.0
 [2.2.0]: https://github.com/GravityKit/MCP/releases/tag/v2.2.0

mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "gravitykit-mcp",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "MCP server for Gravity Forms",
   "author": "GravityKit",
   "license": "MIT",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitykit/mcp",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Full-featured MCP server for Gravity Forms",
   "main": "src/index.js",
   "type": "module",

src/config/field-validation.js

@@ -89,10 +89,12 @@ export class FieldAwareValidator {
         logger.warn(`[FieldValidator] Unknown field type '${field.type}' at ${path}`);
       }
 
-      // Allow unknown types but mark them
+      // Allow unknown types (third-party add-ons, GravityKit, custom fields).
+      // Gravity Forms accepts them on save; pass the field through unchanged. No
+      // internal flag is added: it would be PUT verbatim and nothing reads it.
       return {
         isValid: true,
-        field: { ...field, _unknown: true }
+        field: { ...field }
       };
     }
 

src/field-definitions/field-registry.js

@@ -928,12 +928,12 @@ export function detectFieldVariant(field) {
  */
 export function validateFieldConfig(field) {
   const definition = fieldRegistry[field.type];
-  
+
+  // Unknown / third-party types are tolerated, not rejected (Gravity Forms
+  // accepts them on save). With no config schema to check them against there is
+  // nothing to validate, so report valid and let GF own it.
   if (!definition) {
-    return {
-      isValid: false,
-      error: `Unknown field type: ${field.type}`
-    };
+    return { isValid: true };
   }
 
   // Check required properties

src/field-operations/field-manager.js

@@ -27,48 +27,59 @@ export class FieldManager {
    * @returns {object} Field creation result with warnings
    */
   async addField(formId, fieldType, properties = {}, position = {}) {
-    // 1. Validate field type against registry
-    const fieldDef = this.registry[fieldType];
-    if (!fieldDef) {
-      throw new Error(`Unknown field type: ${fieldType}`);
-    }
+    // The registry is an ENHANCEMENT source, not a gate. Known types get
+    // type-specific defaults and sub-inputs. Unknown types (third-party add-ons,
+    // GravityKit, custom fields) are still created (Gravity Forms accepts them on
+    // save), just without those extras. Callers can pass `inputs`/`choices`
+    // explicitly for custom compound/choice fields.
+    const fieldDef = this.registry[fieldType] || null;
+    const isKnownType = fieldDef !== null;
 
-    // 2. Fetch current form via REST API
+    // Fetch current form via REST API
     const { form } = await this.api.getForm({ id: formId });
 
-    // 3. Generate unique integer field ID (max + 1 pattern)
+    // Generate unique integer field ID (max + 1 pattern)
     const fieldId = this.generateFieldId(form.fields || []);
 
-    // 4. Create field with type-specific defaults
-    const field = this.createField(fieldId, fieldType, properties, fieldDef);
-    
-    // 5. Generate compound sub-inputs if needed (address.1, name.3, etc.)
-    if (fieldDef.storage?.type === 'compound') {
+    // Create field with type-specific defaults (none for unknown types)
+    const field = this.createField(fieldId, fieldType, properties, fieldDef || {});
+
+    // Generate compound sub-inputs only for known compound types (address.1,
+    // name.3, …). Unknown types keep any caller-supplied `inputs` untouched.
+    const isCompoundType = fieldDef?.storage?.type === 'compound';
+    if (isCompoundType) {
       field.inputs = this.generateSubInputs(field, fieldDef);
     }
 
-    // 5b. Normalize layout grid properties (layoutGroupId, layoutGridColumnSpan)
+    // Normalize layout grid properties (layoutGroupId, layoutGridColumnSpan)
     this.normalizeLayoutProperties(field, formId);
 
-    // 6. Calculate insertion position (page-aware)
+    // Calculate insertion position (page-aware)
     const insertIndex = this.positionEngine?.calculatePosition(
       form.fields || [],
       position,
       form.pagination
     ) || form.fields?.length || 0;
 
-    // 7. Insert field at calculated position
+    // Insert field at calculated position
     if (!form.fields) form.fields = [];
     form.fields.splice(insertIndex, 0, field);
 
-    // 8. Replace form via direct PUT (no re-fetch — we already have the full state)
-    const updatedForm = await this.api.replaceForm(formId, form);
-    
-    // 9. Return result with validation warnings
+    // Replace form via direct PUT (no re-fetch; we already have the full state)
+    await this.api.replaceForm(formId, form);
+
+    // Surface field-shape warnings, plus a heads-up when the type is unrecognized.
+    const warnings = this.validator.getWarnings(field);
+    if (!isKnownType) {
+      warnings.unshift(
+        `Field type '${fieldType}' is not in the known field registry; created without type-specific defaults or sub-inputs. Pass 'inputs'/'choices' explicitly if this type needs them.`
+      );
+    }
+
     return {
       success: true,
       field: field,
-      warnings: this.validator.getWarnings(field),
+      warnings,
       form_id: formId,
       position: { 
         index: insertIndex, 

test/field-manager.test.js

@@ -225,17 +225,57 @@ test('FieldManager - addField', async (t) => {
     assert.strictEqual(result.position.index, 3);
   });
 
-  await t.test('rejects unknown field type', async () => {
+  // Custom / third-party field types (Gravity Perks, add-ons, GravityKit, the
+  // MailPot field a customer hit) are not in the static registry, yet Gravity
+  // Forms accepts them on the form PUT. addField must not gate on the registry;
+  // it degrades gracefully: create from caller properties, skip registry-derived
+  // defaults/sub-inputs, and warn.
+  await t.test('accepts an unknown field type instead of throwing', async () => {
     const apiClient = createMockApiClient();
     const registry = createMockRegistry();
     const validator = createMockValidator();
     const manager = new FieldManager(apiClient, registry, validator);
 
-    await assert.rejects(
-      async () => await manager.addField(1, 'unknown_type', {}),
-      /Unknown field type: unknown_type/
+    const result = await manager.addField(1, 'mailpot_custom', { label: 'Custom Field' });
+
+    assert.strictEqual(result.success, true);
+    assert.strictEqual(result.field.type, 'mailpot_custom');
+    assert.strictEqual(result.field.label, 'Custom Field');
+    assert.strictEqual(result.field.id, 4); // Next ID after 1,2,3
+  });
+
+  await t.test('warns when the field type is not in the registry', async () => {
+    const apiClient = createMockApiClient();
+    const registry = createMockRegistry();
+    const validator = createMockValidator();
+    const manager = new FieldManager(apiClient, registry, validator);
+
+    const result = await manager.addField(1, 'mailpot_custom', { label: 'Custom Field' });
+
+    assert.ok(Array.isArray(result.warnings));
+    assert.ok(
+      result.warnings.some((m) => /mailpot_custom/.test(m) && /registr/i.test(m)),
+      'expected a warning naming the unrecognized field type'
     );
   });
+
+  await t.test('preserves caller-supplied inputs for an unknown compound-like type', async () => {
+    const apiClient = createMockApiClient();
+    const registry = createMockRegistry();
+    const validator = createMockValidator();
+    const manager = new FieldManager(apiClient, registry, validator);
+
+    const result = await manager.addField(1, 'custom_compound', {
+      label: 'Custom Compound',
+      inputs: [{ id: '4.1', label: 'Part A' }, { id: '4.2', label: 'Part B' }]
+    });
+
+    assert.strictEqual(result.success, true);
+    assert.deepStrictEqual(result.field.inputs, [
+      { id: '4.1', label: 'Part A' },
+      { id: '4.2', label: 'Part B' }
+    ]);
+  });
 });
 
 test('FieldManager - updateField', async (t) => {