prompt2mcp 📝➡️🛠️

An MCP (Model Context Protocol) server that automatically converts your VS Code prompt files into MCP tools, making your custom prompts available to AI assistants and applications.

🌟 Features

• Automatic Discovery: Scans VS Code workspace and user prompt directories
• Hot Reloading: Automatically detects when prompt files are added, modified, or deleted
• Smart Exclusion: Respects prompt2mcp:false flag to exclude specific prompts
• Intelligent Analysis: Automatically categorizes prompts and generates smart descriptions
• Diverse Prompt Support: Handles architecture, documentation, task planning, code review, and more
• Metadata Support: Parses YAML frontmatter for descriptions, modes, and other settings
• Multiple Locations: Supports both workspace (.github/prompts) and user profile prompts
• Cross-Platform: Works on Windows, macOS, and Linux

🚀 Quick Start

Installation

Using uv (recommended):

# Clone and setup the project
git clone <repository-url>
cd prompt2mcp
uv sync

Using pip:

pip install prompt2mcp

Running the Server

# Run with uv (recommended)
uv run python -m prompt2mcp

# Or run directly if installed
python -m prompt2mcp

Configuration with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "prompt2mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/prompt2mcp", "python", "-m", "prompt2mcp"]
    }
  }
}

📁 Prompt File Locations

The server automatically scans these locations for .prompt.md files:

Workspace Prompts

• .github/prompts/ (in current workspace and parent directories)

User Profile Prompts

• Windows: %APPDATA%\Code\User\prompts\ or %APPDATA%\Code - Insiders\User\prompts\
• macOS: ~/Library/Application Support/Code/User/prompts/ or ~/Library/Application Support/Code - Insiders/User/prompts/
• Linux: ~/.config/Code/User/prompts/ or ~/.config/code-insiders/User/prompts/

📝 Prompt File Format

Prompt files follow the VS Code prompt file format:

Basic Format

# My Custom Prompt

This is the instruction content that will be provided to the AI assistant.

With YAML Frontmatter

---
description: "Custom instructions for code review"
mode: "edit"
model: "claude-3-5-sonnet"
tools: ["filesystem", "search"]
---

# Code Review Instructions

Please review this code for:
- Security vulnerabilities
- Performance issues  
- Best practices compliance

Exclusion from MCP

To exclude a prompt file from being converted to an MCP tool:

Option 1: At the beginning of the file

prompt2mcp:false

# This prompt won't become an MCP tool

Option 2: In YAML frontmatter

---
description: "Internal notes only"
prompt2mcp: false
---

# This prompt won't become an MCP tool

🛠️ How It Works

1. Discovery: Scans configured directories for .prompt.md files
2. Parsing: Extracts metadata from YAML frontmatter and content
3. Tool Creation: Each prompt becomes an MCP tool with:
   • Name derived from filename
   • Description from frontmatter or filename
   • Parameters for additional context and specific tasks
4. Hot Reloading: Monitors file changes and updates tools automatically

🔧 Tool Parameters

Each generated MCP tool accepts these parameters:

• context (string, optional): Additional context or information
• task (string, optional): Specific task or question to address

🎯 Example Usage

Once configured, your prompts become available as tools in MCP clients:

1. Tool Discovery: MCP clients can list all available prompt tools
2. Tool Execution: Execute a tool to get the prompt instructions
3. Dynamic Updates: Tools automatically update when prompt files change

🔍 Logging

The server logs to stderr (not stdout, which is used for MCP communication):

• Discovered prompt files and directories
• File system changes and updates
• Tool executions and errors

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🐛 Troubleshooting

No Tools Found

• Check that prompt files exist in expected locations
• Ensure files have .prompt.md extension
• Verify files don't have prompt2mcp:false exclusion

Server Not Starting

• Check Python version (requires 3.10+)
• Verify MCP dependencies are installed
• Check stderr output for error messages

Tools Not Updating

• File watching may not be working
• Try restarting the MCP server
• Check file permissions in prompt directories

🔗 Related Projects

• Model Context Protocol
• VS Code Prompt Files Documentation
• MCP Python SDK