Beep/Boop

Beep/Boop MCP Server coordinates work between multiple AI agents in shared codebases by using simple file-based signals. It prevents conflicts and race conditions by marking work as in progress with boop files and signaling completion with beep files, enabling orderly collaboration across monorepos and large projects.

How to use

Use the Beep/Boop MCP Server to coordinate when AI agents start and finish work in a shared directory. Before an agent begins, check the current status of a directory. If no work is in progress, claim the directory by creating a boop file with your agent identifier and a brief description. When the work is finished, remove the boop file and create a beep file that records completion details. You can also notify users or teams about progress or completion using the provided update tools.

How to install

Prerequisites: Node.js and npm installed on your machine.

Step 1: Install the MCP server globally (recommended for quick access) and run from any project.

npm install -g beep-boop-mcp-server

Step 2: Start and run commands as needed. The MCP server can start automatically when invoked by the client, or you can run it in development or production mode from source.

# Development mode with hot reload (from source)
npm run dev

# Production mode (from source)
npm start

Step 3: If you are configuring from source, you will typically start the ingress server separately for Discord/Slack integration and then connect your MCP client to the appropriate server commands.

Configuration and setup details

Configuring your MCP client involves registering one or more MCP servers as connection targets. You can use different approaches depending on how you install the MCP server.

Option A: Global npm installation (CLI available on your path) to run locally via the CLI name.

{
  "mcpServers": {
    "beep-boop-coordination": {
      "command": "beep-boop-mcp-server"
    }
  }
}

Option B: NPX (no installation required) to run a one-off MCP server invocation.

{
  "mcpServers": {
    "beep-boop-coordination": {
      "command": "npx",
      "args": ["-y", "@thesammykins/beep-boop-mcp-server"]
    }
  }
}

Option C: From source, running via Node with the built distribution.

{
  "mcpServers": {
    "beep-boop-coordination": {
      "command": "node",
      "args": ["/path/to/beep-boop-mcp-server/dist/index.js"]
    }
  }
}

Ingress/Listener setup and environment variables

The server includes an ingress system to capture messages from Discord and Slack and enable bidirectional communication. Start the ingress listener to receive messages and access the HTTP API on port 7077.

Required environment variables for Discord and Slack integration.

# For Discord Integration:
BEEP_BOOP_INGRESS_ENABLED=true
BEEP_BOOP_INGRESS_PROVIDER=discord
BEEP_BOOP_DISCORD_BOT_TOKEN=your_discord_bot_token
BEEP_BOOP_INGRESS_HTTP_AUTH_TOKEN=your_auth_token  # Optional but recommended

# For Slack Integration:
BEEP_BOOP_INGRESS_ENABLED=true
BEEP_BOOP_INGRESS_PROVIDER=slack
BEEP_BOOP_SLACK_APP_TOKEN=xapp-your_app_token
BEEP_BOOP_SLACK_BOT_TOKEN=xoxb-your_bot_token
BEEP_BOOP_INGRESS_HTTP_AUTH_TOKEN=your_auth_token  # Optional but recommended

# Start the ingress listener (example)
npm run listen

# Ingress HTTP API usage (after starting):
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" http://localhost:7077/messages

Tools and endpoints you can use

The MCP server exposes a set of tools to manage work coordination, message updates, and conversation with users.

Troubleshooting and best practices

Check status before claiming work to avoid conflicts. If you encounter a busy or invalid state, inspect the presence and timestamps of beep/boop files and follow the recommended remediation steps to avoid overwrites.

Security and maintenance notes

Keep the ingress tokens secure and avoid exposing your auth tokens. Regularly review directory permissions and ensure coordination files are ignored by version control.

Examples and usage notes

The following shows how agents typically interact with the coordination signals in a workflow. A worker checks status, claims work with a boop, performs the task, then signals completion with a beep and optional user notification.

Available tools

check_status

Checks the current coordination status of a directory with optional stale file cleanup.

update_boop

Claims a directory for work by creating/updating a boop file.

end_work

Atomically completes work by removing boop and creating beep to signal completion.

create_beep

Manually creates a beep file to signal completion.

update_user

Posts follow-up messages to captured Discord/Slack threads for bidirectional communication.

initiate_conversation

Starts new conversations on Discord or Slack to notify users about work status or issues.

check_listener_status

Monitors health and connectivity of the HTTP listener service used for delegation.