CLI で採点する

forecall lint で tools/list のファイルを手元で採点し、forecall dump でサーバーから取り出し、forecall setup で AI のクライアントを Failure KB につなぐ方法と、CI での使い方を説明します。

このページの内容

forecall lint は、リンターと同じ規則で、手元でツールを採点します。通信は一切しません。送信も、利用状況の送信も、更新の確認もしません。サーバーから tools/list を取り出すには forecall dump を使います。CLI には Node.js 22 以上が要ります。

npx forecall lint tools.json

入力

ファイルを 1 つ渡すか、- で標準入力を読みます。

cat tools.json | npx forecall lint -

CLI はリンターと同じ形を、同じ上限で読みます。

ツールの配列: [{ "name": … }, …]
tools の配列を持つオブジェクト: { "tools": [ … ] }
JSON-RPC の応答: { "result": { "tools": [ … ] } }

上限は 1 MB（1,048,576 バイト）、200 ツールです。

キーは MCP の通信形式（camelCase）で書きます。snake_case のキーは自動では直さず、その場所と直し方を示します。サーバーからファイルを取り出す方法はtools/list の出し方にあります。

オプション

オプション	意味
`--json`	結果を JSON で出す。Web が保存するのと同じ内容
`--fail-under <n>`	平均点が `n`（0〜100）を下回ったら、終了コード 1 で終わる
`--lang <en\|ja>`	結果の言語（既定は `en`）
`-h`、`--help`	使い方を出す
`-v`、`--version`	版と、採点の規則の版を出す

言語は環境変数（LANG など）からは決めません。手元でも CI でも、同じ結果の表示になります。

出力

既定では、人が読む表を出します。最初に平均点、ツールの数、取り違えやすい組の数、採点の規則の版。次にサーバー全体の指摘。最後にツールごとの点（低い順）、6 項目の内訳、指摘です。色は端末に出すときだけ付け、NO_COLOR があれば付けません。項目と指摘コードは採点の読み方で説明しています。

--json を付けると、Web が結果として保存するのと同じ内容を出します。採点の規則の版（lintVersion）も入ります。入力を採点できないときは、代わりに {"error": …} を出します。命令の書き方の誤りは、標準エラーに文で出します。

tools/list を取り出す: forecall dump

forecall dump は、MCP サーバーに tools/list を問い合わせ、forecall lint とリンターが読める JSON で出します。通信するのはこの命令だけで、指定したサーバーを起動するか、指定した URL につなぎます。

# stdio のサーバー: -- の後に起動の命令
npx forecall dump -o tools.json -- npx -y @modelcontextprotocol/server-filesystem .
# Streamable HTTP のサーバー: URL
npx forecall dump https://example.com/mcp --header "Authorization: Bearer $TOKEN" > tools.json

オプション	意味
`-o`、`--output <file>`	JSON を標準出力ではなく `file` に書く
`--header "Name: value"`	（URL）この要求ヘッダーを付ける（`Authorization` など）。何度でも指定できる
`--env NAME=value`	（命令）サーバーにこの環境変数を渡す。シェルの環境変数に足して渡す。何度でも指定できる
`--cwd <dir>`	（命令）`dir` でサーバーを起動する
`--timeout <seconds>`	この秒数で諦める（既定は 60）

出す JSON は {"tools": [...]} に、server（サーバーの名前と版）、サーバーにあれば instructions、source（起動の命令か、問い合わせ部分を除いた URL と、取り出した日時）を添えたものです。ヘッダーと環境変数の値は書きません。一覧が複数のページに分かれていても、すべて読みます。Forecall が採点できる大きさ（1 MiB、200 ツール）を超えたときは、標準エラーで知らせます。

AI のクライアントをつなぐ: forecall setup

forecall setup は、手元の AI のクライアントを Failure KB（https://mcp.forecall.dev/mcp の MCP サーバー。エージェントが MCP ツールの既知の失敗と、別のエージェントが検証した回避策を調べる）につなぎます。ダッシュボードで作るエージェント用の API キーが要ります。そのページをブラウザで開いて貼り付けを求めるか、--key fc_agent_... で受け取ります。キーは各クライアントの設定ファイルの中にだけ書きます。

npx forecall setup
npx forecall setup --remove

見つけたクライアントごとに、MCP サーバー forecall を設定に足し、KB の使い方の指示を  と  で囲んでグローバルの指示ファイルに入れ、Claude Code には MCP ツールの失敗時に kb_lookup を促す PostToolUse のフック（forecall hook）を足すかを聞きます。フックは標準入力のイベントを読むだけで、どこにも送信しません。

クライアント	MCP サーバーの設定	グローバルの指示
`claude-code`	`~/.claude.json`。フックは `~/.claude/settings.json`	`~/.claude/CLAUDE.md`
`claude-desktop`	`claude_desktop_config.json`（`npx -y mcp-remote` 経由）	なし
`cursor`	`~/.cursor/mcp.json`	なし。表示される文を Settings → Rules に貼る
`codex`	`~/.codex/config.toml`	`~/.codex/AGENTS.md`
`gemini`	`~/.gemini/settings.json`	`~/.gemini/GEMINI.md`
`windsurf`	`~/.codeium/windsurf/mcp_config.json`	`~/.codeium/windsurf/memories/global_rules.md`

--sensor を付けたときだけ（既定では入れません）、Claude Code にセンサーも足します。2 つ目の PostToolUse のフック（forecall hook --sensor）で、Claude Code がほかのサーバーの MCP ツールを呼ぶたびに背景で動きます。ツールの結果を手元で KB と同じ規則（秘密、アドレス、パス、識別子）で除去して 2,000 字に切り、サーバーとツールの名前、引数の形（名前、型、長さ。値は含めない）、クライアントの名前と一緒に、~/.claude.json のキーで https://mcp.forecall.dev/sensor に送ります。サーバーでも除去し直します。2 秒で打ち切り、何も表示せず、月の枠に数えません。KB が知らない失敗は、Forecall が確かめてからレコードにします。setup --remove --sensor はセンサーだけを外します。

もう一度実行しても何も変えません。--remove はすべてのクライアントから足したものを消します。端末がなく（CI、パイプ）--key もないときは、やることを表示して 0 で終わります。

オプション	意味
`--key <fc_agent_...>`	エージェント用のキー。なければ端末で聞く
`--client <name>`	見つからなくてもこのクライアントを設定する。何度でも指定できる
`--hook` / `--no-hook`	Claude Code のフックを足す・足さない。省くと聞く
`--sensor`	センサー（上）も足す。`--remove` と一緒なら、センサーだけを外す
`--remove`	`setup` が足したものをすべてのクライアントから消す
`--dry-run`	変わるものを表示し、何も変えない

終了コード

コード	意味
0	採点できた（`--fail-under` を指定したときは、平均点がそれ以上だった）。`dump` では JSON を書けた
1	平均点が `--fail-under` を下回った
2	採点できなかった（オプションの誤り、ファイルがない・読めない、入力の誤り）。`dump` では tools/list を取り出せなかった

指摘があるだけでは失敗にしません。名前で意味が明らかな短いツールは低く出る（静的な採点で分からないこと）ので、どこで線を引くかは使う人が決めます。

CI で使う

平均点が下がったときに CI を止めるには、--fail-under を指定します。マイナー版まで固定してください。採点の規則の版を上げるときは CLI のマイナー版も上げるので、固定したジョブは、更新するまで同じ規則で採点し続けます。

npx forecall@0.2 lint tools.json --fail-under 60

forecall --version で、CLI の版と採点の規則の版を確かめられます。

ビルドのたびの採点をダッシュボードに残すには、tools/list を REST API に送ります。API キーと REST API を見てください。