Smart Prompts MCP

🚀 智能提示MCP服務器

智能提示MCP服務器是一個增強版的MCP（模型上下文協議）服務器，具備從GitHub倉庫中獲取提示的功能，擁有智能發現、組合和管理等特性。它是 prompts-mcp-server 的增強分支，集成了GitHub並具備高級功能。

🚀 快速開始

在開始使用本項目前，請先確保滿足以下條件：

• 安裝了Node.js 18+
• 安裝了npm或yarn包管理器
• 安裝並配置了Git
• 擁有GitHub賬戶（用於GitHub集成）
• 擁有GitHub個人訪問令牌（用於私有倉庫或避免速率限制）

安裝步驟

步驟1：克隆並安裝

# 克隆倉庫
git clone https://github.com/jezweb/smart-prompts-mcp.git
cd smart-prompts-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

# 驗證安裝
./verify-install.sh

步驟2：配置環境

在項目根目錄下創建一個 .env 文件：

# 必需：GitHub配置
GITHUB_OWNER=your-username          # 你的GitHub用戶名或組織名
GITHUB_REPO=your-prompts-repo      # 包含提示的倉庫
GITHUB_BRANCH=main                  # 使用的分支（默認：main）
GITHUB_PATH=                        # 子目錄路徑（可選）
GITHUB_TOKEN=ghp_xxxxx             # 個人訪問令牌（推薦）

# 可選：緩存配置
CACHE_TTL=300000                    # 緩存生存時間（毫秒，默認：5分鐘）
CACHE_REFRESH_INTERVAL=60000        # 自動刷新間隔（毫秒，默認：1分鐘）

# 可選：功能標誌
ENABLE_SEMANTIC_SEARCH=true         # 高級搜索功能
ENABLE_PROMPT_COMPOSITION=true      # 提示組合功能
ENABLE_USAGE_TRACKING=true          # 跟蹤提示使用情況

步驟3：MCP客戶端配置

對於Claude Desktop（macOS）

添加到 ~/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"
      }
    }
  }
}

對於Roo Cline（VS Code）

添加到Roo Cline MCP設置：

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

✨ 主要特性

核心功能

• 🔄 GitHub集成：直接從GitHub倉庫（公共/私有）獲取提示
• 🔍 智能發現：支持按類別和標籤過濾的高級搜索
• 🔗 提示組合：將多個提示組合成工作流
• 📊 使用跟蹤：分析提示使用模式
• ⚡ 實時更新：與GitHub自動同步
• 🤖 AI指導：增強的工具描述和工作流推薦

MCP協議支持

• 工具：7個用於提示管理的專業工具
• 資源：13個以上用於瀏覽和發現的資源端點
• 提示：支持Handlebars的動態模板

📁 提示組織最佳實踐

推薦的文件夾結構

your-prompts-repo/
├── README.md                    # 倉庫概述
├── ai-prompts/                  # AI和元提示
│   ├── meta-prompt-builder.md
│   └── prompt-engineer.md
├── development/                 # 開發提示
│   ├── 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/           # 內容提示
│   ├── blog-post-writer.md
│   └── youtube-metadata.md
├── business/                   # 業務提示
│   ├── proposal-generator.md
│   └── email-templates.md
└── INDEX.md                    # 可選：類別索引

命名約定

• 文件：使用短橫線分隔命名法（例如：api-documentation-generator.md）
• 提示名稱：在前置元數據中使用下劃線分隔命名法（例如：api_documentation_generator）
• 類別：使用小寫字母和連字符（例如：content-creation）
• 保持名稱描述性 且簡潔

📝 提示文件格式

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

🛠️ 可用工具

1. 🔍 search_prompts - 始終從這裡開始！按關鍵字、類別或標籤搜索
2. 📋 list_prompt_categories - 瀏覽可用類別並顯示數量
3. 📖 get_prompt - 獲取特定提示（使用搜索中的準確名稱）
4. ✨ create_github_prompt - 在GitHub中創建新提示
5. 🔗 compose_prompts - 組合多個提示
6. ❓ prompts_help - 獲取上下文幫助和指導
7. ✅ check_github_status - 驗證GitHub連接

推薦工作流

1. search_prompts → 查找現有提示
2. get_prompt → 查看完整內容
3. compose_prompts → 如果需要則組合
4. create_github_prompt → 僅在沒有現有提示時使用

🔧 故障排除

常見問題

1. "GitHub訪問失敗" 錯誤

# 檢查你的令牌是否具有repo權限
# 驗證.env文件中的令牌
GITHUB_TOKEN=ghp_your_actual_token

# 測試GitHub訪問
GITHUB_TOKEN=your_token node test-server.js

2. "速率限制超出" 錯誤

• 添加GitHub令牌以提高速率限制
• 減少緩存刷新間隔
• 使用 CACHE_TTL 進行更長時間的緩存

3. "未找到提示"

• 檢查倉庫結構是否符合預期格式
• 如果使用子目錄，請驗證 GITHUB_PATH
• 確保 .md 文件包含YAML前置元數據

4. MCP客戶端未連接

• 在配置中使用絕對路徑
• 檢查Node.js是否在系統路徑中
• 驗證所有環境變量
• 檢查日誌：tail -f ~/.claude/logs/mcp.log

5. 性能緩慢

• 增加 CACHE_TTL 以減少更新頻率
• 減小倉庫大小（歸檔舊提示）
• 使用類別來限制搜索範圍

📈 擴展考慮

當前限制

1. GitHub API速率限制
   • 每小時60個請求（未認證）
   • 每小時5000個請求（已認證）
   • 每次目錄獲取 = 1個請求
2. 搜索限制
   • GitHub中沒有原生語義搜索
   • 對所有文件進行線性搜索
   • 當提示數量超過100個時性能下降

擴展策略

對於50 - 200個提示

• ✅ 當前實現效果良好
• 使用類別和標籤進行組織
• 實現本地緩存
• 添加GitHub令牌以提高速率限制

對於200 - 1000個提示

• 🔄 實現索引文件

  # 倉庫根目錄下的INDEX.md
  prompts:
    - name: api_generator
      path: development/api-generator.md
      category: development
      tags: [api, codegen]
  

• 📊 添加搜索索引
  • 在構建時生成搜索索引
  • 存儲在 search-index.json 中
  • 通過GitHub Actions更新

對於1000個以上的提示

• 🗄️ 數據庫層
  • 使用SQLite進行本地緩存
  • 具備全文搜索功能
  • 定期與GitHub同步
• 🔍 集成Elasticsearch/Algolia
  • 專業的搜索基礎設施
  • 分面搜索
  • 相關性排序

未來擴展功能（路線圖）

1. 搜索索引生成
   • 使用GitHub Action構建索引
   • 下載單個索引文件
   • 本地語義搜索
2. 懶加載
   • 按需獲取類別
   • 漸進式增強
   • 大列表的虛擬滾動
3. CDN支持
   • 在邊緣緩存提示
   • 減少GitHub API調用
   • 更快的全球訪問

🚀 未來MCP服務器構想

基於GitHub集成模式，以下是潛在的MCP服務器：

1. 代碼片段MCP服務器

在GitHub中存儲和管理可重用的代碼片段

• 按語言組織
• 語法高亮
• 依賴管理
• 版本歷史

2. 文檔模板MCP

基於GitHub的文檔模板庫

• README生成器
• API文檔模板
• 項目文檔
• 從代碼自動生成

3. AI角色MCP服務器

管理AI個性配置

• 專業領域定義
• 溝通風格
• 行為特徵
• 團隊共享

4. 項目腳手架MCP

完整的項目模板管理

• 技術棧
• 樣板代碼
• 最佳實踐
• 配置預設

5. 學習資源MCP

精選的教育內容

• 教程和指南
• 代碼示例
• 進度跟蹤
• 基於技能的推薦

6. 配置管理器MCP

版本控制的應用程序配置

• 環境管理
• 秘密處理
• 團隊同步
• 回滾支持

7. 工作流自動化MCP

集成GitHub Actions

• 工作流模板
• CI/CD管道
• 自動化腳本
• 跨倉庫編排

8. 知識庫MCP

團隊知識管理

• 問答對
• 故障排除指南
• 最佳實踐
• 可搜索的維基

🧪 測試

服務器包含全面的測試，以確保可靠性和性能。

測試套件特性

• 關鍵功能的 100%測試覆蓋率
• 帶有詳細指標的 性能基準測試
• 帶有交互式圖表的 可視化測試報告
• 通過GitHub Actions實現的 自動化CI/CD

運行測試

# 運行完整測試套件
npm test

# 開發時的監視模式
npm run test:watch

# 生成覆蓋率報告
npm run test:coverage

# 運行性能基準測試
npm run test:perf

# 驗證安裝
npm run test:verify

測試報告

測試結果會自動以多種格式生成：

• JSON：用於分析的詳細結果 (test-results/latest.json)
• Markdown：人類可讀的報告 (test-results/latest.md)
• HTML：交互式可視化報告 (test-results/latest.html)

查看最新的測試結果：

• 測試報告（HTML）
• 覆蓋率報告
• 性能基準測試

🤝 貢獻

我們歡迎貢獻！請參閱 CONTRIBUTING.md 瞭解指南。

優先領域

1. 搜索改進
   • 實現模糊搜索
   • 添加搜索結果排名
   • 支持正則表達式模式
2. 性能優化
   • 實現連接池
   • 添加請求批處理
   • 優化緩存策略
3. UI/可視化
   • 用於瀏覽的Web界面
   • 提示預覽工具
   • 使用分析儀表板

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• 由 @tanker327 開發的原始 prompts-mcp-server
• Anthropic的 模型上下文協議
• 受MCP社區的啟發而構建

📞 支持

• 問題反饋：GitHub問題
• 討論交流：GitHub討論
• 示例參考：jezweb/prompts

為MCP社區用心打造 ❤️