MCP Stdio Server Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Stdio Server in Keynobi is an AI-first integration layer that exposes Android development capabilities—such as Gradle builds, Logcat streaming, and device management—to AI agents like Claude Code. It implements the 2025-11-25 MCP specification, allowing external tools to interact with the Android development environment through a standardized JSON-RPC 2.0 interface over standard input/output (stdio).
Sources: src-tauri/src/services/mcp_server.rs:1-15, README.md
Operational Modes
The architecture supports two distinct operational modes, allowing the server to function either as part of the native application or as a standalone background process.
- GUI Mode: The server is started via a Tauri command within the main application. In this mode, it shares state with the GUI (via
AppHandle) and can emit events back to the frontend to update the UI. - Headless Mode: Triggered by the
--mcpCLI flag, the server runs without a graphical interface. It initializes its own state (build runners, device managers) directly from the filesystem and settings.
Sources: src-tauri/src/services/mcp_server.rs:9-15, src-tauri/src/services/mcp_server.rs:955-965
Implementation Diagram
The following diagram illustrates how the server bridges the gap between AI Clients and the Android environment.
Component Overview
AndroidMcpServer State Management
The core logic resides in AndroidMcpServer, which encapsulates various application states. These states are backed by Arc<Mutex<>> to ensure thread safety across asynchronous tool executions.
| Component | Responsibility |
|---|---|
BuildState | Tracks Gradle task progress, logs, and structured error results. |
DeviceState | Manages the list of connected physical devices and emulators. |
LogcatState | Handles the 50K ring buffer of log entries and active streaming. |
FsState | Resolves project roots and Gradle paths for security validation. |
ProcessManager | Controls child process lifecycles (e.g., killing Gradle on cancel). |
Sources: src-tauri/src/services/mcp_server.rs:45-75, src-tauri/Cargo.toml:35-45
Tool and Prompt Routers
The server uses macros from the rmcp SDK to define available capabilities:
- Tools: Discrete executable functions (e.g.,
run_gradle_task,install_apk). These include validation logic to prevent shell injection or unauthorized path access. - Prompts: High-level templates that guide AI agents through complex workflows, such as
diagnose-crashorfull-deploy. - Resources: Static or dynamic data providers (e.g.,
android://health,android://manifest) that agents can read as context.
Sources: src-tauri/src/services/mcp_server.rs:167-200, src-tauri/src/services/mcp_server.rs:698-750
Security and Validation
To maintain system integrity, the server strictly validates all inputs received from external agents.
Key validation rules implemented include:
- Path Security: APK paths must reside within the project's
app/build/outputs/directory. - Input Sanitization: Task names and package names are checked for alphanumeric characters and specific symbols (':', '.', '_') to prevent command injection.
Sources: src-tauri/src/services/mcp_server.rs:928-952
Setup and Registration
The server provides built-in commands to facilitate registration with the Claude CLI. The get_mcp_setup_status command detects the environment and returns the necessary configuration.
| Field | Description |
|---|---|
exePath | The absolute path to the Keynobi binary. |
claudeFound | Boolean indicating if the claude CLI is accessible on the system. |
isConfigured | Boolean indicating if keynobi is already in the Claude config. |
Sources: src-tauri/src/commands/mcp.rs:12-30, src/bindings/McpSetupStatus.ts
Automatic Configuration
The configure_mcp_in_claude command automates the setup process by:
- Resolving the
claudebinary (checking common paths and login shells). - Removing existing
keynobiregistrations to avoid conflicts. - Executing
claude mcp add --transport stdio keynobi -- <path> --mcp.
Sources: src-tauri/src/commands/mcp.rs:72-105
Activity Monitoring
Every interaction with the MCP server is logged into a shared JSONL file for transparency and debugging. This is achieved via a LoggingMcpServer wrapper that intercepts all tool calls, resource reads, and prompt requests.
The frontend McpPanel provides a real-time view of this log, displaying timestamps, execution durations, and status (OK/Error) for every interaction.
Sources: src/components/mcp/McpPanel.tsx:55-80
Conclusion
The MCP Stdio Server Architecture provides a robust, secure, and transparent bridge between AI agents and Android development tools. By supporting both GUI and Headless modes and enforcing strict validation, it enables powerful automation while maintaining project security and user visibility.