Mcp Prompt Manager

MCP Prompt Manager（Git 駆動）

📋 はじめに

これは、プロンプトテンプレートの管理と提供を目的とした、Git 駆動の Model Context Protocol（MCP）サーバーです。プロンプトを専用の Git リポジトリに保存し、MCP プロトコルを通じて Cursor、Claude Desktop などの AI エディターで直接利用できます。

主なメリット：

• 🔄 チームコラボレーション：Git のバージョン管理により、チーム全体でプロンプトのバージョンを統一できます
• 🎯 動的テンプレート：Handlebars 構文に対応し、再利用可能な動的プロンプトを作成できます
• 🚀 ダウンタイムなしの再読み込み：ホットリロードに対応し、再起動せずにプロンプトを更新できます
• 🔍 スマートな管理：プロンプトのバージョン管理、状態の追跡、グループによるフィルタリングを標準で備えています
• 📊 包括的なモニタリング：システムの健全性とプロンプトの統計情報を確認できます

✨ 機能

• Git 同期：指定した Git リポジトリからプロンプトを直接同期し、チーム全体で統一されたプロンプトのバージョンを使用できます。
• Handlebars テンプレート：強力な Handlebars 構文に対応し、動的で再利用可能なプロンプトテンプレートを作成できます。
• パーシャル対応：Handlebars パーシャルに対応し、プロンプトの断片（例：ロール設定、出力形式）を分割して再利用できます。
• ローカルキャッシュ：Git リポジトリのコンテンツをローカルの .prompts_cache ディレクトリに自動的にキャッシュし、読み込みを高速化します。
• キャッシュ有効期限戦略：期限切れのキャッシュ項目を定期的に自動削除し、メモリリークを防いでデータの一貫性を保ちます。
• グループによるフィルタリング：グループでプロンプトをフィルタリングし、必要なものだけを読み込めます。
• エラー処理：問題の追跡に役立つ、包括的なエラー統計とレポート機能を備えています。
• リトライ機構：Git 操作を自動で再試行し、信頼性を高めます。
• 型安全性：Zod を使用して設定とプロンプト定義を検証し、型安全性を確保します。
• プロフェッショナルなロギング：pino ロギングシステムを使用し、構造化ログと複数のログレベルに対応します。

🚀 クイックスタート

オプション 1：マーケットプレイスからインストール（最も簡単）

MCP マーケットプレイス（例：mcp.so）からインストールする場合は、マーケットプレイスのインストール手順に従ってください。通常、次の作業が必要です。

1. マーケットプレイスからインストール：マーケットプレイスのインストール画面を使用します
2. MCP クライアントを設定：MCP クライアントにサーバー設定を追加します

前提条件

インストールする前に、次のものが揃っていることを確認してください。

• Node.js がインストールされていること（バージョン 18.0.0 以上）
• pnpm パッケージマネージャー（バージョン 8.0.0 以上）
• プロンプトを含む Git リポジトリ（またはプロンプトのローカルパス）
• MCP 対応クライアント（Cursor、Claude Desktop、VS Code など）

インストール手順

1. マーケットプレイスからインストール：

   • お好みの MCP マーケットプレイスにアクセスします
   • 「mcp-prompt-manager」を検索します
   • マーケットプレイスのインストール手順に従います
   • サーバーのインストール先のパスをメモします

2. インストール先のパスを確認：

   • マーケットプレイスからインストールした後、dist/index.js の場所を確認します
   • 通常は、グローバルの node_modules ディレクトリまたは専用のインストールフォルダー内にあります
   • 設定には、このファイルの絶対パスが必要です

3. MCP クライアントを設定：

   • MCP クライアントの設定ファイルを開きます（ファイルの場所については、設定セクションを参照してください）
   • サーバーの設定を追加します（以下の例を参照してください）
   • 重要：相対パスではなく、絶対パスを使用してください

設定例

インストール後、次のように MCP クライアント（Cursor、Claude Desktop など）を設定します。

Cursor の場合（~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json）：

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "https://github.com/yourusername/your-prompts-repo.git",
                "MCP_LANGUAGE": "en",
                "MCP_GROUPS": "common",
                "LOG_LEVEL": "info"
            }
        }
    }
}

注：/absolute/path/to/mcp-prompt-manager/dist/index.js を、マーケットプレイスからサーバーをインストールした実際の絶対パスに置き換えてください。

ヒント：設定テンプレートの全体については、mcp.json.exampleを参照してください。

インストール先のパスを確認する

マーケットプレイスからサーバーをインストールした場所がわからない場合は、以下を確認してください。

macOS/Linux：

# Search for the installed file
find ~ -name "index.js" -path "*/mcp-prompt-manager/dist/index.js" 2>/dev/null

# Or check common installation locations
ls -la ~/.local/share/mcp-prompt-manager/dist/index.js
ls -la /usr/local/lib/node_modules/mcp-prompt-manager/dist/index.js

Windows：

# Search for the installed file
Get-ChildItem -Path $env:USERPROFILE -Filter "index.js" -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.FullName -like "*mcp-prompt-manager\dist\index.js" }

検証

設定後：

1. MCP クライアントを完全に再起動します
2. サーバーのステータスを確認します：
   • Cursor の場合：Cmd/Ctrl + Shift + Pを押して、「MCP: Show servers」を検索します
   • Claude Desktop の場合：設定にある MCP サーバーのリストを確認します
3. プロンプトが読み込まれていることを確認します：クライアントの MCP ツールを使用して、利用可能なプロンプトを一覧表示します

MCP クライアントごとの詳しい設定手順については、以下の設定セクションを参照してください。

オプション 2：Docker でのデプロイ（推奨）

Docker を使うのが、最も簡単な始め方です。

# 1. Clone the repository
git clone <project URL>
cd mcp-prompt-manager

# 2. Copy environment variables example
cp .env.docker.example .env

# 3. Edit .env and set your Git repository URL
# PROMPT_REPO_URL=https://github.com/yourusername/your-prompts-repo.git

# 4. Start with Docker Compose
docker-compose up -d

# 5. View logs
docker-compose logs -f

Docker でのデプロイ手順の詳細については、DOCKER.mdを参照してください。

オプション 3：ローカルインストール

開発時、またはインストールを完全に制御したい場合は、このオプションをおすすめします。

前提条件

• Node.js 18.0.0 以上
• pnpm 8.0.0 以上（必須。npm/yarn では失敗します）
• Git（リポジトリのクローンに使用）

インストール手順

1. リポジトリをクローン：

git clone https://github.com/CarlLee1983/mcp-prompt-manager.git
cd mcp-prompt-manager

2. 依存関係をインストール：

# Use pnpm (required - npm/yarn will fail)
pnpm install

注：インストールには pnpm が必須です。preinstall チェックにより、npm/yarn では失敗します。

3. プロジェクトをビルド：

pnpm run build

これにより、TypeScript がコンパイルされ、dist/ディレクトリに JavaScript が生成されます。

4. 環境変数を設定：

サンプル設定ファイルをコピーして、.envを作成します。

cp .env.example .env

.envファイルを編集し、Prompt Git Repository のパスまたは URL を設定します。

# Git Repository source (required)
# Local path example
PROMPT_REPO_URL=/Users/yourname/Desktop/my-local-prompts

# Or remote Git URL examples
# PROMPT_REPO_URL=https://github.com/yourusername/my-prompts.git
# [email protected]:yourusername/my-prompts.git

# Output language setting (optional, default: en)
MCP_LANGUAGE=en  # or zh

# Group filter setting (optional, defaults to loading only common group when not set)
# Example: MCP_GROUPS="laravel,vue,react"
# Note: When not set, the system will explicitly prompt in logs about using default groups
MCP_GROUPS=laravel,vue

# Custom storage directory (optional, default: .prompts_cache)
STORAGE_DIR=/custom/path

# Git branch (optional, default: main)
GIT_BRANCH=main

# Git retry count (optional, default: 3)
GIT_MAX_RETRIES=3

# Cache cleanup interval (optional, default: 10000 milliseconds)
# Set the interval time (in milliseconds) for periodic cleanup of expired cache items
# Default is 10 seconds (CACHE_TTL * 2) to ensure expired items are cleaned up promptly
# Recommended values: 5000-30000 milliseconds, adjust based on usage frequency
CACHE_CLEANUP_INTERVAL=10000

# Log level (optional)
# Options: fatal, error, warn, info, debug, trace, silent
# Notes:
# - stderr only outputs warn/error/fatal level logs (to avoid being marked as error)
# - info/debug/trace level logs only output to file (if LOG_FILE is set)
# - If LOG_FILE is not set, info level logs are completely suppressed (to avoid confusion)
# - Production environment defaults to warn (only warnings and errors), development defaults to info
# - Setting silent completely disables log output
LOG_LEVEL=info

# Log file path (optional, strongly recommended)
# After setting this variable, all level logs will be written to file (JSON format)
# stderr still only outputs warn/error/fatal (to avoid being marked as error)
# Can be absolute or relative path (relative to project root)
# Examples:
# LOG_FILE=/tmp/mcp-prompt-manager.log
# LOG_FILE=logs/mcp.log
# Note: File is written in append mode, will not overwrite existing content
# Recommendation: Set this variable to view complete logs (including info level)
LOG_FILE=logs/mcp.log

5. MCP クライアントを設定：

ビルド後、ローカルにインストールしたサーバーを使用するように MCP クライアントを設定します。パスは次のとおりです。

/path/to/mcp-prompt-manager/dist/index.js

/path/to/mcp-prompt-managerを、リポジトリをクローンした実際の絶対パスに置き換えてください。

クライアントごとの詳しい設定手順については、以下の設定セクションを参照してください。

クイックスタート（開発）

開発時には、次のコマンドを使用できます。

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Start development server with Inspector
pnpm dev

# Run tests
pnpm test:run

# Lint code
pnpm lint

🛠️ 使い方

Inspector でテスト

テスト用に MCP Inspector を起動する便利なコマンドを用意しています。

基本的な使い方

重要：Inspector はコンパイル済みのdist/index.jsを実行するため、ソースコードを変更した場合は、先にコンパイルする必要があります。

# 1. Compile first (if source code was modified)
pnpm run build

# 2. Start Inspector
pnpm run inspector

クイック開発モード

開発時には、Inspector の起動前に自動でコンパイルするコマンドをまとめて実行できます。

pnpm run inspector:dev

これにより、自動的にbuildを実行してから Inspector を起動するため、コンパイル済みの最新コードをテストできます。

Inspector の機能

Inspector を起動すると、以下の操作ができるウェブインターフェースが表示されます。

• 読み込まれたすべてのプロンプトを表示する
• プロンプトの出力をテストする
• エラーメッセージを確認する
• 環境変数の設定を確認する

Cursor での使用

設定ファイルの場所

macOS：

~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json

Windows：

%APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json

Linux：

~/.config/Cursor/User/globalStorage/cursor.mcp/mcp.json

設定手順

1. 設定ファイルを見つける：

   • 方法 1：Cursor で Cmd/Ctrl + Shift + P を押し、「MCP: Add server」を検索します
   • 方法 2：上記のパスにある mcp.json ファイルを直接編集します

2. 設定ファイルを編集する：

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "/Users/yourname/Desktop/my-local-prompts",
                "MCP_LANGUAGE": "zh",
                "MCP_GROUPS": "laravel,vue"
            }
        }
    }
}

3. 重要な設定に関する注意事項：

   • command：コンパイル済みの JavaScript ファイルを実行するには node を使用します
   • args：dist/index.js を指す絶対パスを指定する必要があります
   • env：環境変数（任意。すでに .env に設定されている場合は不要です）

4. 設定を確認する：

   • Cursor を再起動します
   • Cursor で Cmd/Ctrl + Shift + P を押し、「MCP: Show servers」を検索します
   • mcp-prompt-manager が接続済みと表示されることを確認します

注記：

• /path/to/mcp-prompt-manager を、このプロジェクトの実際の絶対パスに置き換えてください
• 環境変数がすでに .env に設定されている場合は、env ブロックを省略できますが、通常は JSON に直接指定するほうが確実です
• 設定ファイルが存在しない場合は、まず mcp.json ファイルを作成する必要があります

Claude Desktop での使用

設定ファイルの場所

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

Linux：

~/.config/Claude/claude_desktop_config.json

設定手順

1. 設定ファイルを作成または編集する：

ファイルが存在しない場合は、まず作成します。

# macOS/Linux
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 設定ファイルを編集する：

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "/Users/yourname/Desktop/my-local-prompts",
                "MCP_LANGUAGE": "zh",
                "MCP_GROUPS": "laravel,vue"
            }
        }
    }
}

3. 設定を確認する：
   • Claude Desktop を完全に終了します（すべてのウィンドウが閉じていることを確認してください）
   • Claude Desktop を再起動します
   • 会話中に、Claude が定義したプロンプトを使用できることを確認します

注記：

• 設定ファイルは有効な JSON 形式である必要があります
• パスには絶対パスを指定する必要があります
• 設定ファイルを変更した後は、Claude Desktop を完全に再起動する必要があります

VS Code での使用（拡張機能経由）

VS Code では、MCP 拡張機能を通じて MCP サーバーを使用できます。

設定手順

1. MCP 拡張機能をインストールする：

   • VS Code の拡張機能マーケットプレースで「MCP」または「Model Context Protocol」を検索します
   • 該当する拡張機能をインストールします

2. MCP サーバーを設定する：

   • VS Code の設定（Cmd/Ctrl + ,）を開きます
   • 「MCP」関連の設定を検索します
   • または、settings.json を編集します。

{
    "mcp.servers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "/path/to/your/repo",
                "MCP_LANGUAGE": "zh",
                "MCP_GROUPS": "laravel,vue"
            }
        }
    }
}

Continue での使用

Continue は、MCP に対応したオープンソースの AI コードアシスタントです。

設定ファイルの場所

macOS：

~/.continue/config.json

Windows：

%APPDATA%\Continue\config.json

Linux：

~/.config/Continue/config.json

設定手順

config.json を編集します。

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "/path/to/your/repo",
                "MCP_LANGUAGE": "zh",
                "MCP_GROUPS": "laravel,vue"
            }
        }
    }
}

Aider での使用

Aider は、MCP に対応した AI コードエディターです。

設定方法

Aider の設定ファイル（通常は ~/.aider/config.json）または環境変数で設定します。

{
    "mcp_servers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "/path/to/your/repo"
            }
        }
    }
}

カスタムアプリケーションでの使用（プログラムからの利用）

独自のアプリケーションを開発していて、MCP サーバーを統合する場合は、MCP SDK を使用できます。

TypeScript/JavaScript の例

import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
import { spawn } from "child_process"

// Create MCP Client
const client = new Client(
    {
        name: "my-app",
        version: "1.0.0",
    },
    {
        capabilities: {},
    }
)

// Create transport (using stdio)
const transport = new StdioClientTransport({
    command: "node",
    args: ["/path/to/mcp-prompt-manager/dist/index.js"],
    env: {
        PROMPT_REPO_URL: "/path/to/repo",
        MCP_LANGUAGE: "en",
    },
})

// Connect
await client.connect(transport)

// List available prompts
const prompts = await client.listPrompts()
console.log("Available prompts:", prompts)

// Get specific prompt
const prompt = await client.getPrompt({
    name: "code-review",
    arguments: {
        code: "const x = 1",
        language: "TypeScript",
    },
})

Python の例

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # Configure server parameters
    server_params = StdioServerParameters(
        command="node",
        args=["/path/to/mcp-prompt-manager/dist/index.js"],
        env={
            "PROMPT_REPO_URL": "/path/to/repo",
            "MCP_LANGUAGE": "en"
        }
    )

    # Create session
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize
            await session.initialize()

            # List prompts
            prompts = await session.list_prompts()
            print(f"Available prompts: {prompts}")

            # Get prompt
            prompt = await session.get_prompt(
                name="code-review",
                arguments={
                    "code": "const x = 1",
                    "language": "TypeScript"
                }
            )
            print(f"Prompt result: {prompt}")

MCP クライアント早見表

クライアント	設定ファイルの場所	設定形式	備考
Cursor	~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json (macOS)	mcpServers	UI での設定に対応
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)	mcpServers	完全な再起動が必要です
VS Code	settings.json	mcp.servers	MCP 拡張機能が必要です
Continue	~/.continue/config.json	mcpServers	オープンソースの AI アシスタント
Aider	~/.aider/config.json	mcp_servers	AI コードエディター

注：パス内の ~ はユーザーのホームディレクトリを表し、次のように展開されます。

• macOS/Linux：/Users/username または /home/username
• Windows：C:\Users\username

共通の設定形式

すべての MCP 対応クライアントで、同じ設定形式が使用されます。

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "your-repo-url-or-path",
                "MCP_LANGUAGE": "en",
                "MCP_GROUPS": "common",
                "LOG_LEVEL": "info"
            }
        }
    }
}

📝 環境変数リファレンス

変数	必須	デフォルト	説明
PROMPT_REPO_URL	はい*	-	Git リポジトリのプライマリ URL、またはローカルパスです。（*PROMPT_REPO_URLS が設定されていない場合は必須です）
PROMPT_REPO_URLS	いいえ	-	複数のリポジトリ URL をカンマ区切りで指定します（例：url1,url2）。
SYSTEM_REPO_URL	いいえ	-	システムレベルのプロンプト（共通プロンプトなど）用の個別のリポジトリ URL です。
MCP_LANGUAGE	いいえ	en	出力言語です。選択肢：en、zh。
MCP_GROUPS	いいえ	-	読み込むプロンプトグループをカンマ区切りで指定します（例：laravel,vue）。未設定の場合、System Repo を確認するか、デフォルトの動作が適用されます。
TRANSPORT_TYPE	いいえ	stdio	通信方式です。選択肢：stdio、http、sse。
LOG_LEVEL	いいえ	info	ログの詳細度です。選択肢：debug、info、warn、error、silent。
LOG_FILE	いいえ	-	ログファイルの出力先パスです（例：logs/mcp.log）。デバッグ用に強く推奨します。
STORAGE_DIR	いいえ	.prompts_cache	クローンしたリポジトリを保存するディレクトリです。
GIT_BRANCH	いいえ	main	クローンするデフォルトの Git ブランチです。
GIT_MAX_RETRIES	いいえ	3	Git 操作が失敗した場合の再試行回数です。
GIT_POLLING_INTERVAL	いいえ	300000	WATCH_MODE=true の場合に更新を確認する間隔（ミリ秒）です。
WATCH_MODE	いいえ	false	リポジトリの変更を検知したときに自動再読み込みを有効にします。
CACHE_PROVIDER	いいえ	local	キャッシュ方式です。選択肢：local、redis。
CACHE_TTL	いいえ	-	キャッシュ項目の有効期間です（任意）。
CACHE_CLEANUP_INTERVAL	いいえ	10000	期限切れのキャッシュ項目をクリーンアップする間隔（ミリ秒）です。

セキュリティに関する注意：

1. .env ファイルはバージョン管理に決してコミットしないでください。.env.example ファイルはテンプレートとしてのみ提供されています。
2. PROMPT_REPO_URL にパスワードやトークンなどの機密情報をハードコードしないでください。
3. 安全でパスワード不要の認証には、SSH キー（[email protected]...）を使用してください。
4. 本番環境では、Docker Secrets またはお使いのプラットフォームのシークレット管理システムを使用してください。

重要な設定上の注意事項

1. 絶対パス：Cursor／Claude などのクライアントを設定する場合、dist/index.js へのパスは絶対パスで指定する必要があります。
2. JSON 形式：設定ファイルが有効な JSON であることを確認してください（末尾にカンマを付けないでください）。
3. 優先順位：クライアント設定 JSON で定義された env は、.env ファイルの設定を上書きします。
4. 再起動：設定を変更した後は、必ず AI エディター／クライアントを再起動してください。

MCP サーバーが正常に起動していることを確認する

方法 1：MCP Inspector を使用する

cd /path/to/mcp-prompt-manager

# If source code was modified, compile first
pnpm run build

# Start Inspector (or use inspector:dev for auto-compile)
pnpm run inspector
# or
pnpm run inspector:dev

ウェブインターフェースが起動し、次の操作を行えます。

• 読み込まれたすべてのプロンプトを表示する
• プロンプトの出力をテストする
• エラーメッセージを確認する

注：Inspector は dist/index.js を実行します。そのため、ソースコードを変更した後、最新の変更を反映するには先に build を実行する必要があります。

方法 2：ログを確認する

詳細なログを表示するには、設定ファイルに環境変数を追加します。

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "/path/to/repo",
                "LOG_LEVEL": "debug"
            }
        }
    }
}

次に、クライアントのログ出力を確認します（Cursor の出力パネル、または Claude Desktop のログ）。

方法 3：ファイルシステムを確認する

Git リポジトリが正常に同期されていることを確認します。

ls -la /path/to/mcp-prompt-manager/.prompts_cache

Git リポジトリからクローンされたファイルが表示されます。

よくある設定上の問題

問題 1：設定ファイルが見つからない

解決方法：

• アプリケーションが少なくとも一度起動されていることを確認します（設定ディレクトリが自動的に作成されます）
• 設定ファイルとディレクトリを手動で作成します
• パスが正しいことを確認します（大文字と小文字、スペースに注意してください）

問題 2：JSON 形式のエラー

解決方法：

• JSON 検証ツール（例：JSONLint）を使用して形式を確認します
• すべての文字列が二重引用符で囲まれていることを確認します
• 最後の項目の後にカンマがないことを確認します

問題 3：サーバーを起動できない

解決方法：

1. dist/index.js ファイルが存在することを確認します
2. パスが絶対パスであることを確認します
3. Node.js がインストールされており、バージョンが 18 以上であることを確認します
4. 環境変数が正しいか確認します
5. クライアントのエラーログを確認します

問題 4：プロンプトが見つからない

解決方法：

1. PROMPT_REPO_URL が正しいことを確認します
2. MCP_GROUPS 設定に必要なグループが含まれているか確認します
   • 注：MCP_GROUPS が設定されていない場合、システムはデフォルトで common グループのみを読み込みます
   • デフォルトのグループが使用されているか、ログメッセージを確認します
   • 他のグループを読み込むには、MCP_GROUPS=laravel,vue などを設定します
3. Git リポジトリに .yaml または .yml ファイルが含まれていることを確認します
4. 詳細なログを表示し、読み込まれたグループを確認するには、LOG_LEVEL=debug を使用します

📂 プロンプトリポジトリの構成

プロンプトリポジトリ（PROMPT_REPO_URL が指すリポジトリ）は、次の構成にしてください。

my-prompts/
├── partials/              # Store Handlebars partials (.hbs)
│   ├── role-expert.hbs
│   └── output-format.hbs
├── common/                # common group (always loaded)
│   ├── common-prompt.yaml
│   └── partials/
│       └── common-partial.hbs
├── laravel/               # laravel group (must be specified in MCP_GROUPS)
│   └── laravel-prompt.yaml
├── vue/                   # vue group (must be specified in MCP_GROUPS)
│   └── vue-prompt.yaml
├── root-prompt.yaml       # Root directory (always loaded)
└── another-prompt.yml

グループのフィルタリングルール

• ルートディレクトリ（/）：常に読み込まれます
• common グループ（common/）：常に読み込まれます
• その他のグループ：MCP_GROUPS 環境変数で指定された場合にのみ読み込まれます

デフォルトの動作

MCP_GROUPS が設定されていない場合：

• システムは common グループ（およびルートディレクトリのプロンプト）を自動的に読み込みます
• 起動ログで、デフォルトのグループを使用していることが明示的に通知されます
• より多くのグループを読み込むために MCP_GROUPS を設定するよう促すメッセージがログに含まれます

例

• MCP_GROUPS=laravel,vue → ルート、common、laravel、vue を読み込みます
• MCP_GROUPS= または未設定 → ルートと common のみを読み込みます（システムはデフォルトを使用していることを通知します）

プロンプト定義ファイルの例（.yaml）

id: "code-review"
title: "Code Review"
description: "Help me review code"
args:
    code:
        type: "string"
        description: "Code to review"
    language:
        type: "string"
        description: "Programming language"
template: |
    {{> role-expert }}

    You are a senior {{language}} engineer.
    Please review the following code:

{{ code }}

パラメーターの型

プロンプトは次の 3 種類のパラメーターに対応しています。

• string：文字列型（デフォルト）
• number：数値型
• boolean：ブール型

レジストリ機能（任意）

プロンプトの公開範囲と非推奨ステータスを一元管理するには、プロンプトリポジトリのルートディレクトリに registry.yaml ファイルを作成できます。

レジストリファイルの形式

prompts:
    - id: "code-review"
      group: "common"
      visibility: "public" # public, private, internal
      deprecated: false
    - id: "old-prompt"
      visibility: "private"
      deprecated: true

レジストリフィールドの説明

• id：プロンプト ID（必須）
• group：グループ名（任意）
• visibility：公開範囲の設定
  • public：公開（デフォルト）
  • private：非公開
  • internal：内部使用
• deprecated：非推奨かどうか（デフォルトは false）

レジストリの目的

• 一元管理：すべてのプロンプトの公開状態と非推奨状態を1つのファイルで管理します
• デフォルト設定の上書き：プロンプト定義ファイルのデフォルト設定を上書きできます
• バージョン管理：Git を通じてプロンプトのライフサイクルを追跡します

注：registry.yaml は任意です。存在しない場合、システムはプロンプト定義ファイルのデフォルト値を使用します。

プロンプトのランタイム状態

各プロンプトには、現在の利用可否を示すランタイム状態（runtime_state）があります。

• active：アクティブな状態です。プロンプトは正常に動作し、MCP ツールとして使用できます
• legacy：レガシー状態です。プロンプトは引き続き利用できますが、旧バージョンとしてマークされており、新しいバージョンの使用が推奨されます
• invalid：無効な状態です。プロンプト定義に問題（必須フィールドの不足、テンプレートのエラーなど）があり、使用できません
• disabled：無効化されています。プロンプトは明示的に無効化されています（レジストリで非推奨としてマークされている場合など）
• warning：警告状態です。プロンプトは動作しますが、警告があります（バージョンが古すぎる場合など）

プロンプトのソース

各プロンプトには、メタデータの取得元を示すソース（source）タグがあります。

• embedded：プロンプト定義ファイルに埋め込まれたメタデータ（metadata: ブロックを使用）
• registry：registry.yaml の設定
• legacy：レガシーモードです。メタデータがなく、デフォルト値を使用します

プロンプトのステータス

各プロンプトには、開発段階を示すステータス（status）があります。

• draft：ドラフトで、開発中です
• stable：安定版で、通常どおり使用できます
• deprecated：非推奨で、使用は推奨されません
• legacy：レガシーバージョンです。引き続き利用できますが、アップグレードが推奨されます

🔧 MCP ツールとリソース

このプロジェクトでは、プロンプトを管理および照会するための複数の MCP ツールとリソースを提供しています。

MCP ツール

1. mcp.reload / mcp.reload_prompts

サーバーを再起動せずに、すべてのプロンプトを再読み込みします（ホットリロード）。

• 機能：Git リポジトリから最新の変更を取得し、キャッシュをクリアして、すべての Handlebars パーシャルとプロンプトを再読み込みします
• パラメーター：なし
• 使用例：

  {
      "tool": "mcp.reload",
      "arguments": {}
  }
  

2. mcp.stats / mcp.prompt.stats

プロンプトの統計情報を取得します。

• 機能：ランタイム状態（active、legacy、invalid、disabled、warning）別の件数を含む、すべてのプロンプトの統計情報を返します
• パラメーター：なし
• 戻り値の内容：
  • total：合計件数
  • active：アクティブ状態の件数
  • legacy：レガシー状態の件数
  • invalid：無効状態の件数
  • disabled：無効化された件数
  • warning：警告状態の件数

3. mcp.list / mcp.prompt.list

複数のフィルターオプションを使って、すべてのプロンプトを一覧表示します。

• 機能：完全なメタデータ情報を含む、すべてのプロンプトランタイムを一覧表示します
• パラメーター（省略可）：
  • status：ステータスでフィルターします（draft、stable、deprecated、legacy）
  • group：グループ名でフィルターします
  • tag：タグでフィルターします（プロンプトにこのタグが含まれている必要があります）
  • runtime_state：ランタイム状態でフィルターします（active、legacy、invalid、disabled、warning）
• 使用例：

  {
      "tool": "mcp.list",
      "arguments": {
          "group": "laravel",
          "runtime_state": "active"
      }
  }
  

4. mcp.inspect

特定のプロンプトの詳細なランタイム情報を確認します。

• 機能：プロンプト ID を使って、状態、ソース、バージョン、タグ、ユースケースを含む完全なランタイムメタデータを取得します
• パラメーター：
  • id：プロンプト ID（必須）
• 使用例：

  {
      "tool": "mcp.inspect",
      "arguments": {
          "id": "code-review"
      }
  }
  

5. mcp.repo.switch

別の Prompt リポジトリに切り替えて、ダウンタイムなしで再読み込みします。

• 機能：新しい Git リポジトリに切り替え、すべてのプロンプトを再読み込みします
• パラメーター：
  • repo_url：リポジトリの URL（必須）
  • branch：ブランチ名（任意）
• 使用例：

  {
      "tool": "mcp.repo.switch",
      "arguments": {
          "repo_url": "/path/to/new/repo",
          "branch": "main"
      }
  }
  

6. preview_prompt

プロンプトテンプレートを実行せずに、指定した引数でプレビュー／レンダリングします（デバッグ用ユーティリティ）。

• 機能：指定した引数でプロンプトテンプレートをレンダリングし、LLM に送信せずに最終的なテキストを表示します。テンプレートのロジックを確認する際に使用します。
• パラメーター：
  • promptId：プロンプト ID（必須。例：'laravel:code-review'）
  • args：テンプレートの引数／変数を含む JSON オブジェクト（必須）
• 戻り値：
  • success：成功または失敗を示すブール値
  • renderedText：レンダリングされたプロンプトテキスト
  • highlightedText：変数を Markdown の太字で強調表示したレンダリング済みテキスト
  • statistics：renderedLength（文字数）と estimatedTokens（推定トークン数）を含むオブジェクト
  • warnings：スキーマ検証の警告の配列（例：推奨フィールドの不足）
• 使用例：

  {
      "tool": "preview_prompt",
      "arguments": {
          "promptId": "laravel:code-review",
          "args": {
              "code": "function test() { return true; }",
              "language": "php"
          }
      }
  }
  

• 高度な機能：
  • スキーマ検証：プロンプトの Zod スキーマに照らして引数を厳密に検証します
  • トークン推定：トークン数を推定します（英語と中国語のテキストに対応）
  • 変数の強調表示：動的に置換された変数を Markdown の太字書式で強調表示します
  • スキーマ警告：不足している必須フィールドや推奨フィールドを検出して報告します

MCP リソース

1. system://health

システムの正常性ステータスを示すリソースです。

• URI：system://health
• MIME タイプ：application/json
• 内容：以下の情報が含まれます：
  • git：Git リポジトリ情報（URL、パス、HEAD コミット）
  • prompts：プロンプトの統計情報（合計数、状態別の件数、読み込み済み件数、グループ一覧）
  • registry：レジストリのステータス（有効／無効、ソース）
  • cache：キャッシュ情報（サイズ、クリーンアップ間隔）
  • system：システム情報（稼働時間、メモリ使用量）

2. prompts://list

プロンプト一覧のリソースです。

• URI：prompts://list
• MIME タイプ：application/json
• 内容：すべてのプロンプトの完全なメタデータ一覧が含まれます：
  • id：プロンプト ID
  • title：タイトル
  • version：バージョン
  • status：ステータス
  • runtime_state：ランタイム状態
  • source：ソース
  • tags：タグの配列
  • use_cases：ユースケースの配列
  • group：グループ名
  • visibility：公開範囲

ツールの使用に関する推奨事項

• 開発時：mcp.reload を使用すると、サーバーを再起動せずにプロンプトをすばやく再読み込みできます
• デバッグ時：mcp.inspect を使用して特定のプロンプトの詳細情報を確認するか、preview_prompt を使用してテンプレートのレンダリングをテストします
• 監視時：mcp.stats と system://health リソースを使用してシステムの状態を監視します
• 検索時：フィルター条件を指定して mcp.list を使用し、特定のプロンプトを検索します
• テスト時：preview_prompt を使用してテンプレートのロジックを検証し、トークン数を確認し、実際に実行する前に変数の置換結果を確認します

💻 開発ガイド

アーキテクチャの概要

MCP Prompt Manager は、関心事を明確に分離したモジュール型アーキテクチャを採用しています。

コアコンポーネント

1. リポジトリインターフェース（src/repositories/strategy.ts）

   • さまざまな種類のリポジトリ（Git、Local）に対応する抽象インターフェースです
   • 優先順位に基づく読み込みにより、複数のリポジトリ戦略をサポートします
   • リポジトリの同期とファイル監視を処理します

2. ソースマネージャー（src/services/sourceManager.ts）

   • プロンプトのライフサイクルを管理するシングルトンパターンです
   • プロンプトの読み込み、キャッシュ、登録を処理します
   • パフォーマンス向上のため、読み込み時にHandlebarsテンプレートをコンパイルします
   • プロンプトの実行時状態とメタデータを管理します

3. キャッシュレイヤー（src/cache/）

   • ローカルとRedis（将来対応）をサポートする抽象キャッシュプロバイダーインターフェースです
   • LRUによる削除とTTLをサポートするローカルキャッシュです
   • 期限切れのキャッシュ項目を自動的にクリーンアップします

プロンプトの保存フロー

┌─────────────────────────────────────────────────────────────┐
│                    Git Repository                            │
│  (Remote URL or Local Path)                                 │
└────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Repository Strategy                            │
│  • GitRepositoryStrategy: Clone/Pull from remote           │
│  • LocalRepositoryStrategy: Watch local file system         │
└────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Local Storage (.prompts_cache)                 │
│  • Cached repository files                                   │
│  • File system cache (TTL-based)                             │
└────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Source Manager                                  │
│  1. Scan YAML files                                          │
│  2. Parse prompt definitions                                 │
│  3. Compile Handlebars templates                             │
│  4. Validate with Zod schemas                                │
│  5. Cache compiled templates                                 │
└────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              MCP Server                                      │
│  • Register prompts as MCP Tools                            │
│  • Provide MCP Resources (health, list)                      │
│  • Handle tool invocations                                   │
└────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              MCP Clients                                     │
│  (Cursor, Claude Desktop, etc.)                              │
└─────────────────────────────────────────────────────────────┘

主なモジュール

• リポジトリインターフェース：Gitおよびローカルリポジトリ向けの抽象ストラテジーパターン
• ソースマネージャー：キャッシュを備えた、プロンプトのライフサイクルを一元管理する機能
• キャッシュプロバイダー：プラグイン可能なキャッシュシステム（ローカルメモリまたはRedis）
• ローダー：プロンプトとパーシャルを読み込むための高レベルAPI
• MCP ツール：読み込まれたプロンプトに基づく動的なツール登録

プロジェクト構成

mcp-prompt-manager/
├── src/
│   ├── index.ts              # Main entry point
│   ├── config/
│   │   └── env.ts            # Environment variable configuration and validation
│   ├── services/
│   │   ├── control.ts        # MCP control tool handlers
│   │   ├── git.ts            # Git sync service
│   │   ├── health.ts         # Health status service
│   │   ├── loaders.ts        # Prompt and Partials loader
│   │   └── sourceManager.ts  # Core prompt lifecycle manager
│   ├── repositories/
│   │   ├── strategy.ts        # Repository interface
│   │   ├── gitStrategy.ts    # Git repository strategy
│   │   ├── localStrategy.ts  # Local file system strategy
│   │   └── repoManager.ts    # Repository manager
│   ├── cache/
│   │   ├── cacheProvider.ts  # Cache interface
│   │   ├── localCache.ts     # Local memory cache
│   │   └── cacheFactory.ts  # Cache factory
│   ├── types/
│   │   ├── prompt.ts         # Prompt type definitions
│   │   ├── promptMetadata.ts # Prompt metadata types
│   │   ├── promptRuntime.ts  # Prompt runtime types
│   │   └── registry.ts       # Registry type definitions
│   └── utils/
│       ├── fileSystem.ts     # File system utilities (with cache)
│       ├── logger.ts         # Logging utilities
│       ├── errorFormatter.ts # Error formatting utilities
│       └── repoConfig.ts     # Repository configuration utilities
├── test/                      # Test files
│   ├── config.test.ts
│   ├── loaders.test.ts
│   ├── sourceManager.test.ts
│   ├── cache.test.ts
│   ├── fileSystem.test.ts
│   └── integration.test.ts  # Integration tests
├── dist/                      # Compiled output
├── package.json
├── tsconfig.json
└── vitest.config.ts

よく使うコマンド

# Compile TypeScript
npm run build
# or
pnpm run build

# Start MCP Inspector for debugging
# Note: Need to run build first, or use inspector:dev for auto-compile
pnpm run build && pnpm run inspector
# or use development mode (auto-compile)
pnpm run inspector:dev

# Run tests
npm run test
# or
pnpm test

# Run tests (once)
npm run test:run
# or
pnpm test:run

# Open test UI
npm run test:ui
# or
pnpm test:ui

# Format code
npm run format
# or
pnpm format

# Check code format
npm run format:check
# or
pnpm format:check

開発ワークフロー

1. src/ ディレクトリ内のコードを変更します。
2. pnpm run build を実行して再コンパイルします（または pnpm run inspector:dev を使うと、自動コンパイルしてテストできます）。
3. pnpm run test を実行してテストします。
4. pnpm run inspector:dev を使って変更を確認します（自動コンパイルしてInspectorを起動します）。
5. CursorまたはClaude DesktopでMCPサーバーを再起動し、変更を反映します。

重要な注意事項：

• inspector コマンドは dist/index.js（コンパイル済みファイル）を実行します
• ソースコードを変更した後、最新の変更を確認するには、まず build を実行する必要があります
• inspector:dev を使うと、自動コンパイルして起動できるため、開発に適しています

プロンプトリポジトリの検証

MCP Prompt Managerにデプロイする前に、@carllee1983/prompt-toolkitを使用してプロンプトリポジトリを検証することをおすすめします。これにより、プロンプトの品質を確保し、開発プロセスの早い段階でエラーを検出できます。

インストール

# Install globally
npm install -g @carllee1983/prompt-toolkit
# or
pnpm add -g @carllee1983/prompt-toolkit

検証を含む開発ワークフロー

1. プロンプトの開発：リポジトリ内でプロンプトを作成、編集します
2. ローカルでの検証：コミット前にツールキットを使用して検証します

   prompt-toolkit validate repo
   

3. CI/CDでの検証：CI/CDパイプラインで自動的に検証します

   prompt-toolkit validate repo --exit-code --severity error
   

4. MCP Prompt Managerへのデプロイ：MCP Prompt Managerが検証済みのプロンプトを読み込みます

すぐに使える検証コマンド

# Validate entire repository
prompt-toolkit validate repo

# Validate with specific severity (show warnings and errors)
prompt-toolkit validate repo --severity warning

# Validate and exit with error code (for CI/CD)
prompt-toolkit validate repo --exit-code

# Validate single prompt file
prompt-toolkit validate file path/to/prompt.yaml

# Validate registry file
prompt-toolkit validate registry --repo-root /path/to/repo

# Validate partials directory
prompt-toolkit validate partials --partials-path partials

CI/CDとの統合

デプロイ前にエラーを検出できるよう、CI/CDパイプラインに検証を追加します。

# .github/workflows/validate-prompts.yml
name: Validate Prompts

on:
    push:
        branches: [main]
    pull_request:
        branches: [main]

jobs:
    validate:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: 20

            - name: Install prompt-toolkit
              run: npm install -g @carllee1983/prompt-toolkit

            - name: Validate repository
              run: prompt-toolkit validate repo --exit-code --severity error

ベストプラクティス

• ✅ コミット前に検証する：変更をプッシュする前に、ローカルで検証を実行します
• ✅ CI/CDを使用する：エラーを検出できるよう、CI/CDパイプラインで自動的に検証します
• ✅ 結果を監視する：リポジトリの健全性を保つため、検証結果を追跡します
• ✅ 重大度で絞り込む：--severity オプションを使って、重大な問題に絞り込みます
• ✅ JSON出力：CI/CDで機械可読な出力を得るには、--format json を使用します

プログラムからの使用

スクリプト内でプログラムからツールキットを使用することもできます。

import { validatePromptRepo } from "@carllee1983/prompt-toolkit"

const result = validatePromptRepo("/path/to/prompt-repo")

if (result.success) {
    console.log("Repository validation passed!")
} else {
    console.error("Validation errors:", result.errors)
}

詳しくは、prompt-toolkitのドキュメントを参照してください。

🧪 テスト

このプロジェクトには、包括的なテストスイートが含まれています。

• 単体テスト：すべてのコア機能を網羅する複数のテストファイル
• 統合テスト：プロンプトの読み込みとMCPツールのエンドツーエンドテスト
• 合計：107件のテストがすべて成功しています

テストを実行するには：

# Watch mode
pnpm test

# Run once
pnpm test:run

# Open UI
pnpm test:ui

テストカバレッジ

このプロジェクトでは、次のしきい値を設定し、包括的なテストカバレッジによって高いコード品質を維持しています。

• ステートメント：≥ 80%
• 行：≥ 75%
• 関数：≥ 75%
• 分岐：≥ 70%

注：カバレッジレポートでは @vitest/coverage-v8 を使用しており、Node.js 19 以上が必要です。コード品質を維持するため、カバレッジのしきい値を適用しています。カバレッジがしきい値を下回ると、品質基準を満たすようテストが失敗します。

カバレッジレポートの表示

1. ローカル開発：pnpm test:coverage を実行してカバレッジレポートを生成するか、pnpm test:coverage:view を実行してブラウザーで HTML カバレッジレポートを自動的に開きます。

2. CI/CD：pnpm test:coverage:ci を実行してカバレッジレポートを生成し、しきい値を適用します。CI パイプラインは、カバレッジのしきい値が満たされない場合に失敗し、マージやリリースの前にコード品質基準が維持されるようにします。

3. カバレッジレポート：カバレッジレポートは coverage/ ディレクトリに複数の形式で生成されます。

   • coverage/index.html - インタラクティブな HTML レポート
   • coverage/coverage-final.json - CI 統合用の JSON 形式
   • coverage/lcov.info - カバレッジサービス用の LCOV 形式

カバレッジコマンド

# Generate coverage report (local development)
pnpm test:coverage

# Generate coverage report with threshold enforcement (CI)
pnpm test:coverage:ci

# Generate coverage report and open HTML report
pnpm test:coverage:view

コード品質と CI/CD

このプロジェクトでは、複数のチェックを通じてコード品質を確保しています。

コミット前フック

コミット前フックは、Husky と lint-staged を使用して、各コミットの前にリンティングとフォーマットを自動的に実行します。

• ESLint：TypeScript ファイルのリンティングの問題を自動的に修正します
• Prettier：コードを自動的にフォーマットし、一貫したスタイルを保ちます
• 型安全性：TypeScript の strict モードが有効になっています（tsconfig.json の strict: true）

コミット前フックはステージング済みのファイルのみを対象とするため、コード品質を維持しながらコミット時間を短縮できます。

継続的インテグレーション（CI）

GitHub Actions の CI ワークフローは、プッシュとプルリクエストのたびに実行されます。

• Node.js の互換性：Node.js 16.x、18.x、20.x でテストします
• リンティング：ESLint でコード品質とスタイルをチェックします
• 型チェック：TypeScript の型チェック（tsc --noEmit）
• テスト：カバレッジレポートを含む全テストスイート
• カバレッジのアップロード：Codecov に自動アップロードします

プルリクエストに必須のチェック

コード品質を確保するため、PR をマージする前に次のチェックに合格する必要があります。

1. Lint：すべての ESLint ルールに合格すること
2. 型チェック：エラーなしで TypeScript のコンパイルが成功すること
3. テスト：カバレッジのしきい値を満たしたうえで、すべてのテストに合格すること

GitHub で必須チェックを設定する方法：

1. リポジトリの設定に移動します
2. Branches → Branch protection rules に移動します
3. メインブランチのルールを追加または編集します
4. Require status checks to pass before merging で、次の項目を有効にします。
   • Test (Node.js 16.x)、Test (Node.js 18.x)、または Test (Node.js 20.x)（少なくとも 1 つ）
   • これらのチェックには、リンティング、型チェック、テストの各ステップが自動的に含まれます

これらのチェックのいずれかに失敗すると、CI ワークフローも自動的に失敗し、品質基準を満たさないコードのマージを防ぎます。

🔧 設定

環境変数

変数名	必須	デフォルト値	説明
PROMPT_REPO_URL	✅	-	Git リポジトリの URL またはローカルパス
MCP_LANGUAGE	❌	en	出力言語（en または zh）
MCP_GROUPS	❌	common	読み込むグループ（カンマ区切り）。未設定の場合、システムがデフォルトの動作について確認します
STORAGE_DIR	❌	.prompts_cache	ローカルキャッシュディレクトリ
GIT_BRANCH	❌	main	Git ブランチ名
GIT_MAX_RETRIES	❌	3	Git 操作の最大再試行回数
CACHE_CLEANUP_INTERVAL	❌	10000	キャッシュクリーンアップ間隔（ミリ秒）。期限切れのキャッシュ項目を定期的にクリーンアップします
LOG_LEVEL	❌	warn (prod) / info (dev)	ログレベル。本番環境のデフォルトでは警告とエラーのみを出力します

キャッシュの有効期限戦略

システムは TTL ベースの定期クリーンアップ機構を使用してファイル一覧キャッシュを管理し、メモリ効率を確保します。

キャッシュ機構

• キャッシュ TTL：5 秒（ハードコード）
• クリーンアップ間隔：デフォルトは 10 秒（CACHE_TTL * 2）。CACHE_CLEANUP_INTERVAL 環境変数で調整できます
• 自動クリーンアップ：アプリケーションの起動時にクリーンアップ機構が自動的に開始します
• 正常なシャットダウン：アプリケーションの終了時にクリーンアップタイマーが自動的に停止します

動作の仕組み

1. キャッシュの作成：getFilesRecursively() が呼び出されると、スキャン結果は 5 秒間キャッシュされます
2. 定期クリーンアップ：10 秒ごと（または設定した間隔ごと）に期限切れのキャッシュ項目を自動的にスキャンして削除します
3. メモリ管理：キャッシュの無制限な増加を防ぎ、メモリリークを回避します

設定例

# Set shorter cleanup interval (for testing)
CACHE_CLEANUP_INTERVAL=2000  # Cleanup every 2 seconds

# Set longer cleanup interval (for production, reduce cleanup frequency)
CACHE_CLEANUP_INTERVAL=30000  # Cleanup every 30 seconds

キャッシュの状態を監視する

ログからキャッシュのクリーンアップ状態を確認できます（LOG_LEVEL=debug の設定が必要です）。

[DEBUG] Cache cleanup mechanism started { interval: 10000 }
[DEBUG] Cache cleanup completed { cleaned: 2 }

キャッシュ機構を検証する

検証方法とテストガイドの詳細については、CACHE_VERIFICATION.md を参照してください。

セキュリティ

• ✅ 入力検証：すべての環境変数を Zod で検証します
• ✅ パスのセキュリティ：パストラバーサル攻撃を防止します
• ✅ グループ検証：グループ名の形式を検証します（英字、数字、アンダースコア、ハイフンのみ使用できます）

📝 ロギング

このプロジェクトでは、構造化ロギングに対応したロギングシステムとして pino を使用しています。

ログレベル

• fatal：プログラムの終了を引き起こす致命的なエラー
• error：エラーメッセージ
• warn：警告メッセージ
• info：一般情報
• debug：デバッグメッセージ
• trace：トレースメッセージ
• silent：ログ出力を完全に無効化します

デフォルトの動作：

• 本番環境（NODE_ENV が未設定、または development 以外）：デフォルトは warn で、警告とエラーのみを出力します
• 開発環境（NODE_ENV=development）：デフォルトは info で、info レベル以上のログを出力します
• LOG_LEVEL 環境変数でデフォルト値を上書きできます

ログレベルの設定

# Set in .env
LOG_LEVEL=debug

# Or set in environment variables
export LOG_LEVEL=debug

❓ FAQ とトラブルシューティング

Q: MCP Prompt Manager はどのようにインストールしますか？

A: インストール方法は 3 つあります。

1. マーケットプレイスからインストール（最も簡単）：mcp.so などの MCP マーケットプレイスからインストールします
2. Docker でデプロイ（本番環境におすすめ）：Docker Compose を使用して簡単にデプロイします
3. ローカルにインストール（開発向け）：リポジトリをクローンし、ローカルでビルドします

詳しい手順については、クイックスタートセクションをご覧ください。

Q: マーケットプレイスからインストールした後、インストール先のパスを確認するにはどうすればよいですか？

A: 次のコマンドを使用して、インストールされたサーバーの場所を確認します。

macOS/Linux：

find ~ -name "index.js" -path "*/mcp-prompt-manager/dist/index.js" 2>/dev/null

Windows：

Get-ChildItem -Path $env:USERPROFILE -Filter "index.js" -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.FullName -like "*mcp-prompt-manager\dist\index.js" }

Q: 設定で絶対パスを使う必要があるのはなぜですか？

A: MCP クライアントはサーバーを別プロセスとして実行するため、実行可能ファイルの場所を特定するには完全なパスが必要です。作業ディレクトリが異なる場合があるため、相対パスは機能しません。

Q: 設定後、MCP クライアントにサーバーが表示されません。

A: 次の手順をお試しください。

1. パスが絶対パスであることを確認する：args に相対パスではなく、完全な絶対パスが指定されていることを確認します
2. Node.js がインストールされていることを確認する：node --version を実行し、Node.js 18 以降がインストールされていることを確認します
3. ファイルが存在することを確認する：指定したパスに dist/index.js が存在することを確認します
4. JSON の構文を確認する：設定ファイルが有効な JSON であること（末尾に余分なカンマがないこと）を検証します
5. 完全に再起動する：MCP クライアントを完全に終了してから再起動します（再読み込みだけではありません）
6. ログを確認する：設定で LOG_LEVEL=debug を有効にし、詳細なエラーメッセージを確認します

Q: サーバーをローカルで実行するにはどうすればよいですか？

A: 開発時は pnpm dev（インスペクター付き）、本番モードでは pnpm start を使用できます。詳しくは package.json のスクリプトをご覧ください。

Q: Git クローンエラー（終了コード 128）が発生します。

A: 通常は、権限の問題または無効な URL が原因です。

1. SSH と HTTPS：SSH（[email protected]...）を使用する場合は、SSH キーが正しくマウントされているか、利用可能であることを確認します。HTTPS を使用する場合は、トークンが不要であることを確認するか、トークンを指定します。
2. 既知のホスト：Docker で実行する場合は、ssh-keyscan を実行済みであること、または known_hosts ファイルがマウントされていることを確認します。
3. リポジトリの有効性：お使いのマシンで git clone <URL> を手動で実行し、URL が正しいことを確認します。

問題：Git の同期に失敗する（一般）

解決方法：

1. PROMPT_REPO_URL が正しいか確認します
2. ネットワーク接続が正常であることを確認します
3. Git の認証情報が正しいか確認します
4. 詳細なエラーメッセージをログで確認します

問題：プロンプトが読み込まれない

解決方法：

1. MCP_GROUPS の設定が正しいか確認します
2. プロンプトファイルが正しいディレクトリ構成（prompts/<group>/...）にあることを確認します
3. YAML ファイルの形式が正しいか確認します
4. ログのエラーメッセージを確認します

問題：パーシャルを使用できない

解決方法：

1. パーシャルファイルの拡張子が .hbs であることを確認します
2. パーシャルが partials/ ディレクトリにあることを確認します
3. パーシャルファイルの内容が正しいか確認します
4. テンプレートで {{> partial-name }} 構文を使用していることを確認します

📦 主な依存関係

• @modelcontextprotocol/sdk：MCP SDK。MCP サーバーのコア機能を提供します
• handlebars：Handlebars テンプレートエンジン。動的なプロンプト生成をサポートします
• simple-git：Git リポジトリの同期に使用する Git 操作ライブラリ
• js-yaml：プロンプト定義ファイルを解析する YAML パーサー
• zod：設定と型の検証に使用する、TypeScript を第一に考えたスキーマ検証ライブラリ
• pino：高性能な構造化ログライブラリ
• dotenv：環境変数の読み込みユーティリティ

📚 関連リソース

• Model Context Protocol 公式ドキュメント
• Handlebars ドキュメント
• Zod ドキュメント
• Simple Git ドキュメント
• Pino ドキュメント
• @carllee1983/prompt-toolkit - MCP 用プロンプトリポジトリ検証ツールキット

📄 ライセンス

ISC

🤝 コントリビューション

Issue と Pull Request の投稿を歓迎します！

---

バージョン：1.0.0
最終更新日：2024-11-30