MCP Zentao Bugs

🚀 ZenTao Bugs MCP Server

A ZenTao Bug management MCP server based on FastMCP, providing product search, Bug query, and resolution functions.

🚀 Quick Start

Installation

npm install -g mcp-zentao-bugs

Configuration and Operation

Method 1: Set Environment Variables

export ZENTAO_BASE_URL="https://your-zentao.com"
export ZENTAO_ACCOUNT="your-username"
export ZENTAO_PASSWORD="your-password"
mcp-zentao-bugs

Method 2: Use a .env File

# Create a .env file in the current directory
echo "ZENTAO_BASE_URL=https://your-zentao.com" > .env
echo "ZENTAO_ACCOUNT=your-username" >> .env
echo "ZENTAO_PASSWORD=your-password" >> .env
mcp-zentao-bugs

💡 Usage Tip

After a global installation, the .env file will be automatically loaded without additional configuration.

Method 3: One-time Settings

ZENTAO_BASE_URL="https://your-zentao.com" \
ZENTAO_ACCOUNT="your-username" \
ZENTAO_PASSWORD="your-password" \
mcp-zentao-bugs

Command Line Options

mcp-zentao-bugs --help      # Display help information
mcp-zentao-bugs --version   # Display version information

✨ Features

• 🔐 Automatic Login - Automatically log in to ZenTao and hold a Token upon startup.
• 🧠 Intelligent Search - Complete product and BUG searches in one step: directly return the BUG list when a single product is found; provide options when multiple products are found.
• 🐛 Bug Management - Query Bugs under a product, get details, and mark them as resolved.
• 🖼️ Image Extraction - Automatically extract image URLs from BUG steps for easy screenshot viewing.
• 🎯 Precise Search - Filter active BUGs at the API level and automatically paginate to ensure enough active BUGs are retrieved.
• 📡 SSE Stream Transmission - Real-time push logs and results via Server-Sent Events.
• 🔄 Serial Processing - Process in a single-process queue to ensure orderly execution of tool invocations.
• 🚀 FastMCP Standard - Compatible with the MCP protocol, supporting HTTP Streaming and SSE.
• 📉 Traffic Optimization - Intelligently merge search steps to reduce API calls and data transmission.

Tool List

Typical Workflow

🔄 Daily Bug Handling Workflow

Step 1: View Available Products (Optional)

{
  "keyword": "E-commerce",
  "limit": 10
}

• 🔍 Product Discovery: Check available products.
• 📝 Precise Naming: Get the accurate product name to avoid fuzzy matching.

Step 2: Get the Full Details of a Bug

{
  "productName": "E-commerce Platform",
  "keyword": "Login"
}

• 🎯 Precise Positioning: Automatically find the first active Bug assigned to you by using the product name.
• 📋 Full Details: Directly return the full information of the Bug without additional calls.
• ⚡ Efficient Search: Use the product name, which is more in line with business practices.
• 🔍 Precise Matching Verification: If multiple products are found during a fuzzy product search, prompt the user to select, ensuring accuracy.

Step 3: Mark as Resolved

{
  "bugId": 123,
  "comment": "Fixed the login page display issue."
}

• ✅ Quick Resolution: One-click to mark the Bug as resolved.

Step 4: Proceed to the Next Bug Repeat Step 2 to handle the next Bug...

📊 Other Tool Usage Scenarios

View Bug List (for Batch Operations)

{
  "productId": 1,
  "limit": 20,
  "keyword": "Interface"
}

View Bug Statistics

{
  "productId": 1,
  "activeOnly": true
}

📊 Workload Management

View My Bug Statistics

{
  "productId": 1,
  "activeOnly": true
}

• 📈 Workload Statistics: Understand how many active BUGs need to be processed currently.
• 📋 Priority Sorting: Automatically sort by severity.

View My Bug List

{
  "productId": 1,
  "limit": 20,
  "keyword": "Interface"
}

• 📝 Batch Viewing: Get the list of BUGs assigned to you.
• 🔍 Keyword Search: Quickly locate specific types of BUGs.

🎯 Tool Advantages

• 🎯 Default to Assigned to Me: All tools default to querying BUGs assigned to you, reducing interference.
• ⚡ Default to Active Status: Only display active BUGs by default, focusing on tasks to be processed.
• 🏷️ Friendly Product Names: Main tools support using product names instead of IDs, which is more in line with business practices.
• 📋 Directly Return Details: getMyBug directly returns the full details of the BUG, reducing the number of calls.
• 🔍 Precise Matching Verification: If multiple products are found during a fuzzy product search, prompt the user to select, ensuring accuracy.
• 🔒 Product Specification Required: All tools require specifying a product to ensure focus on one product at a time.
• 🔄 Process Optimization: The tool design fully complies with the workflow of "Get → Process → Resolve → Next".
• 💰 Traffic Saving: Use the generator pattern to stop once a match is found, avoiding unnecessary data transmission.
• 📊 Intelligent Statistics: Provide accurate workload statistics for easy progress management.

Image Extraction Function

The getBugDetail tool now supports automatically extracting images from BUG steps:

{
  "bug": {
    "id": 123,
    "title": "Login page display anomaly",
    "steps": "<p>Step 1: Open the login page</p><p></p>",
    "stepsImages": [
      "https://example.com/screenshot.png"
    ]
  }
}

Features:

• 🖼️ Automatic Recognition - Extract the src attributes of all <img> tags from HTML content.
• 🔗 URL Filtering - Only return valid image links starting with HTTP/HTTPS.
• 📋 Independent Storage - Store image URLs separately in the stepsImages array for easy access.

Quick Start

1. Environment Configuration

Copy .env.example to .env and configure ZenTao information:

cp .env.example .env

Edit the .env file:

# ZenTao Configuration
ZENTAO_BASE_URL=https://your-zentao.com/api.php/
ZENTAO_ACCOUNT=your-username
ZENTAO_PASSWORD=your-password

# Server Port
PORT=3000

2. Install Dependencies

pnpm install

3. Start the Server

# Method 1: Use npx (Recommended)
npx mcp-zentao-bugs

# Method 2: Run after local installation
pnpm start

# Method 3: Development mode (restart automatically on file changes)
pnpm dev

After the server starts:

• Automatically log in to ZenTao to obtain a Token.
• Start an HTTP Streaming service on the specified port.
• Provide /mcp (HTTP Streaming) and /sse (SSE) endpoints.

4. Health Check

curl http://localhost:3000/health

MCP Client Configuration

Trae / Claude Code Configuration

Add the following to the MCP configuration of Trae or Claude Code:

{
  "mcpServers": {
    "zentao-server": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude Desktop Configuration

Add the following to the MCP configuration file of Claude Desktop:

{
  "mcpServers": {
    "zentao-server": {
      "command": "node",
      "args": ["src/mcp-server.mjs"],
      "env": {
        "ZENTAO_BASE_URL": "https://your-zentao.com/api.php/",
        "ZENTAO_ACCOUNT": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "PORT": "3000"
      }
    }
  }
}

📚 Documentation

Project Structure

├── src/
│   ├── mcp-server.mjs     # Main file of the FastMCP server
│   ├── zentao-api.mjs     # Encapsulation module of the ZenTao API
│   └── server.mjs         # Original SSE server (backup)
├── scripts/               # Publishing and utility scripts
│   ├── publish.sh         # Publishing script for Linux/macOS
│   ├── publish.bat        # Publishing script for Windows
│   └── pre-publish.js     # Pre-publishing check script
├── api-docs/              # API documentation
├── .env                   # Environment variable configuration
├── .env.example           # Environment variable template
├── package.json
└── README.md

Environment Variables

Script Commands

# Install dependencies
pnpm install

# Start the server
pnpm start

# Development mode (watch file changes)
pnpm dev

API Endpoints

• HTTP Streaming: http://localhost:3000/mcp
• SSE: http://localhost:3000/sse
• Health Check: http://localhost:3000/health

🔧 Technical Details

• FastMCP - MCP server framework
• Node.js 20+ - Runtime environment
• Zod - Parameter validation
• dotenv - Environment variable management
• Modular Architecture - The ZenTao API is independently encapsulated for easy maintenance and testing

Troubleshooting

Login Failure

1. Check the ZenTao configuration in the .env file for correctness.
2. Confirm that the network can access the ZenTao server.
3. Verify that the account and password have permission to access the API.

Connection Issues

1. Confirm that the server has started: curl http://localhost:3000/health
2. Check the firewall settings to ensure the port is accessible.
3. View the server logs for detailed error information.

Tool Invocation Failure

1. Check if the ZenTao Token is valid (restart the server if the Token has expired).
2. Confirm that the input parameter format is correct.
3. View the error information in the server logs.

API Pagination Issue

Problem Description: The pagination mechanism of the ZenTao API has a special behavior. When the requested page number exceeds the maximum number of pages, the API does not return empty data but returns the data of the first page, and the returned page number field does not match the requested page number.

Solution:

• Pagination Validity Check: Determine if the maximum number of pages has been exceeded by comparing data.page with the requested page parameter.
• Intelligent Pagination: Retrieve data page by page and stop pagination when the page number inconsistency is detected.
• Performance Optimization: Set a reasonable maximum number of pages limit (50 pages) to prevent infinite loops.
• Data Integrity: Ensure all data is correctly processed when reaching the last page.

Implementation Details:

// Check if pagination is valid: if the returned page number does not match the requested page number, it means the maximum number of pages has been exceeded
if (data.page && data.page !== page) {
  break; // Reached the last page
}

Publishing to npmjs

Pre-publishing Preparation

1. Register an npm Account

   npm adduser
   # Or use an existing account: npm login
   

2. Check the Project Status

   # Run pre-publishing checks
   npm run pre-release
   
   # Or manually check
   ./scripts/publish.sh patch --dry-run
   

Publishing Process

Method 1: Use the Publishing Script (Recommended)

# Publish a patch version
./scripts/publish.sh patch

# Publish a minor version
./scripts/publish.sh minor

# Publish a major version
./scripts/publish.sh major

Method 2: Use npm Commands

# Publish a patch version
npm run release:patch

# Publish a minor version
npm run release:minor

# Publish a major version
npm run release:major

Method 3: Manual Publishing

# 1. Update the version
npm version patch

# 2. Publish
npm publish

# 3. Push tags
git push && git push --tags

Publishing Script Functions

• Automatic Checks: Check the project status, dependencies, and file integrity.
• Version Management: Automatically update the version number and create git tags.
• Secure Publishing: Check the npm login status and package name availability.
• Cross-platform Support: Provide bash and Windows batch scripts.

Version Management Strategy

• patch: Fix bugs, backward compatible (1.0.0 → 1.0.1)
• minor: Add new features, backward compatible (1.0.0 → 1.1.0)
• major: Major changes, may not be compatible (1.0.0 → 2.0.0)

Publishing Checklist

• [ ] Tests pass (npm test)
• [ ] README.md is fully updated
• [ ] The version number has been updated
• [ ] All changes have been committed
• [ ] The npm account is logged in
• [ ] The package name availability has been checked

📄 License

ISC License