@riotprompt/riotprompt 1.0.3-dev.0 → 1.0.4

package/MCP-IMPLEMENTATION.md

@@ -0,0 +1,192 @@
+# RiotPrompt MCP Implementation
+
+This document describes the MCP (Model Context Protocol) implementation for RiotPrompt.
+
+## Overview
+
+The MCP server exposes RiotPrompt's CLI functionality through the Model Context Protocol, allowing AI assistants to programmatically create, process, and execute prompts.
+
+## Architecture
+
+The implementation follows the pattern established in kodrdriv's MCP server:
+
+```
+src/mcp/
+├── index.ts              # Module entry point
+├── server.ts             # Main MCP server implementation
+├── types.ts              # Type definitions
+├── tools/                # Tool implementations
+│   ├── index.ts          # Tool registry and executor
+│   ├── get-version.ts    # Version information tool
+│   ├── create.ts         # Prompt creation tool
+│   ├── process.ts        # Prompt processing tool
+│   └── execute.ts        # Prompt execution tool
+├── prompts/              # Workflow templates
+│   ├── index.ts          # Prompt registry and loader
+│   ├── create_and_execute.md
+│   └── process_and_export.md
+└── resources/            # Read-only resources
+    ├── index.ts          # Resource registry
+    ├── config.ts         # Configuration resource
+    └── version.ts        # Version resource
+```
+
+## Tools
+
+### 1. riotprompt_get_version
+- **Purpose**: Get version information
+- **Parameters**: None
+- **Returns**: Version, name, description
+
+### 2. riotprompt_create
+- **Purpose**: Create new prompt structure or import from file
+- **Parameters**:
+  - `promptName` (required): Name of the prompt
+  - `path` (optional): Base path for creation
+  - `persona` (optional): Initial persona text
+  - `instructions` (optional): Initial instructions text
+  - `createContext` (optional): Create context directory
+  - `importFile` (optional): Import from JSON/XML
+- **Returns**: Path to created prompt, list of files
+
+### 3. riotprompt_process
+- **Purpose**: Process and format prompts
+- **Parameters**:
+  - `promptPath` (required): Path to prompt
+  - `model` (optional): Target model
+  - `format` (optional): Output format (text/json/xml)
+  - `outputFile` (optional): Save to file
+- **Returns**: Formatted output or file path
+
+### 4. riotprompt_execute
+- **Purpose**: Execute prompt using LLM provider
+- **Parameters**:
+  - `promptPath` (required): Path to prompt
+  - `model` (optional): Model to use
+  - `apiKey` (optional): API key override
+  - `temperature` (optional): Temperature setting
+  - `maxTokens` (optional): Max tokens
+- **Returns**: LLM response, usage stats
+
+## Resources
+
+### riotprompt://config
+Read-only access to riotprompt.yaml configuration
+
+### riotprompt://version
+Version information for the package
+
+## Prompts
+
+### create_and_execute
+Workflow template for creating and executing a new prompt
+
+### process_and_export
+Workflow template for processing and exporting existing prompts
+
+## Build Process
+
+The MCP server is built separately from the main library:
+
+1. Main library build: `vite build`
+2. CLI build: `vite build -c vite.config.cli.ts`
+3. MCP server build: `node scripts/build-mcp.js`
+4. Copy prompt templates: `copyfiles -u 1 "src/mcp/prompts/*.md" dist`
+
+The build script (`scripts/build-mcp.js`) uses esbuild to:
+- Bundle the MCP server code
+- Mark external dependencies (MCP SDK, RiotPrompt dependencies)
+- Add shebang for executable
+- Make the file executable
+
+## Dependencies
+
+### Runtime Dependencies
+- `@modelcontextprotocol/sdk`: MCP protocol implementation
+- All RiotPrompt dependencies (marked as external in build)
+
+### Dev Dependencies
+- `esbuild`: For bundling the MCP server
+- `copyfiles`: For copying prompt templates
+- `@modelcontextprotocol/inspector`: For testing
+
+## Testing
+
+```bash
+# Build MCP server
+npm run mcp:build
+
+# Test with MCP inspector
+npm run mcp:inspect
+
+# Watch mode for development
+npm run mcp:dev
+```
+
+## Usage
+
+### In Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "riotprompt": {
+      "command": "npx",
+      "args": ["-y", "@riotprompt/riotprompt", "riotprompt-mcp"]
+    }
+  }
+}
+```
+
+### In Other MCP Clients
+
+Use the `riotprompt-mcp` command or the full path to `dist/mcp-server.js`.
+
+## Environment Variables
+
+The MCP server respects the same environment variables as the CLI:
+- `OPENAI_API_KEY`: For OpenAI models
+- `ANTHROPIC_API_KEY`: For Anthropic/Claude models
+- `GEMINI_API_KEY`: For Google Gemini models
+- `RIOTPROMPT_MCP_SERVER`: Set automatically when running as MCP server
+
+## Error Handling
+
+The server follows MCP best practices:
+- Returns structured error responses
+- Includes context and recovery suggestions
+- Logs are captured and included in responses
+- Undefined values are cleaned from JSON responses
+
+## Future Enhancements
+
+Potential additions:
+- More workflow prompts
+- Streaming support for long-running operations
+- Progress notifications for execution
+- Batch operations
+- Template management tools
+- Validation tools
+
+## Comparison with kodrdriv
+
+Similarities:
+- Same MCP SDK and architecture pattern
+- Similar tool/resource/prompt structure
+- Same build process approach
+- Same error handling patterns
+
+Differences:
+- Simpler tool set (4 tools vs 20+)
+- No tree operations (single package focus)
+- No git integration
+- Focus on prompt operations vs workflow automation
+
+## Notes
+
+- The MCP server runs in a separate process from the CLI
+- All file operations use `fs/promises` to comply with eslint rules
+- The server is stateless - each tool call is independent
+- Prompt templates are loaded from markdown files at runtime

package/MCP-SUMMARY.md

@@ -0,0 +1,198 @@
+# RiotPrompt MCP Implementation - Summary
+
+## What Was Created
+
+Successfully implemented a complete MCP (Model Context Protocol) server for RiotPrompt, following the patterns established in kodrdriv.
+
+### Files Created
+
+#### Core MCP Files
+- `src/mcp/index.ts` - Module entry point
+- `src/mcp/server.ts` - Main MCP server implementation (370 lines)
+- `src/mcp/types.ts` - Type definitions for MCP integration (170 lines)
+
+#### Tools (4 tools)
+- `src/mcp/tools/index.ts` - Tool registry and executor
+- `src/mcp/tools/get-version.ts` - Get version information
+- `src/mcp/tools/create.ts` - Create new prompt structures
+- `src/mcp/tools/process.ts` - Process and format prompts
+- `src/mcp/tools/execute.ts` - Execute prompts using LLM providers
+
+#### Prompts (2 workflow templates)
+- `src/mcp/prompts/index.ts` - Prompt registry and loader
+- `src/mcp/prompts/create_and_execute.md` - Workflow for creating and executing prompts
+- `src/mcp/prompts/process_and_export.md` - Workflow for processing and exporting prompts
+
+#### Resources (2 resources)
+- `src/mcp/resources/index.ts` - Resource registry
+- `src/mcp/resources/config.ts` - Read riotprompt.yaml configuration
+- `src/mcp/resources/version.ts` - Get version information
+
+#### Build & Documentation
+- `scripts/build-mcp.js` - Build script for MCP server
+- `MCP.md` - User-facing documentation
+- `MCP-IMPLEMENTATION.md` - Technical implementation details
+- `MCP-SUMMARY.md` - This file
+
+### Package.json Updates
+
+Added:
+- `bin.riotprompt-mcp` entry point
+- MCP build scripts (`mcp:build`, `mcp:inspect`, `mcp:dev`)
+- Updated main build script to include MCP server
+- Dependencies: `@modelcontextprotocol/sdk`
+- Dev dependencies: `@modelcontextprotocol/inspector`, `copyfiles`, `esbuild`, `rollup-plugin-preserve-shebang`
+
+### ESLint Configuration
+
+Updated `eslint.config.mjs` to ignore `scripts/**` directory to allow console.log in build scripts.
+
+## Tools Provided
+
+### 1. riotprompt_get_version
+Get version information for riotprompt.
+
+### 2. riotprompt_create
+Create a new prompt directory structure or import from JSON/XML file.
+- Scaffolds persona.md, instructions.md, and context/ directory
+- Supports importing existing prompts
+
+### 3. riotprompt_process
+Process a prompt and format it for a specific model or export to JSON/XML.
+- Supports directory-based prompts and file-based prompts
+- Can format for specific models (GPT-4, Claude, Gemini, etc.)
+- Can export to JSON or XML
+
+### 4. riotprompt_execute
+Execute a prompt using an LLM provider (OpenAI, Anthropic, Gemini).
+- Supports all major LLM providers
+- Returns response and token usage
+- Respects API keys from environment or parameters
+
+## Resources Provided
+
+### riotprompt://config
+Read-only access to the riotprompt.yaml configuration file.
+
+### riotprompt://version
+Version information for the riotprompt package.
+
+## Prompts Provided
+
+### create_and_execute
+Workflow template for creating a new prompt and executing it.
+
+### process_and_export
+Workflow template for processing an existing prompt and exporting it.
+
+## Build Process
+
+The build process now includes:
+1. Lint check
+2. TypeScript type checking
+3. Main library build (vite)
+4. CLI build (vite)
+5. MCP server build (esbuild)
+6. Copy prompt templates to dist/
+7. Make MCP server executable
+
+Build command: `npm run build`
+
+## Testing
+
+The MCP server can be tested using:
+```bash
+npm run mcp:inspect
+```
+
+This launches the MCP Inspector for interactive testing.
+
+## Usage
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "riotprompt": {
+      "command": "npx",
+      "args": ["-y", "@riotprompt/riotprompt", "riotprompt-mcp"]
+    }
+  }
+}
+```
+
+### Example Interactions
+
+Once configured, users can ask their AI assistant:
+
+- "Create a new prompt called 'summarizer' for summarizing articles"
+- "Process the prompt at ./my-prompt and format it for Claude"
+- "Execute the prompt at ./my-prompt using GPT-4"
+- "Show me the riotprompt configuration"
+
+## Technical Details
+
+### Architecture
+- Uses `@modelcontextprotocol/sdk` for MCP protocol
+- Stdio transport for communication
+- Stateless design - each tool call is independent
+- Async/await throughout for proper error handling
+
+### Code Quality
+- All files use `fs/promises` instead of sync fs operations
+- Proper TypeScript typing throughout
+- ESLint compliant
+- Follows established patterns from kodrdriv
+
+### Error Handling
+- Structured error responses
+- Context and recovery suggestions included
+- Logs captured and included in responses
+- Undefined values cleaned from JSON
+
+## Comparison with kodrdriv MCP
+
+### Similarities
+- Same MCP SDK and architecture
+- Similar tool/resource/prompt structure
+- Same build process approach
+- Same error handling patterns
+
+### Differences
+- Simpler tool set (4 tools vs 20+)
+- No tree operations (single package focus)
+- No git integration
+- Focus on prompt operations vs workflow automation
+
+## Next Steps
+
+The MCP server is complete and ready for use. Potential future enhancements:
+
+1. Add more workflow prompts
+2. Add streaming support for long-running operations
+3. Add progress notifications for execution
+4. Add batch operations
+5. Add template management tools
+6. Add validation tools
+
+## Files Modified
+
+- `package.json` - Added MCP dependencies and scripts
+- `eslint.config.mjs` - Added scripts/ to ignore list
+- `README.md` - Added MCP section
+
+## Build Verification
+
+✅ Build successful
+✅ MCP server created at `dist/mcp-server.js`
+✅ MCP server is executable (755 permissions)
+✅ Prompt templates copied to `dist/mcp/prompts/`
+✅ All linting checks pass
+✅ TypeScript compilation successful
+
+## Status
+
+**COMPLETE** - The MCP server is fully implemented, built, and ready for use.

package/MCP.md

@@ -0,0 +1,185 @@
+# RiotPrompt MCP Server
+
+Model Context Protocol (MCP) server for RiotPrompt, providing AI assistants with tools to create, process, and execute prompts.
+
+## Overview
+
+The RiotPrompt MCP server exposes RiotPrompt's CLI functionality through the Model Context Protocol, allowing AI assistants to:
+
+- Create new prompt structures
+- Process prompts for different models
+- Execute prompts using LLM providers
+- Access configuration and version information
+
+## Installation
+
+```bash
+npm install -g @riotprompt/riotprompt
+```
+
+## Configuration
+
+Add to your MCP settings (e.g., Claude Desktop config):
+
+```json
+{
+  "mcpServers": {
+    "riotprompt": {
+      "command": "npx",
+      "args": ["-y", "@riotprompt/riotprompt", "riotprompt-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "riotprompt": {
+      "command": "riotprompt-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+### riotprompt_get_version
+
+Get version information for riotprompt.
+
+**Parameters:** None
+
+**Returns:**
+- `version`: Package version
+- `name`: Package name
+- `description`: Package description
+
+### riotprompt_create
+
+Create a new prompt directory structure or import from file.
+
+**Parameters:**
+- `promptName` (required): Name of the prompt to create
+- `path` (optional): Base path to create the prompt in
+- `persona` (optional): Initial text for persona.md
+- `instructions` (optional): Initial text for instructions.md
+- `createContext` (optional): Create context directory (default: true)
+- `importFile` (optional): Import from JSON or XML file
+
+**Returns:**
+- `path`: Full path to created prompt
+- `files`: List of created files
+
+### riotprompt_process
+
+Process a prompt and format it for a specific model or export to JSON/XML.
+
+**Parameters:**
+- `promptPath` (required): Path to prompt directory or file
+- `model` (optional): Model to format for (e.g., gpt-4, claude-3-opus)
+- `format` (optional): Output format (text, json, xml)
+- `outputFile` (optional): Path to save output
+
+**Returns:**
+- `output`: Formatted prompt (if no outputFile specified)
+- `outputFile`: Path to saved file (if outputFile specified)
+- `format`: Output format used
+
+### riotprompt_execute
+
+Execute a prompt using an LLM provider.
+
+**Parameters:**
+- `promptPath` (required): Path to prompt directory or file
+- `model` (optional): Model to use (e.g., gpt-4, claude-3-opus, gemini-1.5-pro)
+- `apiKey` (optional): API key (overrides environment variables)
+- `temperature` (optional): Temperature (0-1)
+- `maxTokens` (optional): Maximum tokens to generate
+
+**Returns:**
+- `content`: Response from the LLM
+- `usage`: Token usage information
+- `model`: Model used
+
+**Environment Variables:**
+- `OPENAI_API_KEY`: For OpenAI models
+- `ANTHROPIC_API_KEY`: For Anthropic/Claude models
+- `GEMINI_API_KEY`: For Google Gemini models
+
+## Resources
+
+### riotprompt://config
+
+Read the current riotprompt configuration from `riotprompt.yaml`.
+
+### riotprompt://version
+
+Get version information for riotprompt.
+
+## Prompts
+
+### create_and_execute
+
+Workflow template for creating a new prompt and executing it.
+
+**Arguments:**
+- `promptName` (required): Name of the prompt to create
+- `model` (optional): Model to use for execution
+- `path` (optional): Path where to create the prompt
+
+### process_and_export
+
+Workflow template for processing an existing prompt and exporting it.
+
+**Arguments:**
+- `promptPath` (required): Path to the prompt
+- `model` (optional): Model to format for
+- `format` (optional): Output format (text, json, xml)
+
+## Example Usage
+
+Once configured, you can ask your AI assistant:
+
+- "Create a new prompt called 'summarizer' with a persona for summarizing text"
+- "Process the prompt at ./my-prompt and format it for Claude"
+- "Execute the prompt at ./my-prompt using GPT-4"
+- "Show me the riotprompt configuration"
+
+## Development
+
+### Building
+
+```bash
+npm run mcp:build
+```
+
+### Testing
+
+```bash
+npm run mcp:inspect
+```
+
+### Local Development
+
+```bash
+# Watch mode
+npm run mcp:dev
+
+# Test with MCP inspector
+npm run mcp:inspect
+```
+
+## Architecture
+
+The MCP server is built using:
+
+- `@modelcontextprotocol/sdk` for MCP protocol implementation
+- RiotPrompt's core functionality for prompt operations
+- Stdio transport for communication with MCP clients
+
+## License
+
+Apache-2.0

package/README.md

@@ -19,7 +19,22 @@ A powerful, flexible prompt building library and CLI tool for AI applications wi
 ## Installation
 
 ```bash
-npm install riotprompt
+npm install @riotprompt/riotprompt
+```
+
+## MCP Server
+
+RiotPrompt includes a Model Context Protocol (MCP) server that allows AI assistants to create, process, and execute prompts. See [MCP.md](MCP.md) for configuration and usage details.
+
+```json
+{
+  "mcpServers": {
+    "riotprompt": {
+      "command": "npx",
+      "args": ["-y", "@riotprompt/riotprompt", "riotprompt-mcp"]
+    }
+  }
+}
 ```
 
 ## CLI Usage

package/dist/mcp/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * MCP Module Entry Point
+ */
+export * from './server.js';

package/dist/mcp/prompts/create_and_execute.md

@@ -0,0 +1,17 @@
+# Create and Execute a Prompt
+
+I need to create a new prompt and execute it.
+
+## Steps
+
+1. Use `riotprompt_create` to create a new prompt structure at ${path}
+2. Review the created structure
+3. Use `riotprompt_execute` to run the prompt with the specified model
+
+## Details
+
+- Prompt name: ${promptName}
+- Model: ${model}
+- Path: ${path}
+
+Please help me create and test this prompt.

package/dist/mcp/prompts/index.d.ts

@@ -0,0 +1,9 @@
+import { McpPrompt, McpPromptMessage } from '../types.js';
+/**
+ * Get all available prompts
+ */
+export declare function getPrompts(): McpPrompt[];
+/**
+ * Get a prompt by name
+ */
+export declare function getPrompt(name: string, args: Record<string, string>): Promise<McpPromptMessage[]>;

package/dist/mcp/prompts/process_and_export.md

@@ -0,0 +1,17 @@
+# Process and Export a Prompt
+
+I need to process an existing prompt and export it to a different format.
+
+## Steps
+
+1. Use `riotprompt_process` to load and process the prompt at ${promptPath}
+2. Format it for ${model} (if specified)
+3. Export to ${format} format
+
+## Details
+
+- Prompt path: ${promptPath}
+- Model: ${model}
+- Output format: ${format}
+
+Please help me process and export this prompt.

package/dist/mcp/resources/config.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Configuration Resource Handler
+ */
+export declare function readConfig(): Promise<any>;

package/dist/mcp/resources/index.d.ts

@@ -0,0 +1,9 @@
+import { McpResource } from '../types.js';
+/**
+ * Get all available resources
+ */
+export declare function getResources(): McpResource[];
+/**
+ * Read a resource by URI
+ */
+export declare function readResource(uri: string): Promise<any>;

package/dist/mcp/resources/version.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Version Resource Handler
+ */
+export declare function readVersion(): Promise<any>;

package/dist/mcp/server.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * RiotPrompt MCP Server
+ *
+ * Exposes riotprompt commands, resources, and prompts via MCP.
+ *
+ * This server provides:
+ * - Tools: Prompt creation, processing, and execution commands
+ * - Resources: Configuration and version information
+ * - Prompts: Workflow templates for common prompt operations
+ *
+ * Uses McpServer high-level API for better progress notification support
+ */
+/**
+ * Recursively remove undefined values from an object to prevent JSON serialization issues
+ * Preserves null values as they are valid in JSON
+ * @internal - Exported for testing purposes
+ */
+export declare function removeUndefinedValues(obj: any): any;

package/dist/mcp/tools/create.d.ts

@@ -0,0 +1,3 @@
+import { McpTool, ToolResult, ToolExecutionContext } from '../types.js';
+export declare const createTool: McpTool;
+export declare function executeCreate(args: any, context: ToolExecutionContext): Promise<ToolResult>;

package/dist/mcp/tools/execute.d.ts

@@ -0,0 +1,3 @@
+import { McpTool, ToolResult, ToolExecutionContext } from '../types.js';
+export declare const executeTool: McpTool;
+export declare function executeExecute(args: any, context: ToolExecutionContext): Promise<ToolResult>;