prompt-mcp

A Model Context Protocol (MCP) server for managing and sharing curated prompts across development teams.

⚠️ TEST STATUS / TESTSTATUS
This package is currently in public testing phase. The example prompts in our test repository
otto-de/otto_prompts_collection are for
demonstration and testing purposes only. Please do not use these prompts in production environments.

🧪 TESTZWECKE
Dieses Package befindet sich in der öffentlichen Testphase. Die Beispiel-Prompts im Test-Repository
otto-de/otto_prompts_collection dienen nur zu
Demonstrations- und Testzwecken. Bitte verwenden Sie diese Prompts nicht in Produktionsumgebungen.

✨ Features

• 🔄 Git & Local Repositories: Load prompts from Git repositories or local directories
• 🏷️ Smart Organization: Alias & label-based prompt organization with fuzzy search
• 🎯 VS Code Copilot Integration: Export prompts directly to VS Code Custom Prompts
• 🔍 Advanced Search: Filter by name, tags, or aliases with fuzzy matching
• ⚡ Auto-Refresh: Automatic cache invalidation and background updates
• 📝 Template Support: Mustache template engine with JSON Schema validation
• 🔒 Governance: Version management, ownership, and visibility controls

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g prompt-mcp

# Or use with npx (no installation required)
npx prompt-mcp@latest

VS Code Setup

Step 1: Install the Package

npm install -g prompt-mcp

Step 2: Configure VS Code Settings

Add this to your VS Code settings (settings.json):

{
  "chat.promptFiles": true,
  "chat.promptFilesLocations": [
    {
      "location": "~/.prompts"
    }
  ]
}

Step 3: Configure MCP Server

Add this to your VS Code mcp.json:

{
  "mcpServers": {
    "prompt-mcp-server": {
      "command": "prompt-mcp-server",
      "env": {
        "PROMPT_SOURCES": "https://github.com/your-org/your-prompts.git",
        "COPILOT_OUTPUT_DIR": "~/.prompts"
      }
    }
  }
}

Step 4: Restart VS Code

After configuration, restart VS Code to load the MCP server.

Step 5: Test the Connection

Use VS Code Command Palette (Cmd+Shift+P / Ctrl+Shift+P):This enables VS Code to recognize and use the exported .prompt.md files from the MCP server.

Step 4: Find Your Global Installation Path (if needed)

If you prefer to use a direct path instead of the global binary: "PROMPT_MCP_AUTO_REFRESH": "1", "PROMPT_MCP_AUTO_REFRESH_INTERVAL": "60", "PROMPT_MCP_NOTIFY_UPDATES": "1", "PROMPT_MCP_AUTO_SYNC_SCOPES": "techwriting,backend", "COPILOT_OUTPUT_DIR": "~/.prompts" }, "type": "stdio" } } } }

#### Step 3: Find Your Global Installation Path

```bash
# Find global npm path
npm root -g

# Example paths:
# macOS with nvm: ~/.nvm/versions/node/v22.14.0/lib/node_modules
# macOS with Homebrew: /usr/local/lib/node_modules  
# Windows: %APPDATA%/npm/node_modules

Update the args path in your mcp.json accordingly.

Step 4: Restart VS Code

After configuration, restart VS Code to load the MCP server.

Step 5: Test the Connection

Use VS Code Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Use VS Code Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`):

MCP: prompt_health MCP: prompt_list

## ⚠️ Important Notice for Production Use

### Test Repository Disclaimer

The example repository [`otto-de/otto_prompts_collection`](https://github.com/otto-de/otto_prompts_collection) 
contains **test prompts only** and is publicly accessible for demonstration purposes. 

**For production use:**

1. **Create your own private repository** with your organization's prompts
2. **Update the `PROMPT_MCP_SOURCES`** configuration to point to your repository
3. **Review and validate all prompts** before adding them to your production repository
4. **Use proper access controls** (private repositories, SSH keys, access tokens)

### Example Production Configuration

```json
{
  "PROMPT_MCP_SOURCES": "[{\"type\":\"git\",\"id\":\"production\",\"url\":\"[email protected]:your-company/internal-prompts.git\",\"ref\":\"main\",\"path\":\"prompts\"}]"
}

📁 Prompt Repository Structure

### Alternative: Workspace-Specific Setup

For project-specific configuration, create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "prompt-mcp": {
      "command": "npx", 
      "args": ["prompt-mcp@latest"],
      "env": {
        "PROMPT_MCP_SOURCES": "[{\"type\":\"local\",\"id\":\"workspace\",\"path\":\"./prompts\"}]",
        "COPILOT_OUTPUT_DIR": "${workspaceFolder}/.vscode/prompts"
      }
    }
  }
}

Basic Usage

1. List all prompts:

   > MCP: prompt_list

2. Get a specific prompt:

   > MCP: prompt_get {"id": "tech-review"}

3. Sync to VS Code Copilot:

   > MCP: prompt_sync_copilot {"scope": "techwriting"}

4. Check server health:

   > MCP: prompt_health

📁 Prompt Repository Structure

# prompts/techwriting/review.yaml
id: tech-review
name: Technical Writing Review
version: 1.0.0
owners: [techwriting-team]
visibility: internal
labels: [documentation, review, editing]
aliases: [doc-review, tw-review]

copilot:
  mode: edit
  tools: ['codebase', 'markdownlint']
  description: Review and improve technical documentation

inputSchema:
  type: object
  properties:
    content:
      type: string
      description: Original document content
  required: [content]

prompt:
  system: |
    You are a technical writing expert. Review and improve documents for clarity and consistency.
  user: |
    Please review and improve this document:
    
    {{content}}

🛠️ Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PROMPT_MCP_SOURCES | JSON array of prompt sources | [] | | PROMPT_MCP_TTL_SECONDS | Cache TTL in seconds | 3600 | | PROMPT_MCP_AUTO_REFRESH | Enable auto-refresh (1/0) | 0 | | PROMPT_MCP_AUTO_REFRESH_INTERVAL | Auto-refresh interval in minutes | 60 | | PROMPT_MCP_NOTIFY_UPDATES | Enable update notifications (1/0) | 0 | | PROMPT_MCP_AUTO_SYNC_SCOPES | Comma-separated scopes for auto-sync | `` | | COPILOT_OUTPUT_DIR | Directory for Copilot exports | ~/.prompts | | LOG_LEVEL | Logging level (debug/info/warn/error) | info |

Source Configuration Examples

Git Repository Source

{
  "type": "git",
  "id": "shared-prompts",
  "url": "https://github.com/otto-de/otto_prompts_collection.git",
  "ref": "main", 
  "path": "prompts/"
}

Local Directory Source

{
  "type": "local",
  "id": "workspace-prompts",
  "path": "./prompts"
}

SSH Git Repository

{
  "type": "git", 
  "id": "private-prompts",
  "url": "[email protected]:company/private-prompts.git",
  "ref": "main",
  "path": "team-prompts/"
}

Advanced Configuration

Multiple Git Sources with Authentication

sources:
  # GitHub with token
  - type: git
    id: shared-prompts
    url: https://github.com/company/prompts.git
    auth: env:GITHUB_TOKEN
    ref: main
    path: prompts/

  # GitLab with SSH
  - type: git
    id: team-prompts
    url: [email protected]:team/prompts.git
    auth: ssh
    ref: develop
    path: team-prompts/

  # Local development
  - type: local
    id: local-dev
    path: ./dev-prompts

cache:
  ttlSeconds: 300  # 5 minutes for dev
  dir: ~/.cache/prompt-mcp-dev

export:
  copilot:
    baseDir: .vscode/prompts
    prune: true

VS Code Workspace Configuration

// .vscode/mcp.json
{
  "mcpServers": {
    "prompt-mcp-server": {
      "command": "prompt-mcp-server",
      "env": {
        "PROMPT_SOURCES": "https://github.com/your-org/your-prompts.git",
        "COPILOT_OUTPUT_DIR": "${workspaceFolder}/.vscode/prompts"
      }
    }
  }
}

🔧 Available Tools

The MCP server provides 9 tools for prompt management:

Core Tools

| Tool | Parameters | Description | |------|------------|-------------| | prompt_list | { filter?: string } | List all prompts with optional filtering by id/alias/label | | prompt_get | { id: string, version?: string } | Retrieve a specific prompt by ID (latest version if not specified) | | prompt_refresh | {} | Asynchronously refresh prompt cache from all sources | | prompt_refresh_sync | {} | Synchronously refresh prompt cache and wait for completion |

Export Tools

| Tool | Parameters | Description | |------|------------|-------------| | prompt_sync_copilot | { scope?: string, dir?: string, prune?: boolean } | Export prompts to VS Code Custom Prompts format |

Scope Options:

• all (default) - Export all prompts
• id:prompt-name - Export specific prompt by ID
• ids:name1,name2 - Export multiple prompts by ID
• labels:tag - Export prompts with specific label
• regex:pattern - Export prompts matching regex pattern

Utility Tools

| Tool | Parameters | Description | |------|------------|-------------| | prompt_health | {} | Health check, configuration info, and refresh status | | prompt_refresh_status | {} | Check status of the last refresh operation | | prompt_tools | {} | List all available tools | | prompt_debug_echo | {} | Debug tool to verify MCP communication |

Usage Examples

// List all techwriting prompts
> MCP: prompt_list { "filter": "labels:techwriting" }

// Get specific prompt
> MCP: prompt_get { "id": "code-review", "version": "1.2.0" }

// Export prompts for VS Code
> MCP: prompt_sync_copilot { 
    "scope": "labels:frontend", 
    "dir": ".vscode/prompts",
    "prune": true 
  }

// Check system health
> MCP: prompt_health {}

🎯 VS Code Integration

Custom Prompts Export

The server can export prompts directly to VS Code's Custom Prompts format:

> MCP: prompt_sync_copilot {
    "scope": "techwriting",
    "dir": ".vscode/prompts",
    "prune": true
  }

This creates .prompt.md files in your workspace that VS Code can use directly.

Example Generated Prompt

---
mode: edit
tools: [codebase, markdownlint]
description: Review and improve technical documentation
---

# Technical Writing Review

Review and improve this document:

{{content}}

📖 Advanced Usage

Filtering and Search

// List prompts by label
prompt_list({"filter": "documentation"})

// Search by alias
prompt_get({"id": "doc-review"})  // resolves to tech-review

// Get specific version
prompt_get({"id": "tech-review", "version": "1.0.0"})

Governance Features

• Ownership: Define prompt owners and teams
• Visibility: Control access (public/team/internal)
• Versioning: Semantic versioning with changelog
• Validation: JSON Schema validation for inputs

🔍 Troubleshooting

VS Code MCP Server Issues

Server Not Starting

1. Check global installation:

   npm list -g prompt-mcp
   which prompt-mcp

2. Verify path in mcp.json:

   # Find your global node_modules path
   npm root -g
   # Adjust the path in mcp.json accordingly

3. Check VS Code logs:

   • Open VS Code Developer Tools (Help > Toggle Developer Tools)
   • Look for MCP-related errors in Console

4. Test direct server execution:

   node /path/to/prompt-mcp/dist/src/server.js
   # Should start without errors

Tools Not Appearing

1. Restart VS Code after configuration changes
2. Check MCP extension is enabled
3. Test connection:

   > MCP: prompt_health

Git Authentication Issues

1. SSH Keys: Ensure SSH keys are configured for git repositories
2. HTTPS with Token: Use personal access tokens for private repos:

   {
     "type": "git",
     "url": "https://[email protected]/org/repo.git"
   }

Common Configuration Issues

Environment Variables

• JSON Format: Ensure PROMPT_MCP_SOURCES is valid JSON
• Path Separators: Use forward slashes / even on Windows
• Tilde Expansion: Use full paths instead of ~ in some environments

Cache Issues

1. Clear cache directory:

   rm -rf ~/.cache/prompt-mcp

2. Force refresh:

   > MCP: prompt_refresh_sync

Debug Mode

Enable detailed logging:

{
  "env": {
    "LOG_LEVEL": "debug",
    "DEBUG": "prompt-mcp:*"
  }
}

🤝 Contributing

Development Setup

git clone https://github.com/otto-de/prompt-mcp.git
cd prompt-mcp
npm install
npm run build
npm test

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- loader.test.ts

Adding New Features

1. Add tests first - Follow TDD approach
2. Update schemas - Extend prompt YAML schema if needed
3. Update documentation - Keep README.md current
4. Test VS Code integration - Verify MCP tools work correctly

Release Process

npm version patch|minor|major
npm run build
npm test
npm publish
git push --tags

📄 License

MIT License - see LICENSE file for details.

Created with ❤️ for better prompt management and collaboration.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol SDK
• Inspired by the need for better prompt governance in development teams
• Special thanks to the VS Code team for Custom Prompts support