MCP Prompt Manager

MCP提示管理器（Git驱动）

Git驱动的模型上下文协议（MCP）服务器，用于管理和提供提示模板

      

英语 | 繁体中文

📋 引言

这是一个Git驱动的模型上下文协议（MCP）服务器，旨在管理和提供提示模板。它允许您将Prompts存储在单独的Git存储库中，并通过MCP协议直接在Cursor、Claude Desktop等AI编辑器中使用它们。

主要优势：

• 🔄 团队协作：通过Git版本控制确保跨团队的统一Prompt版本
• 🎯 动态模板：支持Handlebars语法以创建可重用的动态提示
• 🚀 零停机重新加载：热重新加载支持，无需重新启动即可更新提示
• 🔍 智能管理：内置即时版本管理、状态跟踪和组过滤
• 📊 完整监控：系统健康状态和即时统计

✨ 特性

• Git同步提示直接从指定的Git仓库同步，确保团队使用统一的提示版本。
• 把手模板：支持强大的Handlebars语法，以创建动态、可重用的Prompt模板。
• 党派支持：支持Handlebars Partials用于拆分和重用Prompt片段（例如角色设置、输出格式）。
• 本地缓存：自动将Git回购内容缓存到本地 .prompts_cache 目录以实现更快的读取。
• 缓存过期策略：定期自动清理过期的缓存项，以防止内存泄漏并确保数据一致性。
• 分组过滤：支持按组过滤提示，只加载您需要的内容。
• 错误处理：完整的错误统计和报告，用于问题跟踪。
• 重试机制：自动重试Git操作以提高可靠性。
• 类型安全：使用Zod验证配置并提示类型安全的定义。
• 专业测井：使用具有结构化日志和多个日志级别的pino日志系统。

🚀 快速开始

选项1：市场安装（最简单）

如果您从MCP市场安装（例如。， mcp.so)，请按照市场的安装说明进行操作。通常，您需要：

1. 通过市场安装：使用市场的安装界面
2. 配置您的MCP客户端：将服务器配置添加到MCP客户端

先决条件

安装前，请确保：

• Node.js 已安装（18.0.0或更高版本）
• pnpm 包管理器（8.0.0或更高版本）
• A. Git仓库 包含您的提示（或提示的本地路径）
• 一 MCP兼容客户端 （光标、克劳德桌面、VS代码等）

安装步骤

1. 从市场安装:

- 访问您首选的MCP市场 - 搜索“mcp提示管理器” - 遵循市场的安装说明 - 记下安装服务器的安装路径

1. 查找安装路径:

- 市场安装后，找到位置 dist/index.js 位于 - 这通常位于全局node_modules目录或专用安装文件夹中 - 你需要 绝对路径 转到此文件进行配置

1. 配置MCP客户端:

- 打开MCP客户端的配置文件（请参阅 配置 文件位置部分） - 添加服务器配置（见下面的示例） - 重要：使用绝对路径，而不是相对路径

配置示例

安装后，使用以下内容配置MCP客户端（Cursor、Claude Desktop等）：

对于光标 (~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json):

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

备注：替换 /absolute/path/to/mcp-prompt-manager/dist/index.js 市场安装服务器的实际绝对路径。

小贴士：参见 mcp.json.示例 获取完整的配置模板。

查找安装路径

如果您不确定市场在哪里安装了服务器：

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

视窗:

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

验证

配置后：

1. 重新启动MCP客户端 完全
2. 检查服务器状态:

- 在光标中：按 Cmd/Ctrl + Shift + P，搜索“MCP:显示服务器” - 在Claude Desktop中：检查设置中的MCP服务器列表

1. 验证是否加载了提示：使用客户的MCP工具列出可用提示

有关不同MCP客户端的详细配置说明，请参阅 配置 下面的部分。

选项2：Docker部署（推荐）

最简单的入门方法是使用Docker：

# 1. Clone the repository
git clone 

cd mcp-prompt-manager

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

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

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

# 5. View logs
docker-compose logs -f

有关Docker部署的详细说明，请参阅 医生.md.

选项3：本地安装

建议在开发或希望完全控制安装时使用此选项。

先决条件

• Node.js 18.0.0或更高
• pnpm 8.0.0或更高版本（必填，npm/yarn将失败）
• Git （用于克隆存储库）

安装步骤

1. 克隆存储库:

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

1. 再进行:

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

备注：安装通过pnpm执行；由于预安装检查，npm/yarn将失败。

1. 构建项目:

pnpm run build

这将TypeScript编译为JavaScript dist/ 目录。

1. 配置环境变量:

复制示例配置文件并创建 .env:

cp .env.example .env

编辑 .env file来设置提示Git存储库路径或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

1. 配置MCP客户端:

构建后，您需要配置MCP客户端以使用本地安装的服务器。路径将是：

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

替换 /path/to/mcp-prompt-manager 使用克隆存储库的实际绝对路径。

请参阅 配置 以下部分详细介绍了特定于客户端的配置说明。

快速启动（开发）

出于开发目的，您可以使用以下命令：

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Start development server with Inspector
pnpm dev

# Run tests
pnpm test:run

# Lint code
pnpm lint

🛠️ 用法

检验员测试

我们提供了一个方便的命令来启动MCP检查器进行测试：

基本用法

重要：检查器运行已编译的 dist/index.js，所以如果你修改了源代码，你需要先编译：

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

# 2. Start Inspector
pnpm run inspector

快速开发模式

如果您正在开发，可以使用在启动Inspector之前自动编译的组合命令：

pnpm run inspector:dev

这将自动运行 build 然后启动Inspector，确保您正在测试最新编译的代码。

检查器功能

Inspector启动一个web界面，您可以在其中：

• 查看所有加载的提示
• 测试提示输出
• 检查错误消息
• 验证环境变量设置

在游标中使用

配置文件位置

macOS：

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

窗户：

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

Linux：

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

配置步骤

1. 查找配置文件:

- 方法1：在光标中，按 Cmd/Ctrl + Shift + P，搜索“MCP:添加服务器” - 方法2：直接编辑 mcp.json 文件位于上面的路径

1. 编辑配置文件:

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

1. 重要配置说明:

- command：使用 node 执行已编译的JavaScript文件 - args：必须是 绝对路径 指向 dist/index.js - env：环境变量（可选，如果已在中设置 .env)

1. 验证配置:

- 重新启动游标 - 在光标中，按 Cmd/Ctrl + Shift + P，搜索“MCP:显示服务器” - 确认 mcp-prompt-manager 显示为已连接

备注: - 替换 /path/to/mcp-prompt-manager 与该项目的实际绝对路径 - 如果环境变量已在中设置 .env，the env 块可以省略，但直接在JSON中指定通常更稳健 - 如果配置文件不存在，您需要创建 mcp.json 文件优先

在Claude桌面中使用

配置文件位置

macOS：

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

窗户：

%APPDATA%\Claude\claude_desktop_config.json

Linux：

~/.config/Claude/claude_desktop_config.json

配置步骤

1. 创建或编辑配置文件:

如果文件不存在，请先创建它：

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

1. 编辑配置文件:

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

1. 验证配置:

- 完全关闭Claude Desktop（确保所有窗口均已关闭） - 重新启动克劳德桌面 - 在对话中，Claude应该能够使用您定义的提示

备注: - 配置文件必须是有效的JSON格式 - 路径必须使用绝对路径 - 修改配置文件后，您必须完全重新启动Claude Desktop

在VS代码中使用（通过扩展）

VS Code可以通过MCP扩展使用MCP服务器。

配置步骤

1. 安装MCP扩展:

- 在VS代码扩展市场中搜索“MCP”或“模型上下文协议” - 安装相应的扩展

1. 配置MCP服务器:

- 打开VS代码设置(Cmd/Ctrl + ,) - 搜索“MCP”相关设置 - 或编辑 settings.json:

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

继续使用

Continue是一个支持MCP的开源AI代码助手。

配置文件位置

macOS：

~/.continue/config.json

窗户：

%APPDATA%\Continue\config.json

Linux：

~/.config/Continue/config.json

配置步骤

编辑 config.json:

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

在Aider中使用

Aider是一个支持MCP的AI代码编辑器。

配置方法

在Aider的配置文件中（通常 ~/.aider/config.json 或通过环境变量）：

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

在自定义应用程序中使用（程序化）

如果您正在开发自己的应用程序并希望集成MCP服务器，可以使用MCP SDK：

Types/JavaScript示例

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

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

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

// Connect
await client.connect(transport)

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

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

Python示例

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

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

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

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

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

MCP客户端快速参考

备注：The ~ in paths表示用户主目录，它展开为： - macOS/Linux： /Users/username 或 /home/username - 窗户： C:\Users\username

通用配置格式

所有兼容MCP的客户端都遵循相同的配置格式：

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

📝 环境变量引用

安全说明: 1. 永不承诺 .env 文件到版本控制。这 .env.example 文件仅作为模板提供。 1. 避免在中硬编码敏感凭据（密码、令牌） PROMPT_REPO_URL. 1. 使用SSH密钥(git@github.com...)用于安全、无密码的身份验证。 1. 对于生产，请使用Docker Secrets或您平台的秘密管理系统。

重要配置说明

1. 绝对路径：配置Cursor/Claude等客户端时，路径为 dist/index.js 必须是绝对的。
2. JSON格式：确保您的配置文件是有效的JSON（没有尾随逗号）。
3. 优先: env 在客户端配置中定义JSON覆盖 .env 文件夹。
4. 重启：更改配置后，始终重新启动AI编辑器/客户端。

验证MCP服务器是否正常运行

方法1：使用MCP检查器

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

这将启动一个web界面，您可以在其中：

• 查看所有加载的提示
• 测试提示输出
• 检查错误消息

备注：检查器运行 dist/index.js，因此修改源代码后，必须运行 build 首先看看最新的变化。

方法2：检查日志

在配置文件中添加环境变量以查看详细日志：

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

然后检查客户端的日志输出（Cursor的输出面板或Claude Desktop的日志）。

方法3：检查文件系统

验证Git存储库是否已成功同步：

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

您应该看到从Git存储库克隆的文件。

常见配置问题

问题1：找不到配置文件

解决方案:

• 确认应用程序已启动至少一次（将自动创建配置目录）
• 手动创建配置文件和目录
• 检查路径是否正确（注意区分大小写和空格）

问题2:JSON格式错误

解决方案:

• 使用JSON验证工具检查格式（例如。， Jsonlint)
• 确保所有字符串都使用双引号
• 确保最后一项后没有逗号

问题3：服务器无法启动

解决方案:

1. 确认 dist/index.js 文件存在
2. 确认路径为绝对路径
3. 确认Node.js已安装且版本>=18
4. 检查环境变量是否正确
5. 检查客户端错误日志

问题4：未找到提示

解决方案:

1. 确认 PROMPT_REPO_URL 是正确的
2. 检查是否 MCP_GROUPS 设置包括您想要的组

- 备注：如果 MCP_GROUPS 如果未设置，系统默认只加载 common 群组 - 检查日志消息以确认是否正在使用默认组 - 集 MCP_GROUPS=laravel,vue 等加载其他组

1. 确认Git存储库包含 .yaml 或 .yml 文件
2. 使用 LOG_LEVEL=debug 查看详细日志并确认加载了哪些组

📂 提示存储库结构

您的提示存储库（其中 PROMPT_REPO_URL points to）应具有以下结构：

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

组筛选规则

• 根目录 (/)：始终加载
• 公共组报文 (common/)：始终加载
• 其他组：仅在中指定时加载 MCP_GROUPS 环境变量

默认行为

当 MCP_GROUPS 是 未设置:

• 系统自动加载 common 组（和根目录提示）
• 启动日志将明确提示使用默认组
• 日志将包括建议设置的消息 MCP_GROUPS 加载更多组

例子

• MCP_GROUPS=laravel,vue → 加载根、普通、laravel、vue
• MCP_GROUPS= 或未设置→ 仅加载root和common（系统将提示使用默认值）

提示定义文件示例(.yaml)

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

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

｛｛code｝｝

参数类型

提示支持三种参数类型：

• string：字符串类型（默认）
• number：数字类型
• boolean：布尔类型

注册表功能（可选）

您可以创建 registry.yaml Prompt Repository根目录中的文件，用于集中管理提示可见性和弃用状态。

注册表文件格式

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

注册表字段说明

• id：提示ID（必填）
• group：组名（可选）
• visibility：可见性设置

- public：公共（默认） - private：私人 - internal：内部使用

• deprecated：是否已弃用（默认 false)

注册目的

• 集中管理：在单个文件中管理所有提示的可见性和弃用状态
• 覆盖默认值：可以覆盖提示定义文件中的默认设置
• 版本控制：通过Git跟踪提示生命周期

备注: registry.yaml 是可选的。如果不存在，系统将使用提示定义文件中的默认值。

提示运行时状态

每个提示符都有一个运行时状态(runtime_state)指示提示的当前可用性：

• active：活动状态，提示正常工作，可用作MCP工具
• legacy：传统状态，提示仍然可用，但标记为旧版本，建议使用新版本
• invalid：状态无效，提示定义有问题（例如，缺少必填字段、模板错误等），无法使用
• disabled：已禁用，提示被明确禁用（例如，在注册表中标记为已弃用）
• warning：警告状态，提示可以工作，但有一些警告（例如，版本太旧）

提示来源

每个提示都有一个来源(source)指示元数据来源的标签：

• embedded：提示定义文件中嵌入的元数据（使用 metadata: 块）
• registry：设置来自 registry.yaml
• legacy：传统模式，无元数据，使用默认值

提示状态

每个提示都有一个状态(status)指示提示的发展阶段：

• draft：草案，正在拟订中
• stable：稳定版本，可以正常使用
• deprecated：已弃用，不建议使用
• legacy：旧版本，仍然可用，但建议升级

🔧 MCP工具和资源

该项目提供了多种MCP工具和资源，用于管理和查询Prompts。

MCP工具

1. mcp.reload / mcp.reload_prompts

在不重新启动服务器的情况下重新加载所有提示（热重新加载）。

• 函数：从Git存储库中提取最新更改，清除缓存，重新加载所有Handlebars部分和提示
• 参数：无
• 用法示例:

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

2. mcp.stats / mcp.prompt.stats

获取提示统计数据。

• 函数：返回所有提示的统计信息，包括按运行时状态（活动、传统、无效、禁用、警告）计数
• 参数：无
• 返回内容:

- total：总计数 - active：活动状态计数 - legacy：遗留状态计数 - invalid：状态计数无效 - disabled：禁用计数 - warning：警告状态计数

3. mcp.list / mcp.prompt.list

列出所有带有多个筛选选项的提示。

• 函数：列出所有带有完整元数据信息的提示运行时
• 参数 （可选）：

- status：按状态筛选(draft, stable, deprecated, legacy) - group：按组名筛选 - tag：按标签筛选（提示必须包含此标签） - runtime_state：按运行时状态筛选(active, legacy, invalid, disabled, warning)

• 用法示例:

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

4. mcp.inspect

检查特定提示的详细运行时信息。

• 函数：通过Prompt ID获取完整的运行时元数据，包括状态、源、版本、标签和用例
• 参数:

- id：提示ID（必填）

• 用法示例:

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

5. mcp.repo.switch

切换到其他Prompt存储库并重新加载（零停机时间）。

• 函数：切换到新的Git存储库并重新加载所有提示
• 参数:

- repo_url：存储库URL（必需） - branch：分行名称（可选）

• 用法示例:

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

6. preview_prompt

使用给定的参数预览/呈现提示模板，而不执行它（调试实用程序）。

• 函数：呈现具有给定参数的提示模板，以显示最终文本，而不将其发送给LLM。使用此功能验证模板逻辑。
• 参数:

- promptId：提示ID（必填。， 'laravel:code-review') - args：包含模板参数/变量的JSON对象（必填）

• 退货:

- success：表示成功或失败的布尔值 - renderedText：呈现的提示文本 - highlightedText：以Markdown粗体突出显示变量的渲染文本 - statistics：对象包含 renderedLength （字符数）和 estimatedTokens （估计令牌计数） - warnings：架构验证警告数组（例如，缺少推荐字段）

• 用法示例:

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

• 高级功能:

- 架构验证：严格验证prompt的Zod模式的参数 - 令牌估计：估计令牌计数（支持英文和中文文本） - 可变突出显示：用Markdown粗体格式突出显示动态替换的变量 - 架构警告：检测并报告缺失的必填或推荐字段

MCP资源

1. system://health

系统健康状态资源。

• 统一资源标识符: system://health
• mime类型: application/json
• 内容：包括以下信息：

- git：Git存储库信息（URL、路径、HEAD提交） - prompts：提示统计信息（总计、按州计数、已加载计数、组列表） - registry：注册表状态（已启用，来源） - cache：缓存信息（大小、清理间隔） - system：系统信息（正常运行时间、内存使用情况）

2. prompts://list

提示列表资源。

• 统一资源标识符: prompts://list
• mime类型: application/json
• 内容：所有提示的完整元数据列表，包括：

- id：提示ID - title：标题 - version：版本 - status：状态 - runtime_state：运行时状态 - source：来源 - tags：标签数组 - use_cases：用例数组 - group：组名称 - visibility：可见性

工具使用建议

• 在开发过程中：使用 mcp.reload 在不重新启动服务器的情况下快速重新加载提示
• 调试期间：使用 mcp.inspect 查看特定提示的详细信息，或使用 preview_prompt 测试模板渲染
• 监测期间：使用 mcp.stats 和 system://health 用于监视系统状态的资源
• 查询过程中：使用 mcp.list 使用过滤条件查找特定提示
• 测试期间：使用 preview_prompt 要验证模板逻辑，请在实际执行之前检查令牌计数并查看变量替换

💻 开发指南

架构概述

MCP提示管理器遵循模块化架构，明确分离关注点：

核心组件

1. 存储库接口 (src/repositories/strategy.ts)

- 不同存储库类型（Git、Local）的抽象接口 - 支持基于优先级的加载的多种存储库策略 - 处理存储库同步和文件监视

1. 源管理器 (src/services/sourceManager.ts)

- 用于管理提示生命周期的Singleton模式 - 处理快速加载、缓存和注册 - 在加载时编译Handlebars模板以提高性能 - 管理提示运行时状态和元数据

1. 缓存层 (src/cache/)

- 支持本地和Redis（未来）的抽象缓存提供程序接口 - 具有LRU逐出和TTL支持的本地缓存 - 自动清理过期的缓存项

快速存储流

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

关键模块

• 存储库接口：Git和本地存储库的抽象策略模式
• 源管理器：使用缓存进行集中的快速生命周期管理
• 缓存提供程序：可插拔缓存系统（本地内存或Redis）
• 装载机：用于加载提示和部分的高级API
• MCP工具：基于加载的提示进行动态工具注册

项目结构

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

常用命令

# Compile TypeScript
npm run build
# or
pnpm run build

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

# Run tests
npm run test
# or
pnpm test

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

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

# Format code
npm run format
# or
pnpm format

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

开发流程

1. 修改代码 src/ 目录。
2. 跑 pnpm run build 重新编译（或使用 pnpm run inspector:dev 自动编译和测试）。
3. 跑 pnpm run test 运行测试。
4. 使用 pnpm run inspector:dev 验证更改（将自动编译并启动检查器）。
5. 在Cursor或Claude Desktop中重新启动MCP服务器以应用更改。

重要说明: - 这 inspector 命令运行 dist/index.js （编译文件） - 修改源代码后，必须运行 build 首先看到最新的变化 - 使用 inspector:dev 可以自动编译和启动，适合开发

提示存储库验证

我们建议使用 @carllee1983/prompt-toolkit 在部署到MCP prompt Manager之前，验证您的提示存储库。这确保了及时的质量，并在开发过程的早期发现错误。

安装

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

带验证的开发工作流程

1. 开发提示：在存储库中创建和编辑提示
2. 本地验证：在提交之前使用工具包进行验证

   prompt-toolkit validate repo

1. CI/CD验证：在CI/CD管道中自动验证

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

1. 部署到MCP提示管理器：MCP提示管理器加载经过验证的提示

快速验证命令

# Validate entire repository
prompt-toolkit validate repo

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

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

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

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

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

CI/CD集成

在部署前向CI/CD管道添加验证以捕获错误：

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

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

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

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

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

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

最佳实践

• ✅ 提交前验证：在推送更改之前，在本地运行验证
• ✅ 使用CI/CD：在CI/CD管道中自动验证以捕获错误
• ✅ 监测结果：跟踪验证结果以维护存储库运行状况
• ✅ 严重性过滤：使用 --severity 专注于关键问题的选择
• ✅ JSON输出：使用 --format json 用于CI/CD中的机器可读输出

程序化使用

您还可以在脚本中以编程方式使用该工具包：

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

有关更多信息，请参阅 提示工具包文档.

🧪 测试

该项目包括一个完整的测试套件：

• 单元测试：涵盖所有核心功能的多个测试文件
• 集成测试：对快速加载和MCP工具进行端到端测试
• 总计：107次测试，全部通过

运行测试：

# Watch mode
pnpm test

# Run once
pnpm test:run

# Open UI
pnpm test:ui

测试覆盖率

该项目通过以下阈值的全面测试覆盖率来保持高代码质量：

• 声明: ≥ 80%
• 线条: ≥ 75%
• 函数: ≥ 75%
• 分支: ≥ 70%

备注：覆盖率报告的使用 @vitest/coverage-v8 这需要Node.js 19+。强制执行覆盖阈值以保持代码质量。如果覆盖率低于阈值，测试将无法确保质量标准。

查看覆盖率报告

1. 地方发展：运行 pnpm test:coverage 生成覆盖率报告，或使用 pnpm test:coverage:view 在浏览器中自动打开HTML覆盖率报告。

1. CI/CD：运行 pnpm test:coverage:ci 生成覆盖率报告并执行阈值。如果不满足覆盖阈值，CI管道将失败，确保在合并或发布之前保持代码质量标准。

1. 覆盖范围报告：覆盖率报告在 coverage/ 具有多种格式的目录：

- coverage/index.html -交互式HTML报告 - coverage/coverage-final.json -用于CI集成的JSON格式 - coverage/lcov.info -覆盖服务的LCOV格式

覆盖命令

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

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

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

代码质量与CI/CD

该项目通过多层检查来强制执行代码质量：

预提交钩子

• ESLint：自动修复TypeScript文件中的linting问题
• 更漂亮：自动格式化代码以确保风格一致
• 类型安全：TypeScript严格模式已启用(strict: true 在 tsconfig.json)

预提交挂钩仅在暂存文件上运行，确保快速提交时间，同时保持代码质量。

持续集成（CI）

GitHub Actions CI工作流在每个推送和拉取请求上运行：

• Node.js兼容性：跨Node.js 16.x、18.x和20.x的测试
• 代码检查：ESLint检查代码质量和风格
• 类型检查：TypeScript类型检查(tsc --noEmit)
• 测试：具有覆盖率报告的完整测试套件
• 覆盖上传：自动上传到Codecov

Pull请求所需的检查

为确保代码质量，必须通过以下检查才能合并PR：

1. 棉绒：所有ESLint规则都必须通过
2. 类型检查：TypeScript编译必须成功且无错误
3. 测试：所有测试必须通过，并达到覆盖阈值

在GitHub中设置所需检查：

1. 转到存储库设置
2. 导航至 分支 → 分支保护规则
3. 为您的主分支添加或编辑规则
4. 在...之下 合并前需要通过状态检查，启用：

- Test (Node.js 16.x) 或 Test (Node.js 18.x) 或 Test (Node.js 20.x) （至少一个） - 这些检查将自动包括棉绒、类型检查和测试步骤

如果这些检查中的任何一项失败，CI工作流将自动失败，从而阻止合并不符合质量标准的代码。

🔧 配置

环境变量

缓存过期策略

该系统使用基于TTL的定期清理机制来管理文件列表缓存，确保内存效率。

高速缓存机制

• 缓存TTL：5秒（硬编码）
• 清理间隔：默认10秒(CACHE_TTL * 2)，可通过以下方式调节 CACHE_CLEANUP_INTERVAL 环境变量
• 自动清理：应用程序启动时，清理机制会自动启动
• 优雅地关闭：应用程序关闭时，清理计时器会自动停止

运作原理

1. 缓存创建：何时 getFilesRecursively() 调用时，扫描结果将缓存5秒
2. 定期清理：每10秒（或配置的间隔），自动扫描并删除过期的缓存项
3. 内存管理：防止缓存无限增长，避免内存泄漏

配置示例

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

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

监控缓存状态

您可以通过日志查看缓存清理状态（需要设置 LOG_LEVEL=debug):

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

验证缓存机制

看 CACHE_ERIFICATION.md 完整的验证方法和测试指南。

安全

• ✅ 输入验证：所有环境变量都使用Zod进行验证
• ✅ 路径安全：防止路径遍历攻击
• ✅ 组验证：组名格式验证（只允许字母、数字、下划线、破折号）

📝 日志记录

该项目使用 皮诺 作为测井系统，支持结构化测井。

日志级别

• fatal：导致程序退出的致命错误
• error：错误消息
• warn：警告信息
• info：一般信息
• debug：调试消息
• trace：跟踪消息
• silent：完全禁用日志输出

默认行为:

• 生产环境 (NODE_ENV 未设置或未设置 development)：默认为 warn，仅输出警告和错误
• 开发环境 (NODE_ENV=development)：默认为 info，输出所有信息级别及以上日志
• 可以通过以下方式覆盖默认值 LOG_LEVEL 环境变量

设置日志级别

# Set in .env
LOG_LEVEL=debug

# Or set in environment variables
export LOG_LEVEL=debug

❓ 常见问题解答和故障排除

Q： 如何安装MCP提示管理器？

A.：有三种安装选项：

1. 市场安装 （最简单）：从MCP市场安装，如 mcp.so
2. Docker部署 （推荐用于生产环境）：使用Docker Compose便于部署
3. 本地安装 （用于开发）：克隆存储库并在本地构建

请参阅 快速开始 详细说明部分。

Q： 在市场安装后，我如何找到安装路径？

A.：使用以下命令查找已安装的服务器：

macOS/Linux:

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

视窗:

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

Q： 为什么我需要在配置中使用绝对路径？

A.：MCP客户端将服务器作为单独的进程执行，需要完整的路径来定位可执行文件。相对路径不起作用，因为工作目录可能不同。

Q： 配置后，服务器未出现在我的MCP客户端中。

A.：尝试以下步骤：

1. 验证路径是否为绝对路径：检查一下 args 包含完整的绝对路径，而不是相对路径
2. 检查是否安装了Node.js：运行 node --version 确保已安装Node.js 18+
3. 验证文件是否存在：确保 dist/index.js 存在于指定路径
4. 检查JSON语法：验证配置文件是否为有效的JSON（无尾随逗号）
5. 完全重新启动：完全关闭并重新启动MCP客户端（而不仅仅是重新加载）
6. 检查日志：启用 LOG_LEVEL=debug 在您的配置中查看详细的错误消息

Q： 如何在本地运行服务器？

A.：您可以使用 pnpm dev 用于开发（与检查员一起）或 pnpm start 对于生产模式。看 package.json 脚本以获取更多详细信息。

Q： 我遇到Git克隆错误（退出代码128）。

A.：这通常意味着权限问题或URL无效。

1. SSH与HTTPS：如果使用SSH(git@github.com...)，确保您的SSH密钥已正确安装或可用。如果使用HTTPS，请确保您不需要令牌（或提供令牌）。
2. 已知主机：如果在Docker中运行，请确保 ssh-keyscan 被跑步或你的 known_hosts 文件已装载。
3. 回购有效期：手动尝试 git clone 在您的计算机上验证URL。

问题：Git同步失败（常规）

解决方案:

1. 检查是否 PROMPT_REPO_URL 是正确的
2. 确认网络连接正常
3. 检查Git凭据是否正确
4. 检查日志以获取详细的错误消息

问题：未加载提示

解决方案:

1. 检查是否 MCP_GROUPS 设置正确
2. 确认提示文件位于正确的目录结构中(prompts//...)
3. 检查YAML文件格式是否正确
4. 检查日志中的错误消息

问题：不能使用偏号

解决方案:

1. 确认部分文件扩展名为 .hbs
2. 确认部分内容在 partials/ 目录
3. 检查部分文件内容是否正确
4. 确认使用 {{> partial-name }} 模板中的语法

📦 关键依赖关系

• @模型上下文协议/sdk：MCP SDK，提供MCP服务器核心功能
• 把手：Handlebars模板引擎，支持动态生成Prompt
• 简单git：用于同步Git存储库的Git操作库
• js yaml：用于解析Prompt定义文件的YAML解析器
• 黄道带：TypeScript第一个用于配置和类型验证的模式验证库
• 皮诺：高性能结构化日志库
• Dotenv。：环境变量加载实用程序

📚 相关资源

• 模型上下文协议官方文档
• 手柄杆文档
• Zod文档
• 简单Git文档
• Pino文档
• @carllee1983/prompt工具包 -MCP的快速存储库验证工具包

📄 许可证

国际学生委员会

🤝 贡献

欢迎提交问题和拉取请求！

______________________________________________________________________

版本: 1.0.0\ 最后更新: 2024-11-30