Jason Thistlethwaite
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
---
|
|
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.
|