Beep Boop MCP

Instructions

Implementation Reference

• src/tools.ts:93-154 (handler)

  The main handler function for the create_beep tool that validates input, checks current work status, creates the beep file, and returns appropriate responses.

  export async function handleCreateBeep(params: CreateBeepParams): Promise<ToolResponse> {
    try {
      const { directory, message } = params;
      const config = loadConfig();
      
      // Validate directory access
      try {
        validateDirectoryAccess(directory, config);
      } catch (accessError) {
        if (accessError instanceof CoordinationError) {
          return {
            content: [{
              type: "text",
              text: `❌ ${accessError.message}`
            }],
            isError: true
          };
        }
        throw accessError;
      }
      
      // Check current status first
      const status = await getWorkStatus(directory);
      
      if (status.status === WorkState.WORK_IN_PROGRESS) {
        return {
          content: [{
            type: "text",
            text: `⚠️ Cannot create beep file: Work is currently in progress by agent ${status.agentId}. Use end_work tool instead.`
          }],
          isError: true
        };
      }
  
      await createBeepFile(directory, message, undefined, config);
      
      return {
        content: [{
          type: "text", 
          text: `✅ Beep file created successfully in ${directory}. Work is now marked as complete and cleared for new work.`
        }]
      };
    } catch (error) {
      if (error instanceof CoordinationError) {
        return {
          content: [{
            type: "text",
            text: `❌ ${error.message} (${error.code})`
          }],
          isError: true
        };
      }
      
      return {
        content: [{
          type: "text",
          text: `❌ Unexpected error creating beep file: ${error}`
        }],
        isError: true
      };
    }
  }

• src/tools.ts:33-39 (schema)

  Zod schema defining the input parameters for the create_beep tool: directory (required string) and message (optional string).

  /**
   * Schema for create_beep tool parameters
   */
  export const CreateBeepSchema = z.object({
    directory: z.string().describe('Directory path where to create the beep file'),
    message: z.string().optional().describe('Optional completion message')
  });

• src/index.ts:35-45 (registration)

  MCP server registration of the create_beep tool, linking the schema and handler function.

  server.registerTool(
    'create_beep',
    {
      title: 'Create Beep File',
      description: 'Creates a beep file to signal that work is complete and the directory is cleared for new work. Use this when work is finished but no boop file exists.',
      inputSchema: CreateBeepSchema.shape
    },
    async (params) => {
      return await handleCreateBeep(params);
    }
  );

• src/file-operations.ts:112-152 (helper)

  Low-level helper function that creates the actual beep file with JSON metadata including completion timestamp, message, and optional completer agent.

  export async function createBeepFile(directory: string, message?: string, completedBy?: string, config?: BeepBoopConfig): Promise<void> {
    try {
      // Verify directory exists
      await fs.access(directory);
      
      const beepPath = join(directory, BEEP_FILE);
      const content: BeepFileContent = {
        completedAt: new Date(),
        message: message || 'Work completed',
        completedBy
      };
      
      await fs.writeFile(beepPath, JSON.stringify(content, null, 2));
      
      // Ensure .gitignore entries if configured
      if (config) {
        await ensureGitIgnoreEntries(directory, config);
      }
    } catch (error) {
      if (error instanceof Error) {
        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
          throw new CoordinationError(
            `Directory not found: ${directory}`, 
            ErrorCode.DIRECTORY_NOT_FOUND, 
            directory
          );
        } else if ((error as NodeJS.ErrnoException).code === 'EACCES') {
          throw new CoordinationError(
            `Permission denied: ${directory}`, 
            ErrorCode.PERMISSION_DENIED, 
            directory
          );
        }
      }
      throw new CoordinationError(
        `Failed to create beep file: ${error}`, 
        ErrorCode.FILE_SYSTEM_ERROR, 
        directory
      );
    }
  }