バージョン¶

invenio-mcp はセマンティックバージョニング 2.0.0 に従う（MAJOR.MINOR.PATCH）。2つのサーバは同じ版を持つ。http/mcp_server.py と stdio/server.py の __version__ がそれで、一致することを tools/check.sh が検査し、クライアントには serverInfo.version として見える。

版はまだ 0.x である（1.0 の前を参照）。今の版はこのページに書かない。 出すたびに古くなるからで、変更履歴にある。

python3 stdio/server.py --version      # invenio-mcp stdio server <version>
# HTTP 版は起動時の表示に出る

版が守る範囲¶

セマンティックバージョニングは、公開面が何かを言って初めて意味を持つ。ここでの利用者はたいてい ツールの説明を読む言語モデルであって、シグネチャを読むコンパイラではない。そのことが「破壊的」の意味を変える。

契約の一部	破壊的変更の例
ツール名	ツールの削除・改名。モデルが覚えた使い方も、利用者が保存したプロンプトも壊れる
ツールの引数	引数の削除・改名、必須引数の追加、ふるまいを変える既定値の変更
戻り値の形	結果からキーが消える、型が変わる
scope	今まで不要だったツールに scope が要るようになる、scope の改名。既存のトークンが通らなくなる
エンドポイント	`/mcp` や `/mcp-auth` の移動、canonical URI の導き方の変更
環境変数	設定の改名・削除、ふるまいを変える既定値の変更
言語リソースのキー	コードが参照するキーが消える——完全だった翻訳が黙って部分訳になる

含まれないもの: 説明文やエラー文の言い回し（良くなっていくことが前提）、ログの行の中身、内部のモジュール構成、適合検査のスクリプト。

説明はシグネチャではない。それでも重い¶

ツールの説明を書き直すのは patch である。同時にそれは、全体のふるまいを変える最も効く手でもある。その文章こそがモデルの読む interface だからである。注意書きを削る書き直し——「公開済みレコードにはファイルを足せない」「これには confirm=True が要る」 ——は見た目の問題ではなく、スキーマが1つも動いていなくても変更履歴に書く。

拒否を緩めるのは major¶

このサーバがしていることの一部は、拒否することである。

delete_record は confirm=True が無ければ何もしない
取り下げはソフト削除で、ハード削除は提供しない
公開レコードの読取は未認証で通すが、書き込みは決して通さない
受け取ったトークンは交換する。InvenioRDM へ転送しない
aud が本サーバの canonical URI であることを検証する

これらを緩めるのは、名前が1つも動かなくても major である。壊れるのがビルドではなく、リポジトリのレコードだからである。

2つのサーバに1つの版¶

同時に出す。片方だけ上げると、「invenio-mcp 0.2.0」がどちらのファイルを見たかで別のものを指すことになる。2つの __version__ が食い違えば tools/check.sh が落ち、タグがそれと合わなければ tools/release.sh が進まない。

ここで版が付かないもの¶

InvenioRDM 自身の API。 対象は InvenioRDM v14 である。将来の InvenioRDM が依存している REST のふるまいを変えたら、修正は利用者から見た変化の重さに応じた版で出す。ツールが動かなくなったのなら、誰の変更が原因であれ major である。

MCP の仕様。 HTTP 版は 2026-07-28 の認可仕様を対象にしている。新しい版に追随することは、クライアント側にすべきことが変わるなら破壊的変更である。

1.0 の前¶

版が 0 で始まるあいだは、マイナー番号が破壊的変更を運ぶ。0.1.0 → 0.2.0 は壊れうるが、0.0.1 → 0.0.2 は壊れない。

1.0 を打つのは次が揃ったとき。

ツールの集合が、InvenioRDM のアップグレードを少なくとも1回またいで安定したこと
適合検査が、他の誰かが運用しているインスタンスに対して通ること
keycloak モードが、実演ではなく実際の運用で使われたこと

それまでは版を固定して使うこと。

出し方¶

出すのは手元である。リリースのワークフローは無い。そもそも CI を置いていない理由は参加するにある。

# 1. 両方のサーバの版を上げ、[Unreleased] を新しい版へ移す（両言語とも）
vim http/mcp_server.py stdio/server.py CHANGELOG.md CHANGELOG.ja.md
git commit -am "chore: v0.0.3 を切る" && git push origin main

# 2. 確かめる。ここでは何も出ない
bash tools/release.sh v0.0.3

# 3. 出す。タグを打ち、push し、GitHub のリリースを作る
bash tools/release.sh v0.0.3 --publish

# 4. サイトを出す
bash tools/deploy-docs.sh

tools/release.sh は、タグが両方のサーバの __version__ と一致すること、両方の変更履歴にその版の節が在ることを確かめ、tools/check.sh を走らせ、マニフェストと同じ作り方でイメージを作り、CHANGELOG.md のその版の節をそのままリリースノートにする——同じことを二度書かない。

2 と 3 は同じコマンドで、違うのはフラグだけである。確かめるのは安く、何度でもできる。タグはそうではない。だから既定はタグを打たない。