Claude Code Agent Instructions
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Code Agent integration in Keynobi is facilitated through the Model Context Protocol (MCP). This system allows AI agents, specifically Claude Code, to interact directly with the Android development environment. By exposing a set of specialized tools and prompts, agents can trigger Gradle builds, monitor real-time Logcat streams, manage Android Virtual Devices (AVDs), and inspect project health.
This integration serves as a bridge between the AI's reasoning capabilities and the technical execution layer of Android development. It operates in two primary modes: a GUI mode that shares state with the running Keynobi application and a headless mode for direct CLI interactions.
Sources: README.md:12-25, src-tauri/src/services/mcp_server.rs:1-18
Architecture and Integration Modes
The MCP server is built using the rmcp SDK and supports JSON-RPC 2.0 over a standard I/O (stdio) transport. It is designed to be added to Claude Code via the command: claude mcp add --transport stdio keynobi -- "/path/to/keynobi" --mcp.
Execution Modes
The server handles state management differently depending on how it is invoked:
- GUI Mode: Triggered via the
start_mcp_serverTauri command. It accesses existing managed state (BuildState, DeviceState, LogcatState) through the TauriAppHandle. It can also emit events back to the frontend (e.g.,mcp:client_connected). - Headless Mode: Launched with the
--mcpCLI flag. It initializes its own state directly from the project path and settings file, operating without a graphical window.
Sources: src-tauri/src/services/mcp_server.rs:11-40, src-tauri/src/services/mcp_server.rs:885-920
System Data Flow
The following diagram illustrates how an MCP client like Claude Code interacts with the Keynobi backend to control Android tools.
The diagram shows the communication path from the external MCP client through the Rust-based routers to the underlying Android CLI tools. Sources: README.md:150-185, src-tauri/src/services/mcp_server.rs:43-85
Key MCP Tools for Agents
The MCP server exposes a variety of tools categorized by their function within the Android development lifecycle.
Build and Project Tools
These tools allow agents to execute and diagnose Gradle-related tasks.
| Tool Name | Description | Key Parameters |
|---|---|---|
run_gradle_task | Executes a Gradle task (e.g., assembleDebug). | task, variant |
get_build_errors | Retrieves structured compiler errors/warnings. | N/A |
get_build_log | Fetches raw build output lines for diagnosis. | lines (limit) |
get_project_info | Returns open project name, path, and Gradle root. | N/A |
Sources: src-tauri/src/services/mcp_server.rs:188-300
Device and Logcat Tools
Agents use these tools to interact with physical devices or emulators and monitor runtime behavior.
| Tool Name | Description | Key Parameters |
|---|---|---|
list_devices | Lists connected ADB devices and emulators. | N/A |
start_logcat | Begins streaming logcat from a specific device. | device_serial |
get_logcat_entries | Queries the in-memory buffer with filters. | min_level, tag, text, package |
install_apk | Installs a built APK to a target device. | device_serial, apk_path |
launch_app | Starts an app using am start. | device_serial, package, activity |
Sources: src-tauri/src/services/mcp_server.rs:465-640
Implementation Logic: AndroidMcpServer
The core logic resides in the AndroidMcpServer struct, which implements the ServerHandler trait.
LoggingMcpServer acts as a wrapper to intercept all calls and record them in the mcp_activity log, which is then viewable in the UI's McpPanel. Sources: src-tauri/src/services/mcp_server.rs:43-85, src-tauri/src/services/mcp_server.rs:800-850
Security and Validation
To prevent command injection, the MCP server enforces strict validation on parameters such as Gradle tasks, package names, and device serials using alphanumeric allow-lists.
Sources: src-tauri/src/services/mcp_server.rs:758-795
Agent Setup and Management
Users can manage the MCP integration through the McpPanel and HealthPanel components.
Automated Registration
The configure_mcp_in_claude Rust command attempts to locate the claude binary by searching common paths (e.g., /usr/local/bin, /opt/homebrew/bin) or spawning a login shell. If found, it executes claude mcp add to register the Keynobi binary.
Sources: src-tauri/src/commands/mcp.rs:60-140
UI Integration
In App.tsx, the application registers keybindings and actions to facilitate MCP usage:
Cmd+Shift+M: Opens the MCP Activity Panel.- Copy MCP Setup Command: A command palette action that generates the exact CLI command needed for manual registration.
Sources: src/App.tsx:185-205, src/components/mcp/McpPanel.tsx:160-200
This flow ensures the UI always displays the correct binary path for registration, even if the application has been moved. Sources: src/components/mcp/McpPanel.tsx:115-140, src-tauri/src/commands/mcp.rs:25-55
Summary of Agent Capabilities
The Keynobi MCP implementation provides a comprehensive toolkit for AI-driven Android development. By combining build automation, device control, and deep log inspection into a standardized protocol, it allows Claude Code to perform complex workflows such as "Build and Fix" (running a task, fetching structured errors, and proposing code changes) or "Diagnose Crash" (analyzing logcat stack traces and memory state).
Sources: src-tauri/src/services/mcp_server.rs:700-750, AGENTS.md:1-20