Mantis MCP Server

🚀 Mantis MCP Server

The Mantis MCP Server is a powerful tool designed to interact with the Mantis issue tracking system. It simplifies operations such as issue management, user management, and project management, providing a unified and efficient solution.

🚀 Quick Start

Install Dependencies

npm install

Build

npm run build

Development Mode (Watch for Changes)

npm run watch

Run

npm start

📚 Configuration File Example

module.exports = {
    mantis: {
        url: 'http://your-mantis-server.com',
        username: 'admin', // Mantis administrator account name
        password: 'password' // Mantis administrator password
    },
    log: {
        level: 'info', // Log level: debug, info, warning, error
        dir: './logs/' // Log file storage directory
    },
    pages: {
        pageSize: 20, // Default page size
        defaultPage: 1 // Default starting page number
    }
}

✨ Features

Higher-Order Function: withMantisConfigured

This higher-order function is used to handle common validation logic, ensuring:

• Mantis API configuration check
• Unified error handling
• Standardized response format
• Automatic logging

Error Handling

The complete error handling mechanism includes:

• Mantis API error handling (including HTTP status codes)
• General error handling
• Structured error responses
• Detailed error log recording

Code Structure

Directory Structure

src/
├── config/                 # Configuration folder
│   ├── mantis.config.ts    # Mantis server configuration
│   └── log.config.ts      # Log configuration
├── services/               # Service modules
│   ├── issue.service.ts    # Issue handling logic
│   ├── user.service.ts     # User handling logic
│   └── project.service.ts  # Project handling logic
├── controllers/           # Controller layer
│   ├── issue.controller.ts # Issue interface definition
│   ├── user.controller.ts  # User interface definition
│   └── project.controller.ts # Project interface definition
└── utils/                 # Utility functions
    ├── logger.ts          # Logging tool
    └── errorHandling.ts   # Error handling tool

💻 Usage Examples

Installation

npm install mantis-mcp-server --save

Create a New Project

import { createServer } from 'mantis-mcp-server'

const server = createServer({
    mantis: {
        url: 'http://your-mantis-server.com',
        username: 'admin',
        password: 'password'
    },
    log: {
        level: 'info',
        dir: './logs/'
    }
})

server.listen(3000, () => {
    console.log('Server has started at http://localhost:3000')
})

Configuration

{
    "name": "mantis-mcp-server",
    "version": "1.0.0",
    "description": "Mantis issue tracking system MCP server",
    "main": "dist/index.js",
    "scripts": {
        "start": "node dist/index.js",
        "build": "webpack --config webpack.config.js"
    },
    "dependencies": {
        "express": "^4.18.2",
        "axios": "^1.5.0",
        "lodash": "^4.17.15",
        "moment": "^2.29.1"
    }
}

Release

Local Installation

npm install mantis-mcp-server --save

Global Installation

npm install -g mantis-mcp-server

Create a New Project

npx mantis-mcp-server init my-project
cd my-project && npm install

Update

Update from npm

npm update mantis-mcp-server

Uninstall

npm uninstall mantis-mcp-server

🛠️ Command Line Tools

Install CLI

npm install -g mantis-mcp-cli

Use CLI

mantis-mcp --version # Check the version number
mantis-mcp help # Display help information

📄 API Documentation

getIssues

Get a list of issues.

Parameters

• projectId (number): Project ID
• pageIndex (number): Current page number, default is 1
• pageSize (number): Page size, default is 20

Return

{
    issues: Array<Issue>, // List of issues
    totalPages: number,   // Total number of pages
    totalItems: number   // Total number of records
}

getIssue

Get a single issue.

Parameters

• issueId (number): Issue ID

Return

{
    id: number,       // Issue ID
    title: string,    // Issue title
    description: string, // Issue description
    status: string,   // Issue status
    priority: string, // Issue priority
    assignee: string, // Assignee
    reporter: string  // Reporter
}

createIssue

Create a new issue.

Parameters

{
    title: string,       // Required, issue title
    description: string, // Optional, issue description
    projectId: number,   // Required, project ID
    status: string,      // Optional, default is 'new'
    priority: string,    // Optional, default is 'normal'
    assignee: string     // Optional, default is empty
}

Return

{
    id: number         // ID of the newly created issue
}

updateIssue

Update an issue.

Parameters

{
    issueId: number,   // Required, issue ID
    title?: string,    // Optional, new title
    description?: string, // Optional, new description
    status?: string,   // Optional, new status
    priority?: string, // Optional, new priority
    assignee?: string  // Optional, new assignee
}

deleteIssue

Delete an issue.

Parameters

• issueId (number): Required, issue ID

🔧 Error Handling

All API calls return standard HTTP status codes:

• Success: 200 OK
• Created successfully: 201 Created
• Updated successfully: 204 No Content
• Deleted successfully: 204 No Content
• Failure: 4xx or 5xx error status codes

Error response format:

{
    code: number,     // Error code
    message: string   // Error message
}

⚠️ Important Note

1. All API calls require a valid authentication token.
2. Update and delete operations require additional permission verification.
3. Please ensure that the server time is synchronized with the Mantis time to avoid clock offset issues.

📄 License

MIT License

🤝 Contribution Guidelines

Forks and Pull Requests are welcome!