redmine-mcp-tools/README.md

A comprehensive Model Context Protocol (MCP) server for Redmine integration. Provides 25+ specialized tools for complete Redmine API access including issue management, project administration, time tracking, and user management. Built with TypeScript and d

# Redmine MCP Tools

[![npm version](https://badge.fury.io/js/redmine-mcp-tools.svg)](https://badge.fury.io/js/redmine-mcp-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org/)

A comprehensive Model Context Protocol (MCP) server for Redmine integration, providing seamless access to Redmine's REST API through 25+ specialized tools. Built with TypeScript and designed for optimal performance and developer experience.

## 🚀 Quick Start

```bash
# Install globally
npm install -g redmine-mcp-tools

# Or use with npx (no installation required)
npx redmine-mcp-tools
```

## 📋 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [API Tools](#-api-tools)
- [Examples](#-examples)
- [Development](#-development)
- [Contributing](#-contributing)
- [License](#-license)

## ✨ Features

This MCP server provides complete Redmine functionality through the following tool categories:

### 🎯 Issue Management (7 tools)
- **`list_issues`** - List and search issues with flexible filtering options
- **`get_issue`** - Get detailed information about a specific issue including custom fields
- **`create_issue`** - Create new issues with full metadata support
- **`update_issue`** - Update existing issues with validation
- **`delete_issue`** - Safely delete issues with proper authorization
- **`add_issue_watcher`** - Add watchers to issues for notifications
- **`remove_issue_watcher`** - Remove watchers from issues

### 📁 Project Management (8 tools)
- **`list_projects`** - List projects with optional filtering and pagination
- **`show_project`** - Get detailed project information including modules and trackers
- **`create_project`** - Create new projects with proper hierarchy setup
- **`update_project`** - Update existing project configurations
- **`archive_project`** - Archive projects while preserving data integrity
- **`unarchive_project`** - Restore archived projects
- **`delete_project`** - Permanently delete projects with safeguards
- **`list_project_statuses`** - List all available project status options

### ⏱️ Time Entry Management (6 tools)
- **`list_time_entries`** - List time entries with comprehensive filtering
- **`show_time_entry`** - Get detailed time entry information
- **`create_time_entry_for_project`** - Log time directly to projects with activity tracking
- **`create_time_entry_for_issue`** - Log time to specific issues with detailed comments
- **`update_time_entry`** - Modify existing time entries with audit trail
- **`delete_time_entry`** - Remove time entries with proper validation

### 👥 User Management (5 tools)
- **`list_users`** - List users with advanced filtering and search capabilities
- **`show_user`** - Get comprehensive user profile information
- **`create_user`** - Create new user accounts with role assignment
- **`update_user`** - Update user profiles and permissions
- **`delete_user`** - Deactivate or remove user accounts safely

### 🔧 Core Features
- **Type-safe API** - Full TypeScript support with comprehensive type definitions
- **Error handling** - Robust error management with detailed error messages
- **Authentication** - Secure API key-based authentication
- **Validation** - Input validation using Zod schemas
- **Flexible configuration** - Environment-based configuration management
- **Comprehensive logging** - Detailed logging for debugging and monitoring

## 📦 Installation

### Prerequisites

- **Node.js** 18 or higher
- **Redmine instance** with REST API enabled
- **API access** - Valid Redmine API key with appropriate permissions

### Install Options

#### Option 1: Global Installation (Recommended)

```bash
npm install -g redmine-mcp-tools
```

#### Option 2: Use with npx (No installation required)

```bash
npx redmine-mcp-tools
```

#### Option 3: Local Installation

```bash
npm install redmine-mcp-tools
```

#### Option 4: From Source

```bash
git clone https://github.com/abdullahMASHUK/redmine-mcp-tools.git
cd redmine-mcp-tools
npm install
npm run build
```

## ⚙️ Configuration

### Environment Variables

Configure the following environment variables for your Redmine instance:

```bash
# Required: Redmine server URL
export REDMINE_URL="https://your-redmine-instance.com"

# Required: Your Redmine API token
export USER_API_TOKEN="your_api_token_here"
```

### Alternative Environment Variable Names

The server also supports these alternative variable names for flexibility:

```bash
# Alternative names (case-insensitive)
export redmine_url="https://your-redmine-instance.com"
export user_api_token="your_api_token_here"
```

### Getting Your API Token

1. Log into your Redmine instance
2. Go to **My Account** → **API access key**
3. Click **Show** to reveal your API key
4. Copy the token for use in configuration

## 🚀 Usage

### As a standalone MCP server

#### If installed globally
```bash
redmine-mcp-tools
```

#### If installed locally or using npx
```bash
npx redmine-mcp-tools
```

#### From source
```bash
npm start
```

### Integration with MCP-compatible applications

#### Option 1: Using npx (Recommended)
Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "redmine-connector": {
      "command": "npx",
      "args": ["redmine-mcp-tools"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "USER_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

#### Option 2: Using global installation
```json
{
  "mcpServers": {
    "redmine-connector": {
      "command": "redmine-mcp-tools",
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "USER_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

#### Option 3: Using local installation
```json
{
  "mcpServers": {
    "redmine-connector": {
      "command": "node",
      "args": ["./node_modules/redmine-mcp-tools/dist/index.js"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "USER_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

## 🛠️ API Tools

### Complete Tool Reference

| Category | Tool Name | Description |
|----------|-----------|-------------|
| **Issues** | `list_issues` | List and filter issues with advanced search |
| | `get_issue` | Retrieve detailed issue information |
| | `create_issue` | Create new issues with metadata |
| | `update_issue` | Update existing issue properties |
| | `delete_issue` | Delete issues safely |
| | `add_issue_watcher` | Add watchers to issues |
| | `remove_issue_watcher` | Remove watchers from issues |
| **Projects** | `list_projects` | List projects with filtering |
| | `show_project` | Get detailed project information |
| | `create_project` | Create new projects |
| | `update_project` | Update project configurations |
| | `archive_project` | Archive projects |
| | `unarchive_project` | Restore archived projects |
| | `delete_project` | Delete projects permanently |
| | `list_project_statuses` | List project status options |
| **Time Entries** | `list_time_entries` | List time entries with filters |
| | `show_time_entry` | Get time entry details |
| | `create_time_entry_for_project` | Log time to projects |
| | `create_time_entry_for_issue` | Log time to issues |
| | `update_time_entry` | Update time entries |
| | `delete_time_entry` | Delete time entries |
| **Users** | `list_users` | List users with search |
| | `show_user` | Get user profile details |
| | `create_user` | Create new user accounts |
| | `update_user` | Update user information |
| | `delete_user` | Deactivate user accounts |

## 📚 Examples

### Basic Operations

#### List recent issues
```json
{
  "tool": "list_issues",
  "arguments": {
    "limit": 10,
    "sort": "updated_on:desc",
    "status_id": "open"
  }
}
```

#### Create a new issue
```json
{
  "tool": "create_issue", 
  "arguments": {
    "project_id": 1,
    "subject": "Implement new feature",
    "description": "Detailed description of the feature request",
    "tracker_id": 2,
    "priority_id": 3,
    "assigned_to_id": 5
  }
}
```

#### Update an existing issue
```json
{
  "tool": "update_issue",
  "arguments": {
    "issue_id": 123,
    "status_id": 3,
    "notes": "Work completed and ready for review"
  }
}
```

### Time Tracking

#### Log time to an issue
```json
{
  "tool": "create_time_entry_for_issue",
  "arguments": {
    "issue_id": 123,
    "hours": 2.5,
    "activity_id": 8,
    "spent_on": "2025-01-15",
    "comments": "Implemented feature and added tests"
  }
}
```

#### Log time to a project
```json
{
  "tool": "create_time_entry_for_project",
  "arguments": {
    "project_id": 1,
    "hours": 4,
    "activity_id": 9,
    "spent_on": "2025-01-15",
    "comments": "Project planning and architecture review"
  }
}
```

### Project Management

#### Create a new project
```json
{
  "tool": "create_project",
  "arguments": {
    "name": "New Project",
    "identifier": "new-project",
    "description": "Project description",
    "is_public": false,
    "parent_id": 1
  }
}
```

### User Management

#### List active users
```json
{
  "tool": "list_users",
  "arguments": {
    "status": 1,
    "limit": 50
  }
}
```

## 🔧 Development

### Development Setup

```bash
# Clone the repository
git clone https://github.com/abdullahMASHUK/redmine-mcp-tools.git
cd redmine-mcp-tools

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your Redmine configuration

# Development mode with auto-reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Build TypeScript
npm run build

# Run built version
npm start
```

### Project Structure

```
redmine-mcp-tools/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── handlers/             # Request handlers
│   │   ├── issues.ts         # Issue management handlers
│   │   ├── projects.ts       # Project management handlers
│   │   ├── time_entries.ts   # Time tracking handlers
│   │   └── users.ts          # User management handlers
│   ├── tools/                # Tool definitions
│   ├── lib/                  # Core utilities
│   │   ├── client.ts         # Redmine API client
│   │   └── config.ts         # Configuration management
│   └── types/                # TypeScript type definitions
├── dist/                     # Compiled JavaScript
├── tests/                    # Test files
└── docs/                     # Documentation
```

## 📖 API Reference

All tools follow Redmine's REST API conventions. For detailed parameter information, refer to:

- [Redmine REST API Documentation](https://www.redmine.org/projects/redmine/wiki/rest_api)
- [Redmine API Guide](https://www.redmine.org/projects/redmine/wiki/Rest_api)

### Authentication

This server uses API key authentication. Ensure your API key has the necessary permissions for the operations you want to perform.

### Error Handling

The server provides comprehensive error handling with detailed error messages for:
- Authentication failures
- Permission issues
- Invalid parameters
- Network connectivity problems
- Redmine server errors

## 🤝 Contributing

We welcome contributions! Here's how you can help:

### Getting Started

1. **Fork the repository** on GitHub
2. **Clone your fork** locally
3. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
4. **Make your changes** with proper documentation
5. **Add tests** for new functionality
6. **Run the test suite** (`npm test`)
7. **Commit your changes** (`git commit -m 'Add amazing feature'`)
8. **Push to your branch** (`git push origin feature/amazing-feature`)
9. **Open a Pull Request**

### Development Guidelines

- **Code Style**: Follow the existing TypeScript/ESLint configuration
- **Testing**: Add unit tests for new features and bug fixes
- **Documentation**: Update README and inline documentation
- **Type Safety**: Maintain full TypeScript coverage
- **API Compatibility**: Ensure backward compatibility

### Reporting Issues

When reporting issues, please include:
- **Environment details** (Node.js version, OS, Redmine version)
- **Steps to reproduce** the issue
- **Expected vs actual behavior**
- **Error messages or logs**
- **Configuration details** (without sensitive information)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **npm Package**: [redmine-mcp-tools](https://www.npmjs.com/package/redmine-mcp-tools)
- **GitHub Repository**: [abdullahMASHUK/redmine-mcp-tools](https://github.com/abdullahMASHUK/redmine-mcp-tools)
- **Issue Tracker**: [GitHub Issues](https://github.com/abdullahMASHUK/redmine-mcp-tools/issues)
- **Redmine Documentation**: [Redmine REST API](https://www.redmine.org/projects/redmine/wiki/rest_api)
- **Model Context Protocol**: [MCP Documentation](https://modelcontextprotocol.io/)

## 📞 Support

Need help? Here are your options:

### Documentation
- **README**: This document covers most common use cases
- **API Reference**: Check the [Redmine REST API documentation](https://www.redmine.org/projects/redmine/wiki/rest_api)
- **Examples**: See the examples section above for common patterns

### Troubleshooting
1. **Check your configuration**: Verify `REDMINE_URL` and `USER_API_TOKEN`
2. **Verify API permissions**: Ensure your API key has sufficient permissions
3. **Test connectivity**: Try accessing your Redmine instance directly
4. **Check logs**: Enable debug logging for detailed error information

### Getting Help
- **GitHub Issues**: [Report bugs or request features](https://github.com/abdullahMASHUK/redmine-mcp-tools/issues)
- **Discussions**: [Community discussions and Q&A](https://github.com/abdullahMASHUK/redmine-mcp-tools/discussions)

---

**Made with ❤️ by [abdullahMASHUK](https://github.com/abdullahMASHUK)**