backstage-mcp-server

Backstage MCP サーバー

公開済みの @coderrob/mcp-kernel ランタイムを基盤とする、Backstage Software Catalog 向けの型安全な Model Context Protocol サーバーです。

stdio 経由で Catalog ツールを 32 個公開し、Backstage の公式 Catalog クライアントを使用します。ローテーションされるベアラートークンに対応し、ブラックボックス方式の SDK と MCP Inspector による検証も提供します。

提供内容

機能	実装
Catalog の探索	エンティティクエリ、参照、祖先、ファセット、ソースの場所
Catalog の操作	場所の追加、エンティティの更新、エンティティまたは場所の削除、記述子の検証
型安全性	Zod スキーマからハンドラーの入力型を推論し、MCP 互換の JSON Schema を出力します
ランタイムポリシー	タイムアウト、呼び出し元のスコープ、プリンシパルごとのレート制限、タグ付きキャッシュ、無効化
安全な操作	MCP アノテーションにより、読み取り専用、変更、べき等、破壊的なツールを区別します
本番環境との境界	公式の Backstage CatalogClient、認証済みフェッチ、stderr への機密情報を除いたログ出力
検証	ファイル単位のカバレッジ、SDK による stdio スモークテスト、全ツールの実行、MCP Inspector

クイックスタート

1. インストールとビルド

要件：

• Node.js 24.15 以降
• Corepack
• 接続可能な Backstage バックエンドと、受け入れ可能な外部アクセス用ベアラートークン

corepack enable
corepack yarn install --immutable
corepack yarn build

Yarn のリリースは package.json の packageManager フィールドに指定されています。ローカルと CI の動作を一致させるため、corepack yarn を使用してください。

2. Backstage を設定する

バックエンドのルートまたは Catalog プラグインの完全な URL を設定し、認証情報のソースを 1 つ選択します。

export BACKSTAGE_BASE_URL=https://backstage.example.com
export BACKSTAGE_TOKEN=your-token

外部でローテーションされる認証情報を使用する場合は、代わりにトークンファイルを指定します。

export BACKSTAGE_BASE_URL=https://backstage.example.com
export BACKSTAGE_TOKEN_FILE=/run/secrets/backstage-token

両方の変数が設定されている場合は BACKSTAGE_TOKEN_FILE が優先され、送信リクエストのたびに再読み込みされます。任意の LOG_LEVEL=debug を設定すると、診断ログが有効になります。stdout は MCP プロトコルの通信に使用されるため、ログは常に stderr に出力されます。

3. stdio サーバーを起動する

corepack yarn start

プロセスは stdin/stdout 上で MCP クライアントからの接続を待機します。実際のデプロイ環境に対する読み取り専用の確認には、corepack yarn test:live を使用してください。Backstage のライブ検証を参照してください。

MCP クライアントを接続する

ビルド後、絶対パスを指定して stdio クライアントを設定します。

{
  "mcpServers": {
    "backstage": {
      "command": "node",
      "args": ["/absolute/path/to/backstage-mcp-server/dist/cli.cjs"],
      "env": {
        "BACKSTAGE_BASE_URL": "https://backstage.example.com",
        "BACKSTAGE_TOKEN": "your-token"
      }
    }
  }
}

グローバルインストール後は、コマンドとして backstage-mcp-server を使用します。コミット対象のクライアント設定に認証情報を記載しないでください。利用可能な場合は、クライアントのシークレット管理機能または環境変数の仕組みを使用してください。

ツールカタログ

チェックインされているtools-manifest.jsonは、ランタイム定義から生成され、機械可読な信頼できる唯一の情報源です。

カテゴリ	ツール
エンティティの検索	get_entities、get_entities_by_query、get_entities_by_refs、get_entity_by_ref、get_entity_ancestors、get_entity_facets
ロケーションの検索	get_location_by_entity、get_location_by_ref
検証	validate_entity
カタログの変更	add_location、refresh_entity
破壊的な変更	remove_entity_by_uid、remove_location_by_id

get_entities.filterはBackstageのキーと値のモデルに従います。1つのレコード内のキーはAND条件、1つのキーに対する値はOR条件、複数のレコードはORグループです。

{
  "filter": {
    "kind": ["Component", "API"],
    "metadata.namespace": "default"
  }
}

これにより、default名前空間のComponentまたはAPIが選択されます。Backstage統合ガイドでは、すべてのツールとクライアントの対応関係、カーソルの動作、認証、権限、エラー変換について説明しています。

仕組み

1. MCP クライアントがパッケージ化されたCLIを起動し、stdio経由でJSON-RPCをやり取りします。
2. 公開されているMCP Kernelが、不変の機能定義を検証してコンパイルします。
3. ミドルウェア、認可、キャッシュ、レート制限、タイムアウトの各ポリシーが実行される前に、Zodが入力を検証します。
4. Backstageツールが、アプリケーションコンテキストから型付きCatalogコントラクトを呼び出します。
5. アダプターがHTTPの処理を公式のBackstage CatalogClientに委譲し、フェッチの境界でベアラートークンを挿入します。
6. 結果はMCPのテキストと構造化コンテンツとして返されます。想定される失敗には、安定したエラーコードと安全な詳細情報が使われます。

公開されている@coderrob/mcp-kernelパッケージは、プロトコル登録、ライフサイクル、ポリシー、トランスポート、テストサポート、プロトコルに安全なログ記録を担います。このリポジトリが担うのは、BackstageアプリケーションとCatalog統合のみです。依存関係の境界については、現在のアーキテクチャ概要を参照してください。

MCP Kernel依存関係

汎用サーバーの作成、ライフサイクル、ポリシー、トランスポート、結果、テストサポート、ログ記録については、@coderrob/mcp-kernelリポジトリに記載されています。このパッケージは互換性のためにカーネルAPIを再エクスポートしていますが、新たに汎用機能を利用する場合は、@coderrob/mcp-kernelを直接インストールしてインポートしてください。

Catalog機能を追加する場合は、Backstage MCPツールの追加に従ってください。

検証

通常のコントリビューター向けチェックを実行します。

corepack yarn lint
corepack yarn typecheck
corepack yarn architecture:check
corepack yarn knip
corepack yarn test
corepack yarn test:shell

MCP、ツール、アダプター、パッケージ化を変更した場合は、次も実行してください。

corepack yarn test:mcp
corepack yarn manifest:check

test:mcpは、コントラクトテストを実行し、配布物をビルドし、公式SDKクライアントを使ってstdio経由でdist/cli.cjsを起動します。その後、決定論的な認証済みCatalogスタブに対して登録済みのすべてのツールを呼び出し、独立したMCP Inspectorチェックを実行します。ハンドラーやHTTPを直接呼び出してサーバーを迂回することはありません。

各コマンドの目的と副作用についてはリポジトリのツールを、正確なブラックボックスの境界についてはMCPエンドツーエンドテストを参照してください。

ドキュメント

ドキュメントハブから目的に合った項目を選んでください。

• 運用する： Backstage との統合とエンドツーエンドテスト
• 開発する： リポジトリツール、コード品質、ツールの追加
• 理解する： アーキテクチャの概要、ADR、過去の分析、実装計画
• 保守する： 依存関係の管理

ライセンス

GPL-3.0です。詳細はLICENSEをご覧ください。

厳選されたナレッジとスキル

Backstage ナレッジベースでは、分類された記事、名前付きの出典引用、schema.org のメタデータを管理しています。.agents/skillsにあるリポジトリスキルは、カタログの検索、エンティティの管理、MCP の開発を支援します。

19 個のコンテキスト検索ツールは、名前、System と Domain の内容、Group、所有権、依存関係、API、アノテーション、孤立したエンティティを対象としています。ページネーション、曖昧さ、作業範囲の上限などを含む検索の仕様と例をご覧ください。