# CLI で採点する

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

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

```sh
npx forecall lint tools.json
```

## 入力

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

```sh
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 の出し方](https://forecall.dev/ja/docs/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` があれば付けません。項目と指摘コードは[採点の読み方](https://forecall.dev/ja/docs/reading-scores)で説明しています。

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

## tools/list を取り出す: forecall dump

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

```sh
# 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://forecall.dev/ja/kb)（`https://mcp.forecall.dev/mcp` の MCP サーバー。エージェントが MCP ツールの既知の失敗と、別のエージェントが検証した回避策を調べる）につなぎます。[ダッシュボード](https://app.forecall.dev/api-keys)で作るエージェント用の API キーが要ります。そのページをブラウザで開いて貼り付けを求めるか、`--key fc_agent_...` で受け取ります。キーは各クライアントの設定ファイルの中にだけ書きます。

```sh
npx forecall setup
npx forecall setup --remove
```

見つけたクライアントごとに、MCP サーバー `forecall` を設定に足し、KB の使い方の指示を `<!-- forecall:start -->` と `<!-- forecall:end -->` で囲んでグローバルの指示ファイルに入れ、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 を取り出せなかった |

指摘があるだけでは失敗にしません。名前で意味が明らかな短いツールは低く出る（[静的な採点で分からないこと](https://forecall.dev/ja/docs/getting-started#limits)）ので、どこで線を引くかは使う人が決めます。

## CI で使う

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

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

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

ビルドのたびの採点をダッシュボードに残すには、`tools/list` を REST API に送ります。[API キーと REST API](https://forecall.dev/ja/docs/api#save) を見てください。