# 🤖👈 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)
```bash
npm install -g @thesammykins/beep-boop-mcp-server
```

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

### From Source
```bash
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
```bash
# 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
```json
{
  "mcpServers": {
    "beep-boop-coordination": {
      "command": "beep-boop-mcp-server"
    }
  }
}
```

#### For NPX (No Installation Required)
```json
{
  "mcpServers": {
    "beep-boop-coordination": {
      "command": "npx",
      "args": ["-y", "@thesammykins/beep-boop-mcp-server"]
    }
  }
}
```

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

### 3. Use in Your AI Agent Workflows

```typescript
// 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:*
```json
{
  "directory": "./src/auth"
}
```

*Check with automatic stale cleanup and claim:*
```json
{
  "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
```bash
# Start the ingress listener
npm run listen

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

#### Required Environment Variables
**For Discord Integration:**
```bash
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:**
```bash
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:

```bash
# 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:
```json
{
  "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:

```typescript
// 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`)
```json
{
  "completedAt": "2024-08-20T10:30:00.000Z",
  "message": "Refactoring completed successfully",
  "completedBy": "claude-assistant"
}
```

#### Boop File (`boop`) 
```json
{
  "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
```bash
# 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
```bash  
# 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
```bash
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):

```bash
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):
```bash
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:
```bash
npm run listen
```

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

Run the test suite:
```bash
npm test
```

Test with a real MCP client:
```bash
# 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):
```json path=null start=null
{
  "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
```typescript
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
```yaml
- name: Check work coordination
  run: |
    if [ -f "boop" ]; then
      echo "Work in progress, skipping deployment"
      exit 1
    fi
```

### With Monitoring
```typescript
// 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
```bash
# 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](https://github.com/thesammykins/beep_boop_mcp)
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](.github/WORKFLOW_SETUP.md) for detailed configuration.

## 📄 License

MIT License - see LICENSE file

## 📁 Documentation & Examples

### Documentation
- [Agent Coordination Rules](./docs/AGENT_COORDINATION_RULE.md) - Core coordination principles
- [Beep/Boop File Specification](./docs/BEEP_BOOP_RULE.md) - File format and state machine details
- [Configuration Guide](./docs/CONFIGURATION.md) - Environment variables and setup options
- [Stale Cleanup Examples](./docs/stale-cleanup-example.md) - Advanced cleanup scenarios

### Example Configurations
- [Development Config](./example-configs/mcp-config.development.json) - Local development setup
- [CI/CD Config](./example-configs/mcp-config.ci.json) - Continuous integration environment
- [Enterprise Config](./example-configs/mcp-config.enterprise.json) - Production enterprise setup
- [Config Selection Script](./example-configs/select-config.sh) - Environment-based config switching
- [Example MCP Client](./example-configs/example-client.js) - Sample integration code

## 🔗 Related

- [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP specification
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - SDK used by this server

## 📞 Support

For issues and questions:
- Check [existing GitHub issues](https://github.com/thesammykins/beep_boop_mcp/issues)
- Review the troubleshooting guide above
- [Create new issue](https://github.com/thesammykins/beep_boop_mcp/issues/new) with reproduction steps

---

**Built with ❤️ for AI agent collaboration**