# Connector tool reference

Source: https://www.testifysec.com/docs/badger/reference/connector-tools/

Every tool each Badger connector registers, with its parameters, generated from the connectors themselves.

This page lists the MCP tools each connector on this branch registers, as the connector itself reports them over `tools/list` with writes enabled. It is generated by `docs/tools/generate.ts`, which builds and runs every connector under `testifysec/connectors/`, so it cannot drift from the code. Each tool is labelled from its MCP `readOnlyHint` annotation: Read when the hint is true, Write when it is false. The shared connector library registers a Write tool only when the connector runs with `--enable-writes`.

 

The Jira, Confluence and GitLab connectors are on `main`; `example` is the reference connector for authors. A managed Badger session cannot load a connector yet; see [connectors](https://www.testifysec.com/docs/badger/concepts/connectors).

 

### confluence

 

#### `confluence_create_page`

 

Write. Create a page in a space (key), optionally under parent\_id. body is markdown: headings, paragraphs, lists, fenced code, bold, inline code and http(s) links. Changes the service. Every result carries the connector's configured classification marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes |  |
| `parent_id` | string | no |  |
| `space` | string | yes |  |
| `title` | string | yes |  |

 

#### `confluence_get_page`

 

Read. Get a page as markdown with its labels, version and ancestor ids. Pass id, or space (key) and exact title. Every result carries the connector's configured classification marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no |  |
| `space` | string | no |  |
| `title` | string | no |  |

 

#### `confluence_list_children`

 

Read. List the child pages of a page id. limit 1-50 (default 25), start to page. Every result carries the connector's configured classification marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `limit` | integer | no |  |
| `start` | integer | no |  |

 

#### `confluence_list_spaces`

 

Read. List spaces you can see. limit 1-50 (default 25), start to page, type global or personal. Every result carries the connector's configured classification marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no |  |
| `start` | integer | no |  |
| `type` | string | no |  |

 

#### `confluence_search`

 

Read. Search content with CQL (e.g. `space = ENG and type = page and text ~ "release"`). limit 1-50 (default 10); page with start, or cursor when the result says so. Returns ids, titles and spaces. Every result carries the connector's configured classification marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `cql` | string | yes |  |
| `cursor` | string | no |  |
| `limit` | integer | no |  |
| `start` | integer | no |  |

 

#### `confluence_update_page`

 

Write. Replace a page body (markdown, as for create) and optionally its title. version must be the page's current version number from confluence\_get\_page; the update is refused if the page has changed since. Changes the service. Every result carries the connector's configured classification marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes |  |
| `id` | string | yes |  |
| `title` | string | no |  |
| `version` | integer | yes |  |

 

### example

 

Reference connector for authors; not shipped.

 

#### `example_add_note`

 

Write. Add a note to an item. Changes the service.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes |  |
| `text` | string | yes |  |

 

#### `example_get_item`

 

Read. Get one item by numeric id: title, state, author and body.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes |  |

 

### gitlab

 

#### `gitlab_add_note`

 

Write. Add a comment to an issue or merge request. Changes the service.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | markdown comment |
| `iid` | integer | yes | the project-scoped number shown as #N or !N |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `target` | string | yes | issue or merge\_request |

 

#### `gitlab_create_issue`

 

Write. Create an issue in a project. Changes the service.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | no | markdown body |
| `labels` | array of string | no | labels to set |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `title` | string | yes | issue title |

 

#### `gitlab_get_file`

 

Read. Get a text file from the repository at a branch, tag or commit. Binary files are refused, and a path containing ";" cannot be read. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | string | yes | file path inside the repository, e.g. cmd/app/main.go |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `ref` | string | no | branch, tag or commit; default the project's default branch |

 

#### `gitlab_get_issue`

 

Read. Get one issue with its description and the first discussion threads (system notes left out). The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `iid` | integer | yes | the project-scoped number shown as #N or !N |
| `notes` | integer | no | how many discussion threads to include, 0-100, default 20; 0 leaves them out |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |

 

#### `gitlab_get_job_log`

 

Read. Get the last lines of a CI job's log, with terminal escapes removed. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | integer | yes | job id from gitlab\_list\_pipelines |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `tail_lines` | integer | no | lines from the end, 1-2000, default 200 |

 

#### `gitlab_get_merge_request`

 

Read. Get one merge request with its description and discussion threads, including the file and line of review comments. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `iid` | integer | yes | the project-scoped number shown as #N or !N |
| `notes` | integer | no | how many discussion threads to include, 0-100, default 20; 0 leaves them out |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |

 

#### `gitlab_get_merge_request_diff`

 

Read. Get a merge request's changed files and diffs, capped per file and per call. Paged by file. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `iid` | integer | yes | the project-scoped number shown as #N or !N |
| `page` | integer | no | page number, default 1 |
| `per_page` | integer | no | items per page, 1-100, default 20 |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |

 

#### `gitlab_get_project`

 

Read. Get a project: path, default branch, visibility, topics, description. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |

 

#### `gitlab_list_merge_requests`

 

Read. List a project's merge requests, newest first. Paged. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `labels` | string | no | comma-separated labels |
| `page` | integer | no | page number, default 1 |
| `per_page` | integer | no | items per page, 1-100, default 20 |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `search` | string | no | text to find in title and description |
| `source_branch` | string | no | source branch |
| `state` | string | no | opened, closed, merged, locked or all |
| `target_branch` | string | no | target branch |

 

#### `gitlab_list_pipelines`

 

Read. List a project's pipelines, newest first, or with pipeline\_id the jobs of one pipeline (job ids feed gitlab\_get\_job\_log).

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | page number, default 1 |
| `per_page` | integer | no | items per page, 1-100, default 20 |
| `pipeline_id` | integer | no | list this pipeline's jobs instead |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `ref` | string | no | branch or tag |
| `status` | string | no | pipeline status, e.g. failed, success, running |

 

#### `gitlab_search_issues`

 

Read. List or search a project's issues, newest first. Paged. The result's classification banner is the connector's configured marking.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `labels` | string | no | comma-separated labels, all must match |
| `page` | integer | no | page number, default 1 |
| `per_page` | integer | no | items per page, 1-100, default 20 |
| `project` | string | yes | numeric project id or full path, e.g. group/subgroup/project |
| `search` | string | no | text to find in title and description |
| `state` | string | no | opened, closed or all |

 

### jira

 

#### `jira_add_comment`

 

Write. Add a comment (Jira wiki markup) to an issue. Changes the service.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes |  |
| `body` | string | yes |  |

 

#### `jira_create_issue`

 

Write. Create an issue in a project. Changes the service.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | string | yes | project key, e.g. PROJ |
| `issue_type` | string | yes | issue type name, e.g. Task |
| `summary` | string | yes |  |
| `description` | string | no | Jira wiki markup |

 

#### `jira_get_issue`

 

Read. Get one issue by key (PROJ-123): summary, status, type, priority, assignee, reporter, labels, components, description as markdown, and linked issues.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes | issue key, e.g. PROJ-123 |

 

#### `jira_list_comments`

 

Read. List an issue's comments, oldest first, one page at a time (default 20, at most 50).

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes |  |
| `start_at` | integer (minimum 0) | no |  |
| `max_results` | integer (minimum 1, maximum 50) | no |  |

 

#### `jira_search`

 

Read. Search issues with JQL. Returns one page (default 20, at most 50) of key, status, summary, type, priority, assignee and updated date; pass start\_at from the previous page's next\_page to continue. fields adds or replaces the returned fields (Jira field ids).

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `jql` | string | yes | JQL query |
| `start_at` | integer (minimum 0) | no |  |
| `max_results` | integer (minimum 1, maximum 50) | no |  |
| `fields` | array of string (at most 20) | no |  |

 

#### `jira_transition_issue`

 

Write. Move an issue through its workflow by transition name or id. If the transition is not available, the error lists the ones that are. Changes the service.

 

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes |  |
| `transition` | string | yes | transition name or id |

Reference generated from the product documentation. Match commands and support details to your installed release.