MCP Prompt Fetcher

A powerful MCP (Model Context Protocol) server that provides intelligent development prompts for Cursor, VS Code, and other IDE tools. Supports GitHub, GitLab, and local directory sources with automatic platform detection.

🌟 Features

• 🚀 Multi-Platform Support: GitHub, GitLab, and local directories
• ⚡ Auto-Detection: Automatically detects platform from PROMPT_PATH
• 🔐 Unified Authentication: Single GIT_TOKEN for both GitHub and GitLab
• 🎛️ Flexible Dialogs: Native system dialogs and web-based interfaces
• 📦 Zero Configuration: Works out-of-the-box with intelligent defaults
• 🔄 Smart Caching: Optimized remote file fetching with TTL-based caching (3-hour default)
• ⚡ Lazy Loading: Prompt content loaded on-demand to minimize API calls
• 🛡️ Rate Limit Protection: Automatic fallback to cached data and graceful degradation
• 🎯 Efficient API Usage: Only fetches file lists on startup, content on tool invocation
• 🌍 Cross-Platform: Full macOS and Linux compatibility

📦 Installation

# Install globally (recommended)
npm install -g mcp-prompt-fetcher

# Or install locally
npm install mcp-prompt-fetcher

⚙️ Quick Setup

1️⃣ Simple Configuration (Only 2 environment variables needed!)

Add to your IDE's MCP configuration file (e.g., ~/.cursor/mcp.json):

GitHub Repository

{
  "mcpServers": {
    "mcp-prompt-fetcher": {
      "command": "mcp-prompt-fetcher",
      "env": {
        "PROMPT_PATH": "username/repository",
        "GIT_TOKEN": "ghp_your_github_token_here"
      }
    }
  }
}

GitLab Repository

{
  "mcpServers": {
    "mcp-prompt-fetcher": {
      "command": "mcp-prompt-fetcher",
      "env": {
        "PROMPT_PATH": "https://gitlab.com/group/project",
        "GIT_TOKEN": "glpat-your_gitlab_token_here"
      }
    }
  }
}

Local Directory

{
  "mcpServers": {
    "mcp-prompt-fetcher": {
      "command": "mcp-prompt-fetcher",
      "env": {
        "PROMPT_PATH": "/path/to/your/prompts"
      }
    }
  }
}

Local Test by Source

{
  "osp-prompt": {
    "command": "node",
    "args": [
      "/Users/penuel/workspace_script/osp-prompt/dev-mcp/server.js"
    ],
    "env": {
      "PROMPT_PATH": "https://gitlab.com/test-group/test-repo/-/tree/master",
      "GIT_TOKEN": "your-actual-git-token",
      "CACHE_TTL_SEC": "10800",
      "AUTOMATED_MODE": "false",
      "DEBUG_LOG": "true"
    }
  }
}

2️⃣ Universal URL Parser - Handle Any Complex URL!

Our advanced URL parser supports any complex GitLab and GitHub repository structure:

Complex URL Examples That Work:

# GitLab with multi-level projects and complex branches
"https://gitlab.com/Keccac256-evg/opensocial/osp-prompt/-/tree/master/dev-arch"
"https://gitlab.com/group/subgroup/project/-/tree/feature/new-ui/src/components"
"https://gitlab.com/company/team/service/-/tree/v1.2.3/docs/api"

# GitHub with deep nested paths and feature branches
"https://github.com/feast-dev/feast/tree/master/examples/java-demo/feature_repo/data"
"https://github.com/microsoft/vscode/tree/main/src/vs/editor/contrib"
"https://github.com/facebook/react/tree/feature/concurrent/packages/react/src"

Auto-Detection Results:

Smart Features:

• ✅ Multi-level projects: group/subgroup/project
• ✅ Complex branch names: feature/new-ui, hotfix/urgent-fix
• ✅ Deep file paths: src/main/java/com/example/service
• ✅ Version tags: v1.2.3, release/2024.1
• ✅ Automatic API URL generation for both platforms

🚀 Usage

Once configured, the following tools become available in your IDE:

• dev-feature - 🚀 Complete feature development (TDD workflow)
• dev-design - 📐 System architecture design and planning
• dev-refactor - 🔧 Code refactoring and optimization
• dev-small - ⚡ Quick development and bug fixes
• dev-tests - 🧪 Test coverage implementation (90%+ coverage)
• dev-bugfix - 🐛 Precise problem analysis and minimal-impact fixes
• dev-manual - 📋 Manual development type selection
• dev-feedback - 🔄 Interactive step-by-step confirmation

Command Examples

dev-feature: Implement user authentication with email/phone login
dev-design: Design microservices architecture for e-commerce platform
dev-refactor: Improve code readability in user management module
dev-small: Fix login button display issue in Safari browser
dev-tests: Achieve 90%+ test coverage for user registration feature
dev-bugfix: Debug intermittent session loss during user login

🔧 Environment Variables

🧪 Testing

Verify Installation

# Test local mode
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | PROMPT_PATH="./dev-arch" mcp-prompt-fetcher

# Test GitHub mode
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | PROMPT_PATH="user/repo" GIT_TOKEN="your_token" mcp-prompt-fetcher

# Test GitLab mode
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | PROMPT_PATH="https://gitlab.com/group/project" GIT_TOKEN="your_token" mcp-prompt-fetcher

Run Test Suite

npm test

install npm

<!-- 自动递增打包并打git tag -->
npm version patch|minor|major
<!-- 本地打包查看即将发布的内容 -->
npm pack --dry-run 
<!-- 跑测试 + 审计脚本 -->
npm run test:all  
npm run audit:security
<!-- 发布包 -->
npm publish --access public
<!-- 查看结果 -->
npm info mcp-prompt-fetcher

📁 Directory Structure

For local mode, your prompt directory should contain .prompt.md files:

dev-arch/
├── feature.prompt.md      # → dev-feature tool
├── design.prompt.md       # → dev-design tool
├── refactor.prompt.md     # → dev-refactor tool
├── small.prompt.md        # → dev-small tool
├── tests.prompt.md        # → dev-tests tool
└── bugfix.prompt.md       # → dev-bugfix tool

🎯 Best Practices

Recommended Configurations

Token Permissions

GitHub Token Requirements:

• public_repo (for public repositories)
• repo (for private repositories)

GitLab Token Requirements:

• read_repository
• read_api

🔍 Troubleshooting

Common Issues

Cache Management

# Clear cache
rm -rf ~/.cache/prompts/*.md

# Or force update
export FORCE_UPDATE=true

Debug Mode

Set DEBUG_LOG=true to see detailed execution logs for troubleshooting.

📋 API Reference

MCP Methods

• initialize - MCP protocol handshake
• tools/list - Get available tools (config-driven)
• tools/call - Execute specific tool

Tool Schema

Each tool follows this input schema:

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Development requirements or task description"
    }
  },
  "required": ["source"]
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋 Support

• Documentation: Check this README and inline code comments
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🎉 Happy Coding with Intelligent Prompts!