contest-mcp

n3fjp-mcp

MCP サーバー。Claude Desktop などの MCP 対応クライアントから、N3FJP logging software — Amateur Contact Log および 100 種類以上の N3FJP コンテストロガー — にアマチュア無線の QSO を記録できます。

N3FJP スイートのすべてのプログラムは、共通の TCP 制御 API を使用します。n3fjp-mcp はこのプロトコルを直接（Python 標準ライブラリの socket を使用し、サードパーティのラッパーは使用せずに）扱い、論理的にグループ化された少数の MCP ツールとして公開します。これにより、アシスタントは自然な言葉で交信を記録したり、ログを読み取ったり、重複チェックを実行したり、バンドやモードを管理したりできます。

これは「運用 → 記録」ワークフローの記録部分を担います。姉妹プロジェクトの fldigi-mcp は無線機を操作します。

ステータス： 実験段階（v0.3）。N3FJP の ARRL Field Day Contest Log に対して、API バージョン 2.2 で実機検証済みです。プロトコルはスイート内で共通ですが、フィールドのセットはコンテストごとに異なります。fields ツールで確認してください。

⚠️ 独立プロジェクト — N3FJP とは無関係です

n3fjp-mcp は Stefan Brunner (AE5VG) による独立したコミュニティプロジェクトで、権利者の許可を得て「N3FJP」の名称を使用しています。N3FJP Software / Affirmatech との提携、承認、サポート関係はありません。このアプリに関するすべてのサポートの問い合わせは、課題トラッカーまでお寄せください。N3FJP には問い合わせないでください。MIT ライセンス。「N3FJP」は権利者のコールサインおよび商標です。

特長

• 自動記録 — 中心となる log ツールは、実際の N3FJP の手順を実行します。コールサインを設定 → CALLTAB（重複チェックと過去の交信の検索）→ コンテスト交換情報を設定 → ENTER。重複応答と追加されたレコード数も表示します。
• 幅広い機能 — 読み取りクエリ、フィールドの読み書き、検索／一覧表示、重複およびエンティティのチェック、バンド／モード／周波数、データベースへの直接操作、オプトイン方式のプッシュ通知を、各ツールに 1 つの権限を割り当てた 9 つのツールにまとめています。読み取り専用の diagnostics ツールと、使用頻度の低いコマンドや今後のコマンドに対応する n3fjp_call のエスケープハッチも用意しています。
• 安全性を重視した設計：ログデータベースにアクセスするツールのため、次のように設計しています。
  • 読み取りは読み取り専用として設定されているため、クライアントでデフォルトの権限を 常に許可 にできます。
  • 書き込み（記録、バンド／モードの設定、個別レコードの追加・編集・削除）は、追加の帯域内確認を行わず、承認が必要 に設定されています。
  • データベース全体の消去／上書きは、専用の N3FJP_ALLOW_DB_WIPE スイッチを有効にしない限り、デフォルトでは許可されず、実行を拒否します。
• N3FJP と同じ名称 — ツールとフィールドには、N3FJP 自身の用語（Action ENTER、CALLTAB、TXTENTRY… ボックス、Class／Section など）を使用しています。
• 不安定な依存関係なし — 実行時の依存関係は MCP SDK のみです。

必要条件

デスクトップ拡張機能（.mcpb）をインストールするには：

• N3FJP プログラムが実行中であり、**Settings → Application Program Interface → 「TCP API Enabled」**にチェックが入っていること（API のデフォルトポートは 1100）。

Claude Desktop の uv ランタイムが Python と依存関係を提供するため、エンドユーザーが Python や uv を自分でインストールする必要はありません。

ソースから開発する場合は、さらに Python 3.10+ と uv が必要です（MCP Inspector を使用する場合のみ Node.js も必要です）。

インストール

最も簡単な方法：ワンクリックのデスクトップ拡張機能

最新の リリースから n3fjp-mcp.mcpb をダウンロードし、Claude Desktop で Settings → Extensions → Advanced settings → Install Extension… に移動して、ファイルを選択します。短い設定フォームでホスト／ポートを指定します（デフォルトは 127.0.0.1:1100）。ターミナルも、Python も、インストールする uv も不要です。

👉 初めての方は、手順に沿ったインストールガイドをご覧ください。

ソースから（開発）

git clone https://github.com/sbrunner-atx/n3fjp-mcp.git
cd n3fjp-mcp
uv sync

次に、Claude Desktop の設定に追加します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "contest": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/n3fjp-mcp", "run", "n3fjp-mcp"],
      "env": { "N3FJP_HOST": "127.0.0.1", "N3FJP_PORT": "1100" }
    }
  }
}

Claude Desktop を再起動し、「N3FJP のステータスは？」 と尋ねてください。

MCP Inspector で試す

uv run mcp dev src/n3fjp_mcp/server.py

ツール

各ツールは1つの権限であり、operation 引数を受け取ります。

ツール	デフォルト	操作
status	読み取り	スナップショット：プログラム、バージョン、API バージョン、QSO 数、バンド／モード／周波数
diagnostics	読み取り	解決されたホストとポート、このプロセスの Python とホスト名、ネットワークインターフェース。N3FJP への接続は行いません
query	読み取り	プログラム、qso_count、next_serial、ログ／設定／共有パス、qso_rate、band_mode_freq
fields	読み取り	1つの入力ボックスを読み取るか、値を含む表示中／すべてのフィールドを一覧表示
search	読み取り	最近の項目の一覧、検索、重複チェック（副作用なし）、エンティティの状態
log	承認が必要	log_qso（コールを設定 → CALLTAB → コンテスト交換情報 → ENTER）、設定、set_many、calltab、enter、clear、focus
bandmode	承認が必要	change_freq、set_band、set_mode、ignore_rig_polls
notifications	承認が必要	プッシュイベントの有効化／無効化、バッファーされたイベントの取得
database	承認が必要	add_direct、レコードの削除、生 SQL、checklog、openlog、sqlclose
n3fjp_call	承認が必要	エスケープハッチ — 将来のコマンドを含む、任意の生コマンドを送信

すべての書き込みツールは承認が必要な階層にあるため、クライアントで常に許可に設定すれば、手放しで自動化できます。ただし、データベース全体の消去（下記参照）だけは例外で、常にブロックされます。

主な機能は log → log_qso です。

log_qso  call="W1AW"  contest="field_day"  exchange={"class":"2A","section":"CT"}

コールを設定し、CALLTAB（重複チェック）を実行してコンテスト交換情報を入力し、ENTER を送信します。その後、追加されたレコード数と重複に関する詳細を報告します。

設定

変数	デフォルト	用途
N3FJP_HOST	127.0.0.1	N3FJP API ホスト
N3FJP_PORT	1100	N3FJP API ポート（スイートのデフォルト）
N3FJP_TIMEOUT	6	ソケット／応答タイムアウト（秒）
N3FJP_ALLOW_DB_WIPE	off	危険。 データベース全体の削除／上書きを許可します（生 SQL の DROP／TRUNCATE／スコープ指定のない DELETE／UPDATE）。本当に必要な場合を除き、off のままにしてください

パッケージ版デスクトップ拡張機能では、これらは設定フォームに表示されます。

安全性モデル

ログ記録では送信機のキー操作を行わないため、送信ゲートはありません。ここで保護するのはログデータベースです。

• 読み取り操作（status、query、fields、search）は読み取り専用としてマークされているため、クライアントではデフォルトで常に許可に設定できます。
• 書き込み操作 — ログ記録（log）、バンド／モード（bandmode）、通知、個別レコードの追加、編集、削除（database）、および n3fjp_call エスケープハッチ — はすべて承認が必要な階層にあります。バンド内での追加確認はないため、クライアントで常に許可に設定すれば、自動化を手放しで実行できます。
• データベース全体に対する操作 — ログ全体を削除または上書きする可能性がある生 SQL（DROP、TRUNCATE、WHERE のない DELETE／UPDATE）だけは例外で、N3FJP_ALLOW_DB_WIPE が有効でない限り拒否されます。この切り替えはクライアントの承認プロンプトとは別で、より厳格な制限が適用されます。また、設定フォームには厳重な警告が表示されます。有効にする前に、必ずログをバックアップしてください。

可能な限り、n3fjp-mcp は N3FJP 独自の検証を利用し（重複をチェックして問題を報告します）、検証を再実装するのではなく、その応答を提示します。

リモート／コンテスト局のセットアップ（別のコンピューター上で動作する N3FJP）

N3FJP は Windows でのみ動作します。Claude Desktop と同じ Windows コンピューターで N3FJP が動作している場合は、N3FJP_HOST を 127.0.0.1 のままにすれば完了です。Macでは、N3FJP は常に別の場所にあります。Windows 仮想マシン（Parallels、VMware Fusion、UTM）内、または LAN 上の Windows PC で動作します。仮想マシンは独自のネットワークアドレスを持つため、別のコンピューターとして扱われ、以下のブリッジが必要です。

N3FJP が別のコンピューターで動作している場合は、注意点があります。サンドボックス化された MCP クライアント（特に Claude Desktop）は、コネクターが 127.0.0.1 にしか接続できず、LAN アドレスには接続できない状態で実行されます。そのため、設定に N3FJP の LAN IP を指定すると、その IP への telnet が機能していてもタイムアウトします。クライアントコンピューターにスタンドアロンの mcp-host-bridge ツールをインストールして解決し、ホストを 127.0.0.1 に設定してください。

pipx install mcp-host-bridge            # or download a binary from its releases
mcp-host-bridge install n3fjp --to 192.168.1.50   # knows n3fjp = port 1100; auto-starts

mcp-host-bridge status n3fjp ／ uninstall n3fjp で管理できます。詳しくは docs/REMOTE-HOST.md と mcp-host-bridge README をご覧ください。diagnostics ツールを使うと、このブリッジが必要かどうかを確認できます。API は認証なしで利用できるため、信頼できる LAN 上でのみリンクを使用してください。

ドキュメント

📻 実地検証済みの N3FJP API リファレンス（コミュニティ向け無料リソース）

このサーバーの開発では、N3FJP TCP API をリバースエンジニアリングして実機で検証しました。現在の API（v2.2）が公開されている 0.9 のドキュメントと異なる箇所もいくつかありました。コミュニティへの還元として、これらを人が読みやすい完全なガイドにまとめ、無料で公開しています。

• N3FJP TCP API — 実地検証済みリファレンス (PDF) — 通信方式、分野別にまとめた全コマンド、検証済みの応答例、コンテストの交換情報フィールド、そして苦労して見つけた注意点（API とネットワークのポート、CMD_NOT_FOUND、0.9 以降に削除されたコマンド、CALLTABEVENT の検索、ネットワークモードでは ENTER が 0 を返してもログに記録される理由）。
• 機械可読な仕様 — 同じ情報を簡潔で構造化されたコマンドカタログとしてまとめています。コード生成に適しています。

修正や追加は歓迎します。issue または PR を作成してください。

プロジェクトのドキュメント

• インストールガイドとテスト計画。
• Field Day 2026 の教訓 — n3fjp-mcp と fldigi-mcp を使って自律型 BPSK31 Field Day 局（クラス 2A、コールサインは匿名化）を運用した際の完全な事後レポートです。運用サイクル、現場で遭遇した特殊なケース、推奨される改善点を記載しています。

スキル

skills/ ディレクトリには、実際の交信運用からまとめた運用手順であるエージェントスキルが含まれています。リポジトリおよび .mcpb パッケージに同梱されています。

• contest-operating — コンテスト QSO の状態遷移（CQ → 交換情報 → TU → ログ記録）、特殊ケースへの対応手順（QRM、判読しにくいコールサイン、ダブリング、コピーできない場合の再送要求、コールサインのみを送る呼び出し局）、および既知の癖を含む検証済みの N3FJP ログ記録手順です。ARRL Field Day 2026 で実地検証済みです。

運用スキルのフィールドガイド （PDF）では、このスキルと、関連プロジェクトの fldigi-mcp にある fldigi-operating と signal-hunting を解説しています。スキルの概要、インストール方法、Claude を初めて使うアマチュア無線家向けの平易な「初回セッション」章、運用標準、特殊ケースへの対応手順、ARRL Field Day 2026 の記録から書き起こした実例を掲載しています。

Claude Code ／ Cowork で使用するには、スキルのディレクトリを ~/.claude/skills/（またはプロジェクトの .claude/skills/）にコピーしてください。無線機を操作するには、fldigi-mcp の fldigi-operating スキルと組み合わせてください。

開発

uv sync
uv run ruff check .      # lint
uv run pytest            # tests (no running N3FJP required)
python3 smoke_test.py 192.168.1.50 1100   # Phase 0: prove the link to N3FJP

テストスイートでは、ワイヤープロトコル、操作マップとフィールドカタログ、型の変換、権限モデルおよびデータベース消去の安全モデルを網羅しています。いずれも N3FJP の実行は必要ありません。

ライセンス

MIT © 2026 Stefan Brunner (AE5VG)