redmine/skills/redmine-communicator/SKILL.md

name, description

name	description
redmine-communicator	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:

   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:

   <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 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.