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-osp-prompt": {
      "command": "mcp-osp-prompt",
      "env": {
        "PROMPT_PATH": "username/repository",
        "GIT_TOKEN": "ghp_your_github_token_here"
      }
    }
  }
}

GitLab Repository

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

Local Directory

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

Local Test by Source

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

Auto-Detection Results:

| PROMPT_PATH Format | Platform | Parsed As | |--------------------|----------|-----------| | user/repo | GitHub | user/repo@main:dev-arch | | https://github.com/owner/repo/tree/branch/path/to/files | GitHub | owner/repo@branch:path/to/files | | https://gitlab.com/group/project/-/tree/branch/path | GitLab | group/project@branch:path | | https://gitlab.com/a/b/c/-/tree/feature/x/deep/nested/path | GitLab | a/b/c@feature/x:deep/nested/path | | /absolute/path | Local | Local filesystem | | ./relative/path | Local | Local filesystem |

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

| Variable | Default | Description | |----------|---------|-------------| | PROMPT_PATH | (required) | Platform will be auto-detected from this path | | GIT_TOKEN | (required for remote) | GitHub (ghp_...) or GitLab (glpat-...) token | | DIALOG_MODE | auto | Dialog mode: auto|native|browser | | AUTOMATED_MODE | true | false=interactive confirmation, true=auto-execute | | CACHE_TTL_SEC | 86400 | Cache TTL in seconds (24 hours) | | FORCE_UPDATE | false | true=force remote fetch, bypass cache | | DEBUG_LOG | false | Enable detailed logging |

🧪 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-osp-prompt

📁 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

| Use Case | Configuration | Benefits | |----------|---------------|----------| | Local Development | Local mode + Native dialogs | Fast response, offline ready | | Team Collaboration | Remote mode + Browser dialogs | Beautiful UI, centralized management | | CI/CD Pipeline | Remote mode + AUTOMATED_MODE=true | No GUI dependencies | | Step-by-Step Development | Any mode + AUTOMATED_MODE=false | Interactive confirmation |

Token Permissions

GitHub Token Requirements:

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

GitLab Token Requirements:

• read_repository
• read_api

🔍 Troubleshooting

Common Issues

| Problem | Symptoms | Solution | |---------|----------|----------| | Tools not responding | Click tool, no response | 1. Check MCP config syntax2. Restart IDE3. Verify token validity | | Dialog not showing | Tool calls but no GUI | 1. Check DIALOG_MODE setting2. Try browser mode3. Check system permissions | | Invalid content returned | Wrong prompt content | 1. Check repository permissions2. Verify branch and file paths3. Clear cache | | API Rate Limit (429 errors) | Service starts with basic tools only | Normal behavior - basic tools work offline, cached content used when available | | Slow first-time loading | Long delay on first tool call | Expected - prompt content fetched on-demand, then cached for 3 hours |

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!