Skip to main content
Glama

Smart Prompts MCP Server

README-original.mdโ€ข13.9 kB
# Smart Prompts MCP Server An enhanced MCP (Model Context Protocol) server that fetches prompts from GitHub repositories with intelligent discovery, composition, and management features. This is an enhanced fork of [prompts-mcp-server](https://github.com/tanker327/prompts-mcp-server) with GitHub integration and advanced features. ## Quick Start ```bash # 1. Install git clone https://github.com/jezweb/smart-prompts-mcp.git cd smart-prompts-mcp npm install && npm run build # 2. Set up GitHub repository export GITHUB_OWNER=your-username export GITHUB_REPO=your-prompts-repo # 3. Add to your MCP client config (e.g., Claude Desktop) # Add this to ~/Library/Application Support/Claude/claude_desktop_config.json: { "mcpServers": { "smart-prompts": { "command": "node", "args": ["/path/to/smart-prompts-mcp/dist/index.js"], "env": { "GITHUB_OWNER": "your-username", "GITHUB_REPO": "your-prompts-repo" } } } } # 4. Restart your MCP client and start using the enhanced features! ``` ## Features ### ๐Ÿš€ Core Features - **GitHub Integration**: Fetch prompts directly from GitHub repositories (no local storage required) - **Smart Discovery**: Search prompts using keywords with intelligent matching - **Prompt Composition**: Combine multiple prompts dynamically - **Usage Tracking**: Track which prompts are used most frequently - **Real-time Updates**: Automatic cache refresh from GitHub ### ๐Ÿ”ง MCP Protocol Support - **Tools**: Search, compose, and manage prompts - **Resources**: Browse prompts by category, tags, or usage - **Prompts**: Interactive templates with dynamic arguments ### ๐Ÿ’ก Enhanced Capabilities - YAML frontmatter support for rich metadata - Handlebars templating for dynamic content - Category and tag-based organization - Usage statistics and analytics - Backward compatibility with local file storage ## Installation ```bash # Clone the repository git clone https://github.com/jezweb/smart-prompts-mcp.git cd smart-prompts-mcp # Install dependencies npm install # Build the project npm run build ``` ## Configuration ### Environment Variables ```bash # GitHub Configuration GITHUB_OWNER=jezweb # GitHub username or organization GITHUB_REPO=prompts # Repository name GITHUB_BRANCH=main # Branch to fetch from GITHUB_PATH= # Path within repo (optional) GITHUB_TOKEN= # Personal access token (for private repos) # Cache Configuration CACHE_TTL=300000 # Cache time-to-live (5 minutes) CACHE_REFRESH_INTERVAL=60000 # Refresh interval (1 minute) # Feature Flags ENABLE_SEMANTIC_SEARCH=true # Enable semantic search ENABLE_PROMPT_COMPOSITION=true # Enable prompt composition ENABLE_USAGE_TRACKING=true # Enable usage tracking # Install dependencies npm install # Build the TypeScript code npm run build # Test the installation npm test ``` ### Option 2: Direct Download 1. Download the latest release from GitHub 2. Extract to your desired location 3. Run installation steps above ### Option 3: Development Setup ```bash # Clone and set up for development git clone https://github.com/tanker327/prompts-mcp-server.git cd prompts-mcp-server npm install # Start development server with auto-reload npm run dev # Run tests in watch mode npm run test:watch ``` ### Verification After installation, verify the server works: ```bash # Start the server (should show no errors) npm start # Or test with MCP Inspector npx @modelcontextprotocol/inspector node dist/index.js ``` ## Testing Run the comprehensive test suite: ```bash npm test ``` Run tests with coverage: ```bash npm run test:coverage ``` Watch mode for development: ```bash npm run test:watch ``` ## MCP Tools The server provides the following tools: ### `add_prompt` Add a new prompt to the collection. If no YAML frontmatter is provided, default metadata will be automatically added. - **name** (string): Name of the prompt - **content** (string): Content of the prompt in markdown format with optional YAML frontmatter ### `create_structured_prompt` Create a new prompt with guided metadata structure and validation. - **name** (string): Name of the prompt - **title** (string): Human-readable title for the prompt - **description** (string): Brief description of what the prompt does - **category** (string, optional): Category (defaults to "general") - **tags** (array, optional): Array of tags for categorization (defaults to ["general"]) - **difficulty** (string, optional): "beginner", "intermediate", or "advanced" (defaults to "beginner") - **author** (string, optional): Author of the prompt (defaults to "User") - **content** (string): The actual prompt content (markdown) ### `get_prompt` Retrieve a prompt by name. - **name** (string): Name of the prompt to retrieve ### `list_prompts` List all available prompts with metadata preview. No parameters required. ### `delete_prompt` Delete a prompt by name. - **name** (string): Name of the prompt to delete ## Usage Examples Once connected to an MCP client, you can use the tools like this: ### Method 1: Quick prompt creation with automatic metadata ```javascript // Add a prompt without frontmatter - metadata will be added automatically add_prompt({ name: "debug_helper", content: `# Debug Helper Help me debug this issue by: 1. Analyzing the error message 2. Suggesting potential causes 3. Recommending debugging steps` }) // This automatically adds default frontmatter with title "Debug Helper", category "general", etc. ``` ### Method 2: Structured prompt creation with full metadata control ```javascript // Create a prompt with explicit metadata using the structured tool create_structured_prompt({ name: "code_review", title: "Code Review Assistant", description: "Helps review code for best practices and potential issues", category: "development", tags: ["code", "review", "quality"], difficulty: "intermediate", author: "Development Team", content: `# Code Review Prompt Please review the following code for: - Code quality and best practices - Potential bugs or issues - Performance considerations - Security vulnerabilities ## Code to Review [Insert code here]` }) ``` ### Method 3: Manual frontmatter (preserves existing metadata) ```javascript // Add a prompt with existing frontmatter - no changes made add_prompt({ name: "custom_prompt", content: `--- title: "Custom Assistant" category: "specialized" tags: ["custom", "specific"] difficulty: "advanced" --- # Custom Prompt Content Your specific prompt here...` }) ``` ### Other operations ```javascript // Get a prompt get_prompt({ name: "code_review" }) // List all prompts (shows metadata preview) list_prompts({}) // Delete a prompt delete_prompt({ name: "old_prompt" }) ``` ## File Structure ``` prompts-mcp-server/ โ”œโ”€โ”€ src/ โ”‚ โ”œโ”€โ”€ index.ts # Main server orchestration โ”‚ โ”œโ”€โ”€ types.ts # TypeScript type definitions โ”‚ โ”œโ”€โ”€ cache.ts # Caching system with file watching โ”‚ โ”œโ”€โ”€ fileOperations.ts # File I/O operations โ”‚ โ””โ”€โ”€ tools.ts # MCP tool definitions and handlers โ”œโ”€โ”€ tests/ โ”‚ โ”œโ”€โ”€ helpers/ โ”‚ โ”‚ โ”œโ”€โ”€ testUtils.ts # Test utilities โ”‚ โ”‚ โ””โ”€โ”€ mocks.ts # Mock implementations โ”‚ โ”œโ”€โ”€ cache.test.ts # Cache module tests โ”‚ โ”œโ”€โ”€ fileOperations.test.ts # File operations tests โ”‚ โ”œโ”€โ”€ tools.test.ts # Tools module tests โ”‚ โ””โ”€โ”€ index.test.ts # Integration tests โ”œโ”€โ”€ prompts/ # Directory for storing prompt markdown files โ”‚ โ”œโ”€โ”€ code_review.md โ”‚ โ”œโ”€โ”€ debugging_assistant.md โ”‚ โ””โ”€โ”€ api_design.md โ”œโ”€โ”€ dist/ # Compiled JavaScript output โ”œโ”€โ”€ CLAUDE.md # Development documentation โ”œโ”€โ”€ package.json โ”œโ”€โ”€ tsconfig.json โ””โ”€โ”€ README.md ``` ## Architecture The server uses a modular architecture with the following components: - **PromptCache**: In-memory caching with real-time file change monitoring via chokidar - **PromptFileOperations**: File I/O operations with cache integration - **PromptTools**: MCP tool definitions and request handlers - **Type System**: Comprehensive TypeScript types for all data structures ## YAML Frontmatter Support Prompts can include structured metadata using YAML frontmatter: ```yaml --- title: "Prompt Title" description: "Brief description of the prompt" category: "development" tags: ["tag1", "tag2", "tag3"] difficulty: "beginner" | "intermediate" | "advanced" author: "Author Name" version: "1.0" --- # Prompt Content Your prompt content goes here... ``` ## MCP Client Configuration This server can be configured with various MCP-compatible applications. Here are setup instructions for popular clients: ### Claude Desktop Add this to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "prompts-mcp-server": { "command": "node", "args": ["/path/to/prompts-mcp-server/dist/index.js"], "env": { "PROMPTS_DIR": "/path/to/your/prompts/directory" } } } } ``` ### Cline (VS Code Extension) Add to your Cline MCP settings in VS Code: ```json { "cline.mcp.servers": { "prompts-mcp-server": { "command": "node", "args": ["/path/to/prompts-mcp-server/dist/index.js"], "env": { "PROMPTS_DIR": "/path/to/your/prompts/directory" } } } } ``` ### Continue.dev In your `~/.continue/config.json`: ```json { "mcpServers": [ { "name": "prompts-mcp-server", "command": "node", "args": ["/path/to/prompts-mcp-server/dist/index.js"], "env": { "PROMPTS_DIR": "/path/to/your/prompts/directory" } } ] } ``` ### Zed Editor In your Zed settings (`~/.config/zed/settings.json`): ```json { "assistant": { "mcp_servers": { "prompts-mcp-server": { "command": "node", "args": ["/path/to/prompts-mcp-server/dist/index.js"], "env": { "PROMPTS_DIR": "/path/to/your/prompts/directory" } } } } } ``` ### Custom MCP Client For any MCP-compatible application, use these connection details: - **Protocol**: Model Context Protocol (MCP) - **Transport**: stdio - **Command**: `node /path/to/prompts-mcp-server/dist/index.js` - **Environment Variables**: - `PROMPTS_DIR`: Custom directory for storing prompts (optional, defaults to `./prompts`) ### Development/Testing Setup For development or testing with the MCP Inspector: ```bash # Install MCP Inspector npm install -g @modelcontextprotocol/inspector # Run the server with inspector npx @modelcontextprotocol/inspector node dist/index.js ``` ### Docker Configuration Create a `docker-compose.yml` for containerized deployment: ```yaml version: '3.8' services: prompts-mcp-server: build: . environment: - PROMPTS_DIR=/app/prompts volumes: - ./prompts:/app/prompts stdin_open: true tty: true ``` ## Server Configuration - The server automatically creates the `prompts/` directory if it doesn't exist - Prompt files are automatically sanitized to use safe filenames (alphanumeric characters, hyphens, and underscores only) - File changes are monitored in real-time and cache is updated automatically - Prompts directory can be customized via the `PROMPTS_DIR` environment variable ### Environment Variables | Variable | Description | Default | |----------|-------------|---------| | `PROMPTS_DIR` | Directory to store prompt files | `./prompts` | | `NODE_ENV` | Environment mode | `production` | ## Requirements - Node.js 18.0.0 or higher - TypeScript 5.0.0 or higher - Dependencies: - @modelcontextprotocol/sdk ^1.0.0 - gray-matter ^4.0.3 (YAML frontmatter parsing) - chokidar ^3.5.3 (file watching) ## Development The project includes comprehensive tooling for development: - **TypeScript**: Strict type checking and modern ES modules - **Vitest**: Fast testing framework with 95 tests and 84.53% coverage - **ESLint**: Code linting (if configured) - **File Watching**: Real-time cache updates during development ## Troubleshooting ### Common Issues #### "Module not found" errors ```bash # Ensure TypeScript is built npm run build # Check that dist/ directory exists and contains .js files ls dist/ ``` #### MCP client can't connect 1. Verify the server starts without errors: `npm start` 2. Check the correct path is used in client configuration 3. Ensure Node.js 18+ is installed: `node --version` 4. Test with MCP Inspector: `npx @modelcontextprotocol/inspector node dist/index.js` #### Permission errors with prompts directory ```bash # Ensure the prompts directory is writable mkdir -p ./prompts chmod 755 ./prompts ``` #### File watching not working - On Linux: Install `inotify-tools` - On macOS: No additional setup needed - On Windows: Ensure Windows Subsystem for Linux (WSL) or native Node.js ### Debug Mode Enable debug logging by setting environment variables: ```bash # Enable debug mode DEBUG=* node dist/index.js # Or with specific debug namespace DEBUG=prompts-mcp:* node dist/index.js ``` ### Getting Help 1. Check the [GitHub Issues](https://github.com/tanker327/prompts-mcp-server/issues) 2. Review the test files for usage examples 3. Use MCP Inspector for debugging client connections 4. Check your MCP client's documentation for configuration details ### Performance Tips - The server uses in-memory caching for fast prompt retrieval - File watching automatically updates the cache when files change - Large prompt collections (1000+ files) work efficiently due to caching - Consider using SSD storage for better file I/O performance ## License MIT

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jezweb/smart-prompts-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server