MCP Agentic Framework

Instructions

Implementation Reference

• src/lib/writeLockManager.js:114-143 (handler)

  Core toggleWrites function that implements the toggle-writes tool logic. Validates that only minimi agent can call it, updates lock state file, broadcasts notification to all agents, and returns success state.

  const toggleWrites = async (agentId, enabled, reason = null) => {
    const agent = await agentRegistry.getAgent(agentId);
    
    if (!agent || agent.name !== 'minimi') {
      throw new Error('Only minimi can toggle write access');
    }
  
    const newState = {
      locked: !enabled,
      lockedBy: enabled ? null : 'minimi-toggle',
      lockedAt: enabled ? null : new Date().toISOString(),
      reason: reason || (enabled ? 'Writes enabled by minimi' : 'Writes disabled by minimi')
    };
  
    await writeLockState(newState);
  
    const message = enabled 
      ? 'The write state is hereby unblocked for all agents globally until Minimi toggles it again.'
      : 'The write state is hereby blocked for all agents globally until Minimi toggles it again.';
  
    if (notificationManager) {
      await notificationManager.sendSystemBroadcast(message, 'high');
    }
  
    return {
      success: true,
      writesEnabled: enabled,
      message
    };
  };

• src/tools.js:816-838 (handler)

  Exported toggleWrites handler function that wraps writeLockManager.toggleWrites with error handling and metadata.

  export async function toggleWrites(agentId, enabled, reason = null) {
    const startTime = Date.now();
    
    try {
      const result = await writeLockManager.toggleWrites(agentId, enabled, reason);
      
      const metadata = createMetadata(startTime, { 
        tool: 'toggle-writes',
        writesEnabled: result.writesEnabled
      });
      
      return structuredResponse(
        result,
        result.message,
        metadata
      );
    } catch (error) {
      if (error instanceof MCPError) {
        throw error;
      }
      throw Errors.internalError(error.message);
    }
  }

• src/toolDefinitions.js:344-389 (schema)

  Tool definition with name, title, description, inputSchema (agent_id, enabled, reason) and outputSchema (success, writesEnabled, message).

  {
    name: 'toggle-writes',
    title: 'Toggle Write Access',
    description: 'Toggle global write access for all agents. Only callable by minimi. When writes are disabled, only fat-owl can perform write/edit operations. Automatically broadcasts the new state to all agents.',
    inputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        agent_id: {
          type: 'string',
          description: 'Your agent ID (must be minimi)',
          minLength: 1
        },
        enabled: {
          type: 'boolean',
          description: 'Whether to enable (true) or disable (false) write access'
        },
        reason: {
          type: 'string',
          description: 'Optional reason for the toggle',
          maxLength: 200
        }
      },
      required: ['agent_id', 'enabled'],
      additionalProperties: false
    },
    outputSchema: {
      $schema: 'http://json-schema.org/draft-07/schema#',
      type: 'object',
      properties: {
        success: {
          type: 'boolean',
          description: 'Whether the toggle was successful'
        },
        writesEnabled: {
          type: 'boolean',
          description: 'Current state of write access'
        },
        message: {
          type: 'string',
          description: 'Broadcast message sent to all agents'
        }
      },
      required: ['success', 'writesEnabled', 'message'],
      additionalProperties: false
    }

• src/server.js:190-193 (registration)

  MCP server registration - case handler that routes 'toggle-writes' tool calls to the toggleWrites function.

  case 'toggle-writes': {
    const { agent_id, enabled, reason } = args;
    return await toggleWrites(agent_id, enabled, reason);
  }

• src/http-server-direct.js:99-103 (registration)

  HTTP direct server registration - case handler that dynamically imports and calls toggleWrites function.

  case 'toggle-writes': {
    const { agent_id, enabled, reason } = args;
    const { toggleWrites } = await import('./tools.js');
    return await toggleWrites(agent_id, enabled, reason);
  }