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 with GitHub integration and advanced features.

🌟 Key Features

Core Capabilities

🔄 GitHub Integration: Fetch prompts directly from GitHub repositories (public/private)
🔍 Smart Discovery: Advanced search with category and tag filtering
🔗 Prompt Composition: Combine multiple prompts into workflows
📊 Usage Tracking: Analytics on prompt usage patterns
⚡ Real-time Updates: Automatic synchronization with GitHub
🤖 AI Guidance: Enhanced tool descriptions and workflow recommendations

MCP Protocol Support

Tools: 7 specialized tools for prompt management
Resources: 13+ resource endpoints for browsing and discovery
Prompts: Dynamic templates with Handlebars support

📋 Prerequisites

Before installation, ensure you have:

Node.js 18+ installed
npm or yarn package manager
Git installed and configured
GitHub account (for GitHub integration)
GitHub Personal Access Token (for private repos or to avoid rate limits)

🚀 Installation

Step 1: Clone and Install

# 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

# Verify installation
./verify-install.sh

Step 2: Configure Environment

Create a .env file in the project root:

# Required: GitHub Configuration
GITHUB_OWNER=your-username          # Your GitHub username or org
GITHUB_REPO=your-prompts-repo      # Repository containing prompts
GITHUB_BRANCH=main                  # Branch to use (default: main)
GITHUB_PATH=                        # Subdirectory path (optional)
GITHUB_TOKEN=ghp_xxxxx             # Personal access token (recommended)

# Optional: Cache Configuration
CACHE_TTL=300000                    # Cache time-to-live in ms (default: 5 min)
CACHE_REFRESH_INTERVAL=60000        # Auto-refresh interval in ms (default: 1 min)

# Optional: Feature Flags
ENABLE_SEMANTIC_SEARCH=true         # Advanced search features
ENABLE_PROMPT_COMPOSITION=true      # Prompt combination features
ENABLE_USAGE_TRACKING=true          # Track prompt usage

Step 3: MCP Client Configuration

For Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smart-prompts": {
      "command": "node",
      "args": ["/absolute/path/to/smart-prompts-mcp/dist/index.js"],
      "env": {
        "GITHUB_OWNER": "your-username",
        "GITHUB_REPO": "your-prompts-repo",
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

For Roo Cline (VS Code)

Add to Roo Cline MCP settings:

"smart-prompts": {
  "command": "node",
  "args": ["/absolute/path/to/smart-prompts-mcp/dist/index.js"],
  "env": {
    "GITHUB_OWNER": "your-username",
    "GITHUB_REPO": "your-prompts-repo",
    "GITHUB_TOKEN": "ghp_your_token_here"
  }
}

📁 Prompt Organization Best Practices

Recommended Folder Structure

your-prompts-repo/
├── README.md                    # Repository overview
├── ai-prompts/                  # AI and meta-prompts
│   ├── meta-prompt-builder.md
│   └── prompt-engineer.md
├── development/                 # Development prompts
│   ├── backend/
│   │   ├── api-design.md
│   │   └── database-schema.md
│   ├── frontend/
│   │   ├── react-component.md
│   │   └── vue-composition.md
│   └── testing/
│       ├── unit-test-writer.md
│       └── e2e-test-suite.md
├── content-creation/           # Content prompts
│   ├── blog-post-writer.md
│   └── youtube-metadata.md
├── business/                   # Business prompts
│   ├── proposal-generator.md
│   └── email-templates.md
└── INDEX.md                    # Optional: Category index

Naming Conventions

Files: Use kebab-case (e.g., api-documentation-generator.md)
Prompt Names: Use snake_case in frontmatter (e.g., api_documentation_generator)
Categories: Use lowercase with hyphens (e.g., content-creation)
Keep names descriptive but concise

📝 Prompt File Format

---
name: api_documentation_generator
title: REST API Documentation Generator
description: Generate comprehensive API documentation with examples
category: documentation
tags: [api, rest, documentation, openapi, swagger]
difficulty: intermediate
author: jezweb
version: 1.0
arguments:
  - name: api_spec
    description: The API specification or endpoint details
    required: true
  - name: format
    description: Output format (markdown, openapi, etc)
    required: false
    default: markdown
---

# API Documentation Generator

Generate comprehensive documentation for {{api_spec}} in {{format}} format.

Include:
- Endpoint descriptions
- Request/response examples
- Authentication details
- Error codes
- Rate limiting information

🛠️ Available Tools

🔍 search_prompts - Always start here! Search by keyword, category, or tags
📋 list_prompt_categories - Browse available categories with counts
📖 get_prompt - Retrieve specific prompt (use exact name from search)
✨ create_github_prompt - Create new prompts in GitHub
🔗 compose_prompts - Combine multiple prompts
❓ prompts_help - Get contextual help and guidance
✅ check_github_status - Verify GitHub connection

Recommended Workflow

1. search_prompts → Find existing prompts
2. get_prompt → View full content
3. compose_prompts → Combine if needed
4. create_github_prompt → Only if nothing exists

🔧 Troubleshooting

Common Issues

1. "GitHub access failed" Error

# Check your token has repo scope
# Verify token in .env file
GITHUB_TOKEN=ghp_your_actual_token

# Test GitHub access
GITHUB_TOKEN=your_token node test-server.js

2. "Rate limit exceeded" Error

Add a GitHub token to increase rate limits
Reduce cache refresh interval
Use CACHE_TTL to cache longer

3. "No prompts found"

Check repository structure matches expected format
Verify GITHUB_PATH if using subdirectory
Ensure .md files have YAML frontmatter

4. MCP Client Not Connecting

Use absolute paths in configuration
Check Node.js is in PATH
Verify all environment variables
Check logs: tail -f ~/.claude/logs/mcp.log

5. Slow Performance

Increase CACHE_TTL for less frequent updates
Reduce repository size (archive old prompts)
Use categories to limit search scope

📈 Scaling Considerations

Current Limitations

GitHub API Rate Limits
- 60 requests/hour (unauthenticated)
- 5,000 requests/hour (authenticated)
- Each directory fetch = 1 request
Search Limitations
- No native semantic search in GitHub
- Linear search through all files
- Performance degrades with 100+ prompts

Scaling Strategies

For 50-200 Prompts

✅ Current implementation works well
Use categories and tags for organization
Implement local caching
Add GitHub token for higher rate limits

For 200-1000 Prompts

🔄 Implement Index File

# INDEX.md in repo root
prompts:
  - name: api_generator
    path: development/api-generator.md
    category: development
    tags: [api, codegen]

📊 Add Search Index
- Generate search index on build
- Store in search-index.json
- Update via GitHub Actions

For 1000+ Prompts

🗄️ Database Layer
- SQLite for local caching
- Full-text search capabilities
- Sync with GitHub periodically
🔍 Elasticsearch/Algolia Integration
- Proper search infrastructure
- Faceted search
- Relevance ranking

Future Scaling Features (Roadmap)

Search Index Generation
- GitHub Action to build index
- Download single index file
- Local semantic search
Lazy Loading
- Fetch categories on demand
- Progressive enhancement
- Virtual scrolling for large lists
CDN Support
- Cache prompts at edge
- Reduce GitHub API calls
- Faster global access

🚀 Future MCP Server Ideas

Building on the GitHub integration pattern, here are potential MCP servers:

1. Code Snippets MCP Server

Store and manage reusable code snippets in GitHub

Language-specific organization
Syntax highlighting
Dependency management
Version history

2. Documentation Templates MCP

GitHub-based documentation template library

README generators
API documentation templates
Project documentation
Auto-generated from code

3. AI Personas MCP Server

Manage AI personality configurations

Expertise definitions
Communication styles
Behavioral traits
Team sharing

4. Project Scaffolding MCP

Full project template management

Technology stacks
Boilerplate code
Best practices
Configuration presets

5. Learning Resources MCP

Curated educational content

Tutorials and guides
Code examples
Progress tracking
Skill-based recommendations

6. Configuration Manager MCP

Version-controlled app configs

Environment management
Secret handling
Team synchronization
Rollback support

7. Workflow Automation MCP

GitHub Actions integration

Workflow templates
CI/CD pipelines
Automation scripts
Cross-repo orchestration

8. Knowledge Base MCP

Team knowledge management

Q&A pairs
Troubleshooting guides
Best practices
Searchable wiki

🧪 Testing

The server includes comprehensive testing to ensure reliability and performance.

Test Suite Features

100% test coverage of critical functionality
Performance benchmarks with detailed metrics
Visual test reports with interactive charts
Automated CI/CD via GitHub Actions

Running Tests

# Run full test suite
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run performance benchmark
npm run test:perf

# Verify installation
npm run test:verify

Test Reports

Test results are automatically generated in multiple formats:

JSON: Detailed results for analysis (test-results/latest.json)
Markdown: Human-readable reports (test-results/latest.md)
HTML: Interactive visual reports (test-results/latest.html)

View the latest test results:

Test Report (HTML)
Coverage Report
Performance Benchmarks

🧪 Development

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Priority Areas

Search Improvements
- Implement fuzzy search
- Add search result ranking
- Support for regex patterns
Performance Optimization
- Implement connection pooling
- Add request batching
- Optimize cache strategies
UI/Visualization
- Web interface for browsing
- Prompt preview tool
- Usage analytics dashboard

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Original prompts-mcp-server by @tanker327
Model Context Protocol by Anthropic
Built with inspiration from the MCP community

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Examples: jezweb/prompts

Made with ❤️ for the MCP community