@promptprojectmanager/mcp-server 4.2.0 → 4.2.2

package/README.md

@@ -4,36 +4,31 @@ MCP server that exposes Prompt Project Manager prompts and tickets through dual
 
 ## Overview
 
-`@promptprojectmanager/mcp-server` is a standalone npm package that integrates your Prompt Project Manager workspace with Claude Code, Codex CLI, and Gemini CLI via the Model Context Protocol (MCP).
+`@promptprojectmanager/mcp-server` is a standalone npm package that integrates your Prompt Project Manager project with Claude Code, Codex CLI, and Gemini CLI via the Model Context Protocol (MCP).
 
-### Two Authentication Modes
+### Authentication
 
-| Mode | Env Variable | Scope | Use Case |
-|------|--------------|-------|----------|
-| **API Key** | `PPM_API_KEY` | Full account access | Multi-project workflows, all prompts |
-| **Project Token** | `PPM_PROJECT_TOKEN` | Single project, tickets only | CI/CD, agents, scoped access |
+| Mode | Env Variable | Scope |
+|------|--------------|-------|
+| **Project Token** | `PPM_PROJECT_TOKEN` | Single project (prompts + tickets) |
+
+Project tokens provide scoped access to a single project, including all prompts (via the token owner's account) and ticket management.
 
 ### Two Interfaces
 
-1. **Prompts Interface** (Slash Commands) - Explicitly invoke prompts via `/ppm:project:prompt` commands
+1. **Prompts Interface** (Slash Commands) - Explicitly invoke prompts via `/ppm:prompt_slug` commands
 2. **Tools Interface** (AI Discovery) - AI assistants can discover and invoke prompts/tickets naturally
 
 ## Features
 
-- **Dual Authentication** - API keys for full access, project tokens for scoped access
-- **Project Filtering** - Use `--projects` flag to limit scope (API key mode only)
+- **Project-Scoped Access** - Each token is scoped to one project for security
+- **Full Prompt Access** - Access all prompts from the token owner's account
 - **Ticket Management** - Create, update, close tickets via MCP tools
-- **Agent Identity** - Use `PPM_AGENT` to identify which agent is making requests
-- **Selective Exposure** - Only prompts with "Expose to MCP" enabled appear
+- **Agent Identity** - Token name appears in activity logs
 - **Zero Configuration** - Works out of the box with `npx`
-- **Flexible Caching** - Choose between cached (fast) or lazy loading (always fresh) modes
 
 ## Quick Start
 
-### Option 1: Project Token (Recommended for Agents)
-
-Project tokens are scoped to a single project and provide ticket access. **No `--projects` flag needed** - the token already knows which project it belongs to.
-
 ```json
 {
   "mcpServers": {
@@ -48,131 +43,44 @@ Project tokens are scoped to a single project and provide ticket access. **No `-
 }
 ```
 
-Get your project token from: Project → Agents → Create/View Agent
-
-### Option 2: API Key (Full Account Access)
-
-API keys provide access to all projects and prompts. Use `--projects` to filter.
-
-```json
-{
-  "mcpServers": {
-    "ppm": {
-      "command": "npx",
-      "args": ["@promptprojectmanager/mcp-server@latest", "--projects", "my-project"],
-      "env": {
-        "PPM_API_KEY": "api_key_your_key_here"
-      }
-    }
-  }
-}
-```
-
-Get your API key from: Settings → API Keys
-
-## Authentication
-
-### Project Token Mode (`PPM_PROJECT_TOKEN`)
-
-Best for: CI/CD pipelines, automated agents, scoped access
-
-- **Scope**: Single project (determined by token)
-- **Access**: Tickets only (prompts not available)
-- **Flag**: `--projects` is **ignored** (token already scoped)
-
-```bash
-# Token is already scoped - no --projects needed
-PPM_PROJECT_TOKEN=wst_xxx npx @promptprojectmanager/mcp-server@latest
-```
-
-### API Key Mode (`PPM_API_KEY`)
-
-Best for: Development, multi-project workflows, full prompt access
-
-- **Scope**: All projects in your account
-- **Access**: Prompts + Tickets
-- **Flag**: Use `--projects` to filter
-
-```bash
-# Access all projects
-PPM_API_KEY=api_key_xxx npx @promptprojectmanager/mcp-server@latest
-
-# Filter to specific projects
-PPM_API_KEY=api_key_xxx npx @promptprojectmanager/mcp-server@latest --projects myproject
-
-# Multiple projects
-PPM_API_KEY=api_key_xxx npx @promptprojectmanager/mcp-server@latest --projects proj1,proj2
-```
-
-### Agent Identity (`PPM_AGENT`)
-
-When using API key auth, you can specify which agent identity to use for ticket operations:
-
-```bash
-PPM_API_KEY=api_key_xxx PPM_AGENT=my-agent npx @promptprojectmanager/mcp-server@latest
-```
-
-This identifies the agent in ticket history and audit logs.
+Get your project token from: **Project → Agents → Create/View Agent**
 
 ## CLI Arguments
 
-| Argument | Description | API Key | Project Token |
-|----------|-------------|---------|---------------|
-| `--projects`, `-p` | Filter to specific project(s) | ✅ Supported | ❌ Ignored (token scoped) |
-| `--lazy-loading` | Fetch fresh prompts on each call | ✅ Supported | ✅ Supported |
-| `--dev` | Use development Convex deployment | ✅ Supported | ✅ Supported |
-
-### Project Filtering Examples
-
-```bash
-# Single project
---projects myproject
-
-# Multiple projects (comma-separated)
---projects proj1,proj2,proj3
-
-# Multiple --projects flags
---projects proj1 --projects proj2
-
-# Short flag
--p myproject
-```
+| Argument | Description |
+|----------|-------------|
+| `--dev` | Use development Convex deployment |
 
 ## Available Tools
 
-### Prompt Tools (API Key Mode Only)
-
-Each prompt with "Expose to MCP" enabled appears as a tool:
+### Prompt Tools
 
-- `project_prompt_slug` - Invoke a specific prompt
-- `list_prompts` - List all available prompts
-
-### Ticket Tools (Both Modes)
-
-Each project gets ticket management tools:
+Each prompt appears as a global tool:
 
 | Tool | Description |
 |------|-------------|
-| `project_tickets_work` | Get next ticket or open specific ticket |
-| `project_tickets_close` | Mark a ticket as completed |
-| `project_tickets_update` | Append content to a ticket |
-| `project_tickets_create` | Create a new ticket |
-| `project_tickets_list` | List active tickets |
-| `project_tickets_get` | Get a specific ticket |
-| `project_tickets_search` | Search tickets by content |
+| `{prompt_slug}` | Execute a specific prompt directly (e.g., `code_review`) |
+| `system_prompts` | List all available prompts |
+| `system_run_prompt` | Execute a prompt by slug (for dynamic invocation) |
+
+### Ticket Tools
 
-### System Tools
+Each project gets ticket management tools:
 
 | Tool | Description |
 |------|-------------|
-| `system_prompts` | List all available prompts |
-| `system_run_prompt` | Execute a prompt by slug |
+| `{project}_tickets_work` | Get next ticket or open specific ticket |
+| `{project}_tickets_close` | Mark a ticket as completed |
+| `{project}_tickets_update` | Append content to a ticket |
+| `{project}_tickets_create` | Create a new ticket |
+| `{project}_tickets_list` | List active tickets |
+| `{project}_tickets_get` | Get a specific ticket |
+| `{project}_tickets_search` | Search tickets by content |
 
 ## Configuration Examples
 
 ### Claude Code (JSON)
 
-**With Project Token:**
 ```json
 {
   "mcpServers": {
@@ -187,37 +95,6 @@ Each project gets ticket management tools:
 }
 ```
 
-**With API Key + Project Filter:**
-```json
-{
-  "mcpServers": {
-    "ppm": {
-      "command": "npx",
-      "args": ["@promptprojectmanager/mcp-server@latest", "--projects", "my-project"],
-      "env": {
-        "PPM_API_KEY": "api_key_xxx"
-      }
-    }
-  }
-}
-```
-
-**With API Key + Agent Identity:**
-```json
-{
-  "mcpServers": {
-    "ppm": {
-      "command": "npx",
-      "args": ["@promptprojectmanager/mcp-server@latest", "--projects", "my-project"],
-      "env": {
-        "PPM_API_KEY": "api_key_xxx",
-        "PPM_AGENT": "claude-code-agent"
-      }
-    }
-  }
-}
-```
-
 ### Codex CLI (TOML)
 
 ```toml
@@ -233,80 +110,47 @@ PPM_PROJECT_TOKEN = "wst_your_token"
 
 Same format as Claude Code.
 
-## Caching Modes
-
-### Cached Mode (Default)
-
-- Prompts fetched **once** at startup
-- Fast execution, minimal network
-- Restart required after editing prompts
-
-### Lazy Loading Mode
-
-Add `--lazy-loading` to args:
-
-```json
-"args": ["@promptprojectmanager/mcp-server@latest", "--lazy-loading"]
-```
-
-- Prompts fetched **fresh on each invocation**
-- Changes appear immediately
-- ~50-100ms overhead per call
-
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `PPM_API_KEY` | One of these | Full account access (prompts + tickets) |
-| `PPM_PROJECT_TOKEN` | required | Scoped project access (tickets only) |
-| `PPM_AGENT` | No | Agent identity for ticket operations (API key mode) |
-| `THEPROMPTEDITOR_API_KEY` | No | Legacy alias for `PPM_API_KEY` |
+| `PPM_PROJECT_TOKEN` | Yes | Project token (wst_* prefix) for authentication |
 
 ## Troubleshooting
 
 ### No Tools Available
 
-1. Verify authentication: `PPM_API_KEY` or `PPM_PROJECT_TOKEN` is set
-2. For prompts: Ensure "Expose to MCP" is enabled
+1. Verify `PPM_PROJECT_TOKEN` is set correctly
+2. Check token is not revoked in project settings
 3. Restart your CLI tool to refresh tools
 
-### Wrong Project Scope
-
-- **Project token**: Token is pre-scoped, `--projects` is ignored
-- **API key**: Use `--projects` flag to filter
-
 ### Stale Content
 
-1. Enable `--lazy-loading` for immediate updates
-2. Or restart CLI tool to refresh cache
+Restart CLI tool to refresh — prompts are fetched fresh on startup.
 
 ## Version History
 
-### 4.1.0 (2025-01-15) - Documentation Update
+### 4.2.1 (2026-01-15) - Project Token Only
 
-**Documentation:**
-- Added comprehensive documentation for project token authentication
-- Documented `--projects` flag behavior (ignored for project tokens)
-- Added ticket tools reference
-- Added `PPM_AGENT` environment variable documentation
-- Updated examples for both auth modes
+**Breaking Change:**
+- Removed API key authentication (`PPM_API_KEY`)
+- All authentication now uses project tokens (`PPM_PROJECT_TOKEN`)
+- Removed `--projects` flag (token is already project-scoped)
+- Removed `PPM_AGENT` (token provides identity directly)
 
-**No Code Changes** - Server already handled both auth modes correctly.
+**Migration:**
+- Replace `PPM_API_KEY` with `PPM_PROJECT_TOKEN`
+- Get project token from Project → Agents section
+- Remove `--projects` flag from args (no longer needed)
 
-### 4.0.3 (2025-01-08) - Prompt Folders
+### 4.1.0 - Documentation Update
 
-- Added prompt folder support for organization
+- Added comprehensive documentation for project token authentication
 
-### 4.0.0 (2024-12-XX) - Project Tokens & Tickets
+### 4.0.0 - Project Tokens & Tickets
 
 - Added `PPM_PROJECT_TOKEN` authentication mode
 - Added ticket management tools per project
-- Added `--projects` flag for API key filtering
-- Added `PPM_AGENT` for agent identity
-
-### 3.x - Earlier Versions
-
-See git history for earlier changelog.
 
 ## Support