beep_boop_mcp by thesammykins - MCP Server

🤖👈 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

Discord/Slack Bot receives mentions or messages in configured channels
Message Storage saves captured messages to .beep-boop-inbox/messages/
HTTP API provides programmatic access to captured messages (port 7077)
Agent Processing handles messages via MCP tools and posts updates using update_user
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

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make changes with tests
Push to your branch: git push origin feature/my-feature
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 for detailed configuration.

📄 License

MIT License - see LICENSE file

📁 Documentation & Examples

Documentation

- Core coordination principles
- File format and state machine details
- Environment variables and setup options
- Advanced cleanup scenarios

Example Configurations

- Local development setup
- Continuous integration environment
- Production enterprise setup
- Environment-based config switching
- 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

thesammykins/beep_boop_mcp

🤖👈 Beep/Boop 👉🤖 MCP Server

🎯 Overview

📦 Installation

From NPM (Recommended)

From Source

🚀 Quick Start

1. Start the MCP Server

For NPM Installation

For Source Installation

2. Configure Your MCP Client

For Global NPM Installation

For NPX (No Installation Required)

For Source Installation

3. Use in Your AI Agent Workflows

🔧 API Reference

Tools

check_status

update_boop

end_work

create_beep

update_user

initiate_conversation

check_listener_status

📡 Ingress/Listener System

Message Capture Workflow

Quick Setup

Start Ingress Server

Required Environment Variables

HTTP API Endpoints

Message Format

Integration with Coordination

Bot Setup Requirements

🏗️ Architecture

File Format

Beep File (beep)

Boop File (boop)

State Machine

Error States

🎯 Best Practices

Directory Granularity

Agent ID Guidelines

Git Integration

Error Handling

🔍 Troubleshooting

Common Issues

"Directory is busy" - Another agent is working

"Invalid state" - Both beep and boop exist

Permission errors

Debug Mode

Log Files

🧪 Testing

Ingress Listener (Discord/Slack)

🤝 Integration Examples

MCP tool: update_user

With Task Planners

With CI/CD

With Monitoring

🛠️ Development

Project Structure

Building and Testing

Contributing

Automated Publishing

📄 License

📁 Documentation & Examples

Documentation

Example Configurations

🔗 Related

📞 Support

`check_status`

`update_boop`

`end_work`

`create_beep`

`update_user`

`initiate_conversation`

`check_listener_status`

Beep File (`beep`)

Boop File (`boop`)