Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt

Use this file to discover all available pages before exploring further.

Ghostly is purpose-built to work with Cursor’s Model Context Protocol support. Once the MCP server is registered, Cursor’s Composer agent gains direct access to Ghostly’s testing tools — meaning you can describe a user journey in plain English inside Composer and Cursor will call submit_plan or ghostly_run_flow on your behalf, without you writing a single line of test code manually.

​
Automatic setup with ghostly install

The fastest way to wire Ghostly into Cursor is to run the install command after generating your API key:
1

Install the Ghostly CLI

npm install -g @ghostly-io/cli
2

Generate local credentials

ghostly keygen
This initialises the local cryptography store and generates a per-machine API key. Each machine needs its own key — do not copy a key from another computer.
3

Run the installer

ghostly install
This command does three things for Cursor automatically:
  • Writes the ghostly MCP server entry to ~/.cursor/mcp.json
  • Copies Cursor rules to ~/.cursor/rules/ghosttester-expert-architect.mdc
  • Installs Ghostly skills to ~/.cursor/skills/ghosttester-expert-architect/
4

Start the Ghostly engine

ghostly up
This prepares the local SQLite database and starts the orchestration API at http://localhost:4000. The dashboard is also served from this address.
After running ghostly update to upgrade the CLI, always run ghostly install again to refresh the Cursor rules, skills, and MCP configuration to the latest version.

​
Manual mcp.json entry

If you need to add or update the entry by hand, open ~/.cursor/mcp.json (create it if it doesn’t exist) and merge in the following: 
{
  "mcpServers": {
    "ghostly": {
      "command": "node",
      "args": ["/path/to/node_modules/@ghostly-io/cli/dist/assets/mcp-server/index.js"],
      "env": {
        "GHOST_API_KEY": "<your-api-key>",
        "X_API_KEY": "<your-api-key>",
        "GHOST_API_URL": "http://localhost:4000"
      }
    }
  }
}
mcp.json stores your API key in plaintext. Do not commit this file to any repository.

​
Using Ghostly from Cursor Composer

Once the MCP server is active and ghostly up is running, you can drive tests directly from Cursor’s Composer panel.
1

Confirm the engine is running

Verify Ghostly is up by visiting http://localhost:4000/health in your browser or checking that ghostly up is active in a terminal.
2

Open Cursor Composer

Press Ctrl+I (Windows/Linux) or Cmd+I (macOS) to open the Composer panel. Make sure you are in Agent mode so that MCP tools are available.
3

Describe your test goal

Type a natural-language instruction. For example:
“Run an E2E test that logs in to http://localhost:3000 with user@example.com and verifies the dashboard loads.”
Cursor’s agent will read the project map via get_project_map, compose the steps, and call submit_plan with the structured plan.
4

Watch results stream in the dashboard

The submitted run appears immediately in the Ghostly dashboard at http://localhost:4000. Progress is delivered in real time via Server-Sent Events (SSE) — you can watch each step pass or fail as it happens.

​
Typical Composer prompts

Submit a full login flow

“Use Ghostly to test logging in at http://localhost:3000 with admin@acme.com, then verify the /dashboard route loads.”

Inspect your project's components

“Call get_project_map for the current project root and tell me which forms are available.”

Run a local headless flow

“Run a headless ghostly_run_flow that navigates to /signup and fills out the registration form.”

List existing projects

“List my Ghostly projects and show me the IDs I can use as the project parameter.”

​
Cursor Agent CLI as an LLM provider

Ghostly’s assisted mode supports a local Cursor CLI binary as the LLM provider. If you configure cursor-cli as the model source in ghostly config, the following additional requirements apply:
The agent binary from Cursor must be installed separately on your system path, and you must have completed authentication by running agent login at least once before Ghostly’s assisted mode can use it. This is independent from the MCP integration and only applies when using Cursor’s AI as Ghostly’s strategist/healer model.

​
What ghostly install writes to Cursor

PathPurpose
~/.cursor/mcp.jsonRegisters the Ghostly MCP server with your API key and API URL
~/.cursor/rules/ghosttester-expert-architect.mdcCursor rule that instructs the agent how to use Ghostly tools correctly
~/.cursor/skills/ghosttester-expert-architect/Skill definitions that guide the Composer agent through the Ghostly testing workflow
These files are safe to inspect and version in a personal dotfiles repository, except for mcp.json which contains your API key.

Build docs developers (and LLMs) love

Get started for freeTalk to us