th2-report

An MCP (Model Context Protocol) server that connects AI assistants (Claude, Cursor, etc.) to a TH2 Report Viewer instance. Query test results, drill into failures, and inspect FIX/Java API messages — all from your AI chat.

What is TH2?

TH2 is an open-source microservice test framework used for automated trading platform testing. It records every message and event in a structured tree. This MCP server exposes that tree to AI assistants so you can investigate test failures conversationally.

Requirements

• Node.js ≥ 18
• A running TH2 Report backend accessible over HTTP
• An MCP-compatible client (Claude Desktop, Cursor, VS Code with MCP extension, etc.)

Installation

npm install -g th2-report

Or use directly via npx (no install needed):

npx th2-report

Configuration

The server is configured entirely via environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | TH2_BASE_URL | Yes | — | Base URL of your TH2 backend, e.g. http://th2-host:30000/th2-env/backend | | TH2_BOOK_ID | No | test_quod | TH2 book ID | | TH2_SCOPE | No | test_scope | TH2 scope |

MCP Client Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "th2-report": {
      "command": "npx",
      "args": ["th2-report"],
      "env": {
        "TH2_BASE_URL": "http://your-th2-host:30000/th2-env/backend",
        "TH2_BOOK_ID": "test_quod",
        "TH2_SCOPE": "test_scope"
      }
    }
  }
}

Claude Code (CLI)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "th2-report": {
      "command": "npx",
      "args": ["th2-report"],
      "env": {
        "TH2_BASE_URL": "http://your-th2-host:30000/th2-env/backend",
        "TH2_BOOK_ID": "test_quod",
        "TH2_SCOPE": "test_scope"
      }
    }
  }
}

Cursor / VS Code

Add the same JSON block to your MCP server configuration in the IDE settings.

Available Tools

search_test_case

Search for a test case by name (e.g. QAP_T2429). Returns matching events with status and timestamps.

| Parameter | Type | Default | Description | |---|---|---|---| | test_case_name | string | — | Test case name or partial name | | minutes_back | number | 120 | How far back to search | | max_results | number | 5 | Maximum results to return |

get_event_by_id

Fetch a single TH2 event by its full composite ID.

Tip: Always prefer the full composite ID (e.g. test_quod:test_scope:20260401101038186404000:0800d46e-...). Passing only a UUID triggers an expensive 8-hour-wide search.

| Parameter | Type | Default | Description | |---|---|---|---| | event_id | string | — | Full composite event ID (or bare UUID as fallback) | | include_raw | boolean | false | Include full raw TH2 payload |

get_event_children

Get child events (steps) of a parent TH2 event. Ideal for drilling into a test case after finding it with search_test_case.

| Parameter | Type | Default | Description | |---|---|---|---| | parent_event_id | string | — | Full event ID of the parent | | minutes_back | number | 120 | Search window in minutes | | max_results | number | 50 | Max children to return | | failed_only | boolean | false | Return only failed children |

get_failed_tests

Get all failed test events in a time window. Returns a flat list of failed test roots with their event IDs. To investigate a specific failure, follow up with get_test_case_tree or get_event_children.

| Parameter | Type | Default | Description | |---|---|---|---| | minutes_back | number | 60 | How many minutes back to search | | max_results | number | 20 | Maximum results | | name_filter | string | — | Optional name filter (e.g. QAP_T) |

get_test_case_tree

Fetch a full event tree for a test case in a single call. Finds the root event by name, then recursively fetches its children up to max_depth levels.

| Parameter | Type | Default | Description | |---|---|---|---| | test_case_name | string | — | Test case name (e.g. QAP_T2429) | | minutes_back | number | 120 | How far back to search | | max_depth | number | 2 | Depth of child traversal (max 5) | | failed_only | boolean | false | Only traverse failed branches | | max_per_level | number | 20 | Max children per level |

search_messages

Search TH2 for FIX / Java API messages sent or received during a test.

Note: At least one of attached_event_id or session_alias is required.

Typical workflow: get the eventId of a test step from get_test_case_tree, then call search_messages(attached_event_id=<step_eventId>, include_fields=true) to inspect exact FIX messages.

| Parameter | Type | Default | Description | |---|---|---|---| | attached_event_id | string | — | Filter by attached event ID | | session_alias | string | — | FIX session alias (e.g. QUOD317_SELL) | | minutes_back | number | 120 | Search window | | max_results | number | 50 | Max messages to return | | include_fields | boolean | false | Include full FIX fields payload |

get_event_ancestors

Walk up the parent chain of a TH2 event and return all ancestors up to the root. Useful when you have the ID of a failed step and need to find which test case it belongs to.

| Parameter | Type | Default | Description | |---|---|---|---| | event_id | string | — | Full event ID to start from | | max_levels | number | 10 | Max parent hops to follow (max 20) |

debug_raw_search

Returns the raw SSE response and URL for a search query. Use this to inspect what the TH2 API actually returns when troubleshooting connection or data issues.

| Parameter | Type | Default | Description | |---|---|---|---| | minutes_back | number | 60 | Search window | | name | string | — | Optional event name filter | | status | string | — | Optional status filter (e.g. failed) | | parent_id | string | — | Optional parent event ID filter |

Example Conversations

Once connected, you can ask your AI assistant things like:

• "Did QAP_T2429 pass in the last 2 hours?"
• "Show me all failed tests from the last 30 minutes."
• "What FIX messages were sent during QAP_T2429's execution?"
• "Why did QAP_T18128 fail? Show me the full event tree."
• "Which test case does event abc-123-... belong to?"

Event ID Format

TH2 composite event IDs follow the pattern:

<bookId>:<scope>:<timestamp>:<uuid>

Example: test_quod:test_scope:20260401101038186404000:0800d46e-1234-5678-abcd-ef0123456789

Always pass the full composite ID to get_event_by_id for best performance. Bare UUIDs are accepted as a fallback but trigger a slow 8-hour-wide scan.

License

ISC © Quod Financial