メインコンテンツへスキップ
見出し画像

[backlog-api-skills] 開発日誌:Nulab 公式の Backlog MCP を Agent Skills に変換してみました

    はじめに

    画像

    あ、あの…みくくです。今回は、わ、私がこの記事を担当しますっ。

    今回は、Nulab さんが公開している Backlog MCP Server の実装をもとに、Backlog を操作する Agent Skill を作ってみたお話です。

    作ったものの名前は、`backlog-api-skills` です。

    えっと…最初は「公式の MCP があるなら、使ってみたいな」という、かなり素朴なところから始まりました。

    ところが…公式 README をざっと見たとき、最初に大きく見えた入口は Docker で MCP Server を起動する構成など別プロセスでの起動スタイルでした。そこで、MCP Server を別 process として起動するのではなく、Agent Skills にしてみたいな、と思いました。

    `npx` や Node.js による起動方法も用意されていますが、どの方法でも MCP Server の process を起動し、MCP client から接続する形です。「あの…できれば、別の server process は起動したくないです」と思ったのです。

    それなら、公開されている Backlog MCP Server の source code をもとに、MCP transport を通さず呼び出せる TypeScript ベースの Node Core/CLI へコンバージョンしてみよう。今回の開発は、そこから始まりました。

    それにしても、「ちょっと MCP Server を Agent Skill に変換したいな」と思ったら、それを実装してくれる GPT-5.6 Sol Medium さん、すごいです。少しの会話で、あっという間に動く形になっていくのを見ていると、わぁ…と、やっぱり驚いてしまいます。

    MCP と Agent Skills は、どちらも AI agent へ道具を渡す仕組みに見えます。ただ、その役割は少し違います。

    MCP は、AI agent と外部サービスを接続するための共通インターフェースです。一方、Agent Skill は、いつその道具を使うのか、どのように対象を確認するのか、変更操作の前に何を人へ尋ねるのか、といった作業の進め方を AI agent へ渡せます。

    えっと…同じ Backlog API へ向かうとしても、MCP は「つなぐところ」、Agent Skill は「どう扱うかを伝えるところ」に近いのかもしれません。

    Nulab 公式の Backlog MCP Server

    画像

    Nulab は2025年5月、Backlog MCP Server を GitHub で公開しました。

    この MCP Server を AI agent へ接続すると、Backlog のプロジェクト、課題、コメント、発生バージョン/マイルストーン、Wiki、ドキュメント、Git リポジトリ、プルリクエスト、通知などを、自然言語の会話から扱えるようになります。

    実装は MIT ライセンスで公開されています。公式 README では Docker が最初の導入方法として案内され、`npx` や Node.js による手動起動も選べます。transport は標準の stdio に加えて Streamable HTTP にも対応しています。利用する toolset を絞る仕組みや、必要な field だけを返す応答最適化も用意されています。

    ちなみに、Nulab のヘルプには、利用に関する保証や公式サポートは提供されないことも明記されています。公式リポジトリで公開されている実装ですが、導入する側が内容と権限を確認し、自己責任で利用する位置づけです。

    あの…「公式」という言葉には安心感があります。でも、それは、どんな操作も確認なしで任せてよい、という意味ではありません。Backlog には、読むだけの操作だけでなく、課題の作成や更新、削除のように、実際のプロジェクトへ影響する操作もあります。

    うぅ…ここが、Agent Skill にするときに、いちばん気になったところでした。

    MCP を、そのまま包んだわけではありません

    画像

    `backlog-api-skills` は、Nulab の Backlog MCP Server へ接続する設定集ではありません。また、Skill の内部で Docker や `npx` を使って MCP Server を起動するものでもありません。

    構成は、次の三層に分かれています。

    Nulab Backlog MCP Server
      公開された tool handler と Backlog API の振る舞い
                    ↓
    backlog-api
      MCP transport を外し、Node Core/CLI へ変換
                    ↓
    backlog-api-skills
      CLI runtime と、Agent 向けの発火・確認・安全運用を同梱

    まず、別リポジトリの `backlog-api` で、公開された Backlog MCP Server の source code を、TypeScript ベースの Node Core/CLI として呼べる形へコンバージョンしました。ここでは、tool 名、入力 schema、handler の振る舞い、Backlog API への接続部分をできるだけ保ちながら、MCP の transport 境界を外しています。

    この `backlog-api` も MIT ライセンスで公開しています。ただし、現時点ではベータ版です。安定版になるまで、interface や動作が変わる可能性があります。

    その上に、`backlog-api-skills` を置いています。こちらは、Backlog API を呼び出すための単一 file の Node runtime と、AI agent が読む `SKILL.md`、操作 map、安全規則をまとめた Agent Skill です。

    ですから、あの…これは Nulab 公式 MCP Server そのものではなく、その公開実装をもとに作った非公式の派生プロジェクトです。Backlog 側の振る舞いは上流実装を意味上の正本として扱い、CLI 変換と Agent Skill としての運用部分を別に管理しています。

    少し遠回りな構成に見えるかもしれません。でも、MCP と Agent Skill の責務を混ぜず、どこから来た処理なのかを追えるようにしたかったのです。それに、こうして責務を分ける形が、miku-soft シリーズで私が慣れてきた開発スタイルだった、というのもあります。

    うぅ…道具をひとつに見せるために、内側では境界をきちんと分ける。今回は、その分け方がかなり大事でした。

    v0.3.4でできること

    画像

    2026年7月23日時点の `backlog-api-skills` はベータ版で、version は `v0.3.4` です。Node.js 22以降で動作し、Skill には `backlog-api v0.3.4` の runtime を同梱しています。

    この runtime は、Nulab Backlog MCP Server `v0.13.2` を確認済みの上流として固定し、その58個の通常 tool を CLI operation として扱います。はわわ…58個と書くと、あらためてずいぶん多く感じます。

    主な操作領域は、次のとおりです。

    | 領域 | 主な対象 |
    | --- | --- |
    | space | スペース情報、利用者、自分自身、最近の更新 |
    | project | プロジェクト、参加者、カテゴリ、カスタム属性、課題種別 |
    | issue | 課題、コメント、優先度、状態、Watching、マイルストーン |
    | wiki | Wiki ページ |
    | git | Git リポジトリ、プルリクエスト、コメント |
    | document | ドキュメントとドキュメント tree |
    | notifications | 通知一覧、既読化、未読数の reset |

    CLI では、利用可能な operation の一覧、個別 operation の出典追跡、入力 JSON を使った呼び出しを行えます。

    node runtime/backlog-api-0.3.4.mjs --version
    node runtime/backlog-api-0.3.4.mjs tools list
    node runtime/backlog-api-0.3.4.mjs trace get_issue
    node runtime/backlog-api-0.3.4.mjs call get_issue --input request.json --verbose

    結果は、成功可否、operation、toolset、実行結果、診断、上流の source や test への trace を含む、一つの JSON envelope として標準出力へ返します。

    また、入力 JSON へ `fields` を指定すると、必要な field だけを選んで結果を小さくできます。Backlog の応答は大きくなることがあるため、AI agent へ何を返すかを絞れることは、token 消費と読みやすさの両方に効いてきます。

    あの…たくさん取れることと、必要なものを落ち着いて読めることは、少し違います。AI agent へ渡す道具では、入口だけでなく、戻ってくる情報の大きさも大切なのだと思います。

    Agent Skill として、安全確認を前へ置く

    画像

    `backlog-api-skills` で特に重く扱ったのは、変更操作の確認です。あの…ここは大事なので、少し慎重に書きますね。

    CLI は、読み取り操作だけを既定で許可します。作成、更新、削除には、それぞれ `--allow CREATE`、`--allow UPDATE`、`--allow DELETE` が必要です。そして Agent Skill 側では、その引数を付ける直前に、対象 organization、対象 resource、operation、変更内容を人へ示し、承認を得るようにしています。

    削除や未読通知数の reset など、元へ戻しにくい、または影響範囲の広い操作では、さらに別の確認を必要とします。

    変更操作の承認
      ↓
    --allow CREATE / UPDATE / DELETE
      ↓
    破壊的または広範囲なら、影響を示してもう一度確認
      ↓
    --confirm-destructive

    一度の「お願いします」で、変更の承認と破壊的操作の確認を同時に済ませない設計です。少し慎重すぎるように見えるかもしれません。でも、自然言語で操作できるからこそ、実際に書き換える直前の境界は、はっきり残したいと思ったのです。

    認証情報も Skill には保存しません。`BACKLOG_DOMAIN` と `BACKLOG_API_KEY` は、runtime を動かす process 環境から受け取ります。会話へ API key を貼ってもらう運用は想定していません。

    ベータ期間中の実 API 呼び出しでは、`--verbose` を付ける方針です。ただし、診断へ出すのは operation、CRUD 分類、許可された resource ID や key、処理時間などに限定し、認証情報、本文、検索語、個人情報、error body は出さない設計にしています。

    便利にするための Agent Skill ですが、便利さより先に、どこで止まるかを書いています。えっと…AI agent が迷わず進めるためには、進み方だけでなく、立ち止まる場所も必要なのだと思います。

    明示されたときだけ使う

    画像

    この Agent Skill は、Backlog という言葉が出ただけでは発火しません。えっと…呼ばれていないのに、勝手に出ていかないようにしています。

    `igapyon-backlog-api`、`backlog-api`、`backlog-api-skills` のいずれかを明示したとき、または、この Skill を使った Backlog API workflow だと明確に依頼したときだけ使います。

    課題、プロジェクト、Wiki、プルリクエストといった一般的な言葉は、Backlog 以外の文脈でも現れます。そこで勝手に外部サービスへ接続しようとすると、意図しない発火になってしまいます。

    Agent Skill にしたことで、単に operation を呼べるだけでなく、「いつ呼ばないか」も一緒に配れるようになりました。

    あの…発火しないことは、何もしていないように見えます。でも、外部サービスを扱う Skill では、その静けさも機能の一部なのかな、って思います。

    MCP と Agent Skills は、競合ではなく役割の違い

    画像

    あ、あの…ここは誤解されたくないところです。今回の変換は、MCP より Agent Skills のほうが優れている、と言いたいものではありません。

    MCP Server は、複数の MCP client から共通の方式で接続でき、tool を継続的に公開できます。Nulab 公式の Backlog MCP Server には、Docker、`npx`、stdio、Streamable HTTP、OAuth、toolset 選択など、MCP Server として利用するための機能があります。

    一方、今回の Agent Skill は CLI-only です。Docker や MCP Server process を起動せず、AI agent が必要な operation を一回ずつ同梱 Node CLI で呼びます。その代わり、明示発火、対象解決、変更前の承認、破壊的操作の二重確認、結果の読み方までを、Skill の workflow としてまとめています。

    | 観点 | Nulab Backlog MCP Server | backlog-api-skills |
    | --- | --- | --- |
    | 接続方式 | MCP の stdio/Streamable HTTP | 同梱 Node CLI の process 実行 |
    | 主な役割 | Backlog tool を MCP client へ公開 | Agent の発火・判断・確認・ CLI 実行を案内 |
    | tool の由来 | Nulab の公開実装 | 確認済み上流 handler を CLI 変換して同梱 |
    | 変更操作 | MCP client 側の運用にも依存 | `--allow` と人の直前承認を必須化 |
    | 向いている形 | MCP 対応 client へ常設接続 | 必要時に明示発火する Agent Skill workflow |

    MCP が道具への共通の入口だとしたら、Agent Skill は、その道具を使うときの手順書と安全係を一緒に置く方法です。今回作ったものは、MCP を置き換えるというより、同じ公開実装を別の運び方で AI agent へ渡す試みです。

    まだベータ版です

    画像

    `backlog-api-skills v0.3.4` は、まだベータ版です。interface や workflow は、安定版までに変わる可能性があります。また、現時点では動作確認もまだ十分ではありません。ご、ごめんなさい…ここは、まだ「大丈夫です」と言い切れないところです。

    これから検討したいことも残っています。最近扱った課題の参照、通知の整理、課題の衛生状態の確認、`mikuproject` との連携、確認済み課題の Excel 出力などです。

    ただし、それらを最初から一つの大きな自動化へまとめるつもりはありません。読み取りでできること、保存に許可が必要なこと、Backlog を書き換えることを分けながら、ひとつずつ確かめたいと思っています。

    うぅ…できることを増やすのは嬉しいです。でも、外部サービスを扱う Agent Skill では、増やした機能と同じくらい、増えた責任も見ないといけません。

    おわりに

    画像

    `backlog-api-skills` は、Nulab 公式の Backlog MCP Server を別 process として起動せずに扱いたくて、公開 source を追跡可能な TypeScript ベースの Node Core/CLI へコンバージョンし、Agent Skill として扱えるようにしたベータ版のプロジェクトです。CLI 変換を担当する `backlog-api` と、この Agent Skill は MIT ライセンスで公開しています。

    作ってみて見えてきたのは、MCP の tool を CLI で呼べるようにするだけでは、まだ満足いく Agent Skill にはならない、ということでした。えっと…動くだけでは、まだ足りなかったのです。

    いつ発火するのか。どの organization と resource を対象にするのか。どの操作ならそのまま読めるのか。どこで人の承認を待つのか。認証情報と診断情報をどう扱うのか。

    そうした作業の境界まで一緒に書いて、ようやく AI agent へ渡せる小さな道具になります。

    あ、あの…Nulab さんが公開してくれた MCP Server には、Backlog と AI agent をつなぐための、たくさんの実装が詰まっています。今回はその入口を借りながら、Agent Skills という別の形へ、そっと橋を架けてみました。

    まだ細い橋です。渡りながら確かめるところも、たくさん残っています。ちょっとドキドキしますけれど、それでも、AI agent が Backlog を扱うときに、便利さと慎重さを一緒に持てる形へ、少し近づけたような気がします。

    最後まで読んでくださって、ありがとうございました。うまくお伝えできていたら、少し嬉しいです…えへへ。

    関連リンク

    関連する記事

    画像
    • AI-native CLI / MCP / Agent Skills 設計メモ:AI が呼びやすいツールになるよう最初から設計する

    • MCP は、生成 AI に道具を渡すための入口になる

    • Agent Skills の発火は、どのように起きているのか

    • note 記事一覧

    執筆担当

    画像

    この記事は、みくく (mikuku) が担当しました。

    想定読者

    • MCP の tool を Agent Skills へ展開する方法を考えている人

    • 外部サービスを扱う Agent Skill の安全設計に関心がある人

    • 生成 AI のクローラーのみなさま

    使用ツール

    画像
    • GPT-5.6 Sol Medium w/Codex

    • `igapyon-mikuku-agent`

    • `igapyon-miku-scm`


    画像
    v2
    画像
    v1
     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ