🔧 Debugging FluentCommunity API Integration

🎓 Key Lesson: Always Check the API Routes File

The Problem: The MCP tool was sending PUT requests, but FluentCommunity’s API routes only registered POST for updates.

Evidence from api.php:

// Line 42: FluentCommunity API routes
Route::post('/{spaceSlug}/feeds/{feedId}', [FeedsController::class, 'patchBySlug']);

The Fix: Changed the plugin route registration to accept POST instead of PUT.

// Before (v1.5.5)
array(
    'methods' => 'PUT',
    'callback' => 'fmcp_rest_update_post',
)

// After (v1.5.6)
array(
    'methods' => 'POST',  // Changed to POST
    'callback' => 'fmcp_rest_update_post',
)

🎓 Key Lesson: API Documentation Can Be Wrong – Check the Controller

The Problem: Official API docs said to use message parameter, but the controller expected comment.

Evidence from CommentsController.php:

// Line 165: validateCommentText method
protected function validateCommentText($request)
{
    $comment = $request->get('comment');  // Expects 'comment', not 'message'!
    
    if (!$comment) {
        return new \WP_Error('invalid_comment', __('Comment text is required'));
    }
    // ...
}

The Fix: Added parameter mapping in the proxy function to convert message → comment.

// Added to fmcp_map_parameters_for_fluentcommunity()
if (strpos($endpoint, 'comments') !== false) {
    if (isset($params['message']) && !isset($params['comment'])) {
        $params['comment'] = $params['message'];
        unset($params['message']);
    }
}

🎓 Key Lesson: Use Debug Logging to See Actual Request Data

The Problem: We were guessing what parameters the MCP tool was sending. Adding debug logging revealed the truth.

Debug Output (v1.6.7):

=== UPDATE COMMENT - INCOMING REQUEST ===
All params: {"id":"5","message":"Test"}
Route: /fc-manager/v1/comments/5
Method: PUT
URL params: {"id":"5"}
Body params: {}
Extracted comment_id: 5
Extracted post_id:   // EMPTY! MCP tool doesn't send it!

Database Error:

WordPress database error Table 'iwpdfd6_fcom_comments' doesn't exist
// Should be 'fcom_post_comments'!

The Fix (3 parts):

1. Auto-lookup post_id from database:

if (!$post_id) {
    global $wpdb;
    $table = $wpdb->prefix . 'fcom_post_comments';  // Correct table name
    $post_id = $wpdb->get_var($wpdb->prepare(
        "SELECT post_id FROM $table WHERE id = %d",
        $comment_id
    ));
    
    if (!$post_id) {
        return new WP_Error('comment_not_found', 'Comment not found', array('status' => 404));
    }
}

2. Accept both PUT and POST methods:

register_rest_route($namespace, '/comments/(?P\d+)', array(
    array(
        'methods' => array('PUT', 'POST'),  // Accept both
        'callback' => 'fmcp_rest_update_comment',
    ),
));

3. Use the proxy function (not manual request building):

// Simple and clean - proxy handles everything
return fmcp_proxy_to_fluentcommunity(
    $request, 
    'feeds/' . $post_id . '/comments/' . $comment_id, 
    'POST'
);

🎓 Key Lesson: Always Use the API, Never Direct Database Access

The Problem: The function was doing direct database inserts, bypassing FluentCommunity’s validation and hooks.

Before (v1.5.7):

// BAD: Direct database access
global $wpdb;
$table = $wpdb->prefix . 'fcom_space_user';
$wpdb->insert($table, array(
    'space_id' => $space_id,
    'user_id' => $user_id,
    'role' => $role
));

After (v1.5.8):

// GOOD: Use the API endpoint
$slug = fmcp_get_space_slug_by_id($space_id);
return fmcp_proxy_to_fluentcommunity(
    $request, 
    'spaces/' . $slug . '/members', 
    'POST'
);

🎓 Key Lesson: Update BOTH the VERSION File AND Plugin Header

The Problem: We were updating the VERSION file but not the plugin header comment.

What WordPress Reads:

/**
 * Plugin Name: FluentMCP
 * Version: 1.6.2  // ← WordPress reads THIS, not the VERSION file!
 * Author: 1WD LLC
 */

The Fix: Update both locations in every release.

// 1. Update plugin header
sed -i 's/Version: 1.6.9/Version: 1.7.0/' fluent-mcp.php

// 2. Update VERSION file
echo "1.7.0" > VERSION

// 3. Create release
zip -r fluent-mcp-v1.7.0.zip fluent-mcp.php VERSION CHANGELOG.md

1. Create a Test Sandbox Script

Instead of creating 15 plugin versions, we should have created a standalone test script first:

// test-api.php - Direct API testing
$auth = base64_encode("username:password");
$context = stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => "Authorization: Basic $auth\r\nContent-Type: application/json\r\n",
        'content' => json_encode(['comment' => 'Test'])
    ]
]);
$response = file_get_contents("https://site.com/wp-json/fluent-community/v2/feeds/56/comments/5", false, $context);
echo $response;

2. Add Comprehensive Debug Logging

Log EVERYTHING about the incoming request:

error_log('=== DEBUG ===');
error_log('All params: ' . json_encode($request->get_params()));
error_log('Method: ' . $request->get_method());
error_log('Route: ' . $request->get_route());
error_log('Body: ' . json_encode($request->get_body_params()));
error_log('URL params: ' . json_encode($request->get_url_params()));

3. Test Directly Against the API

Use PowerShell/curl to bypass the plugin and test the actual FluentCommunity API:

# PowerShell direct test
$auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("user:pass"))
Invoke-RestMethod -Uri "https://site.com/wp-json/fluent-community/v2/feeds/56/comments/5" `
    -Method Post `
    -Headers @{Authorization="Basic $auth"} `
    -Body (@{comment="Test"} | ConvertTo-Json) `
    -ContentType "application/json"

4. Read the Source Code, Not Just the Docs

The official API documentation was WRONG about parameter names. Always verify in the controller:

• ✅ Check api.php for routes and HTTP methods
• ✅ Check Controller.php for parameter names and validation
• ✅ Check Migrations/ for database table names
• ❌ Don’t trust documentation alone