Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/documents.ts:805-843 (handler)

  Core handler function implementing the get_document_collaboration tool logic: validates input, fetches document and collaborations, retrieves activity if requested, analyzes patterns, and returns structured response with collaborators, activity, and statistics.

  export const getDocumentCollaboration = requireAuth(async (args: any) => {
    const { document_id, include_activity, time_range } = GetDocumentCollaborationSchema.parse(args)
    
    logger.info('Getting document collaboration', { document_id, time_range })
  
    const document = await supabaseService.getDocument(document_id)
    if (!document) {
      throw new Error('Document not found')
    }
  
    // Get collaborators
    const collaborations = await supabaseService.getDocumentCollaborations(document_id)
    
    // Get activity if requested
    let activity = []
    if (include_activity) {
      activity = await getDocumentActivity(document_id, time_range)
    }
  
    // Analyze collaboration patterns
    const collaborationStats = analyzeCollaborationPatterns(collaborations, activity)
  
    return {
      document: {
        id: document.id,
        title: document.title,
        created_by: document.created_by
      },
      collaborators: collaborations.map(c => ({
        user_id: c.user_id,
        permission_level: c.permission_level,
        status: c.status,
        joined_at: c.invited_at,
        last_activity: activity.filter(a => a.user_id === c.user_id)[0]?.timestamp
      })),
      activity: activity.slice(0, 50), // Limit to 50 recent activities
      statistics: collaborationStats
    }
  })

• src/tools/documents.ts:799-803 (schema)

  Zod schema used for input validation in the getDocumentCollaboration handler.

  const GetDocumentCollaborationSchema = z.object({
    document_id: z.string().min(1),
    include_activity: z.boolean().default(true),
    time_range: z.enum(['day', 'week', 'month', 'all']).default('week')
  })

• src/tools/documents.ts:773-797 (registration)

  MCPTool registration object defining the tool's metadata, name, description, and input schema for the MCP system.

  export const getDocumentCollaborationTool: MCPTool = {
    name: 'get_document_collaboration',
    description: 'Get collaboration history and current collaborators for a document',
    inputSchema: {
      type: 'object',
      properties: {
        document_id: {
          type: 'string',
          description: 'ID of the document'
        },
        include_activity: {
          type: 'boolean',
          default: true,
          description: 'Whether to include recent activity'
        },
        time_range: {
          type: 'string',
          enum: ['day', 'week', 'month', 'all'],
          default: 'week',
          description: 'Time range for activity'
        }
      },
      required: ['document_id']
    }
  }

• src/tools/documents.ts:1346-1358 (registration)

  Registration of the getDocumentCollaboration handler function in the exported documentHandlers object, mapping tool name to implementation.

  export const documentHandlers = {
    list_documents: listDocuments,
    create_document: createDocument,
    get_document: getDocument,
    update_document: updateDocument,
    search_documents: searchDocuments,
    get_document_context: getDocumentContext,
    add_document_collaborator: addDocumentCollaborator,
    analyze_document_content: analyzeDocumentContent,
    get_document_collaboration: getDocumentCollaboration,
    generate_document_template: generateDocumentTemplate,
    bulk_document_operations: bulkDocumentOperations
  }

• src/tools/documents.ts:1219-1232 (helper)

  Helper function called by the handler to analyze collaboration statistics and patterns.

  function analyzeCollaborationPatterns(collaborations: any[], activity: any[]): any {
    return {
      total_collaborators: collaborations.length,
      active_collaborators: collaborations.filter(c => c.status === 'active').length,
      permission_distribution: {
        read: collaborations.filter(c => c.permission_level === 'read').length,
        comment: collaborations.filter(c => c.permission_level === 'comment').length,
        edit: collaborations.filter(c => c.permission_level === 'edit').length,
        admin: collaborations.filter(c => c.permission_level === 'admin').length
      },
      recent_activity_count: activity.length,
      collaboration_health: collaborations.length > 0 && activity.length > 0 ? 'active' : 'low'
    }
  }