ISSUE_48_COMMENT_SUPPORT_SUMMARY.md

Comment Support Implementation Summary

Overview

Added comprehensive comment support to both coaiapy and coaiapy-mcp packages, enabling full access to Langfuse comment functionality for traces, observations, sessions, and prompts.

Changes Made

1. Enhanced coaiapy/cofuse.py (coaiapy:289-362)

Modified Functions:

get_comments() - Enhanced with filtering support

• New Parameters:
  • object_type: Filter by object type (trace, observation, session, prompt)
  • object_id: Filter by specific object ID (requires object_type)
  • author_user_id: Filter by author user ID
  • page: Page number (starts at 1, default=1)
  • limit: Items per page (default=50)
• Returns: JSON response with filtered comments

get_comment_by_id(comment_id) - New function

• Purpose: Retrieve specific comment by its unique ID
• Parameters: comment_id (required)
• Returns: JSON response with comment data

post_comment(text, object_type, object_id) - Enhanced with object attachment

• New Parameters:
  • object_type: Type of object to attach comment to
  • object_id: ID of the object to attach comment to
• Returns: JSON response with created comment data

2. Added MCP Tools (coaiapy-mcp/tools.py:521-689)

New Tool Functions:

coaia_fuse_comments_list() - List/filter comments

• Wraps get_comments() with MCP-compatible error handling
• Supports all filtering parameters
• Returns structured JSON response

coaia_fuse_comments_get(comment_id) - Get specific comment

• Wraps get_comment_by_id() with MCP error handling
• Returns parsed JSON or raw string with success status

coaia_fuse_comments_create(text, object_type, object_id) - Create comment

• Wraps post_comment() with MCP error handling
• Supports attaching to traces, observations, sessions, prompts

Tool Registry Updates:

• Added 3 new tools to TOOLS dict
• Updated __all__ export list

3. MCP Server Registration (coaiapy-mcp/server.py:223-263)

New Tool Definitions:

coaia_fuse_comments_list

{
  "name": "coaia_fuse_comments_list",
  "description": "List comments with optional filtering by object type/ID or author",
  "inputSchema": {
    "object_type": "string",
    "object_id": "string",
    "author_user_id": "string",
    "page": "integer (default: 1)",
    "limit": "integer (default: 50)"
  }
}

coaia_fuse_comments_get

{
  "name": "coaia_fuse_comments_get",
  "description": "Get a specific comment by ID",
  "inputSchema": {
    "comment_id": "string (required)"
  }
}

coaia_fuse_comments_create

{
  "name": "coaia_fuse_comments_create",
  "description": "Create a comment attached to an object",
  "inputSchema": {
    "text": "string (required)",
    "object_type": "string",
    "object_id": "string"
  }
}

API Compliance

All implementations match Langfuse OpenAPI spec (references/openapi.yml:517-693):

✅ GET /api/public/comments - List with filters (objectType, objectId, authorUserId, page, limit) ✅ GET /api/public/comments/{commentId} - Get by ID ✅ POST /api/public/comments - Create with object attachment

Usage Examples

Using coaiapy directly:

from coaiapy.cofuse import get_comments, get_comment_by_id, post_comment

# List all comments for a trace
comments = get_comments(object_type="trace", object_id="trace-123")

# Get specific comment
comment = get_comment_by_id("comment-456")

# Create comment on observation
new_comment = post_comment(
    text="Great performance!",
    object_type="observation",
    object_id="obs-789"
)

Using MCP tools:

# Via Claude Code or MCP-compatible client
await mcp__coaiapy__coaia_fuse_comments_list({
    "object_type": "trace",
    "object_id": "trace-123"
})

await mcp__coaiapy__coaia_fuse_comments_get({
    "comment_id": "comment-456"
})

await mcp__coaiapy__coaia_fuse_comments_create({
    "text": "Analysis complete",
    "object_type": "trace",
    "object_id": "trace-123"
})

Testing

All comment functionality is now exposed through:

1. Direct Python imports from coaiapy.cofuse
2. MCP tools via coaiapy-mcp server
3. Claude Code integration (if MCP server configured)

Files Modified

1. /src/coaiapy/coaiapy/cofuse.py - Enhanced comment functions (lines 289-362)
2. /src/coaiapy/coaiapy-mcp/coaiapy_mcp/tools.py - Added MCP tool wrappers (lines 20-32, 521-741)
3. /src/coaiapy/coaiapy-mcp/coaiapy_mcp/server.py - Registered MCP tools (lines 223-263)

Next Steps

• ✅ Test comment listing with filters
• ✅ Test comment creation on traces/observations
• ✅ Test comment retrieval by ID
• ✅ Verify MCP tool exposure in Claude Code
• 🔄 Add comment functionality to CLI (optional enhancement)
• 🔄 Add comment support to pipeline templates (optional enhancement)