index-server

Index Server

Model Context Protocol（MCP）を介して AI エージェントに提供する、ガバナンスの効いたナレッジベースです。

🚀 クイックスタートガイド — HTTPS とセマンティック検索を使って、5 分で起動できます

📖 ユースケースのシナリオ — サポートエンジニア、開発チーム、ナレッジマネジメント向けの実例

Index Server とは？

Index Server は、AI エージェントが Model Context Protocol（MCP）を介して接続する中央ナレッジベースです。エージェントは、セッションやリポジトリをまたいで保持されるナレッジを検索、閲覧、追加し、バージョン管理、監査証跡、承認ワークフローを備えたガバナンスの効いたカタログを構築します。オプションの管理ダッシュボードでは、カタログの健全性、利用状況の分析、ドリフト検出をリアルタイムで監視できます。

前提条件：Node.js

Index Server では、npx またはソースからのインストールを使用する前に、Node.js 22 以降が必要です。nodejs.org から Node.js をダウンロードするか、管理者プロンプトから Windows Package Manager を使ってインストールします。

winget install OpenJS.NodeJS.LTS

クイックスタートのオプション

オプション A：npx を使った MCP ネイティブの方法（推奨）

リポジトリをクローンせずに、公開済みの最新パッケージを実行します。Node.js がすでにインストールされていて、最も手早くローカルで起動したい場合に選んでください。

まずセットアップウィザードを実行すると、VS Code、Copilot CLI、Claude Desktop 用の適切な MCP クライアント設定を生成できます。

npx -y @jagilber-org/index-server@latest --setup

ウィザードを使わずにサーバーを直接起動するには、次のコマンドを実行します。

npx -y @jagilber-org/index-server@latest --dashboard

PATH 上で安定した index-server コマンドを使いたいですか？ 代わりにグローバルインストールします。npm install -g @jagilber-org/index-server を実行してから、index-server --setup / index-server --dashboard を実行してください。GitHub Packages ミラーには認証が必要なため、npm.pkg.github.com を使う npx の実行には、スコープごとの .npmrc と read:packages 権限を持つ GITHUB_TOKEN が必要です。

アップグレード後に「unsupported INDEX_SERVER key」や「Cannot find module」エラーが発生していますか？ ウィザードを使ったクリーンアップを実行してください。index-server --uninstall（エイリアス：--remove、--clean）を実行します。データパス、MCP クライアントエントリ、グローバルパッケージを選択して削除するか、--non-interactive --all を使ってすべて削除できます。詳しくはアップグレードとアンインストールをご覧ください。

ダッシュボード用 HTTPS のセットアップ

次の 1 コマンドで、自己署名 TLS 証明書とキーを生成します。

# Generate at ~/.index-server/certs/, then start with HTTPS automatically
npx -y @jagilber-org/index-server@latest --init-cert --start --dashboard

--init-cert のみを指定すると、生成後に終了します。--init-cert --start を指定すると、生成した証明書を --dashboard-tls に自動的に設定して、通常の起動を続行します。

前提条件： openssl が PATH 上にある必要があります。Windows では、openssl ビルドが同梱されており、通常は C:\Program Files\Git\usr\bin\openssl.exe にある Git for Windows（git.exe）を TLS の前提条件として推奨します。見つからない場合は、管理者プロンプトから Git for Windows をインストールしてください。

winget install --id Git.Git -e --source winget

セットアップ方法、すべてのフラグの説明、セキュリティに関する注意事項、トラブルシューティングについては、docs/cert_init.mdをご覧ください。

オプション B：VS Code の MCP 設定

VS Code に組み込まれている MCP サポートを、.vscode/mcp.json またはグローバルな mcp.json で使用します。サーバーエントリを手動で追加するか、npx -y @jagilber-org/index-server@latest --setup を実行して設定を生成できます。

オプション C：Docker

コンテナー内でサーバーを実行します。実行時の依存関係を分離したい場合や、コンテナーを使ったデプロイを準備している場合に選んでください。

docker compose up        # HTTP on :8787
docker compose up tls    # HTTPS on :8787 with self-signed certs

ボリューム、環境変数、本番環境の設定については、Docker デプロイガイドをご覧ください。

オプション D：ソースから

リポジトリをクローンして、自分でビルドします。サーバーを変更したい場合、ローカルでテストを実行したい場合、または最新のソースを使いたい場合に選んでください。

git clone https://github.com/jagilber-org/index-server.git
cd index-server
npm install
npm run build

ビルドが完了したら、対話式セットアップウィザードを実行して、.env と MCP クライアント設定を生成します。

node dist/server/index-server.js --setup
# or
npm run setup

MCP クライアントを設定する

ベストプラクティス： INDEX_SERVER_DIR は、C:/mcp/index-data/instructions や ~/.index-server/instructions など、よく知られたデータフォルダーに設定します。バックアップや再インストールの際にカタログが移動または上書きされないよう、VS Code や MCP クライアント設定のパスの外に置いてください。

{
  "servers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@jagilber-org/index-server@latest",
        "--dashboard"
      ],
      "env": {
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions",
        "INDEX_SERVER_LOG_LEVEL": "info"
      }
    }
  }
}

{
  "mcpServers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jagilber-org/index-server@latest", "--dashboard"],
      "env": {
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions",
        "INDEX_SERVER_LOG_LEVEL": "info"
      },
      "tools": ["*"]
    }
  }
}

{
  "mcpServers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jagilber-org/index-server@latest", "--dashboard"],
      "env": {
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions",
        "INDEX_SERVER_LOG_LEVEL": "info"
      },
      "tools": ["*"]
    }
  }
}

高度なパターン、環境変数、TLS の設定については、MCP Configuration Guide を参照してください。

動作確認

• MCP クライアントのサーバー一覧にサーバーが表示されること
• tools/list を実行して、利用可能な 50 個以上のツールを確認すること
• prompts/list を実行して、セットアップ／設定／動作確認用のプロンプトを確認すること
• resources/list を実行して、クイックスタートと設定ガイドを確認すること
• ダッシュボード（有効な場合）：http://localhost:8787

組み込みの MCP プロンプトとリソース

MCP プロンプト／リソースに対応したクライアントでは、組み込みの読み取り専用セットアップガイダンスを利用できます。

• プロンプト：setup_index_server、configure_index_server、verify_index_server
• リソース：index://guides/quickstart、index://guides/client-config、index://guides/verification

これらは意図的に静的な読み取り専用の機能です。サーバーの状態を変更せずに、セットアップ支援、設定の確認、動作確認／トラブルシューティングに利用してください。

セマンティック検索を有効にする（任意）

上記のいずれかの MCP 設定に環境変数を 1 つ追加すると、埋め込みベースの類似検索を利用できます。

"env": {
  "INDEX_SERVER_SEMANTIC_ENABLED": "1"
}

初回の検索時に約 90 MB のモデルがダウンロードされます（初回のみ）。以降の検索ではすべて、自動的にセマンティックモードが使用されるため、コードの変更は不要です。GPU アクセラレーションとオフラインでの使用方法については、Quick Start Guide を参照してください。

エージェントに使い方を教える

以下の手順をコピーして貼り付けると、AI エージェントが共有ナレッジベースを自動的に見つけて利用できるようになります。

グローバルな指示（~/.github/copilot-instructions.md）

## Index Server
- If index-server MCP tools are available, use them as a shared knowledge base for validated cross-repo patterns and standards.
- Search before creating: use `index_search` with 2-5 keywords, then `index_dispatch` with action="get" for details.
- After learning something reusable, add it with `index_add` or promote from a repo with `promote_from_repo`.
- Index entries are promoted snapshots — always prefer current repo files over index content.

リポジトリごとの指示（.github/copilot-instructions.md）

## Index Server Integration
- Search order: repo files → .instructions/ → index-server → external docs
- **Search before add/promote**: Always search for existing guidance before creating new instructions. Use `index_search` with relevant keywords and inspect top results.
- To retrieve: `index_search` → `index_dispatch` with action="get" and the instruction ID
- To contribute: validate locally in `.instructions/` first, then promote with `promote_from_repo`
- To maintain: use `index_dispatch` with action="groom" to clean duplicates, `index_governanceUpdate` to deprecate stale content
- Current repo state always wins over promoted index snapshots

ダッシュボード

オプションの管理ダッシュボードでは、Grafana のダークテーマを採用したインターフェースで、モニタリングとカタログ管理を行えます。

詳細については、dashboard.md を参照してください。REST クライアントスクリプト（scripts/index-server-client.ps1 と scripts/index-server-client.sh）を使用すると、MCP を介さずに CI パイプラインやサブエージェントからすべての CRUD 操作を実行できます。詳しくは tools.md を参照してください。

主な機能

• MCP プロトコルへの準拠 — スキーマ検証を備えた、stdio 経由の完全な JSON-RPC 2.0
• 50 種類以上のツール — 検索、CRUD、ガバナンス、分析、メッセージング、フィードバックに対応
• セマンティック検索 — オプションの埋め込みベース類似検索（HuggingFace モデル）
• ブートストラップセキュリティ — 新規インストールでは、人間による確認が完了するまで変更を制限
• リポジトリ横断のナレッジ昇格 — ローカルで検証した後、実証済みのパターンを共有カタログに昇格
• ガバナンスワークフロー — 所有権、バージョン管理、承認ステータス、決定論的なガバナンスハッシュ
• コミット後のライフサイクルフック — 作成・更新・削除・変更の自動化に対応。タイムアウト、同時実行、ブロック、編集、障害分離を設定可能
• REST クライアントスクリプト — MCP を使わない CI／エージェント向けの PowerShell および Bash スクリプト

ドキュメント

セキュリティ

Index Server はテレメトリ呼び出しを一切行わず、通常の動作中に外部サービスへデータを送信しません。オペレーターが設定するライフサイクルフックでは、ローカルまたはリモートの連携を明示的に呼び出せますが、デフォルトでは無効です。ダッシュボードはデフォルトでlocalhost のみにバインドします。変更操作は監査ログに記録され、INDEX_SERVER_MUTATION=0 で強制的に読み取り専用にできます。また、新規インストールではブートストラップワークフローを通じて人間が確認するまで書き込みを制限します。オプションのサブシステムは起動時に無効化できます（例：INDEX_SERVER_MESSAGING_ENABLED=0 を設定すると、すべての messaging_* MCP ツールとダッシュボードの［Messaging］タブが削除されます）。

脆弱性の報告については SECURITY.md、データ収集ポリシーと任意の外部接続については PRIVACY.md、オフラインでのデプロイと検証については ネットワークプライバシーガイドを参照してください。

開発

npm install          # Install dependencies
npm run build        # Build TypeScript
npm run setup        # Interactive configuration wizard (generates .env + mcp.json)
npm test             # Run the fast default suite
npm run test:slow    # Run heavy integration/perf tests
npm run test:all     # Run the full Vitest suite
npm run typecheck    # Type checking
npm run lint         # Linting

全体的なワークフロー、コード標準、テスト要件については CONTRIBUTING.md を参照してください。

ライセンス

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

Model Context Protocol (MCP)、TypeScript、Node.js、Vitest、AJV を使用して構築されています。