🤖👈 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 workboop- 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 checkmaxAgeHours(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 cleanupnewWorkDescription(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 claimagentId(string): Your unique agent identifierworkDescription(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 completedagentId(string): Agent identifier that did the workmessage(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 completemessage(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 toupdateContent(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 conversationchannelId(string, optional): Channel ID to send message to (uses default if omitted)content(string): Initial message content to sendagentId(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 responsesBEEP_BOOP_CONVERSATION_POLL_INTERVAL_MS(default: 2000) – How often to check for responsesBEEP_BOOP_DISCORD_API_RETRY_ATTEMPTS(default: 3) – Retry attempts for Discord API failuresBEEP_BOOP_DISCORD_API_RETRY_BASE_DELAY_MS(default: 1000) – Base retry delay with exponential backoffBEEP_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:readandchat:writescopes - Event subscriptions for
app_mentionevents
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:
beepandboopfiles won't be committed to version control - ⚙️ Configurable: Use
BEEP_BOOP_MANAGE_GITIGNORE=falseto 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 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