ticket-ai

An MCP server and CLI that measures how your team actually writes tickets, and holds new ones to that. Not this ticket is bad — 31 of the 40 tickets that shipped here have an acceptance-criteria section, and this one does not.

No 'Akzeptanzkriterien' section. 31 of the 40 exemplar tickets (78%) have one.

Most ticket advice is free and therefore ignored. "Add acceptance criteria", "include steps to reproduce" — everyone has heard it, nobody changed anything. A count of what already happened in your own project is harder to wave away, and it is not an opinion about tickets.

There is no model in the loop for any of that. Learning the house style, finding related tickets and measuring a draft are counting, and run with no key and no network beyond your tracker. Writing a ticket needs a model, so that part is opt-in and which one is your choice. What it found when it was run against real boards →

Install

uv tool install ticket-ai-mcp

Configuration is environment variables only — a token passed as --token ends up in your shell history and in the process list.

export TICKET_AI_TRACKER=gitlab
export TICKET_AI_PROJECT=acme/shop        # or the numeric id
export TICKET_AI_GITLAB_URL=https://gitlab.example.com
export TICKET_AI_GITLAB_TOKEN=...         # read_api scope is enough

The token is optional on a public project. TICKET_AI_GITLAB_URL=https://gitlab.com with no token reads any public board, which is the quickest way to see what this does before pointing it at your own instance.

# Jira — Cloud or self-hosted Server / Data Center. Which one you are on is
# detected from the instance; you do not have to say.
export TICKET_AI_TRACKER=jira
export TICKET_AI_PROJECT=PROJ
export TICKET_AI_JIRA_URL=https://acme.atlassian.net

# Leave the credentials unset for a public board — plenty answer without any.
# Cloud: the token comes from id.atlassian.com, and is not the password.
export TICKET_AI_JIRA_EMAIL=you@example.com
export TICKET_AI_JIRA_TOKEN=...
# Self-hosted: a personal access token on its own, sent as a Bearer.
export TICKET_AI_JIRA_TOKEN=...
# Only if detection gets it wrong: cloud | server | auto (the default)
export TICKET_AI_JIRA_API=server

# GitHub
export TICKET_AI_TRACKER=github
export TICKET_AI_PROJECT=acme/shop
export TICKET_AI_GITHUB_TOKEN=...

mcp-name: io.github.syrian963/ticket-ai-mcp

One command

ticket-ai learn      # mine the tracker, cache the profile
ticket-ai style      # what it learned

learn takes a minute or two: ranking needs each ticket's comments and linked merge requests, which is an extra request or two per ticket. It caches to TICKET_AI_CACHE_DIR if you set one and to .ticket-ai/ otherwise, so it happens once rather than once per review.

Then the rest:

ticket-ai learn --from '#412,#98'                  # or name the good ones yourself
ticket-ai context 'export is broken on mobile'     # what already exists
ticket-ai gaps                                     # declared template vs what arrives
ticket-ai draft --title '...' --file draft.md      # check one before creating it
ticket-ai review '#42'                             # measure one that exists
ticket-ai open                                     # every open ticket, worst first

draft is the one worth building a habit around. Checking a ticket after you create it puts the review past the point of no return: the board has already been notified and every fix is now an edit with a history.

$ ticket-ai draft --title 'Filter kaputt' --file draft.md
Alignment with house style: 33% over 3 checks

### MEDIUM - The description is 116 characters.
The shortest quarter of tickets that shipped here start at 639; the median is 1079.

### MEDIUM - The ticket has no labels.
62% of the exemplars are labelled.

--from is taken as given: no filtering, no scoring against your choices. Name a ticket with a three-word description and that is your answer about how this team writes tickets, and the profile will say so.

As an MCP server

{
  "mcpServers": {
    "ticket-ai": {
      "command": "uvx",
      "args": ["ticket-ai-mcp"],
      "env": {
        "TICKET_AI_TRACKER": "gitlab",
        "TICKET_AI_PROJECT": "acme/shop",
        "TICKET_AI_GITLAB_URL": "https://gitlab.example.com",
        "TICKET_AI_GITLAB_TOKEN": "..."
      }
    }
  }
}

Eight tools, all read-only: learn_conventions, house_style, ticket_template, ticket_context, template_gaps, review_draft, review_ticket, review_open_tickets.

Add TICKET_AI_REPO to the env block if the checkout you want searched is not the assistant's working directory.

Writing a ticket this way

The path to reach for if you already use Claude Code: no key, no compose, no second model call. Ask for a ticket and the assistant does five things, three of them here:

1. ticket_template — the shape: which sections, how long, what language, which labels.
2. ticket_context — what exists: related tickets, the files their merge requests changed, the files in the checkout that mention it.
3. It reads those files. ticket_context runs a text search, not an analysis; it says where to look, it does not save you looking.
4. It writes the ticket.
5. review_draft — measures what it wrote, and fixes what that finds before showing you anything.

Where the "AI" is

Counting cannot produce a paragraph of German, so writing a ticket needs a model. Everything else needs nothing.

export TICKET_AI_WRITER=ollama       # or openai, with a base url and key
ticket-ai models                     # what that endpoint can reach
ticket-ai compose --title 'Etikettendruck bricht bei mehr als zehn Positionen ab'
ticket-ai models --workflow          # an Actions workflow that drafts new issues

compose writes the body, measures it, hands the findings back to the model once, and prints the review to stderr so the body alone can be redirected. --fail-under makes it refuse to emit a draft that missed the house style.

Whichever model writes, the draft goes through the same measurement as any other ticket. That loop is why a small local model is usable here: it writes into a shape worked out by counting, and is marked against your team's own tickets afterwards.

A page instead

ticket-ai ui --lang de     # or en

A local page on 127.0.0.1:8760 with three tabs: the house style, a box to paste a draft into, and the open backlog worst-first. Loopback only, because this process holds a tracker token, and there is no flag to change that.

No build step and no CDN — one HTML file with its CSS and JavaScript inline.

Two languages, and they are separate

export TICKET_AI_UI_LANGUAGE=de       # buttons and headings
export TICKET_AI_TICKET_LANGUAGE=de   # what it says to write tickets in

The distinction is easy to collapse and worth keeping. A German team may want the tool's own buttons in English; someone joining a German board still has to write the ticket in German.

TICKET_AI_TICKET_LANGUAGE overrides what the corpus measured and takes effect without re-learning. Leave it unset unless the board is mid-switch — a measurement beats a setting, and forcing a language the board does not use makes every existing ticket fail the language check.

Findings, the caveats under them and the list of what a ticket already got right are all rendered in the reader's language at the moment they are shown. The section names inside them are not: those are the team's own headings, and translating one turns it into a section the team does not have.

In CI

ticket-ai review "$CI_ISSUE" --fail-under 0.5

What it measures

The house style. Sections, length, labels, title markers, language — over a corpus it either took from you or found itself. Every finding cites a count over that corpus.

The tickets that failed, not only the ones that worked. A rate can be a comparison: not "78% of tickets have acceptance criteria" but "78% of the ones that shipped, and 30% of the ones that stalled". The second is evidence; the first invites a shrug.