Openspec MCP X

OpenSpec MCP-NPX软件包

用于Cursor IDE的OpenSpec MCP服务器-AI驱动的API规范生成和管理。现在可以作为NPX软件包使用，便于安装！

关于OpenSpec

OpenSpec是一种人工智能工具，用于生成、管理和验证API规范。此MCP服务器提供与Cursor IDE的无缝集成。

• GitHub: https://github.com/Fission-AI/OpenSpec
• NPM包: https://www.npmjs.com/package/openspec-mcp-x
• 特性：API规范的自动生成、验证和管理

🚀 快速入门（NPX方法-推荐）

使用OpenSpec MCP最简单的方法是通过NPX。无需手动安装！

1.配置光标

打开或创建 ~/.cursor/mcp.json:

窗户： C:\Users\\.cursor\mcp.json\ macOS/Linux： ~/.cursor/mcp.json

添加OpenSpec MCP配置：

{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "openspec-mcp-x@latest"],
      "env": {}
    }
  }
}

⚠️ 如果您已经有其他MCP服务器，添加 "openspec" 进入您现有的 "mcpServers" 对象（不要替换整个文件）。

2.重新启动游标

完全退出并重新启动Cursor IDE。

3.验证安装

在Cursor中，询问AI：

Check OpenSpec installation status

就是这样！NPX软件包将自动：

• ✅ 检测并使用您的Python安装（3.10+）
• ✅ 安装所需的Python依赖项（mcp、请求）
• ✅ 为您设置MCP服务器

4.安装OpenSpec CLI（必需）

OpenSpec MCP需要OpenSpec CLI工具。安装时使用：

npm install -g @fission-ai/openspec

验证安装：

openspec --version

需求

1.Python 3.10+

用于运行MCP服务器。

检查是否已安装：

python --version
# or
python3 --version

如果未安装或版本低于3.10：

• 视窗：参观https://www.python.org/downloads/ (⚠️ 安装时勾选“将Python添加到PATH”）
• macOS：使用自制咖啡： brew install python@3.12 或从以下网址下载https://www.python.org/downloads/

2.Node.js和npm

OpenSpec CLI工作所需。

检查是否已安装：

node --version
npm --version

如果未安装，请按照您平台的安装指南进行操作：

🪟 Windows安装

⚠️ 对窗户很重要：以下所有命令都包含非交互式标志，以避免安装提示。当AI助手执行这些命令时，这一点至关重要。

方法1：机翼（推荐-Windows 10+）

# Install Node.js LTS with non-interactive flags
# These flags prevent interactive prompts that would block automated installation
winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements

# After installation, restart your terminal and verify
node --version
npm --version

方法2：巧克力

# Install Node.js LTS with -y flag to skip confirmation
choco install nodejs-lts -y

# Verify installation
node --version
npm --version

方法3：铲

# Scoop is non-interactive by default
scoop install nodejs-lts
node --version
npm --version

方法4：手动下载

1. 访问https://nodejs.org/
2. 下载 LTS（长期支持） 版本安装程序
3. 运行安装程序（需要管理员权限）
4. 按照安装向导进行操作
5. 安装后重新启动终端
6. 验证： node --version 和 npm --version

📝 注： 在Windows上安装后，您必须重新启动终端或IDE才能更新PATH环境变量。如果命令仍然不起作用，请重新启动计算机。

🍎 macOS安装

方法1：自制（推荐）

# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js LTS
brew install node@20

# Verify installation
node --version
npm --version

方法2:nvm（节点版本管理器）

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal or reload shell configuration
source ~/.bashrc  # or ~/.zshrc for zsh

# Install Node.js LTS
nvm install --lts
nvm use --lts

# Verify installation
node --version
npm --version

方法3：手动下载

1. 访问https://nodejs.org/
2. 下载 长期支持 macOS版本
3. 打开.pkg文件并按照安装程序进行操作
4. 验证： node --version 和 npm --version

✅ 安装后验证

安装Node.js和npm后，验证安装：

# Check Node.js version (should be 18.x or higher)
node --version

# Check npm version
npm --version

# Optional: Update npm to latest version
npm install -g npm@latest

🔧 Node.js安装故障排除

Windows-安装后找不到命令：

1. 完全关闭所有终端窗口
2. 打开一个新的终端/PPowerShell窗口
3. 再试一次： node --version
4. 如果仍然无法工作，请重新启动计算机
5. Windows上需要刷新环境变量

macOS-npm权限错误：

# Fix npm permissions for global packages
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

验证路径：

• Node.js应该自动添加到系统PATH中
• 如果命令不起作用，请检查安装目录是否在PATH中

- 视窗: C:\Program Files\nodejs\ - macOS（自制）: /usr/local/bin/ 或 /opt/homebrew/bin/

3.光标IDE

此MCP服务器集成的IDE。

______________________________________________________________________

🤖 人工智能助理：自动化先决条件安装

如果你是一名帮助用户设置OpenSpec MCP的人工智能助手，请遵循以下自动化工作流程：

步骤1：检查当前系统

首先，检测平台并检查已安装的内容：

# Windows: Check winget availability
winget --version

# macOS: Check if Homebrew is available
brew --version

步骤2：自动检测缺失的先决条件

检查每个要求：

# Check Python (required: 3.10+)
python --version || python3 --version

# Check Node.js (required: 18.x+)
node --version

# Check npm (bundled with Node.js)
npm --version

# Check pip (Python package manager)
pip --version || pip3 --version

步骤3：安装缺失的组件

根据检测结果，使用上述平台特定部分中的适当命令。

🪟 Windows工作流（非交互式命令）

⚠️ 对WINDOWS至关重要：始终使用非交互式标志来防止安装提示！

# If Node.js/npm is missing, use winget with non-interactive flags:
winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements

# Alternative with Chocolatey (if available):
choco install nodejs-lts -y

# After installation, MUST restart terminal or commands won't be found
# Remind user to close and reopen terminal/IDE

# Then verify installation:
node --version
npm --version

为什么非交互式标志在Windows上至关重要：

• --accept-package-agreements：自动接受软件包许可协议
• --accept-source-agreements：自动接受源协议（例如Microsoft Store条款）
• 如果没有这些标志，命令将暂停并等待用户输入，从而阻止自动安装

🍎 macOS工作流

# Ensure Homebrew is installed first
brew --version || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js if needed
brew install node@20

# Verify
node --version
npm --version

步骤4：安装OpenSpec CLI

在确保安装了Node.js和npm之后：

# Install OpenSpec globally
npm install -g @fission-ai/openspec

# Verify OpenSpec installation
openspec --version

对Windows用户很重要：

• 在Windows上，如果 openspec 安装后找不到命令，用户需要重新启动终端
• npm全局包安装到： C:\Users\\AppData\Roaming\npm
• 安装Node.js后，此路径应位于系统path中

步骤5：继续MCP服务器设置

确认所有先决条件后，继续 安装 下面的部分。

💡 AI助手的基本技巧

对于Windows：

1. ⚠️ 始终使用非交互式标志: --accept-package-agreements --accept-source-agreements
2. ⚠️ 始终提醒用户重新启动终端 Node.js安装后
3. 环境变量仅在终端重启后刷新
4. 如果用户在安装后报告“找不到命令”→ 他们需要重新启动终端

对于macOS：

1. 使用前检查Homebrew是否已安装
2. 使用 python3 和 pip3 命令（不是 python 和 pip)
3. npm权限问题可以通过npm全局设置来修复（请参阅故障排除部分）

概述：

1. 在继续之前，请务必在安装后验证每个组件
2. 检查版本号以确保满足要求（Python 3.10+，Node.js 18+）
3. 如果命令失败，请提供相关的故障排除部分链接
4. 在继续安装MCP服务器之前，测试OpenSpec CLI安装

______________________________________________________________________

📦 替代安装方法

方法1:NPX（推荐-见上文快速入门）

NPX方法是最简单的，不需要手动安装。请参阅 快速开始 上面的部分。

方法2：手动安装（高级）

如果您更喜欢手动安装或需要开发设置：

1.验证你的Python命令

首先，检查哪个Python命令在您的系统上工作：

# Try these commands one by one:
python --version
python3 --version

记住哪个命令有效 （要么 python 或 python3)，您将在步骤3中需要它。

2.安装Python包

导航到openspec mcp目录并安装：

cd D:\Tools\0mcp\openspec-mcp
pip install -e .

3.配置光标

配置文件位置

所有平台： ~/.cursor/mcp.json

• macOS/Linux： ~/.cursor/mcp.json
• 窗户： C:\Users\\.cursor\mcp.json

💡 提示： 这是Cursor的主MCP配置文件，由所有MCP服务器共享。

⚠️ 重要提示：添加配置与创建配置

选项A：如果配置文件不存在（第一台MCP服务器）：

创建文件 ~/.cursor/mcp.json 包含以下内容：

{
  "mcpServers": {
    "openspec": {
      "command": "REPLACE_WITH_YOUR_PYTHON_COMMAND",
      "args": ["-m", "openspec_mcp.server"],
      "env": {}
    }
  }
}

⚠️ 替换 REPLACE_WITH_YOUR_PYTHON_COMMAND 使用您在步骤1中验证的命令(python 或 python3).

选项B：如果配置文件已存在（添加到现有的MCP服务器）：

⚠️ 不要替换整个文件！ 仅添加 "openspec" 进入现有 "mcpServers" 对象。

示例-如果您当前的配置有其他服务器：

{
  "mcpServers": {
    "some-other-server": {
      "command": "...",
      "args": ["..."],
      "env": {}
    }
  }
}

添加如下openspec条目（在上一个服务器后添加逗号）：

{
  "mcpServers": {
    "some-other-server": {
      "command": "...",
      "args": ["..."],
      "env": {}
    },
    "openspec": {
      "command": "REPLACE_WITH_YOUR_PYTHON_COMMAND",
      "args": ["-m", "openspec_mcp.server"],
      "env": {}
    }
  }
}

⚠️ 记得更换 REPLACE_WITH_YOUR_PYTHON_COMMAND 使用经过验证的Python命令。

✅ 多个MCP服务器可以在同一配置文件中共存！

4.重新启动游标

完全退出并重新启动Cursor。

______________________________________________________________________

✅ 验证

安装后（NPX或手动方法），在Cursor中验证：

Check OpenSpec installation status

或者直接使用该工具：

Use check_openspec_status tool

这将确认：

• ✅ Python已安装并可访问
• ✅ 已安装MCP依赖项
• ✅ OpenSpec CLI可用
• ✅ MCP服务器运行正常

可用工具

• check_openspec_status -检查是否安装了OpenSpec并获取版本信息
• openspec_init -在目录中初始化OpenSpec
• openspec_generate -生成API规范
• openspec_validate -验证API规范文件
• openspec_help -获取有关OpenSpec命令的帮助信息

使用示例

检查安装状态

Use check_openspec_status tool

这将检查是否安装了OpenSpec CLI并显示版本信息。

安装OpenSpec命令行界面

确保首先安装了Node.js和npm（请参阅 需求 部分）。

使用npm安装OpenSpec CLI：

npm install -g @fission-ai/openspec

验证安装：

openspec --version

在项目中初始化OpenSpec

Use openspec_init tool with:
- directory: ./my-project

生成API规范

Use openspec_generate tool with:
- directory: ./my-project
- output: ./api/openapi.yaml
- format: openapi

验证规范

Use openspec_validate tool with:
- file_path: ./api/openapi.yaml

工作流程

1. 安装Node.js和npm （如果尚未安装）：

- 访问https://nodejs.org/并下载LTS版本，或 - 使用包管理器（请参见 需求 部分）

1. 安装OpenSpec命令行界面 （仅限第一次）：

   npm install -g @fission-ai/openspec

1. 检查安装情况:

   Use check_openspec_status tool

1. 在项目中初始化:

   Use openspec_init tool with directory: ./my-project

1. 生成规格:

   Use openspec_generate tool with directory: ./my-project

1. 验证规格:

   Use openspec_validate tool with file_path: ./api/spec.yaml

故障排除

MCP服务器未显示

1. 检查Python版本： python --version 或 python3 --version （必须为3.10+）
2. 验证配置文件路径
3. 完全重新启动游标
4. 检查Cursor开发人员控制台是否有错误

依赖关系安装失败

# Upgrade pip
python -m pip install --upgrade pip

# Clear cache
pip cache purge

# Reinstall
pip install -e .

未找到OpenSpec CLI

1.检查是否安装了Node.js和npm：

node --version
npm --version

如果找不到，请从以下位置安装Node.jshttps://nodejs.org/或使用包管理器（请参阅 需求).

2.安装OpenSpec CLI：

npm install -g @fission-ai/openspec

3.验证安装：

openspec --version

4.使用MCP进行测试：

Use check_openspec_status tool

npm权限错误（macOS/Linux）

# Use npx instead, or fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

配置

OpenSpec可以通过其配置文件进行配置。运行后 openspec_init，您将在项目目录中找到配置文件。

请参阅 OpenSpec文档 了解详细的配置选项。

许可证

麻省理工学院

📦 包裹信息

NPX包

# Install globally (optional)
npm install -g openspec-mcp-x

# Or use directly with NPX (recommended)
npx openspec-mcp-x@latest

版本历史记录

看 更改日志.md 查看版本历史和更新。

出版

对于维护人员：

# First-time publish
./publish.sh

# Update version and publish
./update.sh

相关资源

• 模型上下文协议
• OpenAPI规范

支持

关于以下问题：

• MCP集成：在此存储库中打开一个问题
• OpenSpec功能：参观https://github.com/Fission-AI/OpenSpec
• NPM包: https://www.npmjs.com/package/openspec-mcp-x