---
name: redmine-communicator
description: Use when an agent needs to install, configure, or operate the redMCP MCP server to communicate with Redmine, including Helpdesk-aware issue reads, safe issue updates, attachment handling, and explicit customer-visible Helpdesk responses.
---

# Redmine Communicator

## Overview

Use this skill to connect an agent to Redmine through `redMCP`, a PHP MCP server
that wraps Redmine's REST API and LDR's Helpdesk-aware extensions.

Use `redMCP` instead of ad hoc HTTP calls when the task involves Redmine issues,
projects, users, attachments, project categories, issue relations, or Helpdesk
customer communications.

## Setup Workflow

1. Install or stage `redMCP` from this repository:

   ```sh
   python3 skills/redmine-communicator/scripts/setup_redmcp.py \
     --redmine-url http://redmine.example.test \
     --redmine-api-key "$REDMINE_API_KEY"
   ```

   The default is dry-run. Add `--apply` to copy files and write `.env`.

2. Configure the MCP client with the printed stdio config. The command points to:

   ```text
   <install-dir>/bin/redmcp-server.php
   ```

3. Verify the server from the agent or client by listing tools. If using the
   Streamable HTTP transport, generate and configure `MCP_SERVER_TOKEN`.

4. Read [references/redmcp-tools.md](references/redmcp-tools.md) before making
   customer-visible changes or using less common tools.

## Operating Rules

- Prefer read-only tools first: list/search projects, issues, users, categories,
  memberships, and Helpdesk context before changing anything.
- For Helpdesk-backed issues, use `redmine_issue_with_helpdesk` instead of a
  plain issue read when customer identity or email context matters.
- `redmine_update_issue` is internal-note safe by default. It does **not** send
  Helpdesk customer email unless `options.send_helpdesk_email=true` is passed.
- Use `redmine_send_helpdesk_response` only when the user explicitly wants a
  customer-visible Helpdesk email.
- Do not invent Redmine project identifiers, tracker ids, category ids, or user
  ids. Discover them with redMCP tools first.
- Do not put Redmine API keys, MCP bearer tokens, passwords, or customer secrets
  in logs, committed files, or final answers.

## Common Tool Choices

- Find work: `redmine_list_issues`, `redmine_search`, `redmine_search_issues`.
- Read one issue: `redmine_get_issue`; use `redmine_issue_with_helpdesk` for
  Helpdesk/customer context.
- Internal update: `redmine_update_issue` with fields only.
- Customer reply: `redmine_send_helpdesk_response`, or
  `redmine_update_issue` with `options.send_helpdesk_email=true`.
- Attachments: `redmine_upload_attachment`, then include returned upload token
  in issue create/update; `redmine_download_attachment` only to safe local paths.
- Structure: issue relation, parent/child, project category, project membership,
  project, and user tools are available through MCP.

## Troubleshooting

- If `redmcp-server.php` fails immediately, check that `.env` contains
  `REDMINE_URL` and `REDMINE_API_KEY`.
- If PHP autoloading fails, run `composer install` in the `redMCP` install
  directory, or install from a package that includes `vendor/`.
- If HTTP transport is used, `MCP_SERVER_TOKEN` is required and clients must send
  `Authorization: Bearer <token>`.
- Debug logging can include customer text and issue notes. Enable it only for
  local troubleshooting and store logs somewhere private.