gi-mcp-server

An MCP (Model Context Protocol) server that exposes Ghost Inspector API tools for use with AI coding agents (e.g. GitHub Copilot). Responses are filtered to only the fields relevant for Playwright test conversion.

Tools

get_test

Fetches a single Ghost Inspector test by ID, returning fields useful for Playwright conversion:

| Field | Description | |---|---| | name | Test name | | details | Test description | | passing | Whether the test is currently passing | | screenshotCompareEnabled | Whether screenshot comparison is enabled | | screenshotComparePassing | Whether screenshot comparison is passing |

get_test_result

Fetches the most recent result for a Ghost Inspector test, returning fields useful for Playwright conversion:

| Field | Description | |---|---| | name | Test name | | screenshotUrl | URL of the final screenshot (screenshot.original.defaultUrl) | | screenshotCompareThreshold | Screenshot comparison threshold | | startUrl | The URL the test starts at | | steps | Array of executed test steps |

list_suites

Fetches all Ghost Inspector suites in your account:

| Field | Description | |---|---| | _id | Suite ID | | name | Suite name | | testCount | Number of tests in the suite |

update_test

Updates a Ghost Inspector test's name and/or suite assignment. Returns a success confirmation.

| Parameter | Required | Description | |---|---|---| | testId | Yes | The ID of the test to update | | name | No | New name for the test | | suite | No | ID of the suite to move the test to |

Installation

npm install -g @energycap/gi-mcp-server

Or use directly via npx without installing:

npx @energycap/gi-mcp-server

Configuration

Set the GI_API_KEY environment variable to your Ghost Inspector API key (found in your account settings):

export GI_API_KEY=your_api_key_here

MCP Client Setup

VS Code (GitHub Copilot agent)

Add the server to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "gi-mcp-server": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@energycap/gi-mcp-server"],
        "tools": ["get_test", "get_test_result", "list_suites", "update_test"],
        "env": {
          "GI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Or if installed globally:

{
  "mcp": {
    "servers": {
      "gi-mcp-server": {
        "type": "stdio",
        "command": "gi-mcp-server",
        "tools": ["get_test", "get_test_result", "list_suites", "update_test"],
        "env": {
          "GI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

GitHub Copilot Custom agents

Add your GI API key to the copilot environment secrets. Make sure it's prefixed with COPILOT_MCP_. For more information, see here.

Then add the MCP server to your custom agent's config file:

---
name: my-custom-agent
description: My custom agent description
tools: ['gi-mcp-server/get_test', 'gi-mcp-server/get_test_result', 'gi-mcp-server/list_suites', 'gi-mcp-server/update_test']
mcp-servers:
  gi-mcp-server:
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@energycap/gi-mcp-server'],
    tools: ['get_test', 'get_test_result', 'list_suites', 'update_test'],
    env: 
      GI_API_KEY: ${{ secrets.COPILOT_MCP_GI_API_KEY }}
---

Custom agent prompt here

For more information, see custom agents configuration.

Building from source

npm install
npm run build
npm start

Publishing

npm publish --dry-run  # verify contents first
npm publish