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,125 @@
+# redMCP Tool Reference
+
+Use this reference after the `redmine-communicator` skill triggers and the task
+requires specific tool selection or setup details.
+
+## Runtime
+
+Required environment:
+
+```text
+REDMINE_URL=http://redmine.example.test
+REDMINE_API_KEY=...
+```
+
+For Streamable HTTP MCP:
+
+```text
+MCP_SERVER_TOKEN=...
+```
+
+Stdio server:
+
+```sh
+redMCP/bin/redmcp-server.php
+```
+
+HTTP server:
+
+```sh
+MCP_SERVER_TOKEN=... redMCP/bin/redmcp-http-server.php --host 0.0.0.0 --port 8765
+```
+
+HTTP endpoint defaults to `/mcp` and requires `Authorization: Bearer <token>`.
+
+## Read Tools
+
+- `redmine_list_projects`: list projects.
+- `redmine_get_project`: fetch one project by id or identifier.
+- `redmine_list_project_memberships`: users/groups and roles for a project.
+- `redmine_list_users`, `redmine_get_user`: user discovery.
+- `redmine_list_issues`: structured issue filters with friendly fields like
+  `project_id`, `status`, `updated`, `created`, `sort`, `limit`, and `page`.
+- `redmine_search`, `redmine_search_issues`: Redmine native text search.
+- `redmine_get_issue`: plain issue read.
+- `redmine_issue_with_helpdesk`: issue plus Helpdesk ticket/contact/messages.
+- `redmine_list_project_issue_categories`, `redmine_get_issue_category`.
+- `redmine_get_attachment`.
+
+## Write Tools
+
+- `redmine_create_issue`: create an issue.
+- `redmine_update_issue`: update fields or add an internal note. Helpdesk email
+  is opt-in with `options.send_helpdesk_email=true`.
+- `redmine_send_helpdesk_response`: send a customer-visible Helpdesk email.
+- `redmine_create_issue_relation`, `redmine_remove_issue_relation`.
+- `redmine_set_issue_parent`, `redmine_clear_issue_parent`.
+- `redmine_create_issue_category`, `redmine_update_issue_category`.
+- `redmine_upload_attachment`, `redmine_download_attachment`,
+  `redmine_update_attachment`.
+
+## Safety Notes
+
+- Customer-visible email requires explicit intent. Prefer internal notes unless
+  the user asks to email the customer.
+- Deletion tools for issues, projects, users, categories, and attachments are
+  intentionally not exposed. Relation removal only unlinks the relationship.
+- For Helpdesk workflows, read with `redmine_issue_with_helpdesk` before
+  replying so the agent sees customer/contact context.
+- For file uploads, use `redmine_upload_attachment` with a path, base64 content,
+  data URL, or file envelope. Use data/file inputs for PDFs and non-image files.
+- `redmine_download_attachment` requires an explicit path under `/tmp` or the
+  repository tree and limits optional base64 response size.
+
+## Example MCP Client Config
+
+```json
+{
+  "mcpServers": {
+    "redmcp": {
+      "command": "/path/to/redMCP/bin/redmcp-server.php"
+    }
+  }
+}
+```
+
+## Example Calls
+
+Read Helpdesk-aware issue context:
+
+```json
+{
+  "name": "redmine_issue_with_helpdesk",
+  "arguments": {
+    "issue_id": 39858,
+    "include": ["journals", "attachments"],
+    "message_limit": 100
+  }
+}
+```
+
+Internal note:
+
+```json
+{
+  "name": "redmine_update_issue",
+  "arguments": {
+    "issue_id": 39858,
+    "fields": {
+      "notes": "Internal follow-up note."
+    }
+  }
+}
+```
+
+Customer-visible Helpdesk reply:
+
+```json
+{
+  "name": "redmine_send_helpdesk_response",
+  "arguments": {
+    "issue_id": 39858,
+    "content": "Customer-visible response text."
+  }
+}
+```