MCP Prompt Manager (Git-Driven)

Git-driven Model Context Protocol (MCP) Server for managing and providing Prompt templates

📋 Introduction

This is a Git-driven Model Context Protocol (MCP) Server designed for managing and providing Prompt templates. It allows you to store Prompts in a separate Git Repository and use them directly in AI editors like Cursor, Claude Desktop, etc., through the MCP protocol.

Key Benefits:

🔄 Team Collaboration: Ensure unified Prompt versions across teams through Git version control
🎯 Dynamic Templates: Support Handlebars syntax to create reusable dynamic Prompts
🚀 Zero-Downtime Reload: Hot-reload support to update Prompts without restarting
🔍 Smart Management: Built-in Prompt version management, state tracking, and group filtering
📊 Complete Monitoring: System health status and Prompt statistics

✨ Features

Git Sync: Prompts are synced directly from the specified Git Repository, ensuring teams use unified Prompt versions.
Handlebars Templates: Support powerful Handlebars syntax to create dynamic, reusable Prompt templates.
Partials Support: Support Handlebars Partials for splitting and reusing Prompt fragments (e.g., role settings, output formats).
Local Cache: Automatically cache Git Repo content to local .prompts_cache directory for faster reads.
Cache Expiration Strategy: Automatically clean up expired cache items periodically to prevent memory leaks and ensure data consistency.
Group Filtering: Support filtering prompts by group, loading only what you need.
Error Handling: Complete error statistics and reporting for issue tracking.
Retry Mechanism: Automatic retry for Git operations to improve reliability.
Type Safety: Use Zod to validate configuration and prompt definitions for type safety.
Professional Logging: Use pino logging system with structured logs and multiple log levels.

🚀 Quick Start

Option 1: Marketplace Installation (Easiest)

If you're installing from an MCP marketplace (e.g., mcp.so), follow the marketplace's installation instructions. Typically, you'll need to:

Install via marketplace: Use the marketplace's installation interface
Configure your MCP client: Add the server configuration to your MCP client

Prerequisites

Before installing, ensure you have:

Node.js installed (version 18.0.0 or higher)
pnpm package manager (version 8.0.0 or higher)
A Git repository containing your prompts (or a local path to prompts)
An MCP-compatible client (Cursor, Claude Desktop, VS Code, etc.)

Installation Steps

Install from Marketplace:
- Visit your preferred MCP marketplace
- Search for "mcp-prompt-manager"
- Follow the marketplace's installation instructions
- Note the installation path where the server was installed
Locate Installation Path:
- After marketplace installation, find where dist/index.js is located
- This is typically in a global node_modules directory or a dedicated installation folder
- You'll need the absolute path to this file for configuration
Configure MCP Client:
- Open your MCP client's configuration file (see Configuration section for file locations)
- Add the server configuration (see example below)
- Important: Use absolute paths, not relative paths

Configuration Example

After installation, configure your MCP client (Cursor, Claude Desktop, etc.) with the following:

For 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"
            }
        }
    }
}

Note: Replace /absolute/path/to/mcp-prompt-manager/dist/index.js with the actual absolute path where the marketplace installed the server.

Tip: See mcp.json.example for a complete configuration template.

Finding the Installation Path

If you're unsure where the marketplace installed the server:

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" }

Verification

After configuration:

Restart your MCP client completely
Check server status:
- In Cursor: Press Cmd/Ctrl + Shift + P, search for "MCP: Show servers"
- In Claude Desktop: Check the MCP servers list in settings
Verify prompts are loaded: Use the client's MCP tools to list available prompts

For detailed configuration instructions for different MCP clients, see the Configuration section below.

Option 2: Docker Deployment (Recommended)

The easiest way to get started is using 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

For detailed Docker deployment instructions, see DOCKER.md.

Option 3: Local Installation

This option is recommended for development or when you want full control over the installation.

Prerequisites

Node.js 18.0.0 or higher
pnpm 8.0.0 or higher (required, npm/yarn will fail)
Git (for cloning the repository)

Installation Steps

Clone the Repository:

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

Install Dependencies:

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

Note: Installs are enforced with pnpm; npm/yarn will fail because of the preinstall check.

Build the Project:

pnpm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Configure Environment Variables:

Copy the example configuration file and create .env:

cp .env.example .env

Edit the .env file to set your Prompt Git Repository path or 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
# PROMPT_REPO_URL=git@github.com: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

Configure MCP Client:

After building, you need to configure your MCP client to use the locally installed server. The path will be:

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

Replace /path/to/mcp-prompt-manager with the actual absolute path where you cloned the repository.

See the Configuration section below for detailed client-specific configuration instructions.

Quick Start (Development)

For development purposes, you can use these commands:

# 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

🛠️ Usage

Testing with Inspector

We provide a convenient command to start the MCP Inspector for testing:

Basic Usage

Important: Inspector runs the compiled dist/index.js, so if you've modified the source code, you need to compile first:

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

# 2. Start Inspector
pnpm run inspector

Quick Development Mode

If you're developing, you can use a combined command that automatically compiles before starting Inspector:

pnpm run inspector:dev

This automatically runs build and then starts Inspector, ensuring you're testing the latest compiled code.

Inspector Features

Inspector launches a web interface where you can:

View all loaded prompts
Test prompt output
Check error messages
Verify environment variable settings

Using in Cursor

Configuration File Location

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

Configuration Steps

Find the configuration file:
- Method 1: In Cursor, press Cmd/Ctrl + Shift + P, search for "MCP: Add server"
- Method 2: Directly edit the mcp.json file at the path above
Edit the configuration file:

{
    "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"
            }
        }
    }
}

Important Configuration Notes:
- command: Use node to execute the compiled JavaScript file
- args: Must be an absolute path pointing to dist/index.js
- env: Environment variables (optional, if already set in .env)
Verify Configuration:
- Restart Cursor
- In Cursor, press Cmd/Ctrl + Shift + P, search for "MCP: Show servers"
- Confirm that mcp-prompt-manager shows as connected

Note:

Replace /path/to/mcp-prompt-manager with the actual absolute path of this project

If environment variables are already set in .env, the env block can be omitted, but specifying directly in JSON is usually more robust

If the configuration file doesn't exist, you need to create the mcp.json file first

Using in Claude Desktop

Configuration File Location

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Configuration Steps

Create or edit the configuration file:

If the file doesn't exist, create it first:

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

Edit the configuration file:

{
    "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"
            }
        }
    }
}

Verify Configuration:
- Completely close Claude Desktop (ensure all windows are closed)
- Restart Claude Desktop
- In conversations, Claude should be able to use your defined prompts

Note:

Configuration file must be valid JSON format

Paths must use absolute paths

After modifying the configuration file, you must completely restart Claude Desktop

Using in VS Code (via Extension)

VS Code can use MCP Server through MCP extensions.

Configuration Steps

Install MCP Extension:
- Search for "MCP" or "Model Context Protocol" in VS Code Extension Marketplace
- Install the corresponding extension
Configure MCP Server:
- Open VS Code settings (Cmd/Ctrl + ,)
- Search for "MCP" related settings
- Or edit 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"
            }
        }
    }
}

Using in Continue

Continue is an open-source AI code assistant that supports MCP.

Configuration File Location

macOS:

~/.continue/config.json

Windows:

%APPDATA%\Continue\config.json

Linux:

~/.config/Continue/config.json

Configuration Steps

Edit 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"
            }
        }
    }
}

Using in Aider

Aider is an AI code editor that supports MCP.

Configuration Method

In Aider's configuration file (usually ~/.aider/config.json or via environment variables):

{
    "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"
            }
        }
    }
}

Using in Custom Applications (Programmatic)

If you're developing your own application and want to integrate the MCP Server, you can use the MCP SDK:

TypeScript/JavaScript Example

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 Example

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 Client Quick Reference

Client	Configuration File Location	Config Format	Notes
Cursor	`~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json` (macOS)	`mcpServers`	Supports UI config
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)	`mcpServers`	Requires full restart
VS Code	`settings.json`	`mcp.servers`	Requires MCP extension
Continue	`~/.continue/config.json`	`mcpServers`	Open-source AI assistant
Aider	`~/.aider/config.json`	`mcp_servers`	AI code editor

Note: The ~ in paths represents the user home directory, which expands to:

macOS/Linux: /Users/username or /home/username

Windows: C:\Users\username

Universal Configuration Format

All MCP-compatible clients follow the same configuration format:

{
    "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"
            }
        }
    }
}

📝 Environment Variables Reference

Variable	Required	Default	Description
`PROMPT_REPO_URL`	Yes*	-	Primary Git repository URL or local path. (*Required if `PROMPT_REPO_URLS` is not set)
`PROMPT_REPO_URLS`	No	-	Comma-separated list of multiple repository URLs (e.g. `url1,url2`).
`SYSTEM_REPO_URL`	No	-	Separate repository URL for system-level prompts (e.g. common prompts).
`MCP_LANGUAGE`	No	`en`	Output language. Options: `en`, `zh`.
`MCP_GROUPS`	No	-	Comma-separated list of prompt groups to load (e.g. `laravel,vue`). If unset, checks System Repo or default behaviors.
`TRANSPORT_TYPE`	No	`stdio`	Communication method. Options: `stdio`, `http`, `sse`.
`LOG_LEVEL`	No	`info`	Logging verbosity. Options: `debug`, `info`, `warn`, `error`, `silent`.
`LOG_FILE`	No	-	Path to write log file (e.g. `logs/mcp.log`). Highly recommended for debugging.
`STORAGE_DIR`	No	`.prompts_cache`	directory to store cloned repositories.
`GIT_BRANCH`	No	`main`	Default Git branch to clone.
`GIT_MAX_RETRIES`	No	`3`	Number of retries for failed Git operations.
`GIT_POLLING_INTERVAL`	No	`300000`	Interval (ms) to check for updates when `WATCH_MODE=true`.
`WATCH_MODE`	No	`false`	Enable auto-reloading when changes are detected in the repository.
`CACHE_PROVIDER`	No	`local`	Caching mechanism. Options: `local`, `redis`.
`CACHE_TTL`	No	-	Time-to-live for cache items (optional).
`CACHE_CLEANUP_INTERVAL`	No	`10000`	Interval (ms) to clean up expired cache items.

Security Note:

Never commit .env files to version control. The .env.example file is provided as a template only.

Avoid hardcoding sensitive credentials (passwords, tokens) in PROMPT_REPO_URL.

Use SSH keys (git@github.com...) for secure, password-less authentication.

For production, use Docker Secrets or your platform's secret management system.

Important Configuration Notes

Absolute Paths: When configuring clients like Cursor/Claude, paths to dist/index.js must be absolute.
JSON Format: Ensure your config file is valid JSON (no trailing commas).
Precedence: env defined in client config JSON overrides .env files.
Restart: Always restart your AI editor/client after changing configuration.

Verifying MCP Server is Running Properly

Method 1: Using 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

This launches a web interface where you can:

View all loaded prompts
Test prompt output
Check error messages

Note: Inspector runs dist/index.js, so after modifying source code, you must run build first to see the latest changes.

Method 2: Check Logs

Add environment variables in the configuration file to view detailed logs:

{
    "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"
            }
        }
    }
}

Then check the client's log output (Cursor's output panel or Claude Desktop's logs).

Method 3: Check File System

Verify Git repository has been synced successfully:

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

You should see files cloned from the Git repository.

Common Configuration Issues

Issue 1: Configuration File Not Found

Solution:

Confirm the application has been started at least once (will automatically create configuration directory)
Manually create the configuration file and directory
Check if the path is correct (note case sensitivity and spaces)

Issue 2: JSON Format Error

Solution:

Use JSON validation tools to check format (e.g., JSONLint)
Ensure all strings use double quotes
Ensure no comma after the last item

Issue 3: Server Cannot Start

Solution:

Confirm dist/index.js file exists
Confirm path is absolute
Confirm Node.js is installed and version >= 18
Check if environment variables are correct
Check client error logs

Issue 4: No Prompts Found

Solution:

Confirm PROMPT_REPO_URL is correct
Check if MCP_GROUPS setting includes the groups you want
- Note: If MCP_GROUPS is not set, the system defaults to loading only the common group
- Check log messages to confirm if default groups are being used
- Set MCP_GROUPS=laravel,vue etc. to load other groups
Confirm Git repository contains .yaml or .yml files
Use LOG_LEVEL=debug to view detailed logs and confirm which groups are loaded

📂 Prompt Repository Structure

Your Prompt Repository (where PROMPT_REPO_URL points to) should have the following structure:

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

Group Filtering Rules

Root directory (/): Always loaded
common group (common/): Always loaded
Other groups: Only loaded when specified in MCP_GROUPS environment variable

Default Behavior

When MCP_GROUPS is not set:

System automatically loads the common group (and root directory prompts)
Startup logs will explicitly prompt about using default groups
Logs will include messages suggesting to set MCP_GROUPS to load more groups

Examples

MCP_GROUPS=laravel,vue → Load root, common, laravel, vue
MCP_GROUPS= or not set → Only load root and common (system will prompt about using default)

Prompt Definition File Example (`.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:

Parameter Types

Prompts support three parameter types:

string: String type (default)
number: Number type
boolean: Boolean type

Registry Feature (Optional)

You can create a registry.yaml file in the root directory of your Prompt Repository to centrally manage prompt visibility and deprecation status.

Registry File Format

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

Registry Field Descriptions

id: Prompt ID (required)
group: Group name (optional)
visibility: Visibility setting
- public: Public (default)
- private: Private
- internal: Internal use
deprecated: Whether deprecated (default false)

Registry Purpose

Centralized Management: Manage all prompts' visibility and deprecation status in a single file
Override Defaults: Can override default settings in prompt definition files
Version Control: Track prompt lifecycle through Git

Note: registry.yaml is optional. If it doesn't exist, the system will use default values from prompt definition files.

Prompt Runtime State

Each prompt has a runtime state (runtime_state) indicating the prompt's current availability:

active: Active state, prompt works normally and can be used as an MCP Tool
legacy: Legacy state, prompt is still available but marked as old version, recommend using new version
invalid: Invalid state, prompt definition has issues (e.g., missing required fields, template errors, etc.), cannot be used
disabled: Disabled, prompt is explicitly disabled (e.g., marked as deprecated in registry)
warning: Warning state, prompt can work but has some warnings (e.g., version too old)

Prompt Source

Each prompt has a source (source) tag indicating where the metadata comes from:

embedded: Metadata embedded in prompt definition file (using metadata: block)
registry: Settings from registry.yaml
legacy: Legacy mode, no metadata, uses default values

Prompt Status

Each prompt has a status (status) indicating the prompt's development stage:

draft: Draft, under development
stable: Stable version, can be used normally
deprecated: Deprecated, not recommended for use
legacy: Legacy version, still available but recommend upgrading

🔧 MCP Tools and Resources

This project provides multiple MCP tools and resources for managing and querying Prompts.

MCP Tools

1. `mcp.reload` / `mcp.reload_prompts`

Reload all Prompts without restarting the server (hot-reload).

Function: Pull latest changes from Git repository, clear cache, reload all Handlebars partials and prompts
Parameters: None

Usage Example:

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

2. `mcp.stats` / `mcp.prompt.stats`

Get Prompts statistics.

Function: Returns statistics for all prompts, including counts by runtime state (active, legacy, invalid, disabled, warning)
Parameters: None
Return Content:
- total: Total count
- active: Active state count
- legacy: Legacy state count
- invalid: Invalid state count
- disabled: Disabled count
- warning: Warning state count

3. `mcp.list` / `mcp.prompt.list`

List all Prompts with multiple filter options.

Function: Lists all prompt runtimes with complete metadata information
Parameters (optional):
- status: Filter by status (draft, stable, deprecated, legacy)
- group: Filter by group name
- tag: Filter by tag (prompts must contain this tag)
- runtime_state: Filter by runtime state (active, legacy, invalid, disabled, warning)

Usage Example:

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

4. `mcp.inspect`

Inspect detailed runtime information for a specific Prompt.

Function: Get complete runtime metadata by Prompt ID, including state, source, version, tags, and use cases
Parameters:
- id: Prompt ID (required)

Usage Example:

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

5. `mcp.repo.switch`

Switch to a different Prompt repository and reload (zero-downtime).

Function: Switch to a new Git repository and reload all prompts
Parameters:
- repo_url: Repository URL (required)
- branch: Branch name (optional)

Usage Example:

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

6. `preview_prompt`

Preview/render a prompt template with given arguments without executing it (debug utility).

Function: Renders a prompt template with given arguments to show the final text without sending it to an LLM. Use this to verify template logic.
Parameters:
- promptId: Prompt ID (required, e.g., 'laravel:code-review')
- args: JSON object containing the arguments/variables for the template (required)
Returns:
- success: Boolean indicating success or failure
- renderedText: The rendered prompt text
- highlightedText: The rendered text with variables highlighted in Markdown bold
- statistics: Object containing renderedLength (character count) and estimatedTokens (estimated token count)
- warnings: Array of schema validation warnings (e.g., missing recommended fields)

Usage Example:

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

Advanced Features:
- Schema Validation: Strict validation of arguments against prompt's Zod schema
- Token Estimation: Estimates token count (supports both English and Chinese text)
- Variable Highlighting: Highlights dynamically replaced variables with Markdown bold formatting
- Schema Warnings: Detects and reports missing required or recommended fields

MCP Resources

1. `system://health`

System health status resource.

URI: system://health
MIME Type: application/json
Content: Includes the following information:
- git: Git repository information (URL, path, HEAD commit)
- prompts: Prompts statistics (total, counts by state, loaded count, group list)
- registry: Registry status (enabled, source)
- cache: Cache information (size, cleanup interval)
- system: System information (uptime, memory usage)

2. `prompts://list`

Prompts list resource.

URI: prompts://list
MIME Type: application/json
Content: Complete metadata list of all prompts, including:
- id: Prompt ID
- title: Title
- version: Version
- status: Status
- runtime_state: Runtime state
- source: Source
- tags: Tags array
- use_cases: Use cases array
- group: Group name
- visibility: Visibility

Tool Usage Recommendations

During Development: Use mcp.reload to quickly reload prompts without restarting the server
During Debugging: Use mcp.inspect to check detailed information for specific prompts, or use preview_prompt to test template rendering
During Monitoring: Use mcp.stats and system://health resource to monitor system status
During Querying: Use mcp.list with filter conditions to find specific prompts
During Testing: Use preview_prompt to verify template logic, check token counts, and see variable replacements before actual execution

💻 Development Guide

Architecture Overview

The MCP Prompt Manager follows a modular architecture with clear separation of concerns:

Core Components

Repository Interface (src/repositories/strategy.ts)
- Abstract interface for different repository types (Git, Local)
- Supports multiple repository strategies with priority-based loading
- Handles repository synchronization and file watching
Source Manager (src/services/sourceManager.ts)
- Singleton pattern for managing prompt lifecycle
- Handles prompt loading, caching, and registration
- Compiles Handlebars templates at load time for performance
- Manages prompt runtime states and metadata
Cache Layer (src/cache/)
- Abstract cache provider interface supporting local and Redis (future)
- Local cache with LRU eviction and TTL support
- Automatic cleanup of expired cache items

Prompt Storage Flow

┌─────────────────────────────────────────────────────────────┐
│                    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.)                              │
└─────────────────────────────────────────────────────────────┘

Key Modules

Repository Interface: Abstract strategy pattern for Git and local repositories
Source Manager: Centralized prompt lifecycle management with caching
Cache Provider: Pluggable cache system (local memory or Redis)
Loaders: High-level API for loading prompts and partials
MCP Tools: Dynamic tool registration based on loaded prompts

Project Structure

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

Common Commands

# 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

Development Workflow

Modify code in the src/ directory.
Run pnpm run build to recompile (or use pnpm run inspector:dev to auto-compile and test).
Run pnpm run test to run tests.
Use pnpm run inspector:dev to verify changes (will auto-compile and start Inspector).
Restart MCP Server in Cursor or Claude Desktop to apply changes.

Important Notes:

The inspector command runs dist/index.js (compiled file)

After modifying source code, you must run build first to see the latest changes

Using inspector:dev can auto-compile and start, suitable for development

Prompt Repository Validation

We recommend using @carllee1983/prompt-toolkit to validate your prompt repository before deploying to MCP Prompt Manager. This ensures prompt quality and catches errors early in the development process.

Installation

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

Development Workflow with Validation

Develop Prompts: Create and edit prompts in your repository
Validate Locally: Use the toolkit to validate before committing
```
prompt-toolkit validate repo
```

CI/CD Validation: Automatically validate in CI/CD pipelines

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

Deploy to MCP Prompt Manager: MCP Prompt Manager loads validated prompts

Quick Validation Commands

# 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 Integration

Add validation to your CI/CD pipeline to catch errors before deployment:

# .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

Best Practices

✅ Validate before committing: Run validation locally before pushing changes
✅ Use CI/CD: Automatically validate in CI/CD pipelines to catch errors
✅ Monitor results: Track validation results to maintain repository health
✅ Severity filtering: Use --severity option to focus on critical issues
✅ JSON output: Use --format json for machine-readable output in CI/CD

Programmatic Usage

You can also use the toolkit programmatically in your scripts:

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)
}

For more information, see the prompt-toolkit documentation.

🧪 Testing

The project includes a complete test suite:

Unit Tests: Multiple test files covering all core functionality
Integration Tests: End-to-end testing for prompt loading and MCP tools
Total: 107 tests, all passing

Run tests:

# Watch mode
pnpm test

# Run once
pnpm test:run

# Open UI
pnpm test:ui

Test Coverage

This project maintains high code quality through comprehensive test coverage with the following thresholds:

Statements: ≥ 80%
Lines: ≥ 75%
Functions: ≥ 75%
Branches: ≥ 70%

Note: Coverage reports use @vitest/coverage-v8 which requires Node.js 19+. Coverage thresholds are enforced to maintain code quality. If coverage falls below thresholds, tests will fail to ensure quality standards.

Viewing Coverage Reports

Local Development: Run pnpm test:coverage to generate coverage reports, or use pnpm test:coverage:view to automatically open the HTML coverage report in your browser.
CI/CD: Run pnpm test:coverage:ci to generate coverage reports and enforce thresholds. The CI pipeline will fail if coverage thresholds are not met, ensuring code quality standards are maintained before merging or releasing.
Coverage Reports: Coverage reports are generated in the coverage/ directory with multiple formats:
- coverage/index.html - Interactive HTML report
- coverage/coverage-final.json - JSON format for CI integration
- coverage/lcov.info - LCOV format for coverage services

Coverage Commands

# 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

Code Quality and CI/CD

This project enforces code quality through multiple layers of checks:

Pre-commit Hooks

Pre-commit hooks automatically run linting and formatting before each commit using Husky and lint-staged:

ESLint: Automatically fixes linting issues in TypeScript files
Prettier: Automatically formats code to ensure consistent style
Type Safety: TypeScript strict mode is enabled (strict: true in tsconfig.json)

The pre-commit hook runs on staged files only, ensuring fast commit times while maintaining code quality.

Continuous Integration (CI)

GitHub Actions CI workflow runs on every push and pull request:

Node.js Compatibility: Tests across Node.js 16.x, 18.x, and 20.x
Linting: ESLint checks for code quality and style
Type Checking: TypeScript type checking (tsc --noEmit)
Testing: Full test suite with coverage reporting
Coverage Upload: Automatic upload to Codecov

Required Checks for Pull Requests

To ensure code quality, the following checks must pass before a PR can be merged:

Lint: All ESLint rules must pass
Typecheck: TypeScript compilation must succeed with no errors
Tests: All tests must pass with coverage thresholds met

Setting up Required Checks in GitHub:

Go to your repository settings
Navigate to Branches → Branch protection rules
Add or edit a rule for your main branch
Under Require status checks to pass before merging, enable:
- Test (Node.js 16.x) or Test (Node.js 18.x) or Test (Node.js 20.x) (at least one)
- These checks will automatically include lint, typecheck, and test steps

The CI workflow will automatically fail if any of these checks fail, preventing merging of code that doesn't meet quality standards.

🔧 Configuration

Environment Variables

Variable Name	Required	Default Value	Description
`PROMPT_REPO_URL`	✅	-	Git repository URL or local path
`MCP_LANGUAGE`	❌	`en`	Output language (`en` or `zh`)
`MCP_GROUPS`	❌	`common`	Groups to load (comma-separated), system will prompt about default behavior when not set
`STORAGE_DIR`	❌	`.prompts_cache`	Local cache directory
`GIT_BRANCH`	❌	`main`	Git branch name
`GIT_MAX_RETRIES`	❌	`3`	Maximum retry count for Git operations
`CACHE_CLEANUP_INTERVAL`	❌	`10000`	Cache cleanup interval (milliseconds), periodic cleanup of expired cache items
`LOG_LEVEL`	❌	`warn` (prod) / `info` (dev)	Log level, production defaults to warnings and errors only

Cache Expiration Strategy

The system uses a TTL-based periodic cleanup mechanism to manage file list cache, ensuring memory efficiency.

Cache Mechanism

Cache TTL: 5 seconds (hardcoded)
Cleanup Interval: Default 10 seconds (CACHE_TTL * 2), adjustable via CACHE_CLEANUP_INTERVAL environment variable
Auto Cleanup: Cleanup mechanism starts automatically when application starts
Graceful Shutdown: Cleanup timer stops automatically when application closes

How It Works

Cache Creation: When getFilesRecursively() is called, scan results are cached for 5 seconds
Periodic Cleanup: Every 10 seconds (or configured interval), automatically scans and removes expired cache items
Memory Management: Prevents cache from growing indefinitely, avoiding memory leaks

Configuration Examples

# 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

Monitor Cache Status

You can view cache cleanup status through logs (requires setting LOG_LEVEL=debug):

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

Verify Cache Mechanism

See CACHE_VERIFICATION.md for complete verification methods and testing guide.

Security

✅ Input Validation: All environment variables are validated with Zod
✅ Path Security: Prevents path traversal attacks
✅ Group Validation: Group name format validation (only letters, numbers, underscores, dashes allowed)

📝 Logging

The project uses pino as the logging system, supporting structured logging.

Log Levels

fatal: Fatal errors that cause program exit
error: Error messages
warn: Warning messages
info: General information
debug: Debug messages
trace: Trace messages
silent: Completely disable log output

Default Behavior:

Production Environment (NODE_ENV not set or not development): Defaults to warn, only outputs warnings and errors
Development Environment (NODE_ENV=development): Defaults to info, outputs all info level and above logs
Can override default value via LOG_LEVEL environment variable

Setting Log Level

# Set in .env
LOG_LEVEL=debug

# Or set in environment variables
export LOG_LEVEL=debug

❓ FAQ & Troubleshooting

Q: How do I install MCP Prompt Manager?

A: There are three installation options:

Marketplace Installation (Easiest): Install from an MCP marketplace like mcp.so
Docker Deployment (Recommended for production): Use Docker Compose for easy deployment
Local Installation (For development): Clone the repository and build locally

See the Quick Start section for detailed instructions.

Q: How do I find the installation path after marketplace installation?

A: Use these commands to locate the installed server:

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: Why do I need to use absolute paths in the configuration?

A: MCP clients execute the server as a separate process and need the full path to locate the executable. Relative paths won't work because the working directory may differ.

Q: The server doesn't appear in my MCP client after configuration.

A: Try these steps:

Verify the path is absolute: Check that args contains a full absolute path, not a relative one
Check Node.js is installed: Run node --version to ensure Node.js 18+ is installed
Verify the file exists: Ensure dist/index.js exists at the specified path
Check JSON syntax: Validate your configuration file is valid JSON (no trailing commas)
Restart completely: Fully close and restart your MCP client (not just reload)
Check logs: Enable LOG_LEVEL=debug in your configuration to see detailed error messages

Q: How do I run the server locally?

A: You can use pnpm dev for development (with inspector) or pnpm start for production mode. See package.json scripts for more details.

Q: I'm getting a Git Clone Error (Exit Code 128).

A: This usually means a permission issue or invalid URL.

SSH vs HTTPS: If using SSH (git@github.com...), ensure your SSH keys are correctly mounted or available. If using HTTPS, ensure you don't need a token (or provide it).
Known Hosts: If running in Docker, ensure ssh-keyscan was run or your known_hosts file is mounted.
Repo Validity: Manually try git clone <URL> on your machine to verify the URL.

Issue: Git Sync Failed (General)

Solution:

Check if PROMPT_REPO_URL is correct
Confirm network connection is normal
Check if Git credentials are correct
Check logs for detailed error messages

Issue: No Prompts Loaded

Solution:

Check if MCP_GROUPS setting is correct
Confirm prompt files are in the correct directory structure (prompts/<group>/...)
Check if YAML file format is correct
Check error messages in logs

Issue: Partials Cannot Be Used

Solution:

Confirm partial file extension is .hbs
Confirm partials are in the partials/ directory
Check if partial file content is correct
Confirm using {{> partial-name }} syntax in templates

📦 Key Dependencies

@modelcontextprotocol/sdk: MCP SDK, provides MCP Server core functionality
handlebars: Handlebars template engine, supports dynamic Prompt generation
simple-git: Git operations library for syncing Git repositories
js-yaml: YAML parser for parsing Prompt definition files
zod: TypeScript-first schema validation library for configuration and type validation
pino: High-performance structured logging library
dotenv: Environment variable loading utility

Model Context Protocol Official Documentation
Handlebars Documentation
Zod Documentation
Simple Git Documentation
Pino Documentation
@carllee1983/prompt-toolkit - Prompt repository validation toolkit for MCP

📄 License

ISC

🤝 Contributing

Welcome to submit Issues and Pull Requests!

Version: 1.0.0
Last Updated: 2024-11-30

MCP Prompt Manager (Git-Driven)

Git-driven Model Context Protocol (MCP) Server for managing and providing Prompt templates

English | 繁體中文

📋 Introduction

Key Benefits:

🔄 Team Collaboration: Ensure unified Prompt versions across teams through Git version control
🎯 Dynamic Templates: Support Handlebars syntax to create reusable dynamic Prompts
🚀 Zero-Downtime Reload: Hot-reload support to update Prompts without restarting
🔍 Smart Management: Built-in Prompt version management, state tracking, and group filtering
📊 Complete Monitoring: System health status and Prompt statistics

✨ Features

Git Sync: Prompts are synced directly from the specified Git Repository, ensuring teams use unified Prompt versions.
Handlebars Templates: Support powerful Handlebars syntax to create dynamic, reusable Prompt templates.
Partials Support: Support Handlebars Partials for splitting and reusing Prompt fragments (e.g., role settings, output formats).
Local Cache: Automatically cache Git Repo content to local .prompts_cache directory for faster reads.
Cache Expiration Strategy: Automatically clean up expired cache items periodically to prevent memory leaks and ensure data consistency.
Group Filtering: Support filtering prompts by group, loading only what you need.
Error Handling: Complete error statistics and reporting for issue tracking.
Retry Mechanism: Automatic retry for Git operations to improve reliability.
Type Safety: Use Zod to validate configuration and prompt definitions for type safety.
Professional Logging: Use pino logging system with structured logs and multiple log levels.

🚀 Quick Start

Option 1: Marketplace Installation (Easiest)

If you're installing from an MCP marketplace (e.g., mcp.so), follow the marketplace's installation instructions. Typically, you'll need to:

Install via marketplace: Use the marketplace's installation interface
Configure your MCP client: Add the server configuration to your MCP client

Prerequisites

Before installing, ensure you have:

Node.js installed (version 18.0.0 or higher)
pnpm package manager (version 8.0.0 or higher)
A Git repository containing your prompts (or a local path to prompts)
An MCP-compatible client (Cursor, Claude Desktop, VS Code, etc.)

Installation Steps

Install from Marketplace:
- Visit your preferred MCP marketplace
- Search for "mcp-prompt-manager"
- Follow the marketplace's installation instructions
- Note the installation path where the server was installed
Locate Installation Path:
- After marketplace installation, find where dist/index.js is located
- This is typically in a global node_modules directory or a dedicated installation folder
- You'll need the absolute path to this file for configuration
Configure MCP Client:
- Open your MCP client's configuration file (see Configuration section for file locations)
- Add the server configuration (see example below)
- Important: Use absolute paths, not relative paths

Configuration Example

After installation, configure your MCP client (Cursor, Claude Desktop, etc.) with the following:

For 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"
            }
        }
    }
}

Note: Replace /absolute/path/to/mcp-prompt-manager/dist/index.js with the actual absolute path where the marketplace installed the server.

Tip: See mcp.json.example for a complete configuration template.

Finding the Installation Path

If you're unsure where the marketplace installed the server:

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" }

Verification

After configuration:

Restart your MCP client completely
Check server status:
- In Cursor: Press Cmd/Ctrl + Shift + P, search for "MCP: Show servers"
- In Claude Desktop: Check the MCP servers list in settings
Verify prompts are loaded: Use the client's MCP tools to list available prompts

For detailed configuration instructions for different MCP clients, see the Configuration section below.

Option 2: Docker Deployment (Recommended)

The easiest way to get started is using 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

For detailed Docker deployment instructions, see DOCKER.md.

Option 3: Local Installation

This option is recommended for development or when you want full control over the installation.

Prerequisites

Node.js 18.0.0 or higher
pnpm 8.0.0 or higher (required, npm/yarn will fail)
Git (for cloning the repository)

Installation Steps

Clone the Repository:

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

Install Dependencies:

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

Note: Installs are enforced with pnpm; npm/yarn will fail because of the preinstall check.

Build the Project:

pnpm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Configure Environment Variables:

Copy the example configuration file and create .env:

cp .env.example .env

Edit the .env file to set your Prompt Git Repository path or 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
# PROMPT_REPO_URL=git@github.com: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

Configure MCP Client:

After building, you need to configure your MCP client to use the locally installed server. The path will be:

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

Replace /path/to/mcp-prompt-manager with the actual absolute path where you cloned the repository.

See the Configuration section below for detailed client-specific configuration instructions.

Quick Start (Development)

For development purposes, you can use these commands:

# 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

🛠️ Usage

Testing with Inspector

We provide a convenient command to start the MCP Inspector for testing:

Basic Usage

Important: Inspector runs the compiled dist/index.js, so if you've modified the source code, you need to compile first:

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

# 2. Start Inspector
pnpm run inspector

Quick Development Mode

If you're developing, you can use a combined command that automatically compiles before starting Inspector:

pnpm run inspector:dev

This automatically runs build and then starts Inspector, ensuring you're testing the latest compiled code.

Inspector Features

Inspector launches a web interface where you can:

View all loaded prompts
Test prompt output
Check error messages
Verify environment variable settings

Using in Cursor

Configuration File Location

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

Configuration Steps

Find the configuration file:
- Method 1: In Cursor, press Cmd/Ctrl + Shift + P, search for "MCP: Add server"
- Method 2: Directly edit the mcp.json file at the path above
Edit the configuration file:

{
    "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"
            }
        }
    }
}

Important Configuration Notes:
- command: Use node to execute the compiled JavaScript file
- args: Must be an absolute path pointing to dist/index.js
- env: Environment variables (optional, if already set in .env)
Verify Configuration:
- Restart Cursor
- In Cursor, press Cmd/Ctrl + Shift + P, search for "MCP: Show servers"
- Confirm that mcp-prompt-manager shows as connected

Note:

Replace /path/to/mcp-prompt-manager with the actual absolute path of this project

If environment variables are already set in .env, the env block can be omitted, but specifying directly in JSON is usually more robust

If the configuration file doesn't exist, you need to create the mcp.json file first

Using in Claude Desktop

Configuration File Location

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Configuration Steps

Create or edit the configuration file:

If the file doesn't exist, create it first:

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

Edit the configuration file:

{
    "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"
            }
        }
    }
}

Verify Configuration:
- Completely close Claude Desktop (ensure all windows are closed)
- Restart Claude Desktop
- In conversations, Claude should be able to use your defined prompts

Note:

Configuration file must be valid JSON format

Paths must use absolute paths

After modifying the configuration file, you must completely restart Claude Desktop

Using in VS Code (via Extension)

VS Code can use MCP Server through MCP extensions.

Configuration Steps

Install MCP Extension:
- Search for "MCP" or "Model Context Protocol" in VS Code Extension Marketplace
- Install the corresponding extension
Configure MCP Server:
- Open VS Code settings (Cmd/Ctrl + ,)
- Search for "MCP" related settings
- Or edit 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"
            }
        }
    }
}

Using in Continue

Continue is an open-source AI code assistant that supports MCP.

Configuration File Location

macOS:

~/.continue/config.json

Windows:

%APPDATA%\Continue\config.json

Linux:

~/.config/Continue/config.json

Configuration Steps

Edit 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"
            }
        }
    }
}

Using in Aider

Aider is an AI code editor that supports MCP.

Configuration Method

In Aider's configuration file (usually ~/.aider/config.json or via environment variables):

{
    "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"
            }
        }
    }
}

Using in Custom Applications (Programmatic)

If you're developing your own application and want to integrate the MCP Server, you can use the MCP SDK:

TypeScript/JavaScript Example

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 Example

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 Client Quick Reference

Client	Configuration File Location	Config Format	Notes
Cursor	`~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json` (macOS)	`mcpServers`	Supports UI config
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)	`mcpServers`	Requires full restart
VS Code	`settings.json`	`mcp.servers`	Requires MCP extension
Continue	`~/.continue/config.json`	`mcpServers`	Open-source AI assistant
Aider	`~/.aider/config.json`	`mcp_servers`	AI code editor

Note: The ~ in paths represents the user home directory, which expands to:

macOS/Linux: /Users/username or /home/username

Windows: C:\Users\username

Universal Configuration Format

All MCP-compatible clients follow the same configuration format:

{
    "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"
            }
        }
    }
}

📝 Environment Variables Reference

Variable	Required	Default	Description
`PROMPT_REPO_URL`	Yes*	-	Primary Git repository URL or local path. (*Required if `PROMPT_REPO_URLS` is not set)
`PROMPT_REPO_URLS`	No	-	Comma-separated list of multiple repository URLs (e.g. `url1,url2`).
`SYSTEM_REPO_URL`	No	-	Separate repository URL for system-level prompts (e.g. common prompts).
`MCP_LANGUAGE`	No	`en`	Output language. Options: `en`, `zh`.
`MCP_GROUPS`	No	-	Comma-separated list of prompt groups to load (e.g. `laravel,vue`). If unset, checks System Repo or default behaviors.
`TRANSPORT_TYPE`	No	`stdio`	Communication method. Options: `stdio`, `http`, `sse`.
`LOG_LEVEL`	No	`info`	Logging verbosity. Options: `debug`, `info`, `warn`, `error`, `silent`.
`LOG_FILE`	No	-	Path to write log file (e.g. `logs/mcp.log`). Highly recommended for debugging.
`STORAGE_DIR`	No	`.prompts_cache`	directory to store cloned repositories.
`GIT_BRANCH`	No	`main`	Default Git branch to clone.
`GIT_MAX_RETRIES`	No	`3`	Number of retries for failed Git operations.
`GIT_POLLING_INTERVAL`	No	`300000`	Interval (ms) to check for updates when `WATCH_MODE=true`.
`WATCH_MODE`	No	`false`	Enable auto-reloading when changes are detected in the repository.
`CACHE_PROVIDER`	No	`local`	Caching mechanism. Options: `local`, `redis`.
`CACHE_TTL`	No	-	Time-to-live for cache items (optional).
`CACHE_CLEANUP_INTERVAL`	No	`10000`	Interval (ms) to clean up expired cache items.

Security Note:

Never commit .env files to version control. The .env.example file is provided as a template only.

Avoid hardcoding sensitive credentials (passwords, tokens) in PROMPT_REPO_URL.

Use SSH keys (git@github.com...) for secure, password-less authentication.

For production, use Docker Secrets or your platform's secret management system.

Important Configuration Notes

Absolute Paths: When configuring clients like Cursor/Claude, paths to dist/index.js must be absolute.
JSON Format: Ensure your config file is valid JSON (no trailing commas).
Precedence: env defined in client config JSON overrides .env files.
Restart: Always restart your AI editor/client after changing configuration.

Verifying MCP Server is Running Properly

Method 1: Using 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

This launches a web interface where you can:

View all loaded prompts
Test prompt output
Check error messages

Note: Inspector runs dist/index.js, so after modifying source code, you must run build first to see the latest changes.

Method 2: Check Logs

Add environment variables in the configuration file to view detailed logs:

{
    "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"
            }
        }
    }
}

Then check the client's log output (Cursor's output panel or Claude Desktop's logs).

Method 3: Check File System

Verify Git repository has been synced successfully:

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

You should see files cloned from the Git repository.

Common Configuration Issues

Issue 1: Configuration File Not Found

Solution:

Confirm the application has been started at least once (will automatically create configuration directory)
Manually create the configuration file and directory
Check if the path is correct (note case sensitivity and spaces)

Issue 2: JSON Format Error

Solution:

Use JSON validation tools to check format (e.g., JSONLint)
Ensure all strings use double quotes
Ensure no comma after the last item

Issue 3: Server Cannot Start

Solution:

Confirm dist/index.js file exists
Confirm path is absolute
Confirm Node.js is installed and version >= 18
Check if environment variables are correct
Check client error logs

Issue 4: No Prompts Found

Solution:

Confirm PROMPT_REPO_URL is correct
Check if MCP_GROUPS setting includes the groups you want
- Note: If MCP_GROUPS is not set, the system defaults to loading only the common group
- Check log messages to confirm if default groups are being used
- Set MCP_GROUPS=laravel,vue etc. to load other groups
Confirm Git repository contains .yaml or .yml files
Use LOG_LEVEL=debug to view detailed logs and confirm which groups are loaded

📂 Prompt Repository Structure

Your Prompt Repository (where PROMPT_REPO_URL points to) should have the following structure:

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

Group Filtering Rules

Root directory (/): Always loaded
common group (common/): Always loaded
Other groups: Only loaded when specified in MCP_GROUPS environment variable

Default Behavior

When MCP_GROUPS is not set:

System automatically loads the common group (and root directory prompts)
Startup logs will explicitly prompt about using default groups
Logs will include messages suggesting to set MCP_GROUPS to load more groups

Examples

MCP_GROUPS=laravel,vue → Load root, common, laravel, vue
MCP_GROUPS= or not set → Only load root and common (system will prompt about using default)

Prompt Definition File Example (`.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:

Parameter Types

Prompts support three parameter types:

string: String type (default)
number: Number type
boolean: Boolean type

Registry Feature (Optional)

You can create a registry.yaml file in the root directory of your Prompt Repository to centrally manage prompt visibility and deprecation status.

Registry File Format

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

Registry Field Descriptions

id: Prompt ID (required)
group: Group name (optional)
visibility: Visibility setting
- public: Public (default)
- private: Private
- internal: Internal use
deprecated: Whether deprecated (default false)

Registry Purpose

Centralized Management: Manage all prompts' visibility and deprecation status in a single file
Override Defaults: Can override default settings in prompt definition files
Version Control: Track prompt lifecycle through Git

Note: registry.yaml is optional. If it doesn't exist, the system will use default values from prompt definition files.

Prompt Runtime State

Each prompt has a runtime state (runtime_state) indicating the prompt's current availability:

active: Active state, prompt works normally and can be used as an MCP Tool
legacy: Legacy state, prompt is still available but marked as old version, recommend using new version
invalid: Invalid state, prompt definition has issues (e.g., missing required fields, template errors, etc.), cannot be used
disabled: Disabled, prompt is explicitly disabled (e.g., marked as deprecated in registry)
warning: Warning state, prompt can work but has some warnings (e.g., version too old)

Prompt Source

Each prompt has a source (source) tag indicating where the metadata comes from:

embedded: Metadata embedded in prompt definition file (using metadata: block)
registry: Settings from registry.yaml
legacy: Legacy mode, no metadata, uses default values

Prompt Status

Each prompt has a status (status) indicating the prompt's development stage:

draft: Draft, under development
stable: Stable version, can be used normally
deprecated: Deprecated, not recommended for use
legacy: Legacy version, still available but recommend upgrading

🔧 MCP Tools and Resources

This project provides multiple MCP tools and resources for managing and querying Prompts.

MCP Tools

1. `mcp.reload` / `mcp.reload_prompts`

Reload all Prompts without restarting the server (hot-reload).

Function: Pull latest changes from Git repository, clear cache, reload all Handlebars partials and prompts
Parameters: None

Usage Example:

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

2. `mcp.stats` / `mcp.prompt.stats`

Get Prompts statistics.

Function: Returns statistics for all prompts, including counts by runtime state (active, legacy, invalid, disabled, warning)
Parameters: None
Return Content:
- total: Total count
- active: Active state count
- legacy: Legacy state count
- invalid: Invalid state count
- disabled: Disabled count
- warning: Warning state count

3. `mcp.list` / `mcp.prompt.list`

List all Prompts with multiple filter options.

Function: Lists all prompt runtimes with complete metadata information
Parameters (optional):
- status: Filter by status (draft, stable, deprecated, legacy)
- group: Filter by group name
- tag: Filter by tag (prompts must contain this tag)
- runtime_state: Filter by runtime state (active, legacy, invalid, disabled, warning)

Usage Example:

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

4. `mcp.inspect`

Inspect detailed runtime information for a specific Prompt.

Function: Get complete runtime metadata by Prompt ID, including state, source, version, tags, and use cases
Parameters:
- id: Prompt ID (required)

Usage Example:

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

5. `mcp.repo.switch`

Switch to a different Prompt repository and reload (zero-downtime).

Function: Switch to a new Git repository and reload all prompts
Parameters:
- repo_url: Repository URL (required)
- branch: Branch name (optional)

Usage Example:

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

6. `preview_prompt`

Preview/render a prompt template with given arguments without executing it (debug utility).

Function: Renders a prompt template with given arguments to show the final text without sending it to an LLM. Use this to verify template logic.
Parameters:
- promptId: Prompt ID (required, e.g., 'laravel:code-review')
- args: JSON object containing the arguments/variables for the template (required)
Returns:
- success: Boolean indicating success or failure
- renderedText: The rendered prompt text
- highlightedText: The rendered text with variables highlighted in Markdown bold
- statistics: Object containing renderedLength (character count) and estimatedTokens (estimated token count)
- warnings: Array of schema validation warnings (e.g., missing recommended fields)

Usage Example:

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

Advanced Features:
- Schema Validation: Strict validation of arguments against prompt's Zod schema
- Token Estimation: Estimates token count (supports both English and Chinese text)
- Variable Highlighting: Highlights dynamically replaced variables with Markdown bold formatting
- Schema Warnings: Detects and reports missing required or recommended fields

MCP Resources

1. `system://health`

System health status resource.

URI: system://health
MIME Type: application/json
Content: Includes the following information:
- git: Git repository information (URL, path, HEAD commit)
- prompts: Prompts statistics (total, counts by state, loaded count, group list)
- registry: Registry status (enabled, source)
- cache: Cache information (size, cleanup interval)
- system: System information (uptime, memory usage)

2. `prompts://list`

Prompts list resource.

URI: prompts://list
MIME Type: application/json
Content: Complete metadata list of all prompts, including:
- id: Prompt ID
- title: Title
- version: Version
- status: Status
- runtime_state: Runtime state
- source: Source
- tags: Tags array
- use_cases: Use cases array
- group: Group name
- visibility: Visibility

Tool Usage Recommendations

During Development: Use mcp.reload to quickly reload prompts without restarting the server
During Debugging: Use mcp.inspect to check detailed information for specific prompts, or use preview_prompt to test template rendering
During Monitoring: Use mcp.stats and system://health resource to monitor system status
During Querying: Use mcp.list with filter conditions to find specific prompts
During Testing: Use preview_prompt to verify template logic, check token counts, and see variable replacements before actual execution

💻 Development Guide

Architecture Overview

The MCP Prompt Manager follows a modular architecture with clear separation of concerns:

Core Components

Repository Interface (src/repositories/strategy.ts)
- Abstract interface for different repository types (Git, Local)
- Supports multiple repository strategies with priority-based loading
- Handles repository synchronization and file watching
Source Manager (src/services/sourceManager.ts)
- Singleton pattern for managing prompt lifecycle
- Handles prompt loading, caching, and registration
- Compiles Handlebars templates at load time for performance
- Manages prompt runtime states and metadata
Cache Layer (src/cache/)
- Abstract cache provider interface supporting local and Redis (future)
- Local cache with LRU eviction and TTL support
- Automatic cleanup of expired cache items

Prompt Storage Flow

┌─────────────────────────────────────────────────────────────┐
│                    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.)                              │
└─────────────────────────────────────────────────────────────┘

Key Modules

Repository Interface: Abstract strategy pattern for Git and local repositories
Source Manager: Centralized prompt lifecycle management with caching
Cache Provider: Pluggable cache system (local memory or Redis)
Loaders: High-level API for loading prompts and partials
MCP Tools: Dynamic tool registration based on loaded prompts

Project Structure

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

Common Commands

# 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

Development Workflow

Modify code in the src/ directory.
Run pnpm run build to recompile (or use pnpm run inspector:dev to auto-compile and test).
Run pnpm run test to run tests.
Use pnpm run inspector:dev to verify changes (will auto-compile and start Inspector).
Restart MCP Server in Cursor or Claude Desktop to apply changes.

Important Notes:

The inspector command runs dist/index.js (compiled file)

After modifying source code, you must run build first to see the latest changes

Using inspector:dev can auto-compile and start, suitable for development

Prompt Repository Validation

Installation

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

Development Workflow with Validation

Develop Prompts: Create and edit prompts in your repository
Validate Locally: Use the toolkit to validate before committing
```
prompt-toolkit validate repo
```

CI/CD Validation: Automatically validate in CI/CD pipelines

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

Deploy to MCP Prompt Manager: MCP Prompt Manager loads validated prompts

Quick Validation Commands

# 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 Integration

Add validation to your CI/CD pipeline to catch errors before deployment:

# .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

Best Practices

✅ Validate before committing: Run validation locally before pushing changes
✅ Use CI/CD: Automatically validate in CI/CD pipelines to catch errors
✅ Monitor results: Track validation results to maintain repository health
✅ Severity filtering: Use --severity option to focus on critical issues
✅ JSON output: Use --format json for machine-readable output in CI/CD

Programmatic Usage

You can also use the toolkit programmatically in your scripts:

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)
}

For more information, see the prompt-toolkit documentation.

🧪 Testing

The project includes a complete test suite:

Unit Tests: Multiple test files covering all core functionality
Integration Tests: End-to-end testing for prompt loading and MCP tools
Total: 107 tests, all passing

Run tests:

# Watch mode
pnpm test

# Run once
pnpm test:run

# Open UI
pnpm test:ui

Test Coverage

This project maintains high code quality through comprehensive test coverage with the following thresholds:

Statements: ≥ 80%
Lines: ≥ 75%
Functions: ≥ 75%
Branches: ≥ 70%

Note: Coverage reports use @vitest/coverage-v8 which requires Node.js 19+. Coverage thresholds are enforced to maintain code quality. If coverage falls below thresholds, tests will fail to ensure quality standards.

Viewing Coverage Reports

Local Development: Run pnpm test:coverage to generate coverage reports, or use pnpm test:coverage:view to automatically open the HTML coverage report in your browser.
CI/CD: Run pnpm test:coverage:ci to generate coverage reports and enforce thresholds. The CI pipeline will fail if coverage thresholds are not met, ensuring code quality standards are maintained before merging or releasing.
Coverage Reports: Coverage reports are generated in the coverage/ directory with multiple formats:
- coverage/index.html - Interactive HTML report
- coverage/coverage-final.json - JSON format for CI integration
- coverage/lcov.info - LCOV format for coverage services

Coverage Commands

# 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

Code Quality and CI/CD

This project enforces code quality through multiple layers of checks:

Pre-commit Hooks

Pre-commit hooks automatically run linting and formatting before each commit using Husky and lint-staged:

ESLint: Automatically fixes linting issues in TypeScript files
Prettier: Automatically formats code to ensure consistent style
Type Safety: TypeScript strict mode is enabled (strict: true in tsconfig.json)

The pre-commit hook runs on staged files only, ensuring fast commit times while maintaining code quality.

Continuous Integration (CI)

GitHub Actions CI workflow runs on every push and pull request:

Node.js Compatibility: Tests across Node.js 16.x, 18.x, and 20.x
Linting: ESLint checks for code quality and style
Type Checking: TypeScript type checking (tsc --noEmit)
Testing: Full test suite with coverage reporting
Coverage Upload: Automatic upload to Codecov

Required Checks for Pull Requests

To ensure code quality, the following checks must pass before a PR can be merged:

Lint: All ESLint rules must pass
Typecheck: TypeScript compilation must succeed with no errors
Tests: All tests must pass with coverage thresholds met

Setting up Required Checks in GitHub:

Go to your repository settings
Navigate to Branches → Branch protection rules
Add or edit a rule for your main branch
Under Require status checks to pass before merging, enable:
- Test (Node.js 16.x) or Test (Node.js 18.x) or Test (Node.js 20.x) (at least one)
- These checks will automatically include lint, typecheck, and test steps

The CI workflow will automatically fail if any of these checks fail, preventing merging of code that doesn't meet quality standards.

🔧 Configuration

Environment Variables

Variable Name	Required	Default Value	Description
`PROMPT_REPO_URL`	✅	-	Git repository URL or local path
`MCP_LANGUAGE`	❌	`en`	Output language (`en` or `zh`)
`MCP_GROUPS`	❌	`common`	Groups to load (comma-separated), system will prompt about default behavior when not set
`STORAGE_DIR`	❌	`.prompts_cache`	Local cache directory
`GIT_BRANCH`	❌	`main`	Git branch name
`GIT_MAX_RETRIES`	❌	`3`	Maximum retry count for Git operations
`CACHE_CLEANUP_INTERVAL`	❌	`10000`	Cache cleanup interval (milliseconds), periodic cleanup of expired cache items
`LOG_LEVEL`	❌	`warn` (prod) / `info` (dev)	Log level, production defaults to warnings and errors only

Cache Expiration Strategy

The system uses a TTL-based periodic cleanup mechanism to manage file list cache, ensuring memory efficiency.

Cache Mechanism

Cache TTL: 5 seconds (hardcoded)
Cleanup Interval: Default 10 seconds (CACHE_TTL * 2), adjustable via CACHE_CLEANUP_INTERVAL environment variable
Auto Cleanup: Cleanup mechanism starts automatically when application starts
Graceful Shutdown: Cleanup timer stops automatically when application closes

How It Works

Cache Creation: When getFilesRecursively() is called, scan results are cached for 5 seconds
Periodic Cleanup: Every 10 seconds (or configured interval), automatically scans and removes expired cache items
Memory Management: Prevents cache from growing indefinitely, avoiding memory leaks

Configuration Examples

# 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

Monitor Cache Status

You can view cache cleanup status through logs (requires setting LOG_LEVEL=debug):

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

Verify Cache Mechanism

See CACHE_VERIFICATION.md for complete verification methods and testing guide.

Security

✅ Input Validation: All environment variables are validated with Zod
✅ Path Security: Prevents path traversal attacks
✅ Group Validation: Group name format validation (only letters, numbers, underscores, dashes allowed)

📝 Logging

The project uses pino as the logging system, supporting structured logging.

Log Levels

fatal: Fatal errors that cause program exit
error: Error messages
warn: Warning messages
info: General information
debug: Debug messages
trace: Trace messages
silent: Completely disable log output

Default Behavior:

Production Environment (NODE_ENV not set or not development): Defaults to warn, only outputs warnings and errors
Development Environment (NODE_ENV=development): Defaults to info, outputs all info level and above logs
Can override default value via LOG_LEVEL environment variable

Setting Log Level

# Set in .env
LOG_LEVEL=debug

# Or set in environment variables
export LOG_LEVEL=debug

❓ FAQ & Troubleshooting

Q: How do I install MCP Prompt Manager?

A: There are three installation options:

Marketplace Installation (Easiest): Install from an MCP marketplace like mcp.so
Docker Deployment (Recommended for production): Use Docker Compose for easy deployment
Local Installation (For development): Clone the repository and build locally

See the Quick Start section for detailed instructions.

Q: How do I find the installation path after marketplace installation?

A: Use these commands to locate the installed server:

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: Why do I need to use absolute paths in the configuration?

A: MCP clients execute the server as a separate process and need the full path to locate the executable. Relative paths won't work because the working directory may differ.

Q: The server doesn't appear in my MCP client after configuration.

A: Try these steps:

Verify the path is absolute: Check that args contains a full absolute path, not a relative one
Check Node.js is installed: Run node --version to ensure Node.js 18+ is installed
Verify the file exists: Ensure dist/index.js exists at the specified path
Check JSON syntax: Validate your configuration file is valid JSON (no trailing commas)
Restart completely: Fully close and restart your MCP client (not just reload)
Check logs: Enable LOG_LEVEL=debug in your configuration to see detailed error messages

Q: How do I run the server locally?

A: You can use pnpm dev for development (with inspector) or pnpm start for production mode. See package.json scripts for more details.

Q: I'm getting a Git Clone Error (Exit Code 128).

A: This usually means a permission issue or invalid URL.

SSH vs HTTPS: If using SSH (git@github.com...), ensure your SSH keys are correctly mounted or available. If using HTTPS, ensure you don't need a token (or provide it).
Known Hosts: If running in Docker, ensure ssh-keyscan was run or your known_hosts file is mounted.
Repo Validity: Manually try git clone <URL> on your machine to verify the URL.

Issue: Git Sync Failed (General)

Solution:

Check if PROMPT_REPO_URL is correct
Confirm network connection is normal
Check if Git credentials are correct
Check logs for detailed error messages

Issue: No Prompts Loaded

Solution:

Check if MCP_GROUPS setting is correct
Confirm prompt files are in the correct directory structure (prompts/<group>/...)
Check if YAML file format is correct
Check error messages in logs

Issue: Partials Cannot Be Used

Solution:

Confirm partial file extension is .hbs
Confirm partials are in the partials/ directory
Check if partial file content is correct
Confirm using {{> partial-name }} syntax in templates

📦 Key Dependencies

@modelcontextprotocol/sdk: MCP SDK, provides MCP Server core functionality
handlebars: Handlebars template engine, supports dynamic Prompt generation
simple-git: Git operations library for syncing Git repositories
js-yaml: YAML parser for parsing Prompt definition files
zod: TypeScript-first schema validation library for configuration and type validation
pino: High-performance structured logging library
dotenv: Environment variable loading utility

Model Context Protocol Official Documentation
Handlebars Documentation
Zod Documentation
Simple Git Documentation
Pino Documentation
@carllee1983/prompt-toolkit - Prompt repository validation toolkit for MCP

📄 License

ISC

🤝 Contributing

Welcome to submit Issues and Pull Requests!

Version: 1.0.0
Last Updated: 2024-11-30

MCP Prompt Manager

MCP Prompt Manager (Git-Driven)

📋 Introduction

✨ Features

🚀 Quick Start

Option 1: Marketplace Installation (Easiest)

Prerequisites

Installation Steps

Configuration Example

Finding the Installation Path

Verification

Option 2: Docker Deployment (Recommended)

Option 3: Local Installation

Prerequisites

Installation Steps

Quick Start (Development)

🛠️ Usage

Testing with Inspector

Basic Usage

Quick Development Mode

Inspector Features

Using in Cursor

Configuration File Location

Configuration Steps

Using in Claude Desktop

Configuration File Location

Configuration Steps

Using in VS Code (via Extension)

Configuration Steps

Using in Continue

Configuration File Location

Configuration Steps

Using in Aider

Configuration Method

Using in Custom Applications (Programmatic)

TypeScript/JavaScript Example

Python Example

MCP Client Quick Reference

Universal Configuration Format

📝 Environment Variables Reference

Important Configuration Notes

Verifying MCP Server is Running Properly

Method 1: Using MCP Inspector

Method 2: Check Logs

Method 3: Check File System

Common Configuration Issues

Issue 1: Configuration File Not Found

Issue 2: JSON Format Error

Issue 3: Server Cannot Start

Issue 4: No Prompts Found

📂 Prompt Repository Structure

Group Filtering Rules

Default Behavior

Examples

Prompt Definition File Example (.yaml)

Parameter Types

Registry Feature (Optional)

Registry File Format

Registry Field Descriptions

Registry Purpose

Prompt Runtime State

Prompt Source

Prompt Status

🔧 MCP Tools and Resources

MCP Tools

1. mcp.reload / mcp.reload_prompts

2. mcp.stats / mcp.prompt.stats

3. mcp.list / mcp.prompt.list

4. mcp.inspect

5. mcp.repo.switch

6. preview_prompt

MCP Resources

1. system://health

2. prompts://list

Tool Usage Recommendations

💻 Development Guide

Architecture Overview

Core Components

Prompt Storage Flow

Key Modules

Prompt Definition File Example (`.yaml`)

1. `mcp.reload` / `mcp.reload_prompts`

2. `mcp.stats` / `mcp.prompt.stats`

3. `mcp.list` / `mcp.prompt.list`

4. `mcp.inspect`

5. `mcp.repo.switch`

6. `preview_prompt`

1. `system://health`

2. `prompts://list`