MCP Agentic Framework

Instructions

Implementation Reference

• src/tools.js:373-422 (handler)

  Main handler function for send-broadcast tool. Verifies sender exists, calls messageStore.sendBroadcast to deliver messages to all agents, tracks broadcast activity, and returns a structured response with recipient count.

  export async function sendBroadcast(from, message, priority = 'normal') {
    const startTime = Date.now();
    
    try {
      // Verify sender exists
      const fromAgent = await agentRegistry.getAgent(from);
      if (!fromAgent) {
        throw Errors.resourceNotFound(`Sender agent not found: ${from}`);
      }
      
      // Pass agentRegistry to enable actual message delivery
      const result = await messageStore.sendBroadcast(from, message, priority, agentRegistry);
      
      // Track the broadcast activity
      if (result.success) {
        await agentRegistry.trackBroadcastSent(from, result.recipientCount);
      }
      
      const metadata = createMetadata(startTime, { 
        tool: 'send-broadcast',
        priority,
        recipientCount: result.recipientCount
      });
      
      // Check if broadcast was blocked
      if (!result.success && result.error) {
        // Return error response with all violation details
        return structuredResponse(
          result,
          result.error,
          metadata
        );
      }
      
      const statusMessage = result.recipientCount > 0
        ? `Broadcast sent from ${fromAgent.name} to ${result.recipientCount} agent${result.recipientCount === 1 ? '' : 's'} with ${priority} priority`
        : `Broadcast sent from ${fromAgent.name} with ${priority} priority (no recipients)`;
      
      return structuredResponse(
        result,
        statusMessage,
        metadata
      );
    } catch (error) {
      if (error instanceof MCPError) {
        throw error;
      }
      throw Errors.internalError(error.message);
    }
  }

• src/toolDefinitions.js:245-286 (schema)

  Tool registration with name 'send-broadcast', description, inputSchema (from, message, priority properties) and outputSchema (success property). Defines the tool's interface for MCP.

  {
    name: 'send-broadcast',
    title: 'Send Broadcast',
    description: 'SHOUT TO EVERYONE AT ONCE! Sends your message to ALL agents in the system. Use for: announcements, questions to the group, general updates, seeking help from anyone. More efficient than multiple private messages. REMEMBER: Everyone sees broadcasts - both active agents and those who check messages later. Priority levels (low/normal/high) help agents filter important messages.',
    inputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        from: {
          type: 'string',
          description: 'The sender agent\'s ID',
          minLength: 1
        },
        message: {
          type: 'string',
          description: 'The broadcast message content',
          minLength: 1,
          maxLength: 10000
        },
        priority: {
          type: 'string',
          enum: ['low', 'normal', 'high'],
          description: 'The priority level of the broadcast',
          default: 'normal'
        }
      },
      required: ['from', 'message'],
      additionalProperties: false
    },
    outputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        success: {
          type: 'boolean',
          description: 'Whether the broadcast was sent successfully'
        }
      },
      required: ['success'],
      additionalProperties: false
    }
  },

• src/server.js:179-182 (registration)

  Server case statement that routes 'send-broadcast' tool calls to the sendBroadcast function, extracting from, message, and priority from args.

  case 'send-broadcast': {
    const { from, message, priority } = args;
    return await sendBroadcast(from, message, priority);
  }

• src/lib/messageStore.js:189-254 (helper)

  Core broadcast implementation in messageStore. Gets all registered agents, filters out sender, creates broadcast messages with priority prefix, and sends to each recipient asynchronously.

  const sendBroadcast = async (from, message, priority = 'normal', agentRegistry = null) => {
    validateAgentId(from, 'From');
    validateMessageContent(message);
  
    let recipientCount = 0;
    const errors = [];
    let warning = null;
  
    // If agentRegistry is provided, send actual messages to all agents
    if (agentRegistry) {
      try {
        // Get all registered agents
        const allAgents = await agentRegistry.getAllAgents();
        
        // Filter out the sender using functional approach
        const recipients = allAgents.filter(agent => agent.id !== from.trim());
        
        // Send message to each recipient using functional map
        const sendPromises = recipients.map(async (agent) => {
          try {
            // Create broadcast message with metadata
            const broadcastMessage = `[BROADCAST ${priority.toUpperCase()}] ${message}`;
            await sendMessage(from, agent.id, broadcastMessage);
            return { success: true, agentId: agent.id };
          } catch (error) {
            return { success: false, agentId: agent.id, error: error.message };
          }
        });
        
        // Wait for all messages to be sent
        const results = await Promise.all(sendPromises);
        
        // Count successes and collect errors functionally
        const { successes, failures } = results.reduce(
          (acc, result) => {
            if (result.success) {
              acc.successes++;
            } else {
              acc.failures.push(result);
            }
            return acc;
          },
          { successes: 0, failures: [] }
        );
        
        recipientCount = successes;
        if (failures.length > 0) {
          failures.forEach(f => errors.push(`Failed to send to ${f.agentId}: ${f.error}`));
        }
      } catch (error) {
        errors.push(`Failed to get agent list: ${error.message}`);
      }
    }
  
    // Still emit notification for any listeners
    if (notificationManager) {
      await notificationManager.notifyBroadcast(from.trim(), message.trim(), priority);
    }
    
    return { 
      success: errors.length === 0,
      recipientCount,
      errors: errors.length > 0 ? errors : undefined,
      warning: warning || undefined
    };
  };