awaBerry For Developers Main Page -> awaBerry MCP Server Documentation
awaBerry MCP Server Documentation
Summary
The awaBerry MCP Server is a robust solution for secure remote device management, enabling developers to connect to and interact with diverse devices (Mac, Linux, Windows, Docker) within an awaBerry project. It supports JSON-based implementations for internal networks and Cloudflare Worker deployments for global reach. The server, through its createMcpServer function, provides essential tools like connect_to_device, execute_terminal_command, and PostgreSQL database interaction tools. The mcpclient facilitates secure terminal access and command execution, while Cloudflare Workers offer firewall-bypassing remote control capabilities via an HTTP endpoint. The entire system is designed for automation and integration with agentic environments, backed by comprehensive testing procedures.
Cloudflare worker implementation of the MCP Server
The provided code implements an MCP (Model Context Protocol) Server as a Cloudflare Worker. It facilitates secure remote device management through awaBerry Remote, allowing connections to devices, execution of terminal commands, and file transfers without direct SSH/SCP or firewall configurations. The server exposes two main tools: connect_to_device for establishing a persistent terminal session, and execute_terminal_command for running shell commands on the connected device. It handles API interactions with agentic.awaberry.net for project and device management, session initiation, and command execution, incorporating connection status polling and robust error handling. The Cloudflare Worker acts as an HTTP endpoint /mcp, processing incoming MCP requests and relaying responses via a custom transport layer.
awaberry MCP Server client
The awaBerry MCP Server client facilitates secure access and management of remote devices (Mac, Linux, Windows, Docker) registered within an awaBerry project. It enables developers to connect to devices, execute terminal commands, and manage persistent terminal sessions using project keys, secrets, and session tokens. The client integrates with environments like Claude Desktop, offering robust capabilities for automation and remote device interaction through natural language or direct tool invocations.
awaberry MCP Server implementations
This manual details the setup and testing of awaBerry MCP Server implementations. It covers prerequisites like Node.js and Git, and explains two primary server types: JSON-based for company intranets/clouds (with references to mcpserver/awaBerryAgenticMcpServerHttpJson.js and Cloudflare worker deployment via cloudflare/worker/awaberrymcpserver/README.md). Testing procedures include method tests for project credentials (test/methodtest/README.md) and dedicated MCP server tests for both JSON and stdio modes using npm run start:mcp:json/stdio and npm run test:mcp:json/stdio commands.
awaBerry Testing Guide
This guide provides comprehensive procedures for local integration testing of awaBerry components, covering HTTP server functionality, MCP client and server interactions, and core agent methods like device connection and command execution. Tests involve configuring environment variables (`projectKey`, `projectSecret`, `deviceName`, `mcpServerUrl`) to establish secure connections and execute remote commands (e.g., 'date') on configured devices. Validation ensures proper session initialization, tool listing, device connectivity, and reliable command execution across various transport mechanisms, including JSON/HTTP and Standard I/O.
Description
The awaBerry MCP Server provides a comprehensive framework for remote device management and automation. It is available for download and contribution on GitHub: https://github.com/awaberry/mcp_server_awaberry.
MCP Client (mcpclient)
The awaBerry MCP Server client (mcpclient) offers secure access and management for remote devices (Mac, Linux, Windows, Docker) registered within an awaBerry project. It empowers developers to connect, execute terminal commands, and manage persistent terminal sessions using project keys, secrets, and session tokens. Its integration with environments like Claude Desktop provides robust capabilities for automation and remote interaction through natural language or direct tool invocations.
MCP Server Implementations (mcpserver, mcpserver/awaberryagenticmcpserver, mcpserver/awaberryagenticmcpserverhttpjson)
The core awaBerryAgenticMcpServer.js exports a createMcpServer function, initializing an MCP server that manages persistent connections and exposes key tools. These tools include connect_to_device for secure terminal connections, execute_terminal_command for running shell commands, execute_database_command_postgres for SQL execution, and describe_database_schema_postgres for schema retrieval.
The mcpserver documentation details setup and testing for JSON-based servers suitable for company intranets/clouds, often referenced through mcpserver/awaBerryAgenticMcpServerHttpJson.js. This HTTP/JSON module sets up an Express.js server with a /mcp POST endpoint, handling streaming interactions via @modelcontextprotocol/sdk/server/streamableHttp.js and ensuring isolated session management.
Cloudflare Worker Deployment (cloudflare)
An MCP Server implementation as a Cloudflare Worker allows for secure remote device management through awaBerry Remote. This worker enables connections to devices, execution of terminal commands, and file transfers without direct SSH/SCP or complex firewall configurations. It exposes connect_to_device and execute_terminal_command tools and manages API interactions with agentic.awaberry.net for project, device, and session handling, acting as an HTTP endpoint at /mcp.
Testing Procedures (test/httpservertest, test/mcpclients, test/mcpservertest, test/methodtest)
The project includes comprehensive testing. test/mcpservertest covers thorough validation of both JSON/HTTP and Standard I/O (Stdio) transport mechanisms, checking session initialization, tool listing, device connection, and terminal command execution. The test/httpservertest specifically outlines testing the HTTP server component by starting a local server and using a client script to send execute commands. test/mcpclients details a test script (testStartAwaberryMcp.js) that orchestrates a full test sequence including protocol session initialization, tool listing, secure device connection, and remote command execution. Finally, test/methodtest focuses on executing local integration tests for the connectToDevice and executeCommand methods using the awaBerry Connect agent, covering preconditions, environment setup, and detailed instructions for testing connectivity, command execution, and managing long-running commands.
