MCP提示管理器（Git驱动）

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

](https://github.com/CarlLee1983/mcp-prompt-manager) ![License](LICENSE) ![TypeScript](https://www.typescriptlang.org/) ](https://nodejs.org/)

英语 | 繁体中文

📋 引言

这是一个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.安装

首先，克隆此项目并安装依赖项：

git clone 

cd mcp-prompt-manager
npm install
# or use pnpm (recommended)
pnpm install

注：安装使用pnpm强制执行；由于预安装检查，npm/yarn将失败。

2.配置环境变量

复制示例配置文件并创建 .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

3.建造

npm run build
# or
pnpm run build

🛠️ 用法

检验员测试

我们提供了一个方便的命令来启动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：在光标中，按 Cmd/Ctrl + Shift + P，搜索“MCP:添加服务器” - 方法2：直接编辑 mcp.json 文件位于上面的路径

编辑配置文件:

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

重要配置说明:

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

验证配置:

- 重新启动游标 - 在光标中，按 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

配置步骤

创建或编辑配置文件:

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

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

编辑配置文件:

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

验证配置:

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

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

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

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

配置步骤

安装MCP扩展:

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

配置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客户端快速参考

客户端	配置文件位置	配置格式	注释
光标	`~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json` （macOS）	`mcpServers`	支持UI配置
克劳德桌面版	`~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）	`mcpServers`	需要完全重新启动
VS Code	`settings.json`	`mcp.servers`	需要MCP扩展
继续	`~/.continue/config.json`	`mcpServers`	开源AI助手
帮助	`~/.aider/config.json`	`mcp_servers`	AI代码编辑器

备注：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"
            }
        }
    }
}

配置字段说明

command：执行命令（通常 node)
args：命令参数数组，必须包含编译后的绝对路径 dist/index.js
env：环境变量对象（可选）

- PROMPT_REPO_URL：Git存储库URL或本地路径（必需） - MCP_LANGUAGE：输出语言， en 或 zh （可选，默认 en) - MCP_GROUPS：要加载的组，逗号分隔（可选，默认为仅加载 common 未设置组时，系统将在日志中提示） - STORAGE_DIR：本地缓存目录（可选） - GIT_BRANCH：Git分支（可选，默认 main) - GIT_MAX_RETRIES：Git重试计数（可选，默认值 3) - CACHE_CLEANUP_INTERVAL：缓存清理间隔（毫秒）（可选，默认值 10000) - LOG_LEVEL：日志级别（可选，默认 info)

重要说明

绝对路径：路径在 args 必须是绝对路径，不能使用相对路径
JSON格式：确保JSON格式正确，最后一项后没有逗号
环境变量优先级: env 在JSON中覆盖了在 .env 文件
重新开始应用程序：修改配置后，必须完全重新启动应用程序才能使更改生效

验证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：服务器无法启动

解决方案:

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

问题4：未找到提示

解决方案:

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

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

确认Git存储库包含 .yaml 或 .yml 文件
使用 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"
    }
  }

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 查看特定提示的详细信息
监测期间：使用 mcp.stats 和 system://health 用于监视系统状态的资源
查询过程中：使用 mcp.list 使用过滤条件查找特定提示

💻 开发指南

项目结构

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
│   ├── 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
├── test/                      # Test files
│   ├── config.test.ts
│   ├── loaders.test.ts
│   ├── promptMetadata.test.ts
│   ├── utils.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

开发流程

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

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

🧪 测试

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

单元测试：53个测试用例
集成测试：9个测试用例
总计：62项测试，全部通过

运行测试：

# Watch mode
pnpm test

# Run once
pnpm test:run

# Open UI
pnpm test:ui

🔧 配置

环境变量

变量名称	必填	默认值	描述
`PROMPT_REPO_URL`	✅	-	Git存储库URL或本地路径
`MCP_LANGUAGE`	❌	`en`	输出语言(`en` 或 `zh`)
`MCP_GROUPS`	❌	`common`	要加载的组（逗号分隔），未设置时系统将提示默认行为
`STORAGE_DIR`	❌	`.prompts_cache`	本地缓存目录
`GIT_BRANCH`	❌	`main`	Git分支名称
`GIT_MAX_RETRIES`	❌	`3`	Git操作的最大重试次数
`CACHE_CLEANUP_INTERVAL`	❌	`10000`	缓存清理间隔（毫秒），定期清理过期的缓存项
`LOG_LEVEL`	❌	`warn` （prod）/ `info` （dev）	日志级别，生产默认仅显示警告和错误

缓存过期策略

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

高速缓存机制

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

运作原理

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

配置示例

# 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

🐛 故障排除

问题：Git同步失败

解决方案:

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

问题：未加载提示

解决方案:

检查是否 MCP_GROUPS 设置正确
确认提示文件位于正确的目录结构中
检查YAML文件格式是否正确
检查日志中的错误消息

问题：不能使用偏号

解决方案:

确认部分文件扩展名为 .hbs
检查部分文件内容是否正确
确认使用 {{> partial-name }} 模板中的语法

📦 关键依赖关系

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

📚 相关资源

📄 许可证

ISC

🤝 贡献

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

______________________________________________________________________

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

MCP Prompts Repo

快速接入

详细介绍

MCP提示管理器（Git驱动）

📋 引言

✨ 特性

🚀 快速开始

1.安装

2.配置环境变量

3.建造

🛠️ 用法

检验员测试

基本用法

快速开发模式

检查器功能

在游标中使用

配置文件位置

配置步骤

在Claude桌面中使用

配置文件位置

配置步骤

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

配置步骤

继续使用

配置文件位置

配置步骤

在Aider中使用

配置方法

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

Types/JavaScript示例

Python示例

MCP客户端快速参考

通用配置格式

配置字段说明

重要说明

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

方法1：使用MCP检查器

方法2：检查日志

方法3：检查文件系统

常见配置问题

问题1：找不到配置文件

问题2:JSON格式错误

问题3：服务器无法启动

问题4：未找到提示

📂 提示存储库结构

组筛选规则

默认行为

例子

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

参数类型

注册表功能（可选）

注册表文件格式

注册表字段说明

注册目的

提示运行时状态

提示来源

提示状态

🔧 MCP工具和资源

MCP工具

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

MCP资源

1. system://health

2. prompts://list

工具使用建议

💻 开发指南

项目结构

常用命令

开发流程

🧪 测试

🔧 配置

环境变量

缓存过期策略

高速缓存机制

运作原理

配置示例

监控缓存状态

提示定义文件示例(`.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`

1. `system://health`

2. `prompts://list`