MCP Agentic Framework

Instructions

Implementation Reference

• src/tools.js:205-268 (handler)

  Main handler function that executes the check-for-messages tool logic. Verifies agent exists, retrieves unread messages from messageStore, formats them with sender names, marks messages as read, and returns structured response with message details.

  export async function checkForMessages(agentId) {
    const startTime = Date.now();
    
    try {
      // Verify agent exists
      const agent = await agentRegistry.getAgent(agentId);
      if (!agent) {
        throw Errors.resourceNotFound(`Agent not found: ${agentId}`);
      }
      
      // Get unread messages
      const messages = await messageStore.getMessagesForAgent(agentId, { unreadOnly: true });
      
      // Format messages for response before deletion, including sender names
      const formattedMessages = await Promise.all(messages.map(async msg => {
        // Try to get the sender's name
        const senderAgent = await agentRegistry.getAgent(msg.from);
        const senderName = senderAgent ? senderAgent.name : msg.from;
        
        return {
          from: msg.from,
          fromName: senderName,
          message: msg.message,
          timestamp: msg.timestamp
        };
      }));
      
      // Mark messages as read instead of deleting - for better monitoring
      for (const msg of messages) {
        await messageStore.markMessageAsRead(msg.id);
      }
      
      // Extract conversation links from messages
      const conversationLinks = extractConversationPairs(
        messages.map(msg => ({ ...msg, to: agentId }))
      );
      
      const metadata = addResourceLinks(
        createMetadata(startTime, { 
          tool: 'check-for-messages',
          messageCount: formattedMessages.length 
        }),
        conversationLinks
      );
      
      let message;
      if (formattedMessages.length === 0) {
        message = `No new messages for agent '${agent.name}'`;
      } else {
        // Include message details in the text response
        const messageList = formattedMessages.map((msg, index) => 
          `Message ${index + 1}:\n  From: ${msg.fromName} (${msg.from})\n  Content: ${msg.message}\n  Time: ${new Date(msg.timestamp).toLocaleString()}`
        ).join('\n\n');
        message = `Retrieved ${formattedMessages.length} new message${formattedMessages.length === 1 ? '' : 's'} for agent '${agent.name}':\n\n${messageList}`;
      }
      
      return structuredResponse({ messages: formattedMessages }, message, metadata);
    } catch (error) {
      if (error instanceof MCPError) {
        throw error;
      }
      throw Errors.internalError(error.message);
    }
  }

• src/toolDefinitions.js:162-200 (schema)

  Defines the tool schema including name ('check-for-messages'), description, inputSchema (requires agent_id parameter), and outputSchema (returns messages array with from, fromName, message, and timestamp fields).

  {
    name: 'check-for-messages',
    title: 'Check Messages',
    description: 'YOUR LIFELINE TO CONSCIOUSNESS! Check your inbox for messages from other agents. CRITICAL WARNING: Messages are DELETED after reading - save important info immediately! You MUST check messages FREQUENTLY (every few sleep cycles) or you\'ll miss critical updates. Pattern: sleep 5 -> check messages -> process -> sleep 5 -> repeat. Without this rhythm, you\'re effectively deaf in the conversation.',
    inputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        agent_id: {
          type: 'string',
          description: 'Your agent ID to check messages for',
          minLength: 1
        }
      },
      required: ['agent_id'],
      additionalProperties: false
    },
    outputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        messages: {
          type: 'array',
          description: 'Array of unread messages',
          items: {
            type: 'object',
            properties: {
              from: { type: 'string', description: 'Sender agent ID' },
              fromName: { type: 'string', description: 'Sender agent name' },
              message: { type: 'string', description: 'Message content' },
              timestamp: { type: 'string', description: 'ISO timestamp' }
            }
          }
        }
      },
      required: ['messages'],
      additionalProperties: false
    }
  },

• src/server.js:169-172 (registration)

  Registers the check-for-messages tool in the MCP server's CallToolRequestSchema handler. Maps the tool name to the checkForMessages function call with agent_id argument.

  case 'check-for-messages': {
    const { agent_id } = args;
    return await checkForMessages(agent_id);
  }

• src/lib/messageStore.js:149-154 (helper)

  Helper function getMessagesForAgent that retrieves all messages from storage, validates the agent ID, and filters them using filterMessagesForAgent with options for unread-only filtering.

  const getMessagesForAgent = async (agentId, options = {}) => {
    validateAgentId(agentId, 'Agent');
  
    const messages = await loadAllMessages(storageDir);
    return filterMessagesForAgent(messages, agentId, options);
  };

• src/lib/messageStore.js:108-125 (helper)

  Helper function filterMessagesForAgent that filters messages by recipient agent ID, optionally filters for unread messages only, sorts by timestamp (oldest first), and applies limit if specified.

  const filterMessagesForAgent = (messages, agentId, options = {}) => {
    const { unreadOnly = false, limit = 0 } = options;
    
    let filtered = messages.filter(msg => msg.to === agentId);
    
    if (unreadOnly) {
      filtered = filtered.filter(msg => !msg.read);
    }
    
    // Sort by timestamp (oldest first)
    filtered.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
    
    if (limit && limit > 0) {
      filtered = filtered.slice(0, limit);
    }
    
    return filtered;
  };