mess-mcp

The MESS MCP server acts as a bridge between AI agents and real-world human executors. By leveraging the Model Context Protocol (MCP), it allows Claude Desktop to integrate directly with the Meatspace Execution and Submission System (MESS) workflow. This tool enables users to create requests for physical tasks, track their status, discover available executor capabilities, and facilitate communication—such as asking for photo verification, physical inspections, or appliance operations—all managed through a structured YAML-based messaging protocol. It is specifically designed for users who wish to delegate real-world actions to a distributed team or personal devices, using GitHub or local files as the backend storage layer. The architecture ensures that task threads remain private, versioned, and easily traceable.

• Provides eight core MCP tools: mess, mess_status, mess_capabilities, mess_request, mess_answer, mess_cancel, mess_fetch, and mess_wait.

• Fully supports YAML-formatted MESS protocol messages for complex request construction, custom metadata, and rich context definitions.

• Features automated syncing with GitHub repositories, allowing for multi-device collaboration and cloud-backed data storage.

• Enables capability-based routing, where tasks are dispatched to executors based on their verified skills like camera access, physical manipulation, or errands.

• Supports various deployment modes including GitHub-only, fully local storage, and hybrid sync configurations for maximum flexibility.

• Integrates with notification systems such as Slack, Google Chat, ntfy, Pushover, and Email to ensure human executors are alerted to new assignments in real-time.

• Uses secure resource URIs for attachment handling (e.g., photos from cameras), keeping agent interactions efficient by fetching heavy data only when necessary.

• Users must provide a GitHub repository for the exchange backend when using GitHub-mode to ensure data persistence and synchronization.

• Requires careful configuration of environment variables such as MESS_GITHUB_TOKEN and MESS_AGENT_ID for secure authentication and agent identification.

• Executor profiles must be registered in the executors/ directory to define what specific tasks, such as visual checks or appliance control, a specific device or person can handle.

• The system is ideal for home automation, personal assistance, and distributed operations where AI planning needs to manifest into human-executed physical steps.

• For best security practices, utilize fine-grained GitHub tokens restricted specifically to the MESS exchange repository to limit the scope of access for the MCP client.