Redmine Assistant

Overview

Manage Redmine projects via mcp__redmine__* tools. Handles issue lifecycle, time tracking, project overview, and team coordination.

Scope: Manages Redmine issues, time entries, projects, and metadata via the Redmine MCP server. Does NOT: Manage GitHub/Jira/Asana/Linear, modify Redmine server config, run custom plugins, access local Redmine database directly, or fabricate data not returned by the API.

Core Capabilities

1. List & Search Issues

mcp__redmine__redmine_list_issues
  Filters: project_id, status_id, assigned_to_id, author_id, tracker_id, priority_id
  - parent_id (filter subtasks of a parent, or "~" for root issues only)
  - subject (partial match search)
  - updated_on, created_on (date filters, e.g. ">=2024-01-01")
  - sort (e.g. "updated_on:desc", "priority:desc")
  - view: "compact" (default) | "full" — controls output columns
  - fields: ["id","subject","status",...] — override columns precisely
  - limit (default 25), offset for pagination

Token optimization — ALWAYS prefer compact view (default). Use fields for precision:

• Default compact: id | subject | status | priority | assigned_to
• Full: adds tracker | done_ratio
• Custom: fields: ["id","subject","status","due_date"]
• Available columns: id, tracker, subject, status, priority, assigned_to, done_ratio, project, updated_on, due_date, author

2. Get Issue Details

mcp__redmine__redmine_get_issue
  - issue_id (required)
  - include: "journals,children,relations,changesets,watchers"
  - view: "compact" (default) | "full"
  - fields: ["id","subject","status",...] — override view

Token optimization — use compact view by default:

• Compact: id, subject, status, priority, assigned_to, done_ratio, tracker, project
• Full: all fields + description + custom_fields + dates
• Custom: fields: ["id","subject","status","custom_fields"] for specific needs

3. Create Issue

mcp__redmine__redmine_create_issue
  required: project_id, subject
  optional: description, tracker_id, status_id, priority_id,
            assigned_to_id, fixed_version_id, parent_issue_id, custom_fields

Before creating: call redmine_list_projects if project unknown, redmine_list_trackers for tracker IDs, redmine_list_priorities for priority IDs.

4. Update Issue

mcp__redmine__redmine_update_issue(id, ...fields)
  - status_id, assigned_to_id, priority_id, fixed_version_id
  - notes (add comment when updating)
  - custom_fields (array of {id, value})

5. Add Note / Comment

mcp__redmine__redmine_add_note(issue_id, notes, private_notes?)

6. Time Tracking

mcp__redmine__redmine_create_time_entry
  required: issue_id or project_id, hours
  optional: activity_id, comments, spent_on (YYYY-MM-DD)

mcp__redmine__redmine_list_time_entries
  - project_id, issue_id, user_id, from/to dates

mcp__redmine__redmine_update_time_entry(time_entry_id, ...)

mcp__redmine__redmine_delete_time_entry(time_entry_id)
  - Irreversible. Confirm with user before deleting.

For bulk timesheet auto-fill ("log this week", "fill timesheet"), see references/smart-time-logging.md.

7. Lookup Helpers

Custom fields rule: Always call redmine_list_custom_fields once per session before sending custom_fields in create/update — IDs vary per Redmine instance. Cache the result mentally for the rest of the session.

Workflows

Quick Project Overview

1. redmine_get_project(id) — project info
2. redmine_list_issues(project_id, status_id="open") — open issues
3. redmine_list_versions(project_id) — active sprints/milestones

Create Issue Workflow

1. Gather from user: project, subject, tracker type (minimum required)
2. Enhance content before creating (see references/ticket-style-guide.md):
   • Fix spelling, grammar, capitalization
   • Format subject: [Component] Clear action-oriented title
   • Structure description with sections if longer than 2 sentences
   • Convert shorthand to full words ("btn" → "button", "impl" → "implement")
3. Show enhanced version to user for confirmation before creating
4. Smart defaults: priority=Normal, status=New, assign to creator
5. Create → return issue URL: {REDMINE_URL}/issues/{id}

Close Issue Workflow

Always check for children first:

1. redmine_get_issue(id, include="children") — check child status
2. If children exist and are open → close children first
3. Then close parent

For Bug Tickets:

• Check if custom fields are required: redmine_list_custom_fields
• Common pattern: Regression + Rootcause fields when closing bugs
• Use redmine_update_issue(id, status_id=X, custom_fields=[...])

For Bulk Closing:

• If >5 sub-tasks: offer to close all at once
• Check all children, if any open → confirm with user to close all
• Iterate children, close each, then close parent

Status Change Workflow

1. redmine_list_statuses — discover available statuses (don't assume IDs)
2. redmine_update_issue(id, status_id=X, notes="reason") — always include note
3. Verify by fetching issue again

My Work View

1. redmine_get_current_user — get my user_id
2. redmine_list_issues(assigned_to_id="me", status_id="open") — my open issues

Time Tracking Report

1. redmine_list_time_entries(user_id="me", from="YYYY-MM-DD", to="YYYY-MM-DD")
2. Summarize by project/issue with total hours
3. Use redmine_list_activities to understand activity types

Find Assignees (Non-Admin)

1. Try redmine_list_users first
2. If 403 → use redmine_list_memberships(project_id) to find team members

Language Rule

ALL content written to Redmine MUST be in English. This applies to:

• Issue subjects and descriptions
• Notes and comments
• Time entry comments
• Any text field sent via API

If the user provides content in another language, translate it to clear, professional English before submitting. Do not ask — just translate and show the enhanced version for confirmation.

Smart Defaults

• When project unclear → ask or list projects (show max 5, suggest search)
• When creating issues → QUICK mode: only ask project + subject + tracker (rest use defaults)
• When updating status → always add notes explaining the change
• When listing → paginate if >25 results expected
• Dates → use YYYY-MM-DD format
• Never assume status/tracker/priority/custom-field IDs — always call lookup tools first

Error Recovery

Known Redmine Behaviors

Parent-Child Requirements

• Parent CANNOT be closed if children are still open
• Check children with: redmine_get_issue(id, include="children")
• Child status is visible in the response — check before closing

Status Transitions

• Redmine may restrict which status transitions are allowed
• If update fails with 422, check allow