MCP Hub

MCP Knot

英語 | 中文版

Knot —— つながり、交差点。複数の MCP サーバーは散らばった糸のようなものです。MCP Knot はそれらをひとつの結び目にまとめ、すべてのツールが交わる軽量なハブになります。

MCP サーバーをひとつにまとめましょう。

複数の MCP サーバーを専用の Streamable HTTP または SSE エンドポイントに集約するために設計された、一元管理型のハブサーバーです。各エンドポイントは特定のユースケースに合わせて調整されており、軽量で、設定不要、2026-07-28 時点のステートレス MCP プロトコルをリードしています。

機能

• 複数サーバーの MCP 統合：複数の MCP サーバーを一元管理できます
• グループベースのルーティング：グループ固有のエンドポイント（/:group/mcp）を通じて MCP サービスにアクセスできます
• バージョン管理されたスキルの配布：ローカルディレクトリ、公開 Git リポジトリ、または skills CLI から選択したスキルをインポートし、固定スナップショットとしてツールとともにグループエンドポイントから公開できます。スキルガイドを参照してください。
• CLI MCP サーバー：ツール集約用のスタンドアロンコマンドライン MCP サーバー
• ストリーミング対応エンドポイント：HTTP と SSE の両方のエンドポイントに対応しています
• ツールのフィルタリング：グループではツールのフィルタリングと選別が可能です
• 検証への対応：セキュリティのため、グループごとに個別の検証キーを設定できます
• モジュール型アーキテクチャ：コアロジック、API、CLI パッケージを明確に分離しています

アーキテクチャ

MCP Knot は、次のパッケージで構成されるモジュール型モノレポアーキテクチャを採用しています。

コアパッケージ

• @mcp-core/mcp-knot-core - コア MCP サービス管理、接続処理、ツール実行
• @mcp-core/mcp-knot-api - グループベースのルーティングと HTTP エンドポイントを備えた Web API サーバー
• @mcp-core/mcp-knot-cli - スタンドアロンのツール集約用コマンドライン MCP サーバー
• @mcp-core/mcp-knot-protocol - プロトコル互換性レイヤー：二世代（最新／レガシー）間の変換、正規化されたモデル、統一されたエラー
• @mcp-core/mcp-knot-share - パッケージ間で共有する型とユーティリティ
• @mcp-core/mcp-knot-web - Vue.js フロントエンドインターフェース（任意）

パッケージ構成

├── backend/              # API server (@mcp-core/mcp-knot-api)
├── frontend/             # Vue.js web interface
├── packages/
│   ├── core/            # Core MCP logic (@mcp-core/mcp-knot-core)
│   ├── cli/             # CLI package (@mcp-core/mcp-knot-cli)
│   ├── protocol/        # Protocol compatibility layer (@mcp-core/mcp-knot-protocol)
│   └── share/           # Shared types (@mcp-core/mcp-knot-share)
└── docs/                # Documentation

インストール

前提条件

• Node.js 22.20+（Node 24 を推奨）
• pnpm パッケージマネージャー

依存関係のインストール

# Install all dependencies
pnpm install

# Build all packages
pnpm build

クイックスタート

1. API サーバー（Web インターフェース）

Web ベースの MCP ハブ機能を利用するには、API サーバーを起動します。

# Development mode
pnpm dev:api

# Production build and start
pnpm build
cd backend && pnpm start

API サーバーは http://localhost:8181 で利用できます。次のエンドポイントが提供されます。

• /mcp - グローバル MCP エンドポイント（レガシー、管理用）
• /:group/mcp - グループ固有の MCP エンドポイント
• /api/groups - グループ管理 API
• /api/skills - スキルソース、同期、市場検索のための管理者用 API
• /api/config - システム設定管理 API
• /api/servers - MCP サーバー管理 API
• /api/tools - ツール管理および実行 API
• /api/debug - デバッグおよびモニタリング API

2. CLI MCP サーバー

CLI パッケージをスタンドアロン MCP サーバーとして使用します。

# Install CLI globally (optional)
npm install -g @mcp-core/mcp-knot-cli

# Or run directly from workspace
cd packages/cli
pnpm build
node dist/cli.js

# Or use the executable
./bin/mcp-knot.js

クイック設定の初期化

MCP Knot CLI には、すぐに使い始められるクイック設定初期化機能があります。

# View all available commands
mcp-knot --help

# Initialize default configuration (includes common server examples)
mcp-knot --init

# Initialize all configurations (includes group configuration)
mcp-knot --init-all

# List all available server presets
mcp-knot --list-presets

# Overwrite existing configuration files
mcp-knot --init-all --overwrite

デフォルト設定には、次の一般的な MCP サーバーが含まれます。

• fetch：Web からの取得と HTTP リクエスト
• time：時刻と日付の機能
• sequential-thinking：順序立てて思考する機能

その他に利用できるサーバープリセット：

• filesystem：ファイルシステム操作
• memory：永続的なメモリストレージ
• brave-search：Brave 検索エンジン
• github：GitHub リポジトリ管理

CLI サーバーは MCP プロトコルを使用して stdin/stdout 経由で通信するため、Claude Desktop などの MCP クライアントとの統合に最適です。

3. フロントエンドインターフェース（任意）

ビジュアル管理用の Web インターフェースを起動します。

# Development mode
pnpm dev:fe

# Production build
pnpm build:fe

フロントエンドは http://localhost:8180（開発環境）で利用できます。本番環境ではバックエンド経由で配信されます。

Web インターフェースの機能

フロントエンドは、次の機能を備えた包括的な Web ベースの管理インターフェースを提供します。

1. 認証とセキュリティ

• JWT 認証：トークンベースの認証による安全なログインシステム
• トークンの自動更新：中断のないシームレスなセッション管理
• ルートガード：認証が必要なページを保護
• セッションの永続化：ブラウザーセッションをまたいでユーザーのログイン状態を保持
• デフォルトの認証情報：ユーザー名：admin、パスワード：admin（本番環境では変更してください！）

2. ダッシュボードとモニタリング

• システム概要：サーバー、ツール、グループのリアルタイム統計
• ステータスのリアルタイム更新：Server-Sent Events（SSE）によるリアルタイムモニタリング
• パフォーマンス指標：リクエスト率、応答時間、エラー率
• アクティビティフィード：最近のシステムアクティビティとイベント
• ヘルスモニタリング：システムのヘルスチェックとアラート

3. サーバー管理

• サーバーリスト：設定済みのすべての MCP サーバーをステータスインジケーターとともに表示
• サーバーの追加／編集：サーバー設定用のビジュアルフォーム
• 接続制御：サーバーへの接続、切断、接続テスト
• ステータスモニタリング：サーバー接続ステータスをリアルタイムで監視
• 設定の検証：保存前にサーバー設定をテスト

4. ツール管理

• ツールブラウザー：サーバー全体で利用可能なすべての MCP ツールを閲覧
• ツールの検索と絞り込み：名前、サーバー、グループでツールを検索
• ツールのテスト：パラメーターを入力して対話的にツールを実行
• 実行履歴：過去のツール実行と結果を表示
• ツールの詳細：ツールのドキュメントとスキーマ情報をすべて表示

5. グループ管理

• グループ設定：サーバーグループを作成、管理
• メンバー管理：サーバーをグループに割り当て
• ツールの絞り込み：グループごとに利用可能なツールを設定
• 検証キー：グループ単位の認証を設定、管理
• グループ統計：使用状況の統計とパフォーマンス指標

6. API と MCP の統合

• API 設定：REST API を MCP ツールに変換
• パラメーターのマッピング：API と MCP 間のパラメーターマッピング用ビジュアルエディター
• API のテスト：デプロイ前に API 設定をテスト
• インポート／エクスポート：環境間で API 設定を共有
• 自動生成：API 仕様から MCP ツールを自動生成

7. デバッグと開発用ツール

• MCP プロトコルモニター：MCP プロトコルの生メッセージを表示
• ツールデバッガー：詳細な実行ログを確認しながらツールをテスト
• パフォーマンスアナライザー：ツールのパフォーマンスとボトルネックを分析
• エラー分析：エラーをインテリジェントに診断し、修正方法を提案
• メッセージインスペクター：リクエスト／レスポンスのペイロードを検査

8. 設定管理

• システム設定：システム全体の設定を構成
• 設定エディター：検証機能付きで設定を編集
• バックアップと復元：設定のバックアップを作成、復元
• 設定履歴：設定の変更を時系列で追跡
• 検証：設定をリアルタイムで検証

認証の設定

フロントエンドでは JWT ベースの認証を使用します。認証を設定するには：

1. デフォルトの認証情報（開発環境）：

   • ユーザー名：admin
   • パスワード：admin

2. 本番環境の設定：

   • system.json で認証情報、JWT シークレット、サーバーポートを設定します（ backend/config/system.json.example と packages/share/src/config/schemas/system.schema.ts のスキーマを参照してください）。
   • ルートの users.admin.password に強力なパスワードを設定します。現在のバックエンドは設定されたパスワードをメモリー内でハッシュ化します。このフィールドに事前計算済みの bcrypt ハッシュを設定しないでください。設定ディレクトリへのアクセスをデプロイユーザーに制限してください。
   • JWT シークレットと有効期限は、環境変数ではなく system.json の auth.jwt ブロックから取得されます。

3. 環境変数：

   # Backend (.env) — only env vars the code actually reads; see .env.production.example
   NODE_ENV=production
   CONFIG_PATH=/path/to/config      # directory containing system.json, mcp_server.json, group.json
   VALIDATION_KEY_SECRET='<your-existing-secret-at-least-32-characters>'  # required when group validation is enabled
   

Web インターフェースへのアクセス

1. バックエンドを起動する：

   pnpm dev:api
   # Backend runs on http://localhost:8181
   

2. フロントエンドを起動する（開発環境）：

   pnpm dev:fe
   # Frontend runs on http://localhost:8180
   

3. ログインする：

   • http://localhost:8180 にアクセスします
   • 認証情報を入力します（デフォルト：admin/admin）
   • ダッシュボードにリダイレクトされます

4. 本番環境へのデプロイ：

   # Build frontend
   pnpm build:fe
   
   # Frontend static files will be in frontend/dist
   # Serve the output with nginx (included in the Web image)
   

   標準的な本番環境の構成は、2 コンテナー構成です。公開されている GHCR イメージを使う場合は docker-compose.release.yml を、ソースからビルドする場合は docker-compose.yml を使用します：

   • mcp-knot-web（nginx、ホストポート 8180）— SPA を配信し、/api/、/mcp、/:group/mcp をバックエンドにリバースプロキシします。SPA のフォールバック（try_files ... /index.html） は frontend/nginx.conf で設定されているため、フロントエンドのどのルートでも再読み込みできます。
   • mcp-knot-api（Node、内部ポート 8181）— API と MCP エンドポイントを提供します。SPA のホストではありません。

   アプリには必ず nginx のポート（8180）経由でアクセスしてください。フロントエンドのパスを使ってバックエンドのポート（8181） に直接アクセスすると、バックエンドが /api/* と /:group/mcp のみを提供するため、404 Not Found が返されます。 これは想定された動作であり、バグではありません。

   # v0.1.1 is published; prepare config and the localhost override per the guide
   export MCP_KNOT_VERSION=v0.1.1
   docker compose -f docker-compose.release.yml -f docker-compose.localhost.yml pull
   docker compose -f docker-compose.release.yml -f docker-compose.localhost.yml up -d --no-build --wait
   curl -f http://localhost:8180/api/ping
   

   書き込み可能な設定ディレクトリを事前に準備してください。このディレクトリは /app/config にマウントされ、 デフォルトでは ./config が使われます。公開イメージは ghcr.io/yourtion/mcp-knot-api と ghcr.io/yourtion/mcp-knot-web です。バージョン変数は必須であり、暗黙的に latest が 使用されることはありません。v0.1.1 の両イメージは現在 Public で、匿名での pull にも成功しています。実際の GHCR amd64 イメージで、Compose の起動、API／Web のチェック、再起動後の設定保持を確認済みです。arm64 はビルド済みで、マニフェストも検証済みですが、 ARM でのアプリケーションの実行はテストされていません。初期化 JSON 全体、UID 1000 の 権限、localhost のオーバーライド、アップグレードについては、 デプロイガイドを参照してください。外部からアクセス可能にする前に、デフォルトの admin/admin と JWT シークレットを変更し、その後 API を再起動してください。API の稼働確認用エンドポイントは /api/ping、サービスの詳細な状態を確認するエンドポイントは /api/health です。

設定

MCP サーバーの設定

backend/config/ ディレクトリに mcp_server.json ファイルを作成します：

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

グループの設定

backend/config/group.json でグループを設定します：

{
  "groups": {
    "development": {
      "name": "Development Tools",
      "description": "Tools for software development",
      "servers": ["filesystem", "git"],
      "allowedTools": ["read_file", "write_file", "git_status"],
      "validationKey": "dev-key-123"
    },
    "research": {
      "name": "Research Tools",
      "description": "Tools for research and information gathering",
      "servers": ["brave-search", "wikipedia"],
      "allowedTools": ["search", "lookup"],
      "validationKey": "research-key-456"
    }
  }
}

使用例

グループ単位の MCP アクセス

グループごとのエンドポイントからツールにアクセスします：

# List tools for development group（MCP 2026-07-28 JSON-RPC）
curl -X POST http://localhost:8181/development/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Call a tool in the research group
curl -X POST http://localhost:8181/research/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/call" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "MCP protocol documentation"
      }
    }
  }'

公式 MCP SDK（Node）で接続する

/:group/mcp エンドポイントは、デフォルトで最新の 2026-07-28 プロトコルを提供し、 プロトコル互換レイヤー（P7）により、2025 年頃の旧式クライアントも受け付けます。受信時の互換性はデフォルトで**すべて有効（最新形式＋旧形式）**です。最新形式の クライアントは server/discover 経由でネゴシエーションし、旧式クライアントの単独の initialize ハンドシェイクも引き続き受け付けられます。この設定は変更できます（ プロトコル互換性を参照してください）。

最新形式のクライアントでは、公式の @modelcontextprotocol/client に versionNegotiation: { mode: 'auto' } を設定してください。これにより、SDK がサーバーの 2026-07-28 バージョンを確認して採用します。

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('http://localhost:8181/default/mcp'));
const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  {
    capabilities: { tools: {} },
    // Recommended: lets the SDK probe and adopt the server's 2026-07-28 version.
    versionNegotiation: { mode: 'auto' },
  },
);

await client.connect(transport); // initialize
const { tools } = await client.listTools(); // tools/list
await client.callTool({ name: 'fetch_fetch', arguments: { url: 'https://example.com' } });

サーバー間の衝突を避けるため、ツールには <serverId>_<toolName> という名前空間が付与されます（例：fetch_fetch、 context7_query-docs）。また、組み込みのメタツール 2 つ （group_status、list_group_tools）も、すべてのグループエンドポイントで公開されます。

プロトコル互換性

Hub には、現代の 2026-07-28 世代と従来の 2025 年世代の MCP を双方向に橋渡しするプロトコル互換性レイヤー（@mcp-core/mcp-knot-protocol）が含まれています。

• 受信（クライアント → Hub）：デフォルトでは 現代と従来の両方を同時に受け付けます。現代のクライアントは server/discover を介してネゴシエートし、従来のクライアントからの単独の initialize リクエストにも引き続き応答します。従来のクライアントを拒否し、現代のクライアントのみを受け付けるには、compatibility.inbound.enabled: false（または CLI の --no-legacy-inbound）を設定してください。
• 送信（Hub → アップストリームサーバー）：世代はサーバーごとに自動で判定されます。Hub は現代のリクエストを従来のアップストリームサーバーに透過的に橋渡しします。バックエンドで現代のアップストリームサーバーのみに接続するには、compatibility.outbound.modernOnly: true（または CLI の --modern-only-upstream）を設定してください。この CLI フラグは予約済みです。現在、コアサービスはアップストリーム接続をシミュレートしており、このフラグを適用しません。
• MRTR とエラー：世代をまたぐ InputRequiredResult（MRTR）の状態とプロトコルエラーは、アップストリームの世代にかかわらず、統一された形式に正規化されます。input_required に対応できない従来のアップストリームサーバーでは、エラーが暗黙に失敗するのではなく、明確な -32601 エラーに切り替わります。

既存のクライアントが引き続き動作するよう、デフォルト設定は意図的に寛容になっています。system.json の compatibility ブロックは省略可能で、一部の項目を上書きできます。すべてを許可するデフォルトの動作にするには、ブロック全体を省略してください。

テスト範囲：世代間の橋渡しは、プロジェクト独自の E2E テスト（protocol-compliance.test.ts：送信側の現代→従来、受信側の従来→現代）に加えて、アダプター／コーデック／正規化レイヤーのユニットテストでカバーされています。公式の @modelcontextprotocol/conformance TCK は回帰テストのゲート（pnpm test:conformance）として組み込まれていますが、TCK v0.1.16 の時点では、サーバーモードで従来の 2025-11-25 世代のみを対象としています。現代の 2026-07-28 世代の適合性テストは、上流の TCK によるサポート待ちです。

CLI MCP サーバーの統合

MCP クライアント（例：Claude Desktop）で CLI サーバーを設定します。

{
  "mcpServers": {
    "mcp-knot": {
      "command": "/path/to/mcp-knot/packages/cli/bin/mcp-knot.js",
      "args": ["--config", "/path/to/mcp_server.json"]
    }
  }
}

開発

利用可能なスクリプト

# Development
pnpm dev:api          # Start API server in development mode
pnpm dev:fe           # Start frontend in development mode

# Building
pnpm build            # Build all packages
pnpm check            # Run linting and formatting

# Testing
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage
pnpm test:e2e         # Run end-to-end tests

# Utilities
pnpm inspector        # Launch MCP inspector for debugging

パッケージの開発

各パッケージは個別に開発できます。

# Core package
cd packages/core
pnpm dev              # Watch mode compilation
pnpm test:watch       # Watch mode testing

# CLI package
cd packages/cli
pnpm dev              # Watch mode compilation
pnpm test:e2e         # End-to-end testing

# API package
cd backend
pnpm dev              # Development server
pnpm test:mcp         # MCP protocol tests

ドキュメント

ユーザーガイド

• Web UI ガイド - Web インターフェースの完全な使用ガイド
• CLI 使用ガイド - CLI の使用方法と設定の詳細
• トラブルシューティング - よくある質問とトラブルシューティング

技術ドキュメント

• API リファレンス - API の完全なドキュメント
• グループルーティングガイド - グループベースのルーティングに関するドキュメント

開発とデプロイ

• 開発ガイド - 開発環境のセットアップとコントリビューションガイド
• リリースプロセス - バージョンの統一とタグベースの公開
• デプロイガイド - 本番環境へのデプロイ手順
• トラブルシューティング - よくある問題と解決策

リリースプロセス

4つの公開パッケージ（share、protocol、core、cli）は、共通の安定版バージョンを使用します。 変更をマージし、main の CI が成功したら、クリーンで最新の main から次を実行します。

pnpm run release:prepare patch  # minor, major, or an explicit X.Y.Z also work
# Review the version-only commit and local vX.Y.Z tag
pnpm run release:push

準備処理ではリリースを検証し、4つのバージョンマニフェストのみをコミットしてから、ローカルタグを作成します。プッシュは main とそのタグのみをアトミックに送信します。タグをトリガーに実行される publish.yml は、npm OIDC を使って検証、ビルド、tarball のチェックを行い、依存関係の順序に従って公開した後、GitHub Release を1つ作成します。すでに公開済みの同一バージョンは、再試行時にスキップされます。オプションの GHCR API/Web 公開は、リポジトリ変数 DOCKER_PUBLISH=true で有効になり、ジョブ単位でスコープされた packages: write 権限を持つ Actions の GITHUB_TOKEN を使用して、amd64/arm64 向けに latest と完全なリリースタグを公開します。新しい GHCR パッケージはデフォルトで非公開です。公開範囲はメンテナーが管理します。現在の API/Web パッケージは Public で、v0.1.1 の匿名プルが検証済みです。GHCR の設定と検証結果を参照してください。

公開を伴わない完全なローカルチェックには pnpm run release:validate を、ビルドとパッケージのチェックには pnpm run release:dry-run を使用してください。セットアップ、初回公開時の認証、再試行の手順についてはRELEASING.mdを参照してください。

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. テストを追加して変更を加えます
4. pnpm check を実行して、コード品質を確認します
5. プルリクエストを送信します

ライセンス

ISC ライセンスです。詳細は LICENSE ファイルを参照してください。