Skip to main content
Glama
heresun

OrbStack MCP Server

by heresun

orbstack_machine_pull

Transfer files from Linux virtual machines to macOS using OrbStack. Specify source path, optional destination, and machine name to copy files between systems.

Instructions

从 Linux 机器拉取文件到 macOS。

Args: params: 包含源文件路径、可选的目标路径和机器名

Returns: str: 传输结果

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Implementation Reference

  • The implementation of the orbstack_machine_pull tool handler.
    async def orbstack_machine_pull(params: MachineFileTransferInput) -> str:
        """从 Linux 机器拉取文件到 macOS。
    
        Args:
            params: 包含源文件路径、可选的目标路径和机器名
    
        Returns:
            str: 传输结果
        """
        args = ["pull"]
        if params.machine:
            args.extend(["-m", params.machine])
        args.append(params.source)
        if params.destination:
            args.append(params.destination)
    
        code, stdout, stderr = await _run_orb(args)
        if code != 0:
            return _format_error(stderr)
        return f"文件已拉取: {params.source}" + (f" -> {params.destination}" if params.destination else "")
  • Registration of the orbstack_machine_pull tool.
    @mcp.tool(
        name="orbstack_machine_pull",
        annotations={
            "title": "从 Linux 机器拉取文件",
            "readOnlyHint": False,
            "destructiveHint": False,
            "idempotentHint": False,
            "openWorldHint": False,
        },
  • Schema definition for MachineFileTransferInput.
    class MachineFileTransferInput(BaseModel):
        """文件传输的输入参数"""
        model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
    
        source: str = Field(
            ...,
            description="源文件路径",
            min_length=1,
        )
        destination: Optional[str] = Field(
            default=None,
            description="目标路径,不指定则使用当前目录",
        )
Behavior2/5

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

Annotations provide basic hints (readOnlyHint=false, destructiveHint=false, etc.), but the description adds minimal behavioral context. It mentions '传输结果' (transfer result) as the return, but doesn't describe what happens on failure, whether files are overwritten, authentication requirements, or network behavior. With annotations covering only basic safety, the description should provide more operational context for a file transfer tool.

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

Conciseness3/5

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

The description is brief but could be better structured. The first sentence states the purpose clearly, but the Args/Returns sections are redundant with the schema and output schema. The information could be more front-loaded and eliminate the schema-like formatting to be more conversational for an AI agent.

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

Completeness3/5

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

Given the tool's complexity (file transfer between systems), annotations provide basic safety hints, and an output schema exists (so return values are documented elsewhere), the description is minimally complete. However, it lacks important context about error conditions, file overwrite behavior, and machine connectivity requirements that would be helpful for an agent using this tool.

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

Parameters3/5

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

The description mentions parameters ('包含源文件路径、可选的目标路径和机器名') but provides no additional semantics beyond what's already in the schema. Since schema description coverage is 0%, the schema itself lacks parameter descriptions, making the description's brief mention insufficient. However, the parameter structure is simple (one object with three fields), so baseline 3 is appropriate given the low complexity.

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

Purpose4/5

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

The description clearly states the tool's purpose: '从 Linux 机器拉取文件到 macOS' (pull files from Linux machine to macOS). This is a specific verb+resource combination that distinguishes it from sibling tools like 'orbstack_machine_push' (which goes in the opposite direction) and 'orbstack_machine_run' (which executes commands). However, it doesn't explicitly differentiate from all siblings, just implies directionality.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. While the title '从 Linux 机器拉取文件' suggests it's for pulling files from Linux machines, there's no mention of prerequisites, when not to use it, or explicit comparison with similar tools like 'orbstack_machine_push' for the reverse operation or 'orbstack_docker_pull' for Docker images.

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