requirements-analysis/docs/NPX_USAGE.md

简化的需求分析MCP服务 - 基于AI软件工程（优化版）6步流程

# 🚀 NPX 启动指南

## 📋 NPX启动方式

### 方法1：本地安装后使用npx（推荐）

#### 1. 打包项目
```bash
cd d:/Projects/试验/软件工程/开发计划(ts)/requirements-analysis-simple
npm run build
npm pack
```

#### 2. 全局安装
```bash
npm install -g requirements-analysis-simple-1.0.0.tgz
```

#### 3. 使用npx启动
```bash
# 完整命令名
npx requirements-analysis-simple

# 或使用短命令
npx req-analysis
```

### 方法2：直接从本地目录启动

#### 1. 在项目目录下
```bash
cd d:/Projects/试验/软件工程/开发计划(ts)/requirements-analysis-simple
npx . 
```

#### 2. 或者使用相对路径
```bash
npx ./dist/index.js
```

### 方法3：发布到npm后使用（生产环境）

#### 1. 发布到npm
```bash
npm publish
```

#### 2. 任何地方使用
```bash
npx requirements-analysis-simple
```

## 🎯 Claude Desktop 配置

### 使用npx命令配置

在Claude Desktop配置文件中：

```json
{
  "mcpServers": {
    "requirements-analysis-simple": {
      "command": "npx",
      "args": ["requirements-analysis-simple"]
    }
  }
}
```

### 或使用短命令

```json
{
  "mcpServers": {
    "requirements-analysis-simple": {
      "command": "npx", 
      "args": ["req-analysis"]
    }
  }
}
```

### 使用本地路径（开发环境）

```json
{
  "mcpServers": {
    "requirements-analysis-simple": {
      "command": "npx",
      "args": ["d:/Projects/试验/软件工程/开发计划(ts)/requirements-analysis-simple/dist/index.js"]
    }
  }
}
```

## 🔧 验证安装

### 检查全局安装
```bash
npm list -g requirements-analysis-simple
```

### 检查可执行文件
```bash
which requirements-analysis-simple
# 或在Windows上
where requirements-analysis-simple
```

### 测试启动
```bash
npx requirements-analysis-simple --help
```

## 📊 启动方式对比

| 方式 | 命令 | 优点 | 缺点 |
|------|------|------|------|
| **NPX全局** | `npx requirements-analysis-simple` | 简洁，任何地方可用 | 需要全局安装 |
| **NPX本地** | `npx ./dist/index.js` | 无需安装，直接使用 | 需要在项目目录 |
| **Node直接** | `node dist/index.js` | 最直接 | 路径依赖 |
| **NPM脚本** | `npm start` | 标准化 | 需要在项目目录 |

## 🎯 推荐配置

### 开发环境
```json
{
  "mcpServers": {
    "requirements-analysis-simple": {
      "command": "node",
      "args": ["d:/Projects/试验/软件工程/开发计划(ts)/requirements-analysis-simple/dist/index.js"],
      "cwd": "d:/Projects/试验/软件工程/开发计划(ts)/requirements-analysis-simple"
    }
  }
}
```

### 生产环境
```json
{
  "mcpServers": {
    "requirements-analysis-simple": {
      "command": "npx",
      "args": ["requirements-analysis-simple"]
    }
  }
}
```

## 🔍 故障排查

### 常见问题

#### 1. npx命令找不到
```bash
# 检查npm全局路径
npm config get prefix

# 检查PATH环境变量
echo $PATH  # Linux/Mac
echo %PATH% # Windows
```

#### 2. 权限问题
```bash
# Windows: 以管理员身份运行
# Linux/Mac: 使用sudo
sudo npm install -g requirements-analysis-simple-1.0.0.tgz
```

#### 3. 版本冲突
```bash
# 卸载旧版本
npm uninstall -g requirements-analysis-simple

# 重新安装
npm install -g requirements-analysis-simple-1.0.0.tgz
```

### 调试模式

#### 启用详细日志
```bash
DEBUG=* npx requirements-analysis-simple
```

#### 检查npx缓存
```bash
npx --help
npm cache clean --force
```

## 📝 使用示例

### 启动服务
```bash
$ npx requirements-analysis-simple
2025-07-11T07:17:51.958Z [INFO]  需求分析MCP服务已启动
  Data: {
  "name": "requirements-analysis-simple",
  "version": "1.0.0", 
  "steps": 6
}
```

### 在Claude Desktop中使用
1. 配置MCP服务器
2. 重启Claude Desktop
3. 输入需求分析请求
4. 按照6步流程执行

## 🎉 成功标志

当看到以下输出时，表示服务启动成功：

```
2025-07-11T07:17:51.958Z [INFO]  需求分析MCP服务已启动
  Data: {
  "name": "requirements-analysis-simple",
  "version": "1.0.0",
  "steps": 6
}
```

## 💡 最佳实践

1. **开发阶段**: 使用本地路径配置，便于调试
2. **测试阶段**: 使用npx本地包，验证打包正确性
3. **生产阶段**: 发布到npm，使用npx全局命令
4. **团队协作**: 统一使用npm scripts，避免环境差异

---

**总结**: NPX提供了灵活的启动方式，既支持开发环境的快速迭代，也支持生产环境的标准化部署。选择合适的方式可以大大提升开发和使用体验。