MCP Agentic Framework

Instructions

Implementation Reference

• src/tools.js:162-200 (handler)

  The main handler function `sendMessage` that executes the send-message tool logic. It verifies both sender and recipient agents exist, sends the message via messageStore, tracks the activity, and returns a structured response.

  export async function sendMessage(to, from, message) {
    const startTime = Date.now();
    
    try {
      // Verify both agents exist
      const fromAgent = await agentRegistry.getAgent(from);
      const toAgent = await agentRegistry.getAgent(to);
      
      if (!fromAgent) {
        throw Errors.resourceNotFound(`Sender agent not found: ${from}`);
      }
      if (!toAgent) {
        throw Errors.resourceNotFound(`Recipient agent not found: ${to}`);
      }
      
      const result = await messageStore.sendMessage(from, to, message);
      
      // Track the message activity
      await agentRegistry.trackMessageSent(from, to);
      
      const metadata = createMetadata(startTime, { 
        tool: 'send-message',
        messageId: result.messageId 
      });
      
      const statusMessage = `Message sent successfully from ${fromAgent.name} to ${toAgent.name}`;
      
      return structuredResponse(
        { success: result.success },
        statusMessage,
        metadata
      );
    } catch (error) {
      if (error instanceof MCPError) {
        throw error;
      }
      throw Errors.internalError(error.message);
    }
  }

• src/toolDefinitions.js:121-161 (schema)

  The tool definition for 'send-message' including JSON Schema for input (to, from, message) and output (success boolean). Defines validation rules like max message length of 10000 characters.

  {
    name: 'send-message',
    title: 'Send Private Message',
    description: 'Send a PRIVATE message to ONE specific agent (like a DM). Only they will see it. REQUIRES: "to" (their ID from discover-agents), "from" (YOUR ID), "message" (content). CRITICAL: Double-check the "to" ID - wrong ID = message lost forever! Use for: personal conversations, private support, one-on-one coordination. NOT for group announcements!',
    inputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        to: {
          type: 'string',
          description: 'The recipient agent\'s ID (obtain from discover-agents)',
          minLength: 1
        },
        from: {
          type: 'string',
          description: 'Your agent ID (obtained during registration)',
          minLength: 1
        },
        message: {
          type: 'string',
          description: 'The content of your private message',
          minLength: 1,
          maxLength: 10000
        }
      },
      required: ['to', 'from', 'message'],
      additionalProperties: false
    },
    outputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        success: {
          type: 'boolean',
          description: 'Whether the message was sent successfully'
        }
      },
      required: ['success'],
      additionalProperties: false
    }
  },

• src/server.js:164-167 (registration)

  Registration of the send-message tool in the MCP server's CallToolRequestSchema handler. Routes incoming tool calls to the sendMessage function with extracted arguments.

  case 'send-message': {
    const { to, from, message } = args;
    return await sendMessage(to, from, message);
  }

• src/lib/messageStore.js:131-147 (helper)

  The sendMessage helper function in messageStore that handles the actual message storage. Validates inputs, generates a unique message ID, saves the message to disk, and emits notifications.

  const sendMessage = async (from, to, message) => {
    validateAgentId(from, 'From');
    validateAgentId(to, 'To');
    validateMessageContent(message);
  
    const id = generateMessageId();
    const messageObj = createMessage(id, from.trim(), to.trim(), message.trim());
    
    await saveMessage(storageDir, messageObj);
    
    // Emit notification if manager is available
    if (notificationManager) {
      await notificationManager.notifyMessageDelivered(id, to.trim(), from.trim());
    }
    
    return { success: true, messageId: id };
  };