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.

The server uses the production MCP TypeScript SDK v1 line and supports the current MCP 2025-11-25 protocol through SDK negotiation. JSON tools publish output schemas and return both structured content and a serialized text fallback for compatibility with older clients.

Tools

get_test

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

| Field | Description | |---|---| | _id | Test ID | | 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 | | screenshotTarget | CSS selector for the screenshot target element | | screenshotExclusions | CSS selectors to exclude from screenshot comparison | | startUrl | The URL the test starts at | | steps | Array of test steps | | suite | The test's suite (_id and name) |

get_test_screenshot

Downloads and returns the screenshot image from the most recent passing Ghost Inspector test result. A passing result is one where the test is passing and, if screenshot comparison is enabled, the screenshot comparison is also passing.

The screenshot is returned as an MCP image content block (base64-encoded) with structured metadata so AI agents can view it directly. The tool scans up to 50 recent results by default and accepts maxResultsToSearch (1–500) when a deeper search is needed. Returns a model-visible error if no qualifying screenshot is found.

list_folders

Fetches all Ghost Inspector folders in your account:

| Field | Description | |---|---| | _id | Folder ID | | name | Folder name |

list_suites

Fetches all Ghost Inspector suites in your account:

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

list_folder_suites

Fetches all Ghost Inspector suites in a folder:

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

list_suite_tests

Fetches all Ghost Inspector tests in a suite:

| Field | Description | |---|---| | _id | Test ID | | 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 |

update_test

Updates a Ghost Inspector test's name, details, and/or suite assignment. At least one update field is required. Returns the filtered, updated test.

| Parameter | Required | Description | |---|---|---| | testId | Yes | The ID of the test to update | | name | No | New name for the test | | details | No | New details/description for the test | | suiteId | No | ID of the suite to move the test to | | suite | No | ID of the suite to move the test to (alias for suiteId) |

Tool contract behavior

• All tools have human-readable titles, focused descriptions, strict input schemas, and MCP behavior annotations.
• Read tools are marked read-only; update_test is marked mutating, potentially destructive, and idempotent.
• Ghost Inspector API failures are returned with isError: true, including the documented API error type and message when available, so agents can self-correct.
• API calls honor MCP cancellation and use a 30-second timeout. Screenshot downloads require HTTPS, an image content type, and a maximum size of 20 MiB.
• The API key is passed only to Ghost Inspector as the documented query parameter and is never included in tool output.

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"],
        "env": {
          "GI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Or if installed globally:

{
  "mcp": {
    "servers": {
      "gi-mcp-server": {
        "type": "stdio",
        "command": "gi-mcp-server",
        "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_screenshot', 'gi-mcp-server/list_folders', 'gi-mcp-server/list_suites', 'gi-mcp-server/list_folder_suites', 'gi-mcp-server/list_suite_tests', 'gi-mcp-server/update_test']
mcp-servers:
  gi-mcp-server:
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@energycap/gi-mcp-server'],
    env: 
      GI_API_KEY: ${{ secrets.COPILOT_MCP_GI_API_KEY }}
---

Custom agent prompt here

For more information, see custom agents configuration.

Building from source

Node.js 18 or newer is required.

npm install
npm run build
npm test
npm start

Publishing

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