350 lines
9.6 KiB
Markdown
350 lines
9.6 KiB
Markdown
# PromptX MCP Server 集成指南
|
||
|
||
## 🎯 概述
|
||
|
||
PromptX MCP Server 将 PromptX 的所有 CLI 功能封装为 Model Context Protocol (MCP) 工具，让 Claude Desktop 等 AI 应用可以直接调用 PromptX 的专业角色和知识系统。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 启动 MCP Server
|
||
|
||
```bash
|
||
# 在 PromptX 项目目录中
|
||
npx dpml-prompt@snapshot mcp-server
|
||
```
|
||
|
||
### 2. Claude Desktop 配置
|
||
|
||
在 Claude Desktop 的配置文件中添加 PromptX MCP Server：
|
||
|
||
**Windows 配置路径：**
|
||
```
|
||
%APPDATA%\Claude\claude_desktop_config.json
|
||
```
|
||
|
||
**macOS 配置路径：**
|
||
```
|
||
~/Library/Application Support/Claude/claude_desktop_config.json
|
||
```
|
||
|
||
**配置内容：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"promptx": {
|
||
"command": "npx",
|
||
"args": ["dpml-prompt@snapshot", "mcp-server"],
|
||
"cwd": "/Users/username/Projects/MyProject"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 💡 **重要：关于 `cwd` 参数**
|
||
|
||
#### **`cwd` 的含义和MCP协议限制**
|
||
- `cwd` = **Current Working Directory** (当前工作目录)
|
||
- **重要**：由于MCP协议限制，**Server无法直接获取配置中的`cwd`参数**
|
||
- `process.cwd()`返回的是AI应用安装目录，而不是配置的工作目录
|
||
|
||
#### **✨ 正确配置方案（基于社区标准）**
|
||
|
||
**方案1：通过环境变量传递工作目录（推荐）**
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"promptx": {
|
||
"command": "npx",
|
||
"args": ["dpml-prompt@snapshot", "mcp-server"],
|
||
"cwd": "/Users/username/Projects/MyProject",
|
||
"env": {
|
||
"PROMPTX_WORKSPACE": "/Users/username/Projects/MyProject"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**方案2：依赖自动检测（适合标准项目）**
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"promptx": {
|
||
"command": "npx",
|
||
"args": ["dpml-prompt@snapshot", "mcp-server"],
|
||
"cwd": "/Users/username/Projects/MyProject"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
PromptX 会自动向上查找项目根目录（检测 `.git`、`package.json`、`.promptx` 等项目标识）。
|
||
|
||
#### **环境变量检测优先级**
|
||
|
||
PromptX 按以下优先级检测工作目录：
|
||
|
||
1. **`WORKSPACE_FOLDER_PATHS`** - VS Code/Cursor 标准环境变量
|
||
2. **`PROMPTX_WORKSPACE`** - PromptX 专用环境变量（推荐）
|
||
3. **`PWD`** - Shell 传递的工作目录
|
||
4. **智能推测** - 向上查找项目根目录
|
||
5. **回退** - 使用 `process.cwd()`
|
||
|
||
#### **应该指向哪里？**
|
||
|
||
```bash
|
||
✅ 推荐：指向你要让AI协助的项目目录
|
||
"cwd": "/Users/username/Projects/MyWebApp" # 你的Node.js项目
|
||
"PROMPTX_WORKSPACE": "/Users/username/Projects/MyWebApp"
|
||
|
||
✅ 具体示例：
|
||
# 前端项目
|
||
"cwd": "/Users/john/Projects/react-dashboard"
|
||
"env": {"PROMPTX_WORKSPACE": "/Users/john/Projects/react-dashboard"}
|
||
|
||
# 后端项目
|
||
"cwd": "/Users/john/Projects/express-api"
|
||
"env": {"PROMPTX_WORKSPACE": "/Users/john/Projects/express-api"}
|
||
|
||
# Windows项目
|
||
"cwd": "D:\\Work\\Projects\\MyDotNetApp"
|
||
"env": {"PROMPTX_WORKSPACE": "D:\\Work\\Projects\\MyDotNetApp"}
|
||
```
|
||
|
||
#### **⚠️ 常见错误和解决方案**
|
||
|
||
**错误现象：**
|
||
```bash
|
||
❌ 日志显示：
|
||
📍 工作目录: D:\Works\DevelopmentKits\cursor # AI应用安装目录
|
||
```
|
||
|
||
**解决方案：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"promptx": {
|
||
"command": "npx",
|
||
"args": ["dpml-prompt@snapshot", "mcp-server"],
|
||
"cwd": "D:\\Your\\Actual\\Project",
|
||
"env": {
|
||
"PROMPTX_WORKSPACE": "D:\\Your\\Actual\\Project"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**验证成功：**
|
||
```bash
|
||
✅ 日志显示：
|
||
[执行上下文] 使用PROMPTX_WORKSPACE: D:\Your\Actual\Project
|
||
📍 工作目录: D:\Your\Actual\Project # ✅ 正确的项目目录
|
||
```
|
||
|
||
#### **🔧 调试和故障排除**
|
||
|
||
**检查环境变量检测：**
|
||
```bash
|
||
# 启动时会显示详细的检测过程
|
||
[执行上下文] 使用PROMPTX_WORKSPACE: /your/project/path
|
||
```
|
||
|
||
**如果自动检测失败：**
|
||
1. **确保项目目录包含项目标识文件**：`.git`、`package.json`、`.promptx` 等
|
||
2. **明确设置环境变量**：添加 `"PROMPTX_WORKSPACE": "项目路径"`
|
||
3. **检查路径格式**：Windows使用双反斜杠 `\\` 或正斜杠 `/`
|
||
|
||
#### **💡 为什么需要环境变量？**
|
||
|
||
这不是PromptX的设计缺陷，而是**MCP协议的普遍限制**：
|
||
|
||
1. **协议限制**：MCP Server 无法直接访问客户端配置参数
|
||
2. **社区标准**：环境变量是社区公认的解决方案
|
||
3. **兼容性**：适用于所有MCP客户端（Claude Desktop、VS Code、Cursor等）
|
||
|
||
#### **📝 完整配置示例**
|
||
|
||
**Windows 示例：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"promptx": {
|
||
"command": "npx",
|
||
"args": ["dpml-prompt@snapshot", "mcp-server"],
|
||
"cwd": "D:\\Work\\Projects\\MyProject",
|
||
"env": {
|
||
"PROMPTX_WORKSPACE": "D:\\Work\\Projects\\MyProject",
|
||
"MCP_DEBUG": "true"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**macOS/Linux 示例：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"promptx": {
|
||
"command": "npx",
|
||
"args": ["dpml-prompt@snapshot", "mcp-server"],
|
||
"cwd": "/Users/username/Projects/MyProject",
|
||
"env": {
|
||
"PROMPTX_WORKSPACE": "/Users/username/Projects/MyProject",
|
||
"MCP_DEBUG": "true"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 可用工具
|
||
|
||
PromptX MCP Server 提供以下 6 个专业工具：
|
||
|
||
### 1. `promptx_init` - 初始化工作环境
|
||
- **功能**: 🏗️ 初始化 PromptX 工作环境
|
||
- **参数**: 无
|
||
- **用途**: 设置基础环境和系统协议
|
||
|
||
### 2. `promptx_hello` - 发现专业角色
|
||
- **功能**: 👋 发现可用的 AI 专业角色
|
||
- **参数**: 无
|
||
- **用途**: 查看所有可用的专业角色列表
|
||
|
||
### 3. `promptx_action` - 激活专业角色
|
||
- **功能**: ⚡ 激活指定专业角色
|
||
- **参数**:
|
||
- `role` (必需): 角色ID，如 `assistant`, `product-manager`, `java-backend-developer`
|
||
- **用途**: 获取特定角色的专业提示词和能力
|
||
|
||
### 4. `promptx_learn` - 学习专业资源
|
||
- **功能**: 📚 学习专业资源和知识
|
||
- **参数**:
|
||
- `resource` (必需): 资源URL，支持格式如 `thought://creativity`, `execution://best-practice`, `knowledge://scrum`
|
||
- **用途**: 深入学习特定领域的专业知识
|
||
|
||
### 5. `promptx_recall` - 检索记忆
|
||
- **功能**: 🔍 检索相关记忆和经验
|
||
- **参数**:
|
||
- `query` (可选): 检索关键词，不提供则返回所有记忆
|
||
- **用途**: 从记忆系统中查找相关的专业经验
|
||
|
||
### 6. `promptx_remember` - 保存记忆
|
||
- **功能**: 💾 保存重要信息到记忆系统
|
||
- **参数**:
|
||
- `content` (必需): 要保存的重要信息或经验
|
||
- `tags` (可选): 自定义标签，用空格分隔
|
||
- **用途**: 将重要信息保存到 AI 记忆系统
|
||
|
||
## 💡 使用示例
|
||
|
||
### 在 Claude Desktop 中的对话示例：
|
||
|
||
**用户**: "帮我初始化 PromptX 环境，然后激活产品经理角色"
|
||
|
||
**Claude 会自动调用**:
|
||
1. `promptx_init()` - 初始化环境
|
||
2. `promptx_hello()` - 查看可用角色
|
||
3. `promptx_action(role: "product-manager")` - 激活产品经理角色
|
||
|
||
**用户**: "学习敏捷开发的最佳实践，并记住关键要点"
|
||
|
||
**Claude 会自动调用**:
|
||
1. `promptx_learn(resource: "execution://agile-best-practice")` - 学习敏捷实践
|
||
2. `promptx_remember(content: "学到的关键要点", tags: "敏捷 最佳实践")` - 保存到记忆
|
||
|
||
## 🔄 工作流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[Claude Desktop] --> B[MCP Protocol]
|
||
B --> C[PromptX MCP Server]
|
||
C --> D[工作目录 cwd]
|
||
D --> E[专业角色系统]
|
||
D --> F[知识学习系统]
|
||
D --> G[记忆管理系统]
|
||
E --> H[返回专业提示词]
|
||
F --> I[返回学习内容]
|
||
G --> J[返回记忆数据]
|
||
```
|
||
|
||
## 🎯 优势
|
||
|
||
### 1. **无环境依赖**
|
||
- 解决了 AI 应用无法直接访问 CLI 环境的问题
|
||
- 通过 MCP 协议标准化接口
|
||
|
||
### 2. **专业能力增强**
|
||
- 6 个专业工具覆盖完整的 AI 能力增强流程
|
||
- 从角色激活到知识学习再到记忆管理
|
||
|
||
### 3. **标准化集成**
|
||
- 遵循 Model Context Protocol 标准
|
||
- 与 Claude Desktop 等主流 AI 应用无缝集成
|
||
|
||
### 4. **智能化操作**
|
||
- AI 可以根据对话需求自动选择合适的工具
|
||
- 支持复杂的多步骤工作流程
|
||
|
||
## 🛠️ 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **MCP Server 启动失败**
|
||
- 检查 Node.js 版本 (需要 >= 18)
|
||
- 确保在正确的项目目录中运行
|
||
|
||
2. **Claude Desktop 连接失败**
|
||
- 检查配置文件路径是否正确
|
||
- 确认 `cwd` 路径指向正确的工作目录
|
||
- 重启 Claude Desktop 应用
|
||
|
||
3. **工具调用失败**
|
||
- 检查 `cwd` 指向的目录是否存在
|
||
- 确认目录具有读写权限
|
||
- 查看 Claude Desktop 的日志输出
|
||
|
||
4. **记忆和配置丢失**
|
||
- 检查 `cwd` 配置是否一致
|
||
- 确认工作目录下是否有 `.promptx/` 文件夹
|
||
- 避免频繁更改 `cwd` 路径
|
||
|
||
### 调试模式
|
||
|
||
启动 MCP Server 时会显示详细的执行日志：
|
||
```bash
|
||
🔧 MCPServerCommand 已创建 (简化版本)
|
||
🚀 启动 PromptX MCP Server...
|
||
📡 等待 AI 应用连接...
|
||
🔧 可用工具:
|
||
- promptx_init: 初始化PromptX工作环境
|
||
- promptx_hello: 发现可用的AI专业角色
|
||
- promptx_action: 激活指定专业角色
|
||
- promptx_learn: 学习专业资源和知识
|
||
- promptx_recall: 检索相关记忆和经验
|
||
- promptx_remember: 保存重要信息到记忆系统
|
||
✅ MCP Server 已启动 (简化模式)
|
||
```
|
||
|
||
### **检查 `cwd` 配置**
|
||
```bash
|
||
# 在你配置的 cwd 目录下运行以下命令测试
|
||
npx dpml-prompt@snapshot --help
|
||
|
||
# 如果能正常显示帮助信息，说明 cwd 配置正确
|
||
```
|
||
|
||
## 🔮 未来规划
|
||
|
||
1. **完整 MCP 协议支持** - 实现完整的 MCP 协议功能
|
||
2. **更多 AI 应用支持** - 扩展到更多 AI 应用平台
|
||
3. **高级工具功能** - 添加更多专业工具和能力
|
||
4. **性能优化** - 提升工具调用的响应速度
|
||
|
||
---
|
||
|
||
通过 PromptX MCP Server，AI 应用可以获得完整的专业角色能力和知识管理系统，实现真正的 AI 能力增强。 |