MCP Prompt Manager (Git-Driven)

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

English | 繁體中文

📋 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:

1. Install via marketplace: Use the marketplace's installation interface

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

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

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

3. 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):

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:

Windows:

Verification

After configuration:

1. Restart your MCP client completely

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

3. 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:

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

1. Clone the Repository:

2. Install Dependencies:

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

3. Build the Project:

This compiles TypeScript to JavaScript in the dist/ directory.

4. Configure Environment Variables:

Copy the example configuration file and create .env:

Edit the .env file to set your Prompt Git Repository path or URL:

5. Configure MCP Client:

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

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:

🛠️ 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:

Quick Development Mode

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

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:

Windows:

Linux:

Configuration Steps

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

2. Edit the configuration file:

3. 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)

4. 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:

Windows:

Linux:

Configuration Steps

1. Create or edit the configuration file:

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

2. Edit the configuration file:

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

1. Install MCP Extension:

   • Search for "MCP" or "Model Context Protocol" in VS Code Extension Marketplace

   • Install the corresponding extension

2. Configure MCP Server:

   • Open VS Code settings (Cmd/Ctrl + ,)

   • Search for "MCP" related settings

   • Or edit settings.json:

Using in Continue

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

Configuration File Location

macOS:

Windows:

Linux:

Configuration Steps

Edit config.json:

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

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

Python Example

MCP Client Quick Reference

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:

📝 Environment Variables Reference

Security Note:

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

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

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

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

Important Configuration Notes

1. Absolute Paths: When configuring clients like Cursor/Claude, paths to dist/index.js must be absolute.

2. JSON Format: Ensure your config file is valid JSON (no trailing commas).

3. Precedence: env defined in client config JSON overrides .env files.

4. Restart: Always restart your AI editor/client after changing configuration.

Verifying MCP Server is Running Properly

Method 1: Using MCP Inspector

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:

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:

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:

1. Confirm dist/index.js file exists

2. Confirm path is absolute

3. Confirm Node.js is installed and version >= 18

4. Check if environment variables are correct

5. Check client error logs

Issue 4: No Prompts Found

Solution:

1. Confirm PROMPT_REPO_URL is correct

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

3. Confirm Git repository contains .yaml or .yml files

4. 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:

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)

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

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

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

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

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

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

Common Commands

Development Workflow

1. Modify code in the src/ directory.

2. Run pnpm run build to recompile (or use pnpm run inspector:dev to auto-compile and test).

3. Run pnpm run test to run tests.

4. Use pnpm run inspector:dev to verify changes (will auto-compile and start Inspector).

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

Development Workflow with Validation

1. Develop Prompts: Create and edit prompts in your repository

2. Validate Locally: Use the toolkit to validate before committing

   prompt-toolkit validate repo

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

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

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

Quick Validation Commands

CI/CD Integration

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

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:

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:

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

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

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

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

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:

1. Lint: All ESLint rules must pass

2. Typecheck: TypeScript compilation must succeed with no errors

3. Tests: All tests must pass with coverage thresholds met

Setting up Required Checks in GitHub:

1. Go to your repository settings

2. Navigate to Branches → Branch protection rules

3. Add or edit a rule for your main branch

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

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

1. Cache Creation: When getFilesRecursively() is called, scan results are cached for 5 seconds

2. Periodic Cleanup: Every 10 seconds (or configured interval), automatically scans and removes expired cache items

3. Memory Management: Prevents cache from growing indefinitely, avoiding memory leaks

Configuration Examples

Monitor Cache Status

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

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

❓ FAQ & Troubleshooting

Q: How do I install MCP Prompt Manager?

A: There are three installation options:

1. Marketplace Installation (Easiest): Install from an MCP marketplace like mcp.so

2. Docker Deployment (Recommended for production): Use Docker Compose for easy deployment

3. 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:

Windows:

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:

1. Verify the path is absolute: Check that args contains a full absolute path, not a relative one

2. Check Node.js is installed: Run node --version to ensure Node.js 18+ is installed

3. Verify the file exists: Ensure dist/index.js exists at the specified path

4. Check JSON syntax: Validate your configuration file is valid JSON (no trailing commas)

5. Restart completely: Fully close and restart your MCP client (not just reload)

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

1. 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).

2. Known Hosts: If running in Docker, ensure ssh-keyscan was run or your known_hosts file is mounted.

3. Repo Validity: Manually try git clone <URL> on your machine to verify the URL.

Issue: Git Sync Failed (General)

Solution:

1. Check if PROMPT_REPO_URL is correct

2. Confirm network connection is normal

3. Check if Git credentials are correct

4. Check logs for detailed error messages

Issue: No Prompts Loaded

Solution:

1. Check if MCP_GROUPS setting is correct

2. Confirm prompt files are in the correct directory structure (prompts/<group>/...)

3. Check if YAML file format is correct

4. Check error messages in logs

Issue: Partials Cannot Be Used

Solution:

1. Confirm partial file extension is .hbs

2. Confirm partials are in the partials/ directory

3. Check if partial file content is correct

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

📚 Related Resources

• 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