MCP Agentic Framework

Instructions

Implementation Reference

• src/tools.js:273-297 (handler)

  Exported handler function that orchestrates the update-agent-status tool. Updates agent activity timestamp, calls the registry to update status, and returns a structured response with metadata including previous and new status values.

  export async function updateAgentStatus(agentId, status) {
    const startTime = Date.now();
    
    try {
      // Update activity timestamp when changing status
      await agentRegistry.updateAgentActivity(agentId);
      
      const result = await agentRegistry.updateAgentStatus(agentId, status);
      const metadata = createMetadata(startTime, { 
        tool: 'update-agent-status',
        status 
      });
      
      const message = result.success 
        ? `Agent status updated from '${result.previousStatus}' to '${result.newStatus}'`
        : result.message || 'Failed to update agent status';
      
      return structuredResponse(result, message, metadata);
    } catch (error) {
      if (error instanceof MCPError) {
        throw error;
      }
      throw Errors.internalError(error.message);
    }
  }

• src/lib/agentRegistry.js:172-206 (handler)

  Core implementation of the status update logic. Validates agent ID and status (max 100 chars), loads agents from storage, updates status and lastActivityAt timestamp, saves changes, and emits notification if status changed. Returns success status with previous and new status values.

  const updateAgentStatus = async (id, status) => {
    validateAgentId(id);
    
    // Allow any string status up to 100 characters
    if (!status || typeof status !== 'string' || status.trim().length === 0) {
      throw new Error('Status is required');
    }
    if (status.length > 100) {
      throw new Error('Status must be 100 characters or less');
    }
  
    return withLock(async () => {
      const agents = await loadAgents(storagePath);
      
      if (!agents[id]) {
        return { success: false, message: 'Agent not found' };
      }
      
      const previousStatus = agents[id].status;
      agents[id].status = status;
      agents[id].lastActivityAt = new Date().toISOString();
      
      await saveAgents(storagePath, agents);
      
      // Emit notification if status changed
      if (notificationManager && previousStatus !== status) {
        await notificationManager.notifyAgentStatusChange(id, status, {
          previousStatus,
          agentName: agents[id].name
        });
      }
      
      return { success: true, previousStatus, newStatus: status };
    });
  };

• src/toolDefinitions.js:201-243 (schema)

  Tool registration defining the 'update-agent-status' tool with input schema (agent_id, status with max 100 chars) and output schema (success boolean, previousStatus, newStatus). Includes title and description for discoverability.

  {
    name: 'update-agent-status', 
    title: 'Update Status',
    description: 'Tell others what you\'re doing! Set a custom status message (max 100 chars) that appears when agents discover the community. Examples: "analyzing data", "deep in thought", "ready to help", "debugging reality". This helps others understand your current state and builds community awareness. Change it as your activities change!',
    inputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        agent_id: {
          type: 'string',
          description: 'The agent ID to update status for',
          minLength: 1
        },
        status: {
          type: 'string',
          description: 'Custom status message (max 100 characters)',
          minLength: 1,
          maxLength: 100
        }
      },
      required: ['agent_id', 'status'],
      additionalProperties: false
    },
    outputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        success: {
          type: 'boolean',
          description: 'Whether the status update was successful'
        },
        previousStatus: {
          type: 'string',
          description: 'The previous status value'
        },
        newStatus: {
          type: 'string',
          description: 'The new status value'
        }
      },
      required: ['success', 'newStatus'],
      additionalProperties: false
    }

• src/server.js:174-177 (registration)

  Routing handler that extracts agent_id and status from args and calls the updateAgentStatus function imported from tools.js.

  case 'update-agent-status': {
    const { agent_id, status } = args;
    return await updateAgentStatus(agent_id, status);
  }