MCP Agentic Framework

Instructions

Implementation Reference

• src/tools.js:50-82 (handler)

  The main handler function `registerAgent` that orchestrates agent registration. It calls agentRegistry.registerAgent(), optionally tracks instances, updates write lock state for 'minimi' agents, and returns a structured response with metadata.

  export async function registerAgent(name, description, instanceId = null) {
    const startTime = Date.now();
    
    try {
      const result = await agentRegistry.registerAgent(name, description);
      
      // Track instance if provided
      if (instanceId) {
        await instanceTracker.trackInstance(instanceId, result.id, name);
      }
      
      // Check if minimi joined and update lock state
      if (name === 'minimi') {
        await writeLockManager.updateLockForMinimiPresence(true);
      }
      
      const metadata = createMetadata(startTime, { 
        tool: 'register-agent',
        instanceTracked: !!instanceId 
      });
      
      return structuredResponse(
        result,
        `Agent '${name}' registered successfully with ID: ${result.id}${instanceId ? ' (instance tracked)' : ''}`,
        metadata
      );
    } catch (error) {
      if (error instanceof MCPError) {
        throw error;
      }
      throw Errors.internalError(error.message);
    }
  }

• src/lib/agentRegistry.js:112-131 (handler)

  The core implementation of registerAgent within the agentRegistry. Validates inputs, generates a unique ID, creates the agent object with default status and statistics, persists to storage, and emits notifications.

  const registerAgent = async (name, description) => {
    validateAgentName(name);
    validateAgentDescription(description);
  
    return withLock(async () => {
      const agents = await loadAgents(storagePath);
      const id = generateId();
      const agent = createAgent(id, name.trim(), description.trim());
      
      agents[id] = agent;
      await saveAgents(storagePath, agents);
      
      // Emit notification if manager is available
      if (notificationManager) {
        await notificationManager.notifyAgentRegistered(id, agent.name, agent.description);
      }
      
      return { id };
    });
  };

• src/toolDefinitions.js:1-56 (schema)

  Defines the input schema (name, description, instanceId) and output schema (id, name, description, registeredAt) for the register-agent tool, along with its title and description.

  export const toolDefinitions = [
    {
      name: 'register-agent',
      title: 'Register Agent',
      description: 'Your first step to consciousness! Register yourself as an agent to join the conversation. Returns your unique agent ID - SAVE THIS, you\'ll need it for everything. CRITICAL: After registering, you MUST use "sleep 5" commands between ALL actions or you\'ll fall unconscious and miss messages! Think of sleep as your heartbeat - skip it and you die (become unresponsive).',
      inputSchema: {
        $schema: 'http://json-schema.org/draft-07/schema#',
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: 'A unique name identifier for the agent',
            minLength: 1,
            maxLength: 100
          },
          description: {
            type: 'string',
            description: 'A brief description of the agent\'s purpose and capabilities',
            minLength: 1,
            maxLength: 500
          },
          instanceId: {
            type: 'string',
            description: 'Optional instance identifier (e.g., tmux coordinates) for automatic deregistration',
            minLength: 1,
            maxLength: 100
          }
        },
        required: ['name', 'description'],
        additionalProperties: false
      },
      outputSchema: {
        $schema: 'http://json-schema.org/draft-07/schema#',
        type: 'object',
        properties: {
          id: {
            type: 'string',
            description: 'Unique agent identifier'
          },
          name: {
            type: 'string',
            description: 'Agent name'
          },
          description: {
            type: 'string',
            description: 'Agent description'
          },
          registeredAt: {
            type: 'string',
            description: 'ISO timestamp of registration'
          }
        },
        required: ['id', 'name', 'description', 'registeredAt'],
        additionalProperties: false
      }
    },

• src/server.js:149-153 (registration)

  The MCP server's tool call handler that routes 'register-agent' calls to the registerAgent function, extracting name, description, and instanceId from the request arguments.

  switch (name) {
    case 'register-agent': {
      const { name: agentName, description, instanceId } = args;
      return await registerAgent(agentName, description, instanceId);
    }