Prompts MCP Server

🚀 Prompts MCP Server

Prompts MCP Server 是一个用于管理和提供提示词的模型上下文协议（MCP）服务器。该服务器允许用户和大语言模型（LLMs）轻松添加、检索和管理以 Markdown 文件形式存储的提示词模板，并支持 YAML 元数据。

🚀 快速开始

# 1. 从 NPM 安装
npm install -g prompts-mcp-server

# 2. 添加到您的 MCP 客户端配置（例如，Claude Desktop）
# 将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：
{
  "mcpServers": {
    "prompts-mcp-server": {
      "command": "prompts-mcp-server"
    }
  }
}

# 3. 重启您的 MCP 客户端并开始使用工具！

✨ 主要特性

• 添加提示词：将新的提示词以带有 YAML 元数据的 Markdown 文件形式存储。
• 检索提示词：按名称获取特定的提示词。
• 列出提示词：查看所有可用提示词及其元数据预览。
• 删除提示词：从集合中移除提示词。
• 基于文件的存储：提示词以 Markdown 文件形式存储在 prompts/ 目录中。
• 实时缓存：内存缓存，可自动监控文件更改。
• YAML 元数据：支持结构化元数据（标题、描述、标签等）。
• TypeScript 实现：完全使用 TypeScript 实现，并提供全面的类型定义。
• 模块化架构：通过依赖注入实现清晰的关注点分离。
• 全面测试：95 个测试用例，代码覆盖率达 84.53%。

📦 安装指南

选项 1：从 NPM 安装（推荐）

从 NPM 全局安装该包：

npm install -g prompts-mcp-server

这将使 prompts-mcp-server 命令在您的系统中可用。

安装完成后，您需要配置 MCP 客户端以使用它。请参阅 MCP 客户端配置。

选项 2：从 GitHub 安装（用于开发）

# 克隆仓库
git clone https://github.com/tanker327/prompts-mcp-server.git
cd prompts-mcp-server

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

# 测试安装
npm test

选项 3：直接下载

1. 从 GitHub 下载最新版本。
2. 解压到您想要的位置。
3. 执行选项 2 中的安装步骤。

验证

安装完成后，验证服务器是否正常工作：

# 启动服务器（应无错误显示）
npm start

# 或者使用 MCP Inspector 进行测试
npx @modelcontextprotocol/inspector prompts-mcp-server

💻 使用示例

基础用法

方法 1：快速创建提示词并自动添加元数据

// 添加一个没有元数据的提示词 - 元数据将自动添加
add_prompt({
  name: "debug_helper",
  content: `# Debug Helper

Help me debug this issue by:
1. Analyzing the error message
2. Suggesting potential causes
3. Recommending debugging steps`
})
// 这将自动添加默认的元数据，标题为 "Debug Helper"，类别为 "general" 等。

方法 2：使用完整元数据控制创建结构化提示词

// 使用结构化工具创建一个带有明确元数据的提示词
create_structured_prompt({
  name: "code_review",
  title: "Code Review Assistant",
  description: "Helps review code for best practices and potential issues",
  category: "development",
  tags: ["code", "review", "quality"],
  difficulty: "intermediate",
  author: "Development Team",
  content: `# Code Review Prompt

Please review the following code for:
- Code quality and best practices
- Potential bugs or issues
- Performance considerations
- Security vulnerabilities

## Code to Review
[Insert code here]`
})

方法 3：手动添加元数据（保留现有元数据）

// 添加一个带有现有元数据的提示词 - 不做任何更改
add_prompt({
  name: "custom_prompt",
  content: `---
title: "Custom Assistant"
category: "specialized"
tags: ["custom", "specific"]
difficulty: "advanced"
---

# Custom Prompt Content
Your specific prompt here...`
})

其他操作

// 获取一个提示词
get_prompt({ name: "code_review" })

// 列出所有提示词（显示元数据预览）
list_prompts({})

// 删除一个提示词
delete_prompt({ name: "old_prompt" })

📚 详细文档

MCP 工具

服务器提供以下工具：

add_prompt

向集合中添加一个新的提示词。如果未提供 YAML 元数据，将自动添加默认元数据。

• name（字符串）：提示词的名称
• content（字符串）：提示词的内容，采用 Markdown 格式，可包含可选的 YAML 元数据

create_structured_prompt

创建一个带有引导式元数据结构和验证的新提示词。

• name（字符串）：提示词的名称
• title（字符串）：提示词的可读标题
• description（字符串）：提示词功能的简要描述
• category（字符串，可选）：类别（默认为 "general"）
• tags（数组，可选）：用于分类的标签数组（默认为 ["general"]）
• difficulty（字符串，可选）："beginner"、"intermediate" 或 "advanced"（默认为 "beginner"）
• author（字符串，可选）：提示词的作者（默认为 "User"）
• content（字符串）：实际的提示词内容（Markdown 格式）

get_prompt

按名称检索提示词。

• name（字符串）：要检索的提示词的名称

list_prompts

列出所有可用提示词及其元数据预览。无需参数。

delete_prompt

按名称删除提示词。

• name（字符串）：要删除的提示词的名称

文件结构

prompts-mcp-server/
├── src/
│   ├── index.ts          # 主服务器编排
│   ├── types.ts          # TypeScript 类型定义
│   ├── cache.ts          # 带有文件监控的缓存系统
│   ├── fileOperations.ts # 文件 I/O 操作
│   └── tools.ts          # MCP 工具定义和处理程序
├── tests/
│   ├── helpers/
│   │   ├── testUtils.ts  # 测试工具
│   │   └── mocks.ts      # 模拟实现
│   ├── cache.test.ts     # 缓存模块测试
│   ├── fileOperations.test.ts # 文件操作测试
│   ├── tools.test.ts     # 工具模块测试
│   └── index.test.ts     # 集成测试
├── prompts/              # 存储提示词 Markdown 文件的目录
│   ├── code_review.md
│   ├── debugging_assistant.md
│   └── api_design.md
├── dist/                 # 编译后的 JavaScript 输出
├── CLAUDE.md            # 开发文档
├── package.json
├── tsconfig.json
└── README.md

架构

服务器采用模块化架构，包含以下组件：

• PromptCache：通过 chokidar 实现实时文件更改监控的内存缓存。
• PromptFileOperations：与缓存集成的文件 I/O 操作。
• PromptTools：MCP 工具定义和请求处理程序。
• 类型系统：为所有数据结构提供全面的 TypeScript 类型。

YAML 元数据支持

提示词可以使用 YAML 元数据包含结构化元数据：

---
title: "Prompt Title"
description: "Brief description of the prompt"
category: "development"
tags: ["tag1", "tag2", "tag3"]
difficulty: "beginner" | "intermediate" | "advanced"
author: "Author Name"
version: "1.0"
---

# Prompt Content

Your prompt content goes here...

MCP 客户端配置

此服务器可以与各种 MCP 兼容的应用程序进行配置。以下是一些流行客户端的设置说明：

Claude Desktop

将以下内容添加到您的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "prompts-mcp-server": {
      "command": "prompts-mcp-server",
      "env": {
        "PROMPTS_FOLDER_PATH": "/path/to/your/prompts/directory"
      }
    }
  }
}

Cline（VS Code 扩展）

在 VS Code 中添加到您的 Cline MCP 设置中：

{
  "cline.mcp.servers": {
    "prompts-mcp-server": {
      "command": "prompts-mcp-server",
      "env": {
        "PROMPTS_FOLDER_PATH": "/path/to/your/prompts/directory"
      }
    }
  }
}

Continue.dev

在您的 ~/.continue/config.json 中：

{
  "mcpServers": [
    {
      "name": "prompts-mcp-server",
      "command": "prompts-mcp-server",
      "env": {
        "PROMPTS_FOLDER_PATH": "/path/to/your/prompts/directory"
      }
    }
  ]
}

Zed Editor

在您的 Zed 设置（~/.config/zed/settings.json）中：

{
  "assistant": {
    "mcp_servers": {
      "prompts-mcp-server": {
        "command": "prompts-mcp-server",
        "env": {
          "PROMPTS_DIR": "/path/to/your/prompts/directory"
        }
      }
    }
  }
}

自定义 MCP 客户端

对于任何 MCP 兼容的应用程序，请使用以下连接详细信息：

• 协议：模型上下文协议（MCP）
• 传输方式：stdio
• 命令：prompts-mcp-server
• 环境变量：
  • PROMPTS_FOLDER_PATH：用于存储提示词的自定义目录（可选，默认为 ./prompts）

开发/测试设置

使用 MCP Inspector 进行开发或测试：

# 安装 MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 使用检查器运行服务器
npx @modelcontextprotocol/inspector prompts-mcp-server

Docker 配置

创建一个 docker-compose.yml 用于容器化部署：

version: '3.8'
services:
  prompts-mcp-server:
    build: .
    environment:
      - PROMPTS_FOLDER_PATH=/app/prompts
    volumes:
      - ./prompts:/app/prompts
    stdin_open: true
    tty: true

服务器配置

• 如果 prompts/ 目录不存在，服务器将自动创建该目录。
• 提示词文件将自动进行清理，以使用安全的文件名（仅包含字母数字字符、连字符和下划线）。
• 实时监控文件更改，并自动更新缓存。
• 可以通过 PROMPTS_FOLDER_PATH 环境变量自定义提示词目录。

环境变量

⚠️ 重要提示

如果设置了 PROMPTS_FOLDER_PATH，将使用该目录作为提示词目录。如果未设置，服务器将默认使用相对于服务器位置的 ./prompts 目录。

🔧 技术细节

要求

• Node.js 18.0.0 或更高版本
• TypeScript 5.0.0 或更高版本
• 依赖项：
  • @modelcontextprotocol/sdk ^1.0.0
  • gray-matter ^4.0.3（YAML 元数据解析）
  • chokidar ^3.5.3（文件监控）

开发

项目包含用于开发的全面工具：

• TypeScript：严格的类型检查和现代 ES 模块。
• Vitest：快速测试框架，95 个测试用例，代码覆盖率达 84.53%。
• ESLint：代码检查（如果配置）。
• 文件监控：开发期间实时更新缓存。

故障排除

常见问题

"Module not found" 错误

# 确保 TypeScript 已构建
npm run build

# 检查 dist/ 目录是否存在并包含 .js 文件
ls dist/

MCP 客户端无法连接

1. 验证服务器是否无错误启动：npm start
2. 检查客户端配置中使用的路径是否正确
3. 确保已安装 Node.js 18+：node --version
4. 使用 MCP Inspector 进行测试：npx @modelcontextprotocol/inspector prompts-mcp-server

提示词目录权限错误

# 确保提示词目录可写
mkdir -p ./prompts
chmod 755 ./prompts

文件监控不起作用

• Linux：安装 inotify-tools
• macOS：无需额外设置
• Windows：确保使用 Windows Subsystem for Linux（WSL）或原生 Node.js

调试模式

通过设置环境变量启用调试日志：

# 启用调试模式
DEBUG=* node dist/index.js

# 或者使用特定的调试命名空间
DEBUG=prompts-mcp:* node dist/index.js

获取帮助

1. 查看 GitHub 问题
2. 查看测试文件以获取使用示例
3. 使用 MCP Inspector 调试客户端连接
4. 查看 MCP 客户端的文档以获取配置详细信息

性能提示

• 服务器使用内存缓存以实现快速提示词检索。
• 文件监控会在文件更改时自动更新缓存。
• 由于缓存机制，大型提示词集合（1000+ 文件）也能高效工作。
• 考虑使用 SSD 存储以获得更好的文件 I/O 性能。

社区变体与扩展

👉 您是否基于 prompts-mcp-server 构建了很酷的东西？
请打开一个问题或拉取请求将其添加到这里，以便其他人可以发现您的变体！

📄 许可证

本项目采用 MIT 许可证。