@promptprojectmanager/mcp-server

MCP server that exposes Prompt Project Manager workspace prompts through dual interfaces: Prompts (slash commands) and Tools (AI-discoverable).

Overview

@promptprojectmanager/mcp-server is a standalone npm package that integrates your Prompt Project Manager workspace with Claude Code via the Model Context Protocol (MCP). It exposes your prompts through two complementary interfaces:

1. Prompts Interface (Slash Commands) - Explicitly invoke prompts via /ppm:workspace:prompt commands
2. Tools Interface (AI Discovery) - AI assistants can discover and invoke prompts naturally through conversation

Both interfaces use the same underlying prompts and return identical flattened content. Choose explicit commands when you know exactly which prompt to use, or let the AI discover the right prompt for your task.

Features

• 🔐 Secure Authentication - Uses API keys from your Prompt Project Manager Settings page
• 🎯 Selective Exposure - Only prompts with "Expose to MCP" enabled appear
• 🏢 Workspace Scoping - Commands namespaced by workspace (e.g., personal-prompt, work-prompt)
• 🤖 Dual Interface - Both slash commands AND AI-discoverable tools
• ⚡ Zero Configuration - Works out of the box with npx
• 📝 Flattened Content - Returns pre-computed prompts with all resources embedded
• 🔄 Flexible Caching - Choose between cached (fast) or lazy loading (always fresh) modes

Installation

No installation required! Use npx to run the server directly:

npx @promptprojectmanager/mcp-server

Configuration

Quick Start (Recommended)

The easiest way to configure the MCP server is through Prompt Project Manager Settings page:

1. Visit https://promptprojectmanager.com/settings
2. Scroll to "MCP Server Configuration" section
3. Select your CLI tool (Claude Code, Codex CLI, or Gemini CLI)
4. Toggle "Lazy Loading" ON or OFF based on your preference
5. Click "Copy Configuration" button
6. Paste the configuration into your CLI's settings file

The settings page automatically generates the correct format (JSON or TOML) with your API key pre-filled and @latest package versioning. See Multi-CLI Support below for details on each CLI tool.

Manual Configuration

If you prefer to configure manually:

Step 1: Get Your API Key

1. Visit your Prompt Project Manager Settings page: https://promptprojectmanager.com/settings
2. Your API key is auto-generated and displayed in the "API Keys" section
3. Copy your API key (starts with api_key_)

Step 2: Configure Your CLI Tool

Claude Code (JSON)

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "tpe": {
      "command": "npx",
      "args": ["@promptprojectmanager/mcp-server@latest"],
      "env": {
        "PPM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Codex CLI (TOML)

Add to ~/.codex/config.toml in the [mcp_servers] section:

[mcp_servers.tpe]
command = "npx"
args = ["@promptprojectmanager/mcp-server@latest"]

[mcp_servers.tpe.env]
PPM_API_KEY = "your_api_key_here"

Gemini CLI (JSON)

Add to ~/.gemini/settings.json in the mcpServers object:

{
  "mcpServers": {
    "tpe": {
      "command": "npx",
      "args": ["@promptprojectmanager/mcp-server@latest"],
      "env": {
        "PPM_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Lazy Loading:

Add --lazy-loading to the args array for any CLI:

"args": ["@promptprojectmanager/mcp-server@latest", "--lazy-loading"]

See Caching Modes below to choose which configuration is right for you.

Step 3: Enable Prompts for MCP

1. Open any prompt in your ContextFS workspace
2. Check the "Expose to MCP" checkbox in the prompt editor
3. Save the prompt
4. Restart Claude Code to refresh available tools

Two Ways to Use Prompts

1. Prompts Interface (Slash Commands)

Explicitly invoke prompts by typing slash commands. Great when you know exactly which prompt you need.

Usage:

User: /ppm:personal-code-review
User: /ppm:work-api-design
User: /ppm:personal-technical-analysis

Pattern:

• Format: /ppm:workspace-prompt
• Example: workspace slug "personal" + prompt slug "code-review" = /ppm:personal-code-review

Note:

• MCP protocol requires tool names to use only [a-zA-Z0-9_-] characters
• Hyphens (-) are used as separators between workspace and prompt
• Folders are NOT included in slash commands (only used for ZIP download organization)

2. Tools Interface (AI Discovery)

Let AI assistants discover and invoke prompts naturally through conversation. Great for exploratory workflows.

Usage:

User: "Help me review this code"
AI: [Discovers and invokes code-review tool]

User: "I need to plan a new feature"
AI: [Discovers and invokes planning tool from appropriate folder]

How it works:

• Each prompt appears as a discoverable tool
• AI reads tool descriptions to match user intent
• AI invokes the appropriate tool automatically
• Same flattened content as slash commands

Command Naming Convention

The MCP server uses a hierarchical workspace-scoped naming convention for slash commands.

Format

Pattern: workspace:prompt

All commands follow this two-part format:

1. Workspace slug (e.g., personal, work)
2. Prompt slug (e.g., code-review, api-design)
3. Separated by a colon (:)

Examples

Command structure:

• /ppm:personal:code-review → workspace: personal, prompt: code-review
• /ppm:work:api-design → workspace: work, prompt: api-design
• /ppm:personal:technical-analysis → workspace: personal, prompt: technical-analysis

Character rules:

• MCP protocol allows: [a-zA-Z0-9_:-]
• Hierarchy separator: : (colon) between workspace and prompt
• Word separator: - (hyphen) within multi-word slugs
• The /ppm: prefix is added by Claude Code (MCP namespace)
• The actual tool name is workspace:prompt (e.g., personal:code-review)

Folder Organization

Important: Folders are NOT included in slash command names.

• Folders are used only for ZIP download organization
• Multiple prompts with the same slug but different folders will have identical slash commands
• To avoid conflicts, ensure prompt slugs are unique across your entire workspace

Caching Modes

The MCP server supports two caching modes to fit different workflows. Choose based on how frequently you update your prompts:

Cached Mode (Default)

How it works:

• Prompts are fetched once when the MCP server starts
• Tool executions use the cached flattenedPrompt content
• Fast execution with minimal database queries

Choose this if you:

• Have stable, infrequently-changed prompts
• Want the fastest possible tool execution
• Prefer minimal network overhead
• Don't mind restarting Claude Code after editing prompts

Configuration: Use basic config without any flags (see Step 2 above)

Lazy Loading Mode

How it works:

• Prompts are fetched fresh from Convex on each tool invocation
• Always returns the latest flattenedPrompt content
• Falls back to cached version on fetch errors

Choose this if you:

• Actively iterate on prompt content frequently
• Want changes to take effect immediately without restarts
• Prefer convenience over maximum performance
• Have a stable internet connection

Configuration: Add --lazy-loading to the args array (see Step 2 above)

Example workflow:

# With lazy loading enabled:
# 1. Edit prompt in ContextFS web UI
# 2. Save changes
# 3. Run tool in Claude Code → sees new content immediately
# 4. No Claude Code restart required!

Performance Note: Lazy loading adds ~50-100ms per tool invocation for the database fetch. For most use cases, this overhead is negligible compared to Claude's processing time.

Multi-CLI Support

The MCP server works with multiple CLI tools. Each CLI has slightly different configuration requirements:

Claude Code

Configuration Location: Claude Code settings UI (MCP Servers section) Format: JSON Installation: https://claude.com/claude-code

Claude Code is Anthropic's official AI-powered code editor with native MCP support. Configuration is managed through the settings UI.

Codex CLI

Configuration Location: ~/.codex/config.toml (paste into [mcp_servers] section) Format: TOML Installation: https://developers.openai.com/codex/mcp

OpenAI's command-line interface for AI-assisted development. Uses TOML format for configuration.

Note: When pasting the TOML configuration, add it to the existing [mcp_servers] section in your config file, or create the section if it doesn't exist. Don't replace your entire config file.

Gemini CLI

Configuration Location: ~/.gemini/settings.json (paste into mcpServers object) Format: JSON Installation: https://ai.google.dev/gemini-api/docs/cli

Google's Gemini CLI for AI-powered development workflows. Uses the same JSON format as Claude Code.

Note: When pasting the JSON configuration, add the tpe object to the existing mcpServers object in your settings file, or create the object if it doesn't exist. Don't replace your entire settings file.

Recommended Approach

For all CLI tools, we recommend using Prompt Project Manager Settings page (https://promptprojectmanager.com/settings) to generate your configuration:

1. Select your CLI tool from the dropdown
2. Toggle lazy loading based on your workflow
3. Click "Copy Configuration"
4. Paste into the appropriate config file for your CLI

This ensures correct formatting, proper API key inclusion, and use of @latest versioning for automatic updates.

System Tools

In addition to your workspace prompts, the MCP server provides built-in system tools:

list_prompts

Lists all available prompts in alphabetical order by tool name. Optionally filter by search term.

Parameters:

• search (optional, string): Filter prompts by name or description (case-insensitive)

Examples:

# List all available prompts
User: "Use list_prompts to see what's available"

# Search for specific prompts
User: "Use list_prompts with search 'review'"
User: "Use list_prompts with search 'documentation'"

Output Format:

• Shows tool name, bundle, and description for each prompt
• Displays total count
• Sorts results alphabetically by tool name

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PPM_API_KEY | Yes | Your Prompt Project Manager API key from Settings page |

Usage Example

Once configured, your prompts appear as tools in Claude Code:

User: "Use the code-reviewer tool to review my changes"

Claude Code: [Invokes development/code-reviewer tool]
Tool Response: [Returns flattened prompt with all embedded resources]

Troubleshooting

No Tools Available

Problem: Claude Code shows no tools from ContextFS

Solutions:

1. Verify at least one prompt has "Expose to MCP" enabled
2. Check that your API key is correct in .mcp.json
3. Restart Claude Code to refresh the tool list
4. Check MCP server logs for authentication errors

Invalid API Key

Problem: Server fails to start with "Invalid API key" error

Solutions:

1. Copy your API key exactly from Settings page
2. Ensure no extra spaces or quotes around the key
3. Regenerate your API key if it was recently changed
4. Verify the key is set in the PPM_API_KEY environment variable

Missing Flattened Content

Problem: Tool execution fails with "no flattened content" error

Solutions:

1. Open the affected prompt in ContextFS
2. Make a minor edit (add a space, then remove it)
3. Save the prompt to trigger re-flattening
4. Restart the MCP server

Stale Prompt Content

Problem: Prompt edits don't appear when running tools in Claude Code

Solutions:

1. Enable lazy loading: Add --lazy-loading to the args array in your .mcp.json config to always fetch fresh content
2. Or restart Claude Code: If using cached mode, restart Claude Code to refresh the cached prompts
3. Verify mode: Check MCP server logs to see which caching mode is active (look for "Lazy loading: ENABLED" or "DISABLED")

How It Works

1. Startup: Server validates your API key with Convex
2. Tool Registration: Fetches all prompts with exposeToMcp: true
3. Tool Creation: Builds MCP tool schemas with bundle-aware naming
4. Execution: Returns flattenedPrompt content when tools are invoked
5. Logging: Outputs diagnostic info to stderr (visible in Claude Code logs)

Development

Building from Source

# Clone the repository
git clone https://github.com/promptprojectmanager/promptprojectmanager
cd promptprojectmanager/packages/mcp-server

# Install dependencies
npm install

# Build the package
npm run build

# Test locally
npm link
PPM_API_KEY=your_key npx @promptprojectmanager/mcp-server

Package Structure

packages/mcp-server/
├── src/
│   ├── index.ts          # CLI entry point with argument parsing
│   ├── server.ts         # MCP server logic and tool registration
│   ├── convex-client.ts  # Convex HTTP client initialization
│   ├── tool-builder.ts   # Tool naming and schema generation
│   └── types.ts          # TypeScript type definitions
├── dist/                 # Compiled output (generated)
├── package.json
├── tsconfig.json
├── tsup.config.ts        # Build configuration
└── README.md

Version History

2.0.6 (2025-11-16) - Bug Fix & Documentation Update

Bug Fixes:

• Fixed field name mismatch (folderPath vs folder) preventing proper data flow from backend
• Removed folder-based command scoping (folders only used for ZIP downloads now)
• Simplified to clean workspace-prompt format for all slash commands

Documentation Updates:

• Clarified that folders are NOT included in slash command names
• Updated all examples to show simple workspace-prompt format
• Added warning about slug uniqueness requirement across workspace

Impact:

• Simple, predictable command names
• No breaking changes for existing users (folder scoping never actually worked)

2.0.2 (2025-11-06) - Character Sanitization Fix (DEPRECATED)

Note: Folder-based scoping was never functional due to field name bug. See v2.0.6 for correct implementation.

• Attempted to fix period (.) handling in folder paths
• Example: .claude/commands → claude-commands

2.0.1 (2025-11-06) - MCP Validation Fix (DEPRECATED)

Note: Folder-based scoping was never functional due to field name bug. See v2.0.6 for correct implementation.

• Changed separators for MCP protocol compliance: colon (:) → underscore (_), slash (/) → hyphen (-)
• Tool name pattern: [a-zA-Z0-9_-]

2.0.0 (2025-11-06) - Dual Interface Release (DEPRECATED)

Note: Folder-based scoping was never functional due to field name bug. See v2.0.6 for correct implementation.

Working Feature:

• Dual Interface Architecture - Added Tools interface alongside Prompts interface
• Each prompt appears as both a slash command AND an AI-discoverable tool

Non-Functional Feature:

• Folder-based command scoping was documented but never worked due to backend field mismatch
• Fixed in v2.0.3 with simplified workspace-prompt format

1.4.0 (2025-11-05)

• Breaking Change: Namespace shortened from theprompteditor to ppm
• Users must update .mcp.json server key to "ppm"
• All slash commands now use /ppm:workspace:prompt format
• Migration: One-line config change, see README for details

1.3.2 (2025-10-30)

• Breaking Change: Removed ppm: prefix - tools now appear as promptprojectmanager:workspace:prompt
• Simplified naming pattern to avoid double prefixing with MCP server name

1.3.1 (2025-10-30)

• Breaking Change: Environment variable renamed from CONTEXTFS_API_KEY to PPM_API_KEY
• Updated all documentation and error messages with new branding

1.3.0 (2025-10-30)

• Breaking Change: Tool naming pattern changed from bundle/prompt to workspace-scoped format
• New Feature: Workspace scoping - prompts are now namespaced by workspace
• Folders are now ignored in tool names (UI organization only)
• Fixed lazy loading to match prompts by both slug AND workspace slug
• Backend now includes workspace metadata in MCP prompt responses
• Updated Convex backend URLs to current deployments

1.1.0 (2025-10-20)

• New Feature: Lazy loading mode (--lazy-loading flag)
• Users can now choose between cached (fast) and lazy loading (always fresh) modes
• Lazy loading fetches fresh prompt content on each invocation
• Enhanced Settings page UI with two-option configuration
• Updated documentation with user-centric caching mode guidance

1.0.1 (2025-10-20)

• Documentation improvements
• Bug fixes

1.0.0 (2025-10-20)

• Initial release
• Production and development deployment support
• Secure API key authentication
• Bundle-aware tool naming
• Flattened prompt execution
• Comprehensive error handling

Support

• Issues: https://github.com/contextfs/contextfs/issues
• Documentation: https://docs.contextfs.com
• Email: [email protected]

License

MIT License - See LICENSE file for details

Made with ❤️ by the ContextFS team