@promptprojectmanager/mcp-server 2.8.1

package/README.md

@@ -0,0 +1,516 @@
+# @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:
+
+```bash
+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](#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:
+
+```json
+{
+  "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:
+
+```toml
+[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:
+
+```json
+{
+  "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:
+
+```json
+"args": ["@promptprojectmanager/mcp-server@latest", "--lazy-loading"]
+```
+
+See [Caching Modes](#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:**
+```bash
+# 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
+
+```bash
+# 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**: support@contextfs.com
+
+## License
+
+MIT License - See LICENSE file for details
+
+---
+
+**Made with ❤️ by the ContextFS team**

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }