jumpstarter-mcp 0.8.1

MCP server for AI agent interaction with Jumpstarter hardware

jumpstarter-mcp

MCP (Model Context Protocol) server for AI agent interaction with Jumpstarter hardware devices.

Overview

This package provides an MCP server that exposes Jumpstarter's lease management, device connections, and command execution as structured tools accessible by AI agents (e.g., via Cursor, Claude Code, or any MCP-compatible host).

IDE Integration

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "jumpstarter": {
      "command": "jmp",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code

Claude Code discovers MCP servers from its configuration. Add Jumpstarter with:

claude mcp add jumpstarter -- jmp mcp serve

Or manually add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jumpstarter": {
      "command": "jmp",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "jumpstarter": {
      "command": "jmp",
      "args": ["mcp", "serve"]
    }
  }
}

Available Tools

Lease & Exporter Management

Tool	Description
jmp_list_exporters	List exporters with online status and lease info
jmp_list_leases	List active leases
jmp_create_lease	Create a new lease by selector or exporter name
jmp_delete_lease	Release a lease

Connection Management

Tool	Description
jmp_connect	Connect to a device (by lease, selector, or exporter)
jmp_disconnect	Disconnect from a device
jmp_list_connections	List active connections

Device Interaction

Tool	Description
jmp_run	Execute CLI commands on a connected device
jmp_get_env	Get environment and code examples for direct access

Discovery & Introspection

Tool	Description
jmp_explore	Discover available CLI commands on a device
jmp_drivers	List driver objects and their methods
jmp_driver_methods	Inspect driver method signatures and docstrings

Typical Workflow

A typical interaction with an AI agent looks like this:

1. List exporters to see what hardware is available:

   "What devices are available on the cluster?"

2. Create a lease for a target device:

   "Get me a QEMU target" or "Lease a board with label board-type=qc8650"

3. Connect to establish a persistent connection:

   "Connect to that lease"

4. Interact with the device:

   "Power on the target and check what OS it's running via SSH"

5. Disconnect and release when done:

   "Disconnect and delete the lease"

Writing Python with AI Assistance

The MCP server is especially useful when writing Python code that interacts with hardware. While connected to a device, the agent can introspect the live connection to discover available drivers, methods, and their signatures -- then use that knowledge to help you write correct code.

Ask the agent to explore what's available on your target:

"I'm connected to an ARM board. What drivers and methods are available?"

The agent calls jmp_drivers and jmp_driver_methods to inspect the live connection and gives you a summary of power, ssh, serial, storage, etc.

Ask for help writing automation scripts:

"Write me a Python script that power-cycles the board, waits for it to boot, and grabs the kernel version over SSH."

The agent inspects the driver methods to discover exact signatures and generates a working script using the env() helper.

Debug a failing interaction:

"My serial expect is timing out. Can you read the serial output and tell me what the board is printing?"

The agent calls jmp_run with ["serial", "pipe"] and a short timeout to capture what the console is outputting right now.

Discover capabilities you didn't know about:

"What can I do with the storage driver on this device?"

The agent calls jmp_driver_methods for the storage driver and shows you methods like flash, write_local_file, read_to_local_file, etc. with their full signatures and docstrings.

Iterate on code with live hardware feedback:

"Run my test script and tell me if the board boots successfully."

The agent uses jmp_get_env to get the shell environment, executes your script, and reports back with the actual device output.

Logging

The MCP server logs to ~/.jumpstarter/logs/mcp-server.log. To monitor:

tail -f ~/.jumpstarter/logs/mcp-server.log