{
  "markdown": "# ticket-ai\n\n![release](https://img.shields.io/badge/release-v0.1.1-1f6feb?style=for-the-badge&labelColor=22272e)\n![MCP tools](https://img.shields.io/badge/MCP%20tools-8-8957e5?style=for-the-badge&labelColor=22272e)\n![CLI commands](https://img.shields.io/badge/CLI%20commands-11-8957e5?style=for-the-badge&labelColor=22272e)\n![trackers](https://img.shields.io/badge/trackers-GitLab%20%7C%20Jira%20%7C%20GitHub-8957e5?style=for-the-badge&labelColor=22272e)\n\n![tests](https://img.shields.io/badge/tests-502-238636?style=for-the-badge&labelColor=22272e)\n![coverage](https://img.shields.io/badge/coverage-93%25-238636?style=for-the-badge&labelColor=22272e)\n![python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-484f58?style=for-the-badge&labelColor=22272e&logo=python&logoColor=white)\n![license](https://img.shields.io/badge/license-MIT-484f58?style=for-the-badge&labelColor=22272e)\n\n**An MCP server and CLI that measures how your team actually writes tickets, and\nholds new ones to that.** Not *this ticket is bad* — *31 of the 40 tickets that\nshipped here have an acceptance-criteria section, and this one does not.*\n\n> **No 'Akzeptanzkriterien' section.**\n> 31 of the 40 exemplar tickets (78%) have one.\n\nMost ticket advice is free and therefore ignored. \"Add acceptance criteria\",\n\"include steps to reproduce\" — everyone has heard it, nobody changed anything.\nA count of what already happened in your own project is harder to wave away,\nand it is not an opinion about tickets.\n\n**There is no model in the loop for any of that.** Learning the house style,\nfinding related tickets and measuring a draft are counting, and run with no key\nand no network beyond your tracker. Writing a ticket needs a model, so that\npart is opt-in and which one is your choice.\n**[What it found when it was run against real boards →](docs/thirty-boards.md)**\n\n## Install\n\n```bash\nuv tool install ticket-ai-mcp\n```\n\nConfiguration is environment variables only — a token passed as `--token` ends\nup in your shell history and in the process list.\n\n```bash\nexport TICKET_AI_TRACKER=gitlab\nexport TICKET_AI_PROJECT=acme/shop        # or the numeric id\nexport TICKET_AI_GITLAB_URL=https://gitlab.example.com\nexport TICKET_AI_GITLAB_TOKEN=...         # read_api scope is enough\n```\n\nThe token is optional on a public project. `TICKET_AI_GITLAB_URL=https://gitlab.com`\nwith no token reads any public board, which is the quickest way to see what\nthis does before pointing it at your own instance.\n\n<details>\n<summary>Jira and GitHub</summary>\n\n```bash\n# Jira — Cloud or self-hosted Server / Data Center. Which one you are on is\n# detected from the instance; you do not have to say.\nexport TICKET_AI_TRACKER=jira\nexport TICKET_AI_PROJECT=PROJ\nexport TICKET_AI_JIRA_URL=https://acme.atlassian.net\n\n# Leave the credentials unset for a public board — plenty answer without any.\n# Cloud: the token comes from id.atlassian.com, and is not the password.\nexport TICKET_AI_JIRA_EMAIL=you@example.com\nexport TICKET_AI_JIRA_TOKEN=...\n# Self-hosted: a personal access token on its own, sent as a Bearer.\nexport TICKET_AI_JIRA_TOKEN=...\n# Only if detection gets it wrong: cloud | server | auto (the default)\nexport TICKET_AI_JIRA_API=server\n\n# GitHub\nexport TICKET_AI_TRACKER=github\nexport TICKET_AI_PROJECT=acme/shop\nexport TICKET_AI_GITHUB_TOKEN=...\n```\n\n</details>\n\nmcp-name: io.github.syrian963/ticket-ai-mcp\n\n## One command\n\n```bash\nticket-ai learn      # mine the tracker, cache the profile\nticket-ai style      # what it learned\n```\n\n`learn` takes a minute or two: ranking needs each ticket's comments and linked\nmerge requests, which is an extra request or two per ticket. It caches to\n`TICKET_AI_CACHE_DIR` if you set one and to `.ticket-ai/` otherwise, so it\nhappens once rather than once per review.\n\nThen the rest:\n\n```bash\nticket-ai learn --from '#412,#98'                  # or name the good ones yourself\nticket-ai context 'export is broken on mobile'     # what already exists\nticket-ai gaps                                     # declared template vs what arrives\nticket-ai draft --title '...' --file draft.md      # check one before creating it\nticket-ai review '#42'                             # measure one that exists\nticket-ai open                                     # every open ticket, worst first\n```\n\n`draft` is the one worth building a habit around. Checking a ticket after you\ncreate it puts the review past the point of no return: the board has already\nbeen notified and every fix is now an edit with a history.\n\n```\n$ ticket-ai draft --title 'Filter kaputt' --file draft.md\nAlignment with house style: 33% over 3 checks\n\n### MEDIUM - The description is 116 characters.\nThe shortest quarter of tickets that shipped here start at 639; the median is 1079.\n\n### MEDIUM - The ticket has no labels.\n62% of the exemplars are labelled.\n```\n\n`--from` is taken as given: no filtering, no scoring against your choices. Name\na ticket with a three-word description and that is your answer about how this\nteam writes tickets, and the profile will say so.\n\n## As an MCP server\n\n```json\n{\n  \"mcpServers\": {\n    \"ticket-ai\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ticket-ai-mcp\"],\n      \"env\": {\n        \"TICKET_AI_TRACKER\": \"gitlab\",\n        \"TICKET_AI_PROJECT\": \"acme/shop\",\n        \"TICKET_AI_GITLAB_URL\": \"https://gitlab.example.com\",\n        \"TICKET_AI_GITLAB_TOKEN\": \"...\"\n      }\n    }\n  }\n}\n```\n\nEight tools, all read-only: `learn_conventions`, `house_style`,\n`ticket_template`, `ticket_context`, `template_gaps`, `review_draft`,\n`review_ticket`, `review_open_tickets`.\n\nAdd `TICKET_AI_REPO` to the `env` block if the checkout you want searched is\nnot the assistant's working directory.\n\n### Writing a ticket this way\n\nThe path to reach for if you already use Claude Code: no key, no `compose`, no\nsecond model call. Ask for a ticket and the assistant does five things, three\nof them here:\n\n1. **`ticket_template`** — the shape: which sections, how long, what language,\n   which labels.\n2. **`ticket_context`** — what exists: related tickets, the files their merge\n   requests changed, the files in the checkout that mention it.\n3. **It reads those files.** `ticket_context` runs a text search, not an\n   analysis; it says where to look, it does not save you looking.\n4. **It writes the ticket.**\n5. **`review_draft`** — measures what it wrote, and fixes what that finds\n   before showing you anything.\n\n## Where the \"AI\" is\n\nCounting cannot produce a paragraph of German, so writing a ticket needs a\nmodel. Everything else needs nothing.\n\n| | Writes | Needs |\n|---|---|---|\n| **MCP, in Claude Code** | yes | nothing — the assistant is already a model |\n| **`--writer ollama`** | yes | a model on your machine. No key, no account, nothing leaves the laptop |\n| **`--writer openai`** | yes | a base URL and a key. OpenRouter, Azure AI Foundry, vLLM, any provider |\n| **no writer (default)** | no | nothing. Measures and gathers; you write |\n\n```bash\nexport TICKET_AI_WRITER=ollama       # or openai, with a base url and key\nticket-ai models                     # what that endpoint can reach\nticket-ai compose --title 'Etikettendruck bricht bei mehr als zehn Positionen ab'\nticket-ai models --workflow          # an Actions workflow that drafts new issues\n```\n\n`compose` writes the body, measures it, hands the findings back to the model\nonce, and prints the review to stderr so the body alone can be redirected.\n`--fail-under` makes it refuse to emit a draft that missed the house style.\n\nWhichever model writes, the draft goes through the same measurement as any\nother ticket. That loop is why a small local model is usable here: it writes\ninto a shape worked out by counting, and is marked against your team's own\ntickets afterwards.\n\n## A page instead\n\n```bash\nticket-ai ui --lang de     # or en\n```\n\nA local page on `127.0.0.1:8760` with three tabs: the house style, a box to\npaste a draft into, and the open backlog worst-first. Loopback only, because\nthis process holds a tracker token, and there is no flag to change that.\n\nNo build step and no CDN — one HTML file with its CSS and JavaScript inline.\n\n### Two languages, and they are separate\n\n```bash\nexport TICKET_AI_UI_LANGUAGE=de       # buttons and headings\nexport TICKET_AI_TICKET_LANGUAGE=de   # what it says to write tickets in\n```\n\nThe distinction is easy to collapse and worth keeping. A German team may want\nthe tool's own buttons in English; someone joining a German board still has to\nwrite the ticket in German.\n\n`TICKET_AI_TICKET_LANGUAGE` overrides what the corpus measured and takes effect\nwithout re-learning. Leave it unset unless the board is mid-switch — a\nmeasurement beats a setting, and forcing a language the board does not use\nmakes every existing ticket fail the language check.\n\nFindings, the caveats under them and the list of what a ticket already got\nright are all rendered in the reader's language at the moment they are shown.\nThe section names inside them are not: those are the team's own headings, and\ntranslating one turns it into a section the team does not have.\n\n### In CI\n\n```bash\nticket-ai review \"$CI_ISSUE\" --fail-under 0.5\n```\n\n## What it measures\n\n**The house style.** Sections, length, labels, title markers, language — over a\ncorpus it either took from you or found itself. Every finding cites a count\nover that corpus.\n\n**The tickets that failed, not only the ones that worked.** A rate can be a\ncomparison: not \"78% of tickets have acceptance criteria\" but *\"78% of the ones\nthat shipped, and 30% of the ones that stalled\"*. The second is evidence; the\nfirst invites a shrug.\n\nThe split is on **outcome alone** — a merged change, a reopen, a run of\nclarifying questions — and never on what the ticket contains, because splitting\non content and then comparing content would be circular. Tickets a staleness\nbot closed are left out of both groups: those say something about attention\nrather than about writing. On a board where nothing separates the two, it says\nso, which is worth knowing before anyone is asked to write differently.\n**[docs/shipped-against-stalled.md](docs/shipped-against-stalled.md)** has the\nguards and the real board that forced the bot exclusion.\n\n**Sections that only travel together.** A section carried by 41% of tickets is\nunder any threshold worth having — but if it is on 76% of the tickets that also\nhave a *Ziel* section and 20% of the ones that do not, the team has a template\nand applies it to one kind of work. A board-wide rate hides that entirely.\n\n**The form you declared, against the tickets you got.** With a\n`.github/ISSUE_TEMPLATE` or `.gitlab/issue_templates` in the checkout, `gaps`\nlines each field up against how often tickets actually carry it — and the gap\nruns both ways. A required field that turns up in 10% of tickets is a form\nasking for something people cannot easily give. A section most tickets carry\nthat no form mentions is a convention the project grew and never wrote down.\n\n**What you need to write one.** Give it a subject and it returns the related\npast tickets, **the files the merge requests for those tickets actually\nchanged**, and the files in your checkout that mention it. That middle one\nlives only in the tracker's history — no amount of reading the code produces\nit, and it is usually the fastest way to find where the work will land.\n\n## How the mining works\n\nOnly closed tickets are sampled: an open ticket may be beautifully written, but\nnothing about it yet shows anyone could act on it. Each is scored on\n\n| Signal | Weight | Why |\n|---|---|---|\n| A merged MR is attached | 0.30 | Strongest evidence someone could build it as written |\n| Substantial description | 0.20 | A stub teaches nothing about a template |\n| Has sections | 0.15 | The template is the thing being learned |\n| No clarifying questions | 0.15 | Eleven \"what do you mean?\" comments means it was not clear |\n| Never reopened | 0.10 | Reopened means closed before it was understood |\n| Labelled | 0.10 | |\n\nTickets opened and closed inside an hour are halved — usually duplicates or\ntypo fixes, whose shape is not the shape of real work. Bot authors are dropped\noutright; learning a house style from Renovate is a real failure mode. No one\nauthor may supply more than 40% of the corpus, or the profile describes your\nmost prolific ticket-writer instead of your team.\n\nEvery score carries the reasons that produced it. A corpus you cannot argue\nwith is one you will not trust.\n\n## What it will not tell you\n\n**Whether your tickets are any good.** Nothing here reads for meaning; it\ncounts. It cannot tell you whether your acceptance criteria make sense. It can\ntell you that the 40 tickets that shipped in this project all had some and this\none does not.\n\n**Alignment is not quality.** The score is distance from the tickets that\nhistorically got built here. A one-line ticket from someone who knows exactly\nwhat they mean can score badly and be completely fine. The tool says this about\nitself, and so should you when you quote it at a colleague.\n\n**Nothing about your tracker's contents changes.** Every operation is a read.\n\nThe ranking signals are also circumstantial. A well-written ticket closed as\nout-of-scope with no MR scores badly, and that is an acceptable error: the goal\nis thirty *representative* tickets, not the thirty best ones. A thin sample\nsays so, loudly, in the report and in every review built on it.\n\nJira has no public API for linked branches and merge requests, so the \"shipped\"\nsignal there falls back to remote links, and a board that does not post them\ncannot be split into shipped and stalled at all. It says that rather than\nreporting every ticket as stalled. That is a limit of the API, not of the\ncorpus.\n\n## Measuring the part a model writes\n\nEvery test in this repository mocks the writer, so none of them says anything\nabout the prose that comes back. `evals/` is the answer to that: a frozen set of\ntitles from public boards, each stored next to the board profile as it stood\nwhen the case was collected.\n\n```bash\nticket-ai eval --baseline evals/baseline.json          # run it and mark the result\nticket-ai eval --runs evals/results/latest.jsonl       # re-score records, no model\nticket-ai eval --repeats 5 --markdown                  # spread, as a table for an MR\n```\n\n**The cases were held out of the profile before it was built.** A case the\nprofile was fitted to flatters the model for a reason that has nothing to do\nwith the model.\n\n**The runner records and does not score.** A case costs thirty to seventy\nseconds on a local model, so scoring separately is what makes a changed metric\nfree to try. `--runs` is that path.\n\nTwo of the figures are not in `review_draft`, deliberately. It asks whether the\nsections a board uses are present; it never asks **what else the draft\ninvented**, because people rarely add a heading their board has never seen and\nmodels do it constantly. The other is spread: one number per case reads as\nprecision a non-deterministic writer cannot support, so `--repeats` exists and\nthe report prints the deviation next to the mean.\n\n### The judge, and why its number never travels alone\n\nCounting cannot say whether the prose is about the title, and that is the\nfailure worth catching: a draft can carry every section, hit the length, take\nthe right labels and describe something else entirely. `review_draft` gives it\nfull marks.\n\n`--judge` asks a model that one question and nothing else. Not \"is this a good\nticket\" - that is the question this tool exists to replace with counts.\n\n```bash\nticket-ai eval --judge --labels evals/labels.jsonl\npython tools/label_drafts.py evals/results/latest.jsonl   # collect the labels\n```\n\n**Raw agreement is close to useless on its own.** If nine drafts in ten are on\ntopic, a judge that answers \"on topic\" every time agrees ninety percent of the\ntime and has learned nothing. Cohen's kappa subtracts the agreement two people\nguessing at those rates would reach, so that judge scores zero.\n\nThe labels come from a person and there is no way around it. A calibration\nwhose human half was generated compares one model to another. Without\n`--labels`, the judge line prints `uncalibrated` every time rather than\ndocumenting the caveat once and letting the number travel without it.\n\nThe dataset is 134 cases over ten public boards. **Thirty are German**, from\n`kern-ux/pattern-library` and `fitko/fim/portal` on gitlab.opencode.de, a public\nGerman GitLab that reads without a token. Three boards are Jira (`KAFKA` and `CASSANDRA` on issues.apache.org, `HHH`\non hibernate.atlassian.net), and four write **pure prose with no recurring\nsections at all**.\n\nThat is not variety for its own sake. `compose` branches on each of them: a\nGerman prompt, a tracker abstraction, and a skeleton block that either lists\nsections or tells the model to write no headings at all. CI asserts all three\nsurvive, because a dataset that lost one would stop measuring it **without the\naverage moving**, and the loss would be invisible in the one number people read.\n\nkern-ux is why `jsonl_lines` exists: one of its\ntickets carries a literal U+2028, `str.splitlines` treats that as a line break\nand `json.dumps` does not escape it, so a valid file read as a truncated record\nand the error blamed the file.\n\n[**evals/README.md**](evals/README.md) has the rules about what may become a\ncase. Public boards only.\n\n### Where it runs\n\nThe cheap half runs on every pull request that touches the harness: every board\nloads, no case is also an exemplar, and a committed results file is re-scored.\nNo model, so it costs seconds.\n\nThe suite itself is `workflow_dispatch`. Composing 134 cases is minutes and\nmoney, and paying for it on a branch about a README typo buys nothing.\n\n`terraform/` is the report's address: an S3 bucket behind CloudFront, and an\nIAM role GitHub Actions assumes with a short-lived OIDC token. **There is no\nAWS key in the repository secrets** to leak or rotate. The trust policy is\nscoped to one repository; `repo:owner/*` would hand the role to every\nrepository that owner ever creates. Everything works without any of it, and the\npublish step skips itself when the role variable is unset.\n\n## Documentation\n\n| | |\n|---|---|\n| [**thirty-boards.md**](docs/thirty-boards.md) | What running it against forty-three real boards, an MCP client, a browser and a clean install found. Almost all of it had full line coverage at the time |\n| [**what-it-produces.md**](docs/what-it-produces.md) | Five tickets it wrote, unedited, with the score each one got |\n| [**shipped-against-stalled.md**](docs/shipped-against-stalled.md) | How the two groups are split, and the guards that keep the comparison honest |\n| [**evaluating-compose.md**](docs/evaluating-compose.md) | The harness over the frozen dataset: what was held out and why, the two metrics `review_draft` does not have, why the gate tolerates noise, and what is still missing |\n| [**local-models.md**](docs/local-models.md) | Running the writer on a 2 GB local model: measured timings, and what it trades away |\n\n### Verified against\n\nRun end to end, read-only, against `home-assistant/core`, `pydantic/pydantic`,\n`astral-sh/uv`, `fastapi/fastapi` (GitHub), `inkscape/inkscape` and\n`gitlab-org/gitlab-runner` (GitLab), `hibernate.atlassian.net` HHH (Jira Cloud),\n`issues.apache.org/jira` KAFKA (Jira Data Center), and one private GitLab board.\n\nHome Assistant produces no conditional rules at all, which is the right answer:\ntheir issue form is mandatory, so every section already clears the board-wide\nthreshold and a conditional has nothing to add.\n\n## Development\n\n```bash\nuv sync\nuv run pytest\nuv run ruff check .\nbash install_check.sh          # build the wheel and drive it from a clean venv\nuv run python tests/fleet.py   # the whole tool across 43 public boards\n```\n\n## License\n\nMIT.\n",
  "bytes": 19792,
  "sha": "6f35fff605d7284f949ab329fb9162bc321914f489893bd235005c04bc6ddd3d",
  "repo_slug": "syrian963/ticket-ai-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_syrian963_ticket_ai_mcp_3f2e0bab/readme"
}