Add redmine-communicator skill docs and setup tooling

2026-05-04 09:50:17 -04:00
parent 4c931bae1a
commit 42fc8318fa
6 changed files with 430 additions and 0 deletions
@@ -0,0 +1,78 @@
+---
+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.