🤖👈 Beep/Boop 👉🤖 MCP Server

A Model Context Protocol (MCP) server for coordinating work between multiple AI agents in monorepos and shared codebases using a simple file-based signaling system.

🎯 Overview

The Beep/Boop coordination system prevents conflicts when multiple AI agents work in the same codebase by using two simple file types:

• beep - Signals work is complete and directory is clear for new work
• boop - Signals work is in progress by a specific agent

This prevents race conditions, merge conflicts, and ensures orderly collaboration between agents.

📦 Installation

From NPM (Recommended)

npm install -g @thesammykins/beep-boop-mcp-server

Note: Package is automatically published via GitHub Actions when changes are pushed to main.

From Source

git clone https://github.com/thesammykins/beep_boop_mcp.git
cd beep_boop_mcp
npm install
npm run build

🚀 Quick Start

1. Start the MCP Server

For NPM Installation

The server starts automatically when called by your MCP client. No manual startup required.

For Source Installation

# Development mode with hot reload
npm run dev

# Production mode
npm start

2. Configure Your MCP Client

Add to your MCP client configuration (e.g., Claude Desktop):

For Global NPM Installation

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

For NPX (No Installation Required)

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

For Source Installation

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

3. Use in Your AI Agent Workflows

// Always check before starting work
const status = await mcpClient.callTool('check_status', {
  directory: './src/components'
});

// Claim the directory
await mcpClient.callTool('update_boop', {
  directory: './src/components',
  agentId: 'my-agent-id',
  workDescription: 'Refactoring components'
});

// Do your work...

// Signal completion
await mcpClient.callTool('end_work', {
  directory: './src/components',
  agentId: 'my-agent-id',
  message: 'Refactoring complete'
});

🔧 API Reference

Tools

check_status

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

Parameters:

• directory (string): Path to directory to check
• maxAgeHours (number, optional): Maximum age in hours before boop files are considered stale (default: 24)
• autoCleanStale (boolean, optional): Whether to automatically clean up stale boop files (default: false)
• newAgentId (string, optional): Agent ID to use when claiming after stale cleanup
• newWorkDescription (string, optional): Work description when claiming after cleanup

Returns:

• Detailed status including file existence, agent info, age information, and next steps
• Automatic cleanup of stale files when requested

Examples:

Basic status check:

{
  "directory": "./src/auth"
}

Check with automatic stale cleanup and claim:

{
  "directory": "./src/auth",
  "maxAgeHours": 8,
  "autoCleanStale": true,
  "newAgentId": "claude-assistant-2",
  "newWorkDescription": "Continuing work after stale cleanup"
}

update_boop

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

Parameters:

• directory (string): Directory to claim
• agentId (string): Your unique agent identifier
• workDescription (string, optional): Description of planned work

Returns:

• Success confirmation or conflict warning

end_work

Atomically completes work by removing boop file and creating beep file.

Parameters:

• directory (string): Directory where work was completed
• agentId (string): Agent identifier that did the work
• message (string, optional): Completion message

Returns:

• Confirmation of successful work completion

create_beep

Manually creates a beep file to signal work completion.

Parameters:

• directory (string): Directory to mark as complete
• message (string, optional): Completion message

Returns:

• Confirmation beep file was created

update_user

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

Parameters:

• messageId (string): ID of the captured message to respond to
• updateContent (string): Message content to send as an update

Returns:

• Confirmation that the update was posted to the original platform

Use Cases:

• Agent progress reports back to original Discord/Slack thread
• Status updates during long-running tasks
• Error notifications and recovery updates
• Task completion confirmations

initiate_conversation

Proactively starts new conversations on Discord or Slack, enabling agents to notify users about work status, errors, or completion.

Parameters:

• platform ("discord" | "slack"): Target platform for the conversation
• channelId (string, optional): Channel ID to send message to (uses default if omitted)
• content (string): Initial message content to send
• agentId (string, optional): Agent ID for attribution

Returns:

• Conversation details including message ID for follow-up updates
• User response details if a reply is received within timeout period
• Timeout notification if no user response within configured time limit

Conversation Flow Configuration:

• BEEP_BOOP_CONVERSATION_TIMEOUT_MINUTES (default: 5) – How long to wait for user responses
• BEEP_BOOP_CONVERSATION_POLL_INTERVAL_MS (default: 2000) – How often to check for responses
• BEEP_BOOP_DISCORD_API_RETRY_ATTEMPTS (default: 3) – Retry attempts for Discord API failures
• BEEP_BOOP_DISCORD_API_RETRY_BASE_DELAY_MS (default: 1000) – Base retry delay with exponential backoff
• BEEP_BOOP_DISCORD_API_TIMEOUT_MS (default: 30000) – Individual Discord API call timeout

Use Cases:

• Notify users about completed background work
• Alert about system issues or failures discovered during routine checks
• Report completion of scheduled tasks or maintenance
• Send proactive status updates for long-running processes
• Alert users when manual intervention is needed

check_listener_status

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

Parameters:

• includeConfig (boolean, optional): Whether to include detailed configuration info

Returns:

• Configuration overview (enabled/disabled status, URLs, timeouts)
• Connectivity test results (health check, MCP endpoint verification)
• Optional detailed configuration when requested

Use Cases:

• Verify ingress service connectivity before delegation
• Troubleshoot communication issues with centralized listener
• Debug listener configuration problems
• Health checks for distributed agent systems
• Validate webhook and bot token configuration

📡 Ingress/Listener System

The Beep/Boop MCP Server includes a powerful ingress system that captures messages from Discord and Slack, enabling bidirectional communication between AI agents and users.

Message Capture Workflow

1. Discord/Slack Bot receives mentions or messages in configured channels
2. Message Storage saves captured messages to .beep-boop-inbox/messages/
3. HTTP API provides programmatic access to captured messages (port 7077)
4. Agent Processing handles messages via MCP tools and posts updates using update_user
5. Message Acknowledgment moves processed messages to processed/ directory

Quick Setup

Start Ingress Server

# Start the ingress listener
npm run listen

# Server will start on http://localhost:7077

Required Environment Variables

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      # Socket Mode required
BEEP_BOOP_SLACK_BOT_TOKEN=xoxb-your_bot_token      # Bot token with proper scopes
BEEP_BOOP_INGRESS_HTTP_AUTH_TOKEN=your_auth_token  # Optional but recommended

HTTP API Endpoints

Once the ingress server is running on port 7077, you can interact with captured messages:

# List all captured messages
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
     http://localhost:7077/messages

# Get specific message details
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
     http://localhost:7077/messages/MESSAGE_ID

# Acknowledge/process a message (moves to processed/)
curl -X POST -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
     http://localhost:7077/messages/MESSAGE_ID/ack

Message Format

Captured messages are stored as JSON with rich metadata:

{
  "id": "uuid-string",
  "platform": "discord" | "slack",
  "content": "@bot-name please help me deploy the application",
  "author": "username",
  "channel": {
    "id": "channel_id",
    "name": "general"
  },
  "timestamp": "2024-08-20T10:30:00.000Z",
  "replyContext": {
    // Platform-specific reply information for update_user
  }
}

Integration with Coordination

The ingress system works seamlessly with beep/boop coordination:

// Agent receives Discord/Slack message asking for deployment
const message = await getMessageFromInbox(messageId);

// Check if deployment directory is available
const status = await mcpClient.callTool('check_status', {
  directory: './deploy'
});

if (status.includes('WORK_IN_PROGRESS')) {
  // Notify user that deployment is already in progress
  await mcpClient.callTool('update_user', {
    messageId: message.id,
    updateContent: "Deployment already in progress by another agent. Will queue your request."
  });
  return;
}

// Claim deployment directory and notify user
await mcpClient.callTool('update_boop', {
  directory: './deploy',
  agentId: 'deploy-agent',
  workDescription: 'Production deployment'
});

await mcpClient.callTool('update_user', {
  messageId: message.id,
  updateContent: "🚀 Starting deployment process. I'll update you with progress..."
});

// Perform deployment work...

// Complete work and notify
await mcpClient.callTool('end_work', {
  directory: './deploy',
  agentId: 'deploy-agent',
  message: 'Production deployment completed successfully'
});

await mcpClient.callTool('update_user', {
  messageId: message.id,
  updateContent: "✅ Deployment completed successfully! Application is now live."
});

Bot Setup Requirements

Discord Bot Permissions:

• Guild Messages Intent
• Message Content Intent
• Send Messages permission in target channels

Slack App Configuration:

• Socket Mode enabled with app-level token
• Bot token with app_mentions:read and chat:write scopes
• Event subscriptions for app_mention events

See docs/INGRESS.md and docs/SCOPES_INTENTS.md for detailed setup instructions.

🏗️ Architecture

File Format

Beep File (beep)

{
  "completedAt": "2024-08-20T10:30:00.000Z",
  "message": "Refactoring completed successfully",
  "completedBy": "claude-assistant"
}

Boop File (boop)

{
  "startedAt": "2024-08-20T10:00:00.000Z",
  "agentId": "claude-assistant",
  "workDescription": "Refactoring authentication components"
}

State Machine

┌─────────────────┐    ┌─────────────────┐
│  NO_COORDINATION │───▶│  WORK_IN_PROGRESS │
│   (no files)    │    │   (boop exists)   │
└─────────────────┘    └─────────────────┘
         ▲                        │
         │                        ▼
┌─────────────────┐    ┌─────────────────┐
│   WORK_ALLOWED  │◀───│   end_work()    │
│  (beep exists)  │    │                 │
└─────────────────┘    └─────────────────┘

Error States

• INVALID_STATE: Both beep and boop files exist (requires manual cleanup)
• WORK_ALREADY_IN_PROGRESS: Another agent has claimed the directory
• AGENT_MISMATCH: Wrong agent trying to end work

🎯 Best Practices

Directory Granularity

• ✅ Good: ./src/auth-service/, ./packages/ui-components/
• ❌ Too granular: ./src/auth-service/login.ts
• ❌ Too broad: ./src/ (entire source)

Agent ID Guidelines

• Use descriptive, unique identifiers: claude-assistant-1, gpt4-refactor-bot
• Avoid generic names: agent, ai, assistant
• Include version/instance info for disambiguation

Git Integration

• ✅ Automatic .gitignore: Coordination files are automatically added to .gitignore
• ✅ Repository Clean: beep and boop files won't be committed to version control
• ⚙️ Configurable: Use BEEP_BOOP_MANAGE_GITIGNORE=false to disable if needed
• 🔧 Smart Detection: Only adds entries if they don't already exist

Error Handling

• Always check status before claiming work
• Provide graceful fallbacks when directories are busy
• Never force-override another agent's coordination files

🔍 Troubleshooting

Common Issues

"Directory is busy" - Another agent is working

# Check who's working
check_status -> shows agentId and timestamps

# Options:
# 1. Wait for work to complete
# 2. Work in different directory  
# 3. If boop file is stale (>30min), alert user

"Invalid state" - Both beep and boop exist

# Manual intervention required
# Check file timestamps and contents
# Remove appropriate file based on actual state

Permission errors

• Verify directory exists and is writable
• Check file system permissions
• Agent may need elevated access

Debug Mode

NODE_ENV=development npm start

Log Files

Server logs errors to stderr to avoid interfering with MCP protocol on stdout.

🧪 Testing

Ingress Listener (Discord/Slack)

Quick test (Discord provider, placeholder token):

• Do not paste secrets inline; export via your shell or MCP config.
• Start with Discord first using a placeholder to validate wiring (HTTP starts, Discord login will fail fast with TokenInvalid, which confirms the path):

BEEP_BOOP_INGRESS_ENABLED=true \
BEEP_BOOP_INGRESS_PROVIDER=discord \
BEEP_BOOP_DISCORD_BOT_TOKEN={{DISCORD_BOT_TOKEN}} \
BEEP_BOOP_INGRESS_HTTP_AUTH_TOKEN={{INGRESS_TOKEN}} \
BEEP_BOOP_LOG_LEVEL=debug \
npm run listen

You should see:

• Config summary
• HTTP endpoint online (http://localhost:7077)
• Discord TokenInvalid (expected when using a placeholder)

HTTP endpoint usage (replace token if configured):

curl -H "Authorization: Bearer {{INGRESS_TOKEN}}" http://localhost:7077/messages
curl -H "Authorization: Bearer {{INGRESS_TOKEN}}" http://localhost:7077/messages/<MESSAGE_ID>
curl -X POST -H "Authorization: Bearer {{INGRESS_TOKEN}}" http://localhost:7077/messages/<MESSAGE_ID>/ack

To actually test Discord end-to-end, set a valid BEEP_BOOP_DISCORD_BOT_TOKEN and invite the bot to your server with intents enabled (Guilds, Guild Messages, Message Content). Mention the bot to create a captured message and get an immediate ack reply.

To test Slack, set:

• BEEP_BOOP_INGRESS_PROVIDER=slack
• BEEP_BOOP_SLACK_APP_TOKEN=xapp-… (Socket Mode app-level token with connections:write)
• BEEP_BOOP_SLACK_BOT_TOKEN=xoxb-… (bot token with app_mentions:read, chat:write; add history scopes as needed if you want to capture non-mention messages)

Then run:

npm run listen

See docs/INGRESS.md and docs/SCOPES_INTENTS.md for full setup.

Run the test suite:

npm test

Test with a real MCP client:

# Terminal 1: Start server
npm run dev

# Terminal 2: Test with MCP client
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

🤝 Integration Examples

MCP tool: update_user

Agents can post follow-up updates back to the original Slack thread or Discord channel for a captured message.

Input fields:

• messageId: ID of the captured message (from the local inbox)
• updateContent: message text to send

Example (pseudo):

{
  "tool": "update_user",
  "params": {
    "messageId": "2b1b8e02-6c6b-4a3d-9f0f-123456789abc",
    "updateContent": "I'll start preparing a deployment plan and report back within 10 minutes."
  }
}

With Task Planners

async function findAvailableWork(tasks: Task[]) {
  const available = [];
  
  for (const task of tasks) {
    const status = await checkStatus(task.directory);
    if (!status.includes('WORK_IN_PROGRESS')) {
      available.push(task);
    }
  }
  
  return available;
}

With CI/CD

- name: Check work coordination
  run: |
    if [ -f "boop" ]; then
      echo "Work in progress, skipping deployment"
      exit 1
    fi

With Monitoring

// Alert on stale boop files
const boopAge = Date.now() - boopTimestamp.getTime();
if (boopAge > 30 * 60 * 1000) { // 30 minutes
  alertUser(`Stale boop file: ${directory}`);
}

🛠️ Development

Project Structure

src/
  ├── index.ts              # Main MCP server entry point  
  ├── types.ts              # TypeScript interfaces
  ├── config.ts             # Configuration management
  ├── file-operations.ts    # Core beep/boop logic
  ├── tools.ts              # MCP tool implementations
  ├── notification-service.ts # Discord/Slack webhook notifications
  ├── http-listener-client.ts # HTTP client for ingress server
  └── ingress/              # Message capture and processing
      ├── index.ts          # Ingress server entry point
      ├── discord-listener.ts # Discord bot integration
      ├── slack-listener.ts # Slack bot integration
      └── inbox.ts          # Message storage and retrieval

root/
├── test-webhooks.ts      # Webhook integration testing script
├── .beep-boop-inbox/     # Message storage directory (auto-created)
│   ├── messages/         # Captured messages from Discord/Slack
│   └── processed/        # Acknowledged/processed messages
└── example-configs/      # Environment-specific configurations
    ├── select-config.sh  # Interactive config selection script
    ├── mcp-config.development.json
    ├── mcp-config.production.json
    ├── mcp-config.ci.json
    └── mcp-config.enterprise.json

docs/
├── AGENT_COORDINATION_RULE.md  # Core coordination principles
├── BEEP_BOOP_RULE.md          # Tool usage reference
├── CONFIGURATION.md           # Environment variables guide
├── INGRESS.md                 # Discord/Slack integration guide
├── SCOPES_INTENTS.md          # Bot permissions setup
└── stale-cleanup-example.md   # Advanced cleanup scenarios

Building and Testing

# Development commands
npm run dev    # Development mode with hot reload
npm run build  # Compile TypeScript to dist/
npm start      # Start production server
npm run listen # Start ingress server for Discord/Slack

# Testing commands
npm test              # Run test suite (build verification)
npm run test:webhooks # Test Discord/Slack webhook integrations
npx tsc --noEmit     # TypeScript compilation check

# Configuration management
npm run config                # Interactive configuration selection
npm run config:dev           # Apply development configuration
npm run config:prod          # Apply production configuration
npm run config:ci            # Apply CI/CD configuration
npm run config:enterprise    # Apply enterprise configuration

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes with tests
4. Push to your branch: git push origin feature/my-feature
5. Create a Pull Request

Automated Publishing

This project uses GitHub Actions for automated testing and publishing:

• Feature Branches: Tests run automatically on push
• Main Branch: Automatic version bumping, npm publishing, and GitHub releases
• Version Bumping: Based on commit message keywords:
  • BREAKING/major: Major version (1.0.0 → 2.0.0)
  • feat/feature/minor: Minor version (1.0.0 → 1.1.0)
  • Everything else: Patch version (1.0.0 → 1.0.1)

See GitHub Workflow Setup for detailed configuration.

📄 License

MIT License - see LICENSE file

📁 Documentation & Examples

Documentation

• Agent Coordination Rules - Core coordination principles
• Beep/Boop File Specification - File format and state machine details
• Configuration Guide - Environment variables and setup options
• Stale Cleanup Examples - Advanced cleanup scenarios

Example Configurations

• Development Config - Local development setup
• CI/CD Config - Continuous integration environment
• Enterprise Config - Production enterprise setup
• Config Selection Script - Environment-based config switching
• Example MCP Client - Sample integration code

🔗 Related

• Model Context Protocol - Official MCP specification
• MCP TypeScript SDK - SDK used by this server

📞 Support

For issues and questions:

• Check existing GitHub issues
• Review the troubleshooting guide above
• Create new issue with reproduction steps

---

Built with ❤️ for AI agent collaboration