Content
# Trae-OpenSpec MCP Tool Suite
🚀 **Zero-Command-Line** OpenSpec project creation and management tool designed for Trae AI.
## 🎯 Features
- **🎨 Graphical Operation**: Fully based on Trae's GUI, no command line required
- **⚡ One-Click Creation**: Automatically generate complete projects through natural language descriptions
- **📋 Intelligent Specification**: AI-driven specification file generation
- **🔧 Code Optimization**: Intelligent code optimization based on OpenSpec specifications
- **🧪 Real-Time Testing**: Built-in testing and validation functions
## 📦 Quick Start
### 1. Environment Requirements
- **Node.js**: v18.0.0 or higher
- **Trae AI**: Latest version
- **Operating System**: Windows/macOS/Linux
### 2. Installation
#### Method 1: Quick Installation (Recommended)
```bash
# 1. Clone the MCP tool repository
git clone https://github.com/leon30083/trae-openspec-mcp.git
cd trae-openspec-mcp
# 2. Install dependencies
npm install
# 3. Start the server
npm start
```
#### Method 2: Global Installation
```bash
# 1. Install the MCP tool globally
npm install -g trae-openspec-mcp
# 2. Start the server in any directory
trae-openspec-mcp
```
#### Method 3: Development Mode Installation
```bash
# 1. Clone the repository
git clone https://github.com/leon30083/trae-openspec-mcp.git
cd trae-openspec-mcp
# 2. Install development dependencies
npm install
# 3. Start in development mode (with debugging information)
npm run dev
```
### 3. Start the MCP Server
You can choose the corresponding startup command according to the installation method:
```bash
# A) Start from local repository (Recommended)
npm start
# Or use Node directly
node mcp-server.js
# B) Start after global installation (CLI)
trae-openspec-mcp
# C) Development mode (automatic restart)
npm run dev
```
Tip: This MCP server is integrated with Trae using STDIO transmission, no HTTP port configuration is required.
### 4. Configure in Trae
1. Open Trae AI settings
2. Go to "MCP Server" configuration
3. Add a new MCP server
Add the MCP server using JSON in Trae's configuration:
```json
{
"mcpServers": {
"trae-openspec-mcp": {
"command": "node",
"args": [
"mcp-server.js"
],
"cwd": "<your local path>/trae-openspec-mcp"
}
}
}
```
Note:
- Set `cwd` to the repository root directory (containing `mcp-server.js`).
- If it has been published to npm, it can be changed to:
```json
{
"mcpServers": {
"trae-openspec-mcp": {
"command": "npx",
"args": ["-y", "trae-openspec-mcp"]
}
}
}
```
**Path Description (Windows)**
- The local path of this project in your environment is: `F:\\Cursor\\OpenSpec\\mcp-tools`
- When using Windows paths in JSON, use double backslashes `\\`
- When using `npx` configuration, you can omit `cwd`, which is resolved by npm to the installation directory
## 🛠️ Core Tools
### 1. Create OpenSpec Project
**Function**: Automatically create a complete OpenSpec project based on natural language descriptions
**Parameters**:
- `description` (required): Project requirements description
- `projectName` (required): Project name
- `techStack` (optional): Technical stack preference
**Example**:
```json
{
"description": "Create a modern blog system that supports user registration, article publishing, and commenting",
"projectName": "MyBlog",
"techStack": "React + Node.js"
}
```
**Returns**:
- Project structure
- Generated specification files
- Next steps guide
### 2. Generate OpenSpec Specification
**Function**: Generate OpenSpec specification files based on requirement descriptions
**Parameters**:
- `requirements` (required): Functional requirements description
- `projectType` (optional): Project type (blog/ecommerce/social/enterprise/custom)
**Example**:
```json
{
"requirements": "User management system, including registration, login, and personal profile management functions",
"projectType": "user_management"
}
```
**Returns**:
- Complete spec.md content
- Corresponding tasks.md content
- Instructions for use
### 3. Optimize Code
**Function**: Optimize existing code based on OpenSpec specifications
**Parameters**:
- `code` (required): Code to be optimized
- `spec` (required): OpenSpec specification content
- `feedback` (optional): Optimization feedback and suggestions
**Example**:
```json
{
"code": "function getUser(id) { return db.query('SELECT * FROM users WHERE id = ' + id); }",
"spec": "# API Specification\n## User Management\n- Input Validation\n- Error Handling\n- SQL Injection Protection",
"feedback": "Need to add input validation and error handling"
}
```
**Returns**:
- Optimized code
- Optimization report
- Improvement suggestions
## 📋 Usage Flow
### Scenario 1: Create a New Project
1. **Describe Requirements**: Describe your project requirements in Trae
2. **Generate Project**: Use the `create_openspec_project` tool
3. **View Results**: Check the generated project structure and specifications
4. **Start Development**: Open the project in Trae for development
### Scenario 2: Generate Specification
1. **Provide Requirements**: Describe your functional requirements
2. **Select Type**: Specify the project type or keep the default
3. **Generate Specification**: Use the `generate_openspec_spec` tool
4. **Apply Specification**: Apply the generated specification to the project
### Scenario 3: Optimize Code
1. **Provide Code**: Paste the code to be optimized
2. **Provide Specification**: Paste the corresponding OpenSpec specification
3. **Add Feedback**: (Optional) Provide optimization suggestions
4. **Get Optimization**: Use the `optimize_code_by_spec` tool
## 🎯 Project Templates
The MCP tool has built-in multiple project templates:
### Blog System (blog)
- User registration/login
- Article CRUD operations
- Comment system
- Rich text editor
### E-commerce Platform (ecommerce)
- Product management
- Shopping cart system
- Order processing
- Payment integration
### User Management (user_management)
- Authentication and authorization
- User profile management
- Permission control
- JWT Token management
### Custom Project (custom)
- Intelligent generation based on requirements
- Flexible feature combination
- Customizable specification templates
## 🔧 Configuration Options
### Server Configuration
Create a `mcp-config.json` file to customize server behavior:
```json
{
"server": {
"name": "trae-openspec-server",
"version": "0.1.0",
"timeout": 30000
},
"templates": {
"customTemplatesPath": "./custom-templates",
"enableCustomTemplates": true
},
"ai": {
"model": "gpt-4",
"temperature": 0.7,
"maxTokens": 2000
}
}
```
### Custom Templates
Add your templates in the `custom-templates` directory:
```
custom-templates/
├── blog/
│ ├── spec.md
│ └── tasks.md
├── ecommerce/
│ ├── spec.md
│ └── tasks.md
└── [your-template]/
├── spec.md
└── tasks.md
```
## 🐛 Troubleshooting
### Common Issues
**Q: MCP server cannot start**
- Check if the Node.js version meets the requirements
- Make sure all dependencies are installed correctly
- Check the console error messages
**Q: Trae cannot connect to the MCP server**
- Check if the server configuration is correct
- Make sure the working directory is set correctly
- Verify the network connection status
**Q: Tool call failed**
- Check if the parameter format is correct
- Make sure the required parameters are provided
- Check the console output for detailed information
### Debug Mode
Development mode will automatically restart and output detailed logs:
```bash
npm run dev
```
## 📚 Example Projects
### Example 1: Create a Blog System
```json
// Request
{
"name": "create_openspec_project",
"arguments": {
"description": "Create a modern personal blog system that supports Markdown editing, tag classification, and commenting",
"projectName": "PersonalBlog",
"techStack": "Next.js + TypeScript"
}
}
// Response
{
"content": [{
"type": "text",
"text": "✅ OpenSpec project \"PersonalBlog\" created successfully!\n\n📁 Generated file structure:\n 📁 PersonalBlog/\n 📁 openspec/\n 📁 specs/\n - spec.md: Blog system API specification\n - tasks.md: Implementation task list\n 📁 src/\n 📁 routes/\n - index.js: Route configuration\n 📁 models/\n - index.js: Data model\n 📄 package.json: Project configuration\n 📄 README.md: Project description\n\n🎯 Next steps:\n1. View the generated specification file\n2. Use AI to generate code\n3. Run and test the project"
}]
}
```
### Example 2: Generate User Management Specification
```json
// Request
{
"name": "generate_openspec_spec",
"arguments": {
"requirements": "Enterprise-level user management system, including organizational structure, role permissions, and single sign-on functions",
"projectType": "enterprise"
}
}
// Response
{
"content": [{
"type": "text",
"text": "# OpenSpec Specification File\n\nSpecification generated based on your requirements:\n\n## Requirements Analysis\nEnterprise-level user management system, including organizational structure, role permissions, and single sign-on functions\n\n## Generated Specification Content\n```markdown\n# API Specification: Enterprise User Management System\n\n## Project Information\n- Name: Enterprise User Management System\n- Version: v1.0.0\n- Description: Enterprise-level system that supports organizational structure, role permissions, and single sign-on\n\n## Core Functions\n### 1. Organizational Structure Management\n- Department management\n- Employee information management\n- Organizational hierarchy\n\n### 2. Role Permission System\n- Role definition and management\n- Permission assignment\n- Resource access control\n\n### 3. Single Sign-On (SSO)\n- OAuth2 integration\n- SAML support\n- Unified identity authentication\n```\n\n📋 Instructions for Use:\n1. Copy the above specification content to the project's spec.md file\n2. Adjust the details as needed\n3. Use AI to generate code implementation"
}]
}
```
## 🤝 Contribution Guide
Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
## 📄 License
MIT License - See [LICENSE](./LICENSE) file for details.
## 🔗 Related Links
- [OpenSpec Official Documentation](https://openspec.dev)
- [Trae AI Official Website](https://trae.ai)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
---
💡 **Tip**: This tool is fully compatible with Trae AI's graphical interface, no need to memorize any command-line instructions!
