Smart Prompts MCP Server

Fetches and manages prompts from GitHub repositories with intelligent discovery and composition features.

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 ofprompts-mcp-serverwith GitHub integration and advanced features.

# 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

# 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

{ "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" } } } }

"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" } }

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

- 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 descriptivebut concise

--- 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

- 🔍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

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

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
- UseCACHE_TTLto cache longer

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

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

- IncreaseCACHE_TTLfor less frequent updates
- Reduce repository size (archive old prompts)
- Use categories to limit search scope

- 60 requests/hour (unauthenticated)
- 5,000 requests/hour (authenticated)
- Each directory fetch = 1 request

- No native semantic search in GitHub
- Linear search through all files
- Performance degrades with 100+ prompts

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

- 🔄Implement Index File

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

- Generate search index on build
- Store insearch-index.json
- Update via GitHub Actions

- 🗄️Database Layer

- SQLite for local caching
- Full-text search capabilities
- Sync with GitHub periodically

- Proper search infrastructure
- Faceted search
- Relevance ranking

- GitHub Action to build index
- Download single index file
- Local semantic search

- Fetch categories on demand
- Progressive enhancement
- Virtual scrolling for large lists

- Cache prompts at edge
- Reduce GitHub API calls
- Faster global access

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

Store and manage reusable code snippets in GitHub

- Language-specific organization
- Syntax highlighting
- Dependency management
- Version history

GitHub-based documentation template library

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

- Expertise definitions
- Communication styles
- Behavioral traits
- Team sharing

- Technology stacks
- Boilerplate code
- Best practices
- Configuration presets

- Tutorials and guides
- Code examples
- Progress tracking
- Skill-based recommendations

- Environment management
- Secret handling
- Team synchronization
- Rollback support

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

- Q&A pairs
- Troubleshooting guides
- Best practices
- Searchable wiki

The server includes comprehensive testing to ensure reliability and performance.

- 100% test coverageof critical functionality
- Performance benchmarkswith detailed metrics
- Visual test reportswith interactive charts
- Automated CI/CDvia GitHub Actions

# 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 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)

- Test Report (HTML)
- Coverage Report
- Performance Benchmarks

# Development mode with hot reload npm run dev # Build for production npm run build # Start production server npm start

We welcome contributions! SeeCONTRIBUTING.mdfor guidelines.

MIT License - seeLICENSEfile for details.

- Originalprompts-mcp-serverby @tanker327
- Model Context Protocolby Anthropic
- Built with inspiration from the MCP community

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

Structured .aide spec files that give AI agents progressive disclosure into your codebase architecture. 6 MCP tools, 8 slash commands, TUI wizard, multi-IDE support.