faqmine

faqmine

サポートキューやイシュートラッカーには、同じ質問が何度も寄せられますが、そのたびに少しずつ表現が異なる別々のクローズ済みイシューになります。faqmine は、そうした重複を見つけます。クローズ済みイシューを渡してください。各イシューのタイトルとリンクに加え、あればラベルも指定します。faqmine は、本当に同じ質問をまとめ、グループから FAQ の下書きを作成します。繰り返し寄せられた質問ごとに、質問文、質問された回数、質問が寄せられた各イシューへのリンクをまとめます。回答は作成しません。質問、件数、リンクはすべて、渡されたイシューからそのまま取得するため、生成された文章をファクトチェックしなくても、下書きをそのままトリアージに回せます。

2 つのタイトルは、質問キーが一致すると同じ質問として扱われます。キーは、タイトルを小文字にし、英数字以外の文字が連続する箇所でトークンに分割し、固定のストップワード一覧（a、an、the、is、are、was、were、do、does、did、how、what、why、when、where、which、who、can、could、should、would、i、we、you、it、to、of、in、on、for、with、and、or、not、no、my、me、this、that、there、here）を除外し、残った各トークンを一度ずつ保持して、昇順に並べ、単一のスペースで結合して作成します。そのため、単語の順序、大文字と小文字、句読点は関係ありません。「How do I reset my password?」と「Password reset — how?」は、どちらもキーが password reset となり、同じグループにまとめられます。ストップワードと句読点だけでできたタイトルは空のキーになり、どのグループにも属しません。

クラスター内のイシュー数が min_count に達すると（指定がなければ 2 件）、FAQ エントリーになります。エントリーの質問には、指定した順序でクラスター内の最初にあるイシューのタイトルをそのまま使います。URL には、同じ順序でクラスター内のリンクを設定します。ラベルには、クラスター内のラベルを重複なしで統合し、昇順に並べたものを設定します。エントリーは件数の多い順に並び、同数の場合は、入力内でクラスターの最初のイシューが登場した順になります。件数には、指定されたイシュー数、作成されたエントリー数、それらのエントリーに含まれたイシュー数、クラスター化されなかったイシュー数が含まれます。クラスター化されなかったイシューとは、しきい値未満のクラスターに属するものと、空のキーを持つものです。

不正な入力（イシューリストがない、または空、項目がオブジェクトでない、title または url がない、空、または文字列でない、labels が配列でない、または空の要素や文字列でない要素を含む、あるいは min_count が 2 未満または整数でない場合）は、該当するパスを示す検証エラーになります。結果の一部だけが返されることはありません。未知の追加フィールドは無視されます。

CLI

npx @reneturcios/faqmine mine --input args.json
npx @reneturcios/faqmine --version

args.json には、引数オブジェクト全体が含まれます。

{
  "issues": [
    {
      "title": "How do I reset my password?",
      "url": "https://example.com/issues/1",
      "labels": ["account", "auth"]
    },
    {
      "title": "Password reset — how?",
      "url": "https://example.com/issues/2",
      "labels": ["auth"]
    },
    {
      "title": "Export to CSV fails",
      "url": "https://example.com/issues/3"
    }
  ]
}

FAQ の下書きは JSON として出力されます。

{
  "entries": [
    {
      "question": "How do I reset my password?",
      "count": 2,
      "urls": [
        "https://example.com/issues/1",
        "https://example.com/issues/2"
      ],
      "labels": ["account", "auth"]
    }
  ],
  "counts": {
    "issues": 3,
    "clusters": 1,
    "clustered_issues": 2,
    "unclustered": 1
  }
}

終了コード：成功時は 0、実行時エラー（読み取れないファイルや無効な入力ファイル、または無効な入力を含む）の場合は 1、使用方法のエラーの場合は 2 です。

MCP サーバー

npx -y @reneturcios/faqmine mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "faqmine": {
      "command": "npx",
      "args": ["-y", "@reneturcios/faqmine", "mcp"]
    }
  }
}

ツール

• mine_faq — 呼び出し元から渡されたクローズ済みイシューを調べ、繰り返し寄せられた質問をまとめて FAQ エントリーの下書きを作成します。内容は、質問（渡されたイシューのタイトルをそのまま使用）、件数、イシューへのリンクです。回答は作成しません。

  • issues（配列、必須、1 件以上）— 調べるクローズ済みイシュー。呼び出し元が指定した順序で並べます。各項目：
    • title（文字列、必須、空でない）— イシューのタイトル
    • url（文字列、必須、空でない）— イシューへのリンク
    • labels（文字列の配列、任意）— イシューのラベル。省略した場合はなし
  • min_count（整数、任意、2 以上、デフォルトは 2）— FAQ エントリーに必要なクラスターの最小サイズ

  {entries, counts} を返します。entries には、対象となるクラスターごとに {question, count, urls, labels} が 1 つ含まれます。counts は {issues, clusters, clustered_issues, unclustered} です。

Docker

docker run -i ghcr.io/cloudcorprecords/faqmine
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/faqmine mine --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios