Which integrations are available for this server?

Enables bidirectional communication with Discord through bot integration, capturing messages from channels and posting updates back to threads for AI agent coordination Automatically manages .gitignore entries to exclude coordination files (beep/boop) from version control, ensuring clean repository state Provides bidirectional communication with Slack workspaces through bot integration, capturing app mentions and posting follow-up messages to threads for AI agent coordination

How do I use Beep Boop MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Beep Boop MCP check status of ./src/components and clean up any stale boop files older than 8 hours" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Beep Boop MCP

by thesammykins

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

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

Related MCP server: junto-memory

📦 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 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

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

Available Tools

7 tools

check_listener_statusCheck Listener StatusC

Checks the status and connectivity of the HTTP listener service used for tool delegation.

ParametersJSON Schema

Name	Required	Description	Default
`includeConfig`	No	Whether to include configuration details in response

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions checking 'status and connectivity', which implies a read-only operation, but doesn't specify whether it requires authentication, has rate limits, or what the response format looks like. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., status codes, error messages, or configuration details when 'includeConfig' is true), which is crucial for a diagnostic tool. The high schema coverage helps with parameters, but overall context is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with one parameter ('includeConfig') fully documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without compensating with extra details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Checks the status and connectivity of the HTTP listener service used for tool delegation.' It specifies the verb ('Checks') and resource ('HTTP listener service'), and mentions the specific aspect ('status and connectivity'). However, it doesn't explicitly differentiate from sibling tools like 'check_status', which might be ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, exclusions, or compare it to sibling tools such as 'check_status', leaving the agent to infer usage context based on the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_statusCheck Work StatusA

Checks the current work coordination status of a directory by examining beep/boop files, provides guidance on next steps, and can automatically clean up stale boop files older than a specified threshold.

ParametersJSON Schema

Name	Required	Description
`autoCleanStale`	No	Whether to automatically clean up stale boop files (default: false)
`directory`	Yes	Directory path to check
`maxAgeHours`	No	Maximum age in hours for boop files before considering them stale (default: 24)
`newAgentId`	No	Agent ID to use when claiming after stale cleanup
`newWorkDescription`	No	Work description when claiming after cleanup

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool examines files, provides guidance, and can perform automatic cleanup with configurable thresholds. However, it doesn't specify what format the guidance takes, whether the operation is idempotent, or any rate limits/authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently communicates the tool's core functionality. It's front-loaded with the primary purpose ('checks the current work coordination status'), followed by implementation details ('by examining beep/boop files'), advisory function ('provides guidance on next steps'), and optional capability ('can automatically clean up stale boop files'). Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters, no annotations, and no output schema, the description provides adequate but incomplete context. It covers the main functionality and cleanup capability well, but doesn't describe the return format, error conditions, or what 'guidance on next steps' entails. Given the complexity and lack of structured output documentation, more detail would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds some context about 'stale boop files older than a specified threshold' which relates to the maxAgeHours parameter, but doesn't provide additional semantic meaning beyond what's already in the parameter descriptions. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('checks', 'examining', 'provides guidance', 'clean up') and resources ('work coordination status', 'directory', 'beep/boop files'). It distinguishes from siblings like 'check_listener_status' by focusing on directory coordination rather than listener status, and from 'create_beep'/'update_boop' by being an inspection/cleanup tool rather than a creation/modification tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context ('checks current work coordination status', 'provides guidance on next steps') but doesn't explicitly state when to use this tool versus alternatives. It mentions automatic cleanup of stale files as a capability, but doesn't provide clear guidance on when to enable this feature versus using other cleanup tools if they exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_beepCreate Beep FileA

Creates a beep file to signal that work is complete and the directory is cleared for new work. Use this when work is finished but no boop file exists.

ParametersJSON Schema

Name	Required	Description	Default
`directory`	Yes	Directory path where to create the beep file
`message`	No	Optional completion message

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions that the tool creates a file and signals completion, but lacks details on permissions needed, error handling, side effects (e.g., does it modify other files?), or what happens if a boop file already exists. For a file creation tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every word earns its place without redundancy. It's efficiently structured and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (file creation with two parameters) and no annotations or output schema, the description is minimally adequate. It explains the purpose and usage context but lacks behavioral details like error cases or return values, which would be needed for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('directory' and 'message') adequately. The description doesn't add any meaningful parameter details beyond what the schema provides, such as format examples or constraints, but it doesn't need to given the high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('creates a beep file') and purpose ('to signal that work is complete and the directory is cleared for new work'), which is specific and actionable. However, it doesn't explicitly distinguish this tool from sibling tools like 'update_boop' or 'end_work', which might have related functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('when work is finished but no boop file exists'), which helps guide the agent. It doesn't explicitly mention when NOT to use it or name alternatives among siblings, but the condition given is specific enough to be helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

end_workEnd WorkA

Atomically completes work by removing the boop file and creating a beep file. This signals that work is complete and clears the directory for new work.

ParametersJSON Schema

Name	Required	Description
`agentId`	Yes	Agent identifier that was doing the work
`directory`	Yes	Directory path where work is being completed
`message`	No	Optional completion message

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses key behavioral traits: atomic operation (implies transactional safety), file system changes (removing and creating files), and signaling purpose. However, it lacks details on permissions, error handling, or side effects beyond clearing the directory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and concise with two sentences that efficiently convey the core action and purpose. Every sentence adds value without redundancy, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description provides adequate context for a tool with 3 parameters and clear file operations. It covers what the tool does and why, but lacks details on return values or error conditions, leaving some gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds no parameter-specific semantics beyond implying 'directory' is where files are manipulated, which is redundant with schema. Baseline 3 is appropriate as schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('removing the boop file and creating a beep file') and resource ('directory'), explaining it 'atomically completes work'. It distinguishes from siblings like 'create_beep' and 'update_boop' by combining both actions, but doesn't explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context ('signals that work is complete and clears the directory for new work'), suggesting when to use it, but doesn't provide explicit guidance on when not to use it or name alternatives like 'create_beep' or 'update_boop' for partial operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

initiate_conversationInitiate ConversationB

Proactively starts a new conversation on Discord or Slack. For Discord, creates a thread automatically.

ParametersJSON Schema

Name	Required	Description
`agentId`	No	Optional agent ID for attribution
`channelId`	No	Channel ID to send message to (optional - uses default if not specified)
`content`	Yes	Initial message content to send
`platform`	Yes	Platform to send message to

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the automatic thread creation for Discord, which adds some context, but fails to cover critical aspects like authentication requirements, rate limits, error handling, or what constitutes a 'conversation' (e.g., direct message vs. channel post). This leaves significant gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences that are front-loaded and waste no words. Every phrase adds value, such as specifying the proactive action and platform-specific behavior for Discord, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a mutation operation with no annotations and no output schema), the description is incomplete. It lacks details on behavioral traits like side effects, response format, error conditions, and prerequisites (e.g., required permissions). The high schema coverage doesn't compensate for these omissions in a tool that initiates conversations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add any meaningful semantic context beyond what the schema provides (e.g., it doesn't clarify the implications of optional vs. required parameters or platform-specific behaviors for parameters). Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('proactively starts a new conversation') and the target resources (Discord or Slack), with explicit differentiation for Discord's automatic thread creation. It uses precise verbs and distinguishes the tool's unique functionality from its siblings, which appear unrelated to conversation initiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying platforms (Discord/Slack) and the proactive nature, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. No sibling tools are directly comparable, so the lack of explicit alternatives is understandable but still leaves guidance incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_boopUpdate Boop FileA

Creates or updates a boop file to claim a directory for work. This signals that work is in progress and prevents other agents from working in the same directory.

ParametersJSON Schema

Name	Required	Description
`agentId`	Yes	Agent identifier claiming the work
`directory`	Yes	Directory path where to create/update the boop file
`workDescription`	No	Optional description of the work being done

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains the tool's effect ('prevents other agents from working in the same directory'), which is a key behavioral trait beyond basic functionality. However, it lacks details on permissions, error handling, or rate limits, leaving some gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, consisting of two concise sentences that directly convey the tool's purpose and effect without any wasted words, making it highly efficient and easy to understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity as a mutation tool with no annotations and no output schema, the description is somewhat complete by explaining the locking mechanism. However, it lacks details on return values, error conditions, or interaction with siblings like 'end_work', leaving room for improvement in contextual coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description does not add any additional meaning or context beyond what the schema provides, such as examples or usage tips, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('creates or updates a boop file') and resource ('to claim a directory for work'), and distinguishes its function from siblings by explaining it prevents other agents from working in the same directory, which is unique among the listed tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('to claim a directory for work' and 'signals that work is in progress'), but it does not explicitly state when not to use it or name alternatives among siblings, such as 'end_work' or 'create_beep', which could be related.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_userUpdate UserC

Sends a follow-up update back to the platform (Slack/Discord) for a captured message.

ParametersJSON Schema

Name	Required	Description	Default
`messageId`	Yes	ID of the captured message to respond to
`updateContent`	Yes	Message content to send as an update

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It implies a write operation ('sends') but doesn't specify permissions, rate limits, or effects (e.g., if updates are editable or permanent). This is inadequate for a mutation tool, leaving key behavioral traits undefined.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action. It avoids redundancy and wastes no words, making it appropriately concise, though it could be more structured with additional context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity as a mutation with no annotations and no output schema, the description is incomplete. It lacks details on behavior, error handling, or return values, failing to compensate for the missing structured data, which is insufficient for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('messageId' and 'updateContent'). The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool 'sends a follow-up update back to the platform (Slack/Discord) for a captured message,' which provides a clear verb ('sends') and resource ('update'), but it's vague about what 'captured message' means and doesn't distinguish this from sibling tools like 'update_boop' or 'create_beep,' leaving ambiguity in its specific role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It mentions 'captured message' but doesn't explain prerequisites, context, or exclusions, and sibling tools like 'update_boop' or 'initiate_conversation' are not referenced, offering no help in tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Disambiguation3/5

Tools have overlapping purposes that could cause confusion, particularly around work coordination. For example, 'create_beep' and 'end_work' both handle work completion with beep files, and 'check_status' includes cleanup functionality that overlaps with 'end_work'. However, descriptions help clarify specific use cases, preventing complete misselection.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern (e.g., 'check_status', 'create_beep', 'update_boop'), which aids predictability. Minor deviations exist with 'initiate_conversation' using 'initiate' instead of a more common verb like 'start', but overall naming is coherent and readable.

Tool Count5/5

With 7 tools, the count is well-scoped for the server's dual purposes of work coordination and platform communication. Each tool appears to serve a distinct role, avoiding bloat while covering necessary operations like status checks, file management, and messaging.

Completeness4/5

The tool set covers core workflows for work coordination (initiate, update, complete, check) and platform communication (initiate, update), with no major gaps. A minor gap exists in lacking a tool to delete or manage stale beep files, but agents can work around this using existing cleanup in 'check_status'.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Apuchat A
io.github.opcastil11
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Communication Agent Orchestration
181
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
mcp-server
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

Agent Orchestration
Agent Orchestration Autonomous Agents
madebyaris
A
license
Not graded
quality
F
maintenance
A Model Context Protocol (MCP) server that enables multiple AI agents to share memory, coordinate tasks, and collaborate effectively across IDEs and CLI tools.
Updated 5 months ago (2026-04-05 06:17 UTC)
33
15
MIT
junto-memory
Knowledge & Memory Agent Orchestration
tlemmons
A
license
Not graded
quality
B
maintenance
A shared memory and coordination server for multiple AI coding agents, built on the Model Context Protocol (MCP).
Updated 9 days ago (2026-08-26 13:29 UTC)
5
MIT
session-coord-mcp
Coding Agents Developer Tools
LingFeng-Vels
A
license
Not graded
quality
D
maintenance
A local-first MCP server for coordinating parallel AI coding sessions with tools like Claude Code and Codex in a single repository.
Updated 3 months ago (2026-05-25 23:36 UTC)
2
MIT
discord-mcp-agent
Communication Workplace & Productivity Developer Tools
zebbern
A
license
A
quality
D
maintenance
A Model Context Protocol (MCP) server for Discord-based AI agent-user communication. Enables AI agents to communicate with users through Discord instead of IDE chat interfaces.
Updated 7 months ago (2026-01-26 20:47 UTC)
5
9
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/thesammykins/beep_boop_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

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

Available Tools

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

`check_status`

`update_boop`

`end_work`

`create_beep`

`update_user`

`initiate_conversation`

`check_listener_status`

Beep File (`beep`)

Boop File (`boop`)