Skip to main content
Glama
heresun

OrbStack MCP Server

by heresun

orbstack_machine_list

Read-onlyIdempotent

List all OrbStack Linux machines with their current status, including machine name, distribution, architecture, and running state.

Instructions

列出所有 OrbStack Linux 机器及其状态。

显示机器名称、发行版、架构和运行状态。

Returns: str: 机器列表信息

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Implementation Reference

  • The handler for the 'orbstack_machine_list' MCP tool, which executes 'orb stack list' and returns the formatted output.
    @mcp.tool(
        name="orbstack_machine_list",
        annotations={
            "title": "列出 Linux 机器",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": False,
        },
    )
    async def orbstack_machine_list() -> str:
        """列出所有 OrbStack Linux 机器及其状态。
    
        显示机器名称、发行版、架构和运行状态。
    
        Returns:
            str: 机器列表信息
        """
        code, stdout, stderr = await _run_orb(["list"])
        if code != 0:
            return _format_error(stderr)
        if not stdout:
            return "当前没有 Linux 机器。使用 orbstack_machine_create 创建一个。"
        return f"Linux 机器列表:\n{stdout}"
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying what information is displayed (machine name, distribution, architecture, running status) and that it returns a string with the list, which complements the annotations without contradiction. It doesn't mention rate limits or auth needs, but those aren't critical here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by specifics on displayed information and return type. Every sentence adds value: the first states the action, the second details the output format, and the third clarifies the return type. There is zero waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, annotations cover safety, and an output schema exists), the description is complete. It explains what the tool does, what information it provides, and the return type, which is sufficient for an AI agent to understand and invoke it correctly without needing additional details from structured fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description correctly omits parameter details, making it appropriately focused. A baseline of 4 is applied as it efficiently handles the zero-parameter case without unnecessary information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('列出所有' - list all) and resource ('OrbStack Linux 机器' - OrbStack Linux machines), and distinguishes it from siblings like orbstack_machine_info (which gets detailed info for one machine) and orbstack_machine_create/delete (which modify machines). It specifies the scope is all machines with their status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by stating it lists all machines and their status, suggesting it's for inventory/overview purposes. However, it doesn't explicitly state when to use this versus alternatives like orbstack_machine_info (for details on a specific machine) or orbstack_status (for overall OrbStack status). The context is clear but lacks explicit exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/heresun/orbstack-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server