Bio-OS

You can run and interact with the Bio-OS MCP Server to manage workflows and Docker image builds through a Model Context Protocol (MCP) client. It supports local deployment as well as cloud-based development environments, giving you flexible options for building and executing WDL workflows inside Bio-OS.

How to use

Connect to the Bio-OS MCP Server using an MCP client (such as a VSCode extension) and start a local or cloud-based session. You will be able to submit workflows, upload WDL files, validate scripts, generate input templates, build Docker images, and monitor build status and logs. Use the local pathway for development on your machine, or choose the cloud pathway to run inside a Miracle Cloud Code Server environment.

How to install

Prerequisites for local installation include a Python package manager and a workflow engine. Install them and then set up the server following the steps below.

pip install uv

Install the workflow engine Cromwell (for local workflow execution).

brew install cromwell

Clone the Bio-OS MCP Server repository to your local machine.

git clone https://github.com/GBA-BI/bioos-mcp-server.git

Configuration and start

Configure the Bio-OS MCP Server script path in your MCP client settings. Use the following example as a reference, replacing placeholders with absolute paths to your installation. After configuring, start the server and wait for the status to turn green.

{
  "mcpServers": {
    "bioos": {
      "command": "path/to/uv",
      "args": [
        "--directory",
        "path/to/bioos-mcp-server",
        "run",
        "path/to/bioos-mcp-server/src/bioos_mcp/bioos_mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/bioos-mcp-server/src",
        "MIRACLE_ACCESS_KEY": "xxxxxxxxxxxx",
        "MIRACLE_SECRET_KEY": "xxxxxxxxxxxx"
      }
    }
  }
}

If you encounter connection issues, use the Retry Connection option in your MCP client. If needed, copy the prompt content into the client’s custom instructions area to optimize your experience.

Cloud installation

For cloud development, you can use a pre-configured Docker image in Miracle Cloud. This option lets you open a Code Server environment that includes Bio-OS MCP Server.

1. Launch an IES instance using the image: registry-vpc.miracle.ac.cn/infcprelease/iespro:250217
2. Open with VSCode to access the development environment

Configuration in Code Server requires you to sign in and verify the MCP connection. In the CLINE extension, configure your LLM model credentials, then verify the Bio-OS MCP Server connection and use Retry Connection if needed.

Once configured, you can begin development with Bio-OS MCP Server in the cloud environment.

Configuration references and usage tips

The server supports the following workflow and Docker image management capabilities to streamline Bio-OS development.

API tools and capabilities

You can access a set of tools to manage your Bio-OS workflows and Docker images. The available tools include submitting workflows, importing WDL workflows, validating WDL scripts, generating input templates, building Docker images, and checking build status.

Notes on security and credentials

Keep your access keys and secret keys secure. Use environment variables provided by your MCP client configuration to pass credentials when using the tools.

Troubleshooting and tips

If the status remains unstable or you need to reestablish a connection, use the Retry Connection option in your MCP client. Ensure all paths in the configuration are absolute and that required dependencies are installed before starting the server.

Available tools

submit_workflow

Submit Bio-OS workflow with required credentials, workspace, and input data.

import_workflow

Upload a WDL workflow to the Bio-OS system with metadata and description.

validate_wdl

Validate a WDL workflow script to ensure syntax and structure correctness.

generate_inputs

Generate a template for WDL inputs based on the workflow.

build_docker_image

Build a Docker image from a Dockerfile or archive and push or store it in the registry.

check_build_status

Query the status of an ongoing or completed Docker image build.