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社区用心打造 ❤️