Skip to content
Back to search

redmine_ai_helper

A Redmine plugin that adds AI agents, MCP Server, smart completion, and vector search.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/haru/redmine_ai_helper with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/haru/redmine_ai_helper'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/haru--redmine-ai-helper/badge.svg)](/listings/haru--redmine-ai-helper)

HTML

<a href="/listings/haru--redmine-ai-helper"><img src="/api/listings/haru--redmine-ai-helper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Extract the plugin to your Redmine plugins folder:

   cd {REDMINE_ROOT}/plugins/
   git clone https://github.com/haru/redmine_ai_helper.git

2. Install required dependencies:

   bundle install

3. Run database migrations:

   bundle exec rake redmine:plugins:migrate RAILS_ENV=production

4. Restart Redmine:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 730 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Redmine AI Helper Plugin
  2. [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
  3. [![build](https://github.com/haru/redmine_ai_helper/actions/workflows/build.yml/badge.svg)](https://github.com/haru/redmine_ai_helper/actions/workflows/build.yml)
  4. [![Maintainability](https://qlty.sh/badges/a0cabed6-3c2d-4eb2-a7b0-2cd58e6fdf72/maintainability.svg)](https://qlty.sh/gh/haru/projects/redmine_ai_helper)
  5. [![codecov](https://codecov.io/gh/haru/redmine_ai_helper/graph/badge.svg?token=1HOSGRHVM9)](https://codecov.io/gh/haru/redmine_ai_helper)
  6. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/haru/redmine_ai_helper)
  7. ![Redmine](https://img.shields.io/badge/redmine->=6.0-blue?logo=redmine&logoColor=%23B32024&labelColor=f0f0f0&link=https%3A%2F%2Fwww.redmine.org)
  8. ![Ruby](https://img.shields.io/badge/ruby->=3.2-blue?logo=ruby&logoColor=%23B32024&labelColor=f0f0f0&link=https%3A%2F%2Fwww.ruby-lang.org)
  9. - [Redmine AI Helper Plugin](#redmine-ai-helper-plugin)
  10. - [✨ Features](#-features)
  11. - [Chat Interface](#chat-interface)
  12. - [Issue Summarization](#issue-summarization)
  13. - [Create a comment draft with AI Helper](#create-a-comment-draft-with-ai-helper)
  14. - [Generate subtasks from issues](#generate-subtasks-from-issues)
  15. - [Similar Issues Search](#similar-issues-search)
  16. - [Duplicate Issue Check](#duplicate-issue-check)
  17. - [Inline Issue Description and Wiki Completion](#inline-issue-description-and-wiki-completion)
  18. - [Typo Checking and Correction Suggestions](#typo-checking-and-correction-suggestions)
  19. - [Assignee Suggestion](#assignee-suggestion)
  20. - [To-Do Suggestions](#to-do-suggestions)
  21. - [Custom Commands](#custom-commands)
  22. - [Project Health Report](#project-health-report)
  23. - [Health Report History](#health-report-history)
  24. - [Health Report REST API](#health-report-rest-api)
  25. - [Chat Channel Gateway](#chat-channel-gateway)
  26. - [Multi-modal File Support](#multi-modal-file-support)
  27. - [📦 Installation](#-installation)
  28. - [⚙️ Basic Configuration](#️-basic-configuration)
  29. - [Plugin Settings](#plugin-settings)
  30. - [Think Model Settings](#think-model-settings)
  31. - [Role and Permission Settings](#role-and-permission-settings)
  32. - [Project-specific Settings](#project-specific-settings)
  33. - [Data Access Policy](#data-access-policy)
  34. - [⚙️ Advanced Configuration](#️-advanced-configuration)
  35. - [Nginx Reverse Proxy Settings](#nginx-reverse-proxy-settings)
  36. - [MCP Server Settings](#mcp-server-settings)
  37. - [Using External MCP Servers](#using-external-mcp-servers)
  38. - [Transport Types](#transport-types)
  39. - [Exposing Redmine as an MCP Server](#exposing-redmine-as-an-mcp-server)
  40. - [Vector Search Settings](#vector-search-settings)
  41. - [Qdrant Setup](#qdrant-setup)
  42. - [Creating the Index](#creating-the-index)
  43. - [Recreating the Index](#recreating-the-index)
  44. - [🛠️ Build your own Agent](#️-build-your-own-agent)
  45. - [🪄 Langfuse integration](#-langfuse-integration)
  46. - [🔒 Running Without External Communication](#-running-without-external-communication)
  47. - [⚠️ Important Notice](#️-important-notice)
  48. - [🤝 Contributing](#-contributing)
  49. - [How to Run Tests](#how-to-run-tests)
  50. - [Preparation](#preparation)
  51. - [Running the Tests](#running-the-tests)
  52. - [🐞 Support](#-support)
  53. - [🌟 Credits](#-credits)
  54. The Redmine AI Helper Plugin adds AI chat functionality to Redmine, enhancing project management efficiency through AI-powered support.
  55. # ✨ Features
  56. - Adds an AI chat sidebar to the right side of your Redmine interface
  57. - The chat can be switched to a popup that you can move and resize; it stays open across pages
  58. - Enables various AI-assisted features including:
  59. - Issue search
  60. - Issue and Wiki content summarization
  61. - Repository source code explanation
  62. - Generate subtasks from issues
  63. - Inline issue description and wiki completion
  64. - Other project and Redmine-related inquiries
  65. - Typo checking and correction suggestions
  66. - To-do suggestions based on assigned issues
  67. - Custom commands for reusable prompt shortcuts
  68. - Provides a project health report
  69. - Supports multi-modal file analysis (images, PDFs, text, code, audio attachments)
  70. - Text attachments that are not UTF-8 are converted using Redmine's "Attachments and repositories encodings" setting (Administration > Settings > Repositories). Add the encoding your files use (e.g. `cp932` for Windows Japanese files containing characters such as ①) to that setting; files that cannot be converted are reported to the AI as unreadable.
  71. - Supports multiple AI models and services
  72. - MCP server integration
  73. - Vector search using Qdrant
  74. ## Chat Interface
  75. The AI Helper Plugin provides a chat interface that allows you to interact with AI models directly within Redmine. You can ask questions, get explanations, and receive assistance with project-related tasks.
  76. ![Image](https://github.com/user-attachments/assets/150259a0-4154-43e5-8e2b-bc75c1365cd8)
  77. ## Issue Summarization
  78. Issue summarization allows you to generate concise summaries of issues pages.
  79. ![Image](https://github.com/user-attachments/assets/2c62a792-b746-46ce-9268-3e29bdb4e53d)
  80. ## Create a comment draft with AI Helper
  81. You can create a comment draft for an issue using the AI Helper Plugin. This feature allows you to generate a comment based on the issue's content, which you can then edit and post.
  82. ![Image](https://github.com/user-attachments/assets/89f58bb4-bbc9-4407-9c55-309fac6893c2)
  83. ## Generate subtasks from issues
  84. You can generate subtasks from issues using the AI Helper Plugin. This feature allows you to create detailed subtasks based on the content of an issue, helping you break down complex tasks into manageable parts.
  85. ![Image](https://github.com/user-attachments/assets/c91a8d96-b608-43f2-9461-a0bdf8b35936)
  86. ## Similar Issues Search
  87. You can search for similar issues using the AI Helper Plugin. This feature is only available if vector search is set up. The AI Helper Plugin allows you to find issues similar to the current one based on its content, making it easier to discover related past issues and solutions.
  88. ![Image](https://github.com/user-attachments/assets/3217149b-4874-49b9-aa98-b35a7324bca3)
  89. ## Duplicate Issue Check
  90. When creating a new issue, you can check for duplicate issues before submitting. This feature uses vector search to find similar existing issues based on the subject and description you enter. This helps prevent creating duplicate issues and encourages reusing or referencing existing issues.
  91. This feature is only available if vector search is set up.
  92. ## Inline Issue Description and Wiki Completion
  93. You can use the AI Helper Plugin to complete issue descriptions and wiki pages inline. This feature provides suggestions and completions as you type, helping you write more detailed and accurate issue descriptions and wiki pages.
  94. You can accept completion suggestions by pressing the TAB key.
  95. ![Image](https://github.com/user-attachments/assets/d8e5da82-a5bb-46bf-836b-b548a32e2ab0)
  96. ### Completion settings
  97. Inline completion works out of the box. To tune it, add an `autocompletion` section to
  98. `{REDMINE_ROOT}/config/ai_helper/config.yml`. The file, the section and every individual key
  99. are optional.
  100. ```yaml
  101. autocompletion:
  102. timeout: 30 # seconds
  103. debounce_delay: 500 # milliseconds
  104. min_length: 5 # characters
  105. wiki_min_length: 5 # characters, wiki pages only
  106. suggestion_color: "#888888"
  107. ```
  108. | Key | Type | Default | Description |
  109. | --- | --- | --- | --- |
  110. | `timeout` | Number, 1–600 (seconds) | `30` | Time limit for the completion request to the LLM. A non-integer value is truncated toward zero before the range check, so `45.9` means 45 seconds. The request is not retried; on timeout the editor simply shows no suggestion. See [ADR-018](./docs/adr/018-completion-llm-requests-timeout-no-retry.md). |
  111. | `debounce_delay` | Number > 0 (milliseconds) | `500` for issues, `300` for wiki pages | How long typing must pause before a completion is requested. |
  112. | `min_length` | Integer ≥ 0 (characters) | `5` | Minimum body length before completions are requested. |
  113. | `wiki_min_length` | Integer ≥ 0 (characters) | falls back to `min_length` | Same as `min_length`, but for wiki pages only. Set it to give the wiki editor a threshold of its own. |
  114. | `suggestion_color` | `"#RGB"` or `"#RRGGBB"` | `"#888888"` | Colour of the inline suggestion text. Other formats are rejected. |
  115. Invalid values are ignored: the default is used instead and a warning naming the key, the
  116. value and the reason is written to the plugin log. Keys that are not listed above are ignored
  117. and reported the same way. A missing file falls back to the defaults, so an absent
  118. configuration never prevents the edit screen from loading. A file that exists but cannot be
  119. parsed as YAML is a different matter: the plugin reads it while Redmine boots, so a syntax
  120. error there stops the whole instance from starting. Check the plugin log after editing it.
  121. ## Typo Checking and Correction Suggestions
  122. You can use the AI Helper Plugin to check for typos and receive correction suggestions. This feature helps you maintain content in your issues and wiki pages by identifying and correcting spelling errors.
  123. ![Image](https://github.com/user-attachments/assets/6a1e1963-f6ef-45fc-82a2-52dc377a35b1)
  124. ## Assignee Suggestion
  125. The AI Helper Plugin can suggest optimal assignees when creating or editing issues. This feature analyzes the issue content, past assignment history, current workload, and project context to recommend suitable team members. Click the "Suggest assignee with AI Helper" link next to the "Assign to me" link in the issue form to receive assignee recommendations.
  126. ![Image](https://github.com/user-attachments/assets/922985fb-4ec9-4784-b757-56b5c87e5e5c)
  127. ## To-Do Suggestions
  128. The AI Helper Plugin can suggest what you should work on today based on your assigned issues. This feature analyzes your issues considering due dates, priorities, and how long they've been untouched, then provides prioritized recommendations for both the current project and other projects you have access to. Access this feature from the "To Do" link in the account menu (available only within project contexts where you have AI Helper permissions). In Redmine 7.0 and later, click your account icon in the top-right corner to open the account menu. In Redmine 6.x and earlier, the link is shown directly in the top menu bar.
  129. ![Image](https://github.com/user-attachments/assets/db12d4ac-58ee-4fd8-893c-d2feda0128cf)
  130. ## Custom Commands
  131. Custom Commands allow you to create reusable prompt shortcuts for the AI Helper chat interface. Define a command once and invoke it by typing `/commandname` in the chat input. An autocomplete dropdown appears as you type, showing available commands with their descriptions.
  132. Three scope levels are available: **Global** (available across all projects), **Project** (available within a specific project), and **User** (personal commands visible only to you). When multiple commands share the same name, User commands take the highest priority, followed by Project commands, then Global commands.
  133. Commands support template variables `{input}`, `{user_name}`, `{project_name}`, and `{datetime}` for dynamic prompt generation. You can manage custom commands from the "Custom Commands" tab on the AI Helper dashboard.
  134. ## Project Health Report
  135. You can generate a project health report using the AI Helper Plugin. This feature provides a comprehensive overview of the project's status, including metrics such as open issues, closed issues, and overall project health.
  136. ![Image](https://github.com/user-attachments/assets/8f01c6ef-6cee-4e79-b693-c17081566c78)
  137. Health reports can be exported to Markdown and PDF formats.
  138. ### Health Report History
  139. Health reports are automatically saved and can be reviewed later. You can:
  140. - View past health reports to track project progress over time
  141. - Compare multiple health reports to analyze trends and changes in project health
  142. - Export comparison results to Markdown and PDF formats
  143. This historical tracking helps you understand how your project's health evolves and identify patterns or issues early.
  144. ### Health Report REST API
  145. You can generate health reports programmatically using the REST API. This allows you to schedule automatic health report generation using cron or other task schedulers.
  146. **Endpoint:**
  147. ```
  148. POST /projects/:project_id/ai_helper/health_report.json
  149. ```
  150. **Authentication:**
  151. Use Redmine's standard API key authentication by including the `X-Redmine-API-Key` header.
  152. **Example Request:**
  153. ```bash
  154. curl -X POST \
  155. -H "X-Redmine-API-Key: your_api_key_here" \
  156. -H "Content-Type: application/json" \
  157. https://your-redmine-instance.com/projects/your-project/ai_helper/health_report.json
  158. ```
  159. **Response:**
  160. ```json
  161. {
  162. "id": 123,
  163. "project_id": 1,
  164. "project_identifier": "your-project",
  165. "health_report": "# Project Health Report\n\n...",
  166. "created_at": "2025-01-15T10:30:00Z"
  167. }
  168. ```
  169. **Requirements:**
  170. - The user associated with the API key must have the `view_ai_helper` permission for the project
  171. - The AI Helper module must be enabled for the project
  172. - REST API must be enabled in Redmine administration settings
  173. **Chart directives in the report body:**
  174. A health report body can contain chart directives. A directive is a single line
  175. that is drawn as a chart (from the metrics stored with the report) on screen,
  176. in the PDF export and in the Markdown export. The API returns the body with the
  177. directive lines unchanged, so API clients that render the report themselves must
  178. interpret them (or ignore them).
  179. ```
  180. {{ai_helper_chart(<type>, version=<version_id>)}}
  181. {{ai_helper_chart(<type>, period=<period_key>)}}
  182. ```
  183. - The directive must occupy a whole line (up to 3 leading spaces) outside fenced
  184. code blocks. Spaces around the comma and `=` are ignored.
  185. - `<type>`: `status`, `tracker`, `priority`, `assignee` (horizontal bars by
  186. count), `progress` (one stacked bar of not started / in progress / completed)
  187. and `open_closed` (a number tile with the completion rate, not a chart).
  188. - `<version_id>`: the numeric id of a version in the report's stored metrics.
  189. - `<period_key>`: `last_week`, `last_month`, `all_time` or `recent`.
  190. - A directive that cannot be drawn (unknown type or target, no stored metrics)
  191. is shown as a message with the reason instead of a chart.
  192. The Markdown export of a health report is a zip file (`<name>.md` plus
  193. `charts/chart-<n>.svg`, where n numbers the charts that can be drawn, in order of
  194. appearance) instead of a single `.md` file. Extract it and open the
  195. `.md` file in a Markdown viewer to see the charts. This is a change from earlier
  196. releases and should be mentioned in the release notes.
  197. **Scheduling with cron:**
  198. To generate health reports automatically every Monday at 9:00 AM, add the following to your crontab:
  199. ```bash
  200. 0 9 * * 1 curl -X POST -H "X-Redmine-API-Key: your_api_key_here" -H "Content-Type: application/json" https://your-redmine-instance.com/projects/your-project/ai_helper/health_report.json
  201. ```
  202. ## Chat Channel Gateway
  203. The Chat Channel Gateway allows users to interact with the AI Helper from external chat tools such as Slack. All questions are processed under a dedicated Redmine service account (the **execution account**) selected by the administrator — restricting that account's roles restricts what the gateway can read and do. All existing behavior — custom commands, agent orchestration, Langfuse tracing — works identically to the web chat.
  204. The gateway runs as a separate background process that connects outward to chat services, so **no public URL is required** for your Redmine server.
  205. ### Slack Integration
  206. 1. Create a Slack App with **Socket Mode** enabled. Generate an App-Level Token (`xapp-`) and note the Bot User OAuth Token (`xoxb-`).
  207. 2. Configure the following Bot Token Scopes: `app_mentions:read`, `im:history`, `chat:write`, `reactions:write`.
  208. 3. Subscribe to bot events: `app_mention`, `message.im`.
  209. 4. In **Administration → AI Helper → Chat integrations** tab, enable Slack, paste the tokens, select the **Execution account** (a Redmine service account, e.g. `ai_helper`, added to the target projects with an appropriate role), and save.
  210. 5. Optionally set a **Default project for direct messages**.
  211. 6. Under **Channel bindings**, map Slack channels to Redmine projects (each channel maps to one project with the AI Helper module enabled).
  212. See [`docs/slack_gateway_setup.md`](docs/slack_gateway_setup.md) for the full setup guide.
  213. ### Running the Gateway
  214. Start the gateway as a long-running process, separate from the Redmine web server:
  215. ```bash
  216. cd /path/to/redmine
  217. bundle exec rake redmine:plugins:ai_helper:chat_channel:gateway RAILS_ENV=production
  218. ```
  219. ### Running under systemd (example)
  220. ```ini
  221. [Unit]
  222. Description=Redmine AI Helper chat gateway
  223. After=network.target
  224. [Service]
  225. Type=simple
  226. User=redmine
  227. WorkingDirectory=/path/to/redmine
  228. Environment=RAILS_ENV=production
  229. ExecStart=/usr/bin/bundle exec rake redmine:plugins:ai_helper:chat_channel:gateway
  230. Restart=on-failure
  231. StartLimitIntervalSec=60
  232. StartLimitBurst=5
  233. [Install]
  234. WantedBy=multi-user.target
  235. ```
  236. `Restart=on-failure` restarts on crashes (non-zero exit). Configuration errors (invalid tokens, no adapter enabled) exit with status **0** and are not restarted automatically — fix the configuration and start again.
  237. ## Multi-modal File Support
  238. The AI Helper Plugin can analyze files attached to Issues, Wiki pages, and Board messages. When enabled, attached files are sent to the LLM alongside the content, allowing the AI to understand and reference file contents when generating summaries or responding in chat.
  239. **Supported file types:**
  240. | Category | Extensions |
  241. |----------|------------|
  242. | Images | .jpg, .jpeg, .png, .gif, .webp, .bmp |
  243. | Documents | .pdf, .txt, .md, .csv, .json, .xml |
  244. | Code | .rb, .py, .js, .html, .css, and more |
  245. | Audio | .mp3, .wav, .m4a, .ogg, .flac |
  246. | Office documents | .docx, .odt (and .xlsx, .pptx with Pandoc 3.8.3 or later) |
  247. Office documents are converted to Markdown with Redmine's own Markdown preview and the text is sent to the LLM. This requires Redmine 7.0 or later and [Pandoc](https://pandoc.org/) (set `pandoc_command` in `config/configuration.yml` if it is not in the `PATH`). On Redmine 6.x, or when Pandoc is not available, Office documents are not sent, as before. Redmine's `markdownized_preview_max_source_size`, `markdownized_preview_max_output_size` and `markdownized_preview_generation_timeout` settings apply. If a document cannot be converted, or the converted text is cut at the size limit, the LLM receives a notice saying so. Images inside documents are not sent; the LLM receives a notice instead. See [Office document attachments](docs/office_document_attachments.md) for details.
  248. To enable this feature, go to the AI Helper settings page in the Administration menu. Check **"Send attachments to LLM"** and optionally set the maximum file size limit (default: 3 MB). Files exceeding the limit are not sent to the LLM.
  249. You can also ask the AI to analyze specific attached files directly in the chat interface using the file analysis tools.
  250. When vector search is enabled, attachment contents are also incorporated into the vector index. The LLM analyzes attachments during index registration and similar-issue searches, resulting in more accurate similarity matching for issues that carry meaningful file attachments.
  251. # 📦 Installation
  252. **Requirements**: Redmine 6.0 or later and Ruby 3.2 or later. Ruby 3.1 is no longer supported.
  253. 1. Extract the plugin to your Redmine plugins folder:
  254. ```bash
  255. cd {REDMINE_ROOT}/plugins/
  256. git clone https://github.com/haru/redmine_ai_helper.git
  257. ```
  258. 2. Install required dependencies:
  259. ```bash
  260. bundle install
  261. ```
  262. 3. Run database migrations:
  263. ```bash
  264. bundle exec rake redmine:plugins:migrate RAILS_ENV=production
  265. ```
  266. 4. Restart Redmine:
  267. # ⚙️ Basic Configuration
  268. ## Plugin Settings
  269. 1. Open the AI Helper settings page from the Administration menu.
  270. 2. Create a model profile and fill in the following fields:
  271. - Type: Choose the AI model type (e.g., OpenAI, Anthropic. Strongly recommend using OpenAI or Anthropic)
  272. - Name: Enter a name for the model profile
  273. - Access Key: Enter the API key for the AI service
  274. - Model name: Specify the AI model name (e.g., gpt-4.1-mini)
  275. - Temperature: Optionally set the temperature for the AI model (e.g., 0.7). Leave it blank to omit the parameter and use the AI service's default (required for models that reject temperature).
  276. - Prompt caching (Anthropic only): Enabled by default. The system prompt, tool definitions and conversation history are cached by Anthropic (default 5-minute lifetime) to reduce input cost and latency. Uncheck it to disable caching for that profile. Other providers ignore this setting; OpenAI, Azure OpenAI and Gemini apply their own automatic prefix caching, and OpenAI-compatible servers may or may not. Cache read/write token counts reported by any provider are recorded in each Langfuse generation (`metadata.cache_read_input_tokens` / `cache_creation_input_tokens`).
  277. 3. Select the model profile you created from the dropdown menu and save the settings.
  278. 4. Optionally enable **Enable web search** on the General tab (disabled by default; system-wide, not per project). When enabled and the main model profile is OpenAI, Anthropic or Gemini, the chat can look up public information on the web through the LLM provider's own search tool and shows the sources (the title when the provider returns one, and the URL) under the answer, in the chat screen and in Slack/Discord replies. Notes:
  279. - Only the chat uses web search (the screen chat and the chat gateway). Other features, such as issue summaries and inline completion, never send a search request.
  280. - The model decides when to search and which search terms to use. The question and the content of issues, wiki pages and other data being viewed may be sent to the LLM provider and its search engine as search terms.
  281. - Azure OpenAI and OpenAI-compatible profiles do not support it; the settings page shows a warning when it is enabled with such a profile, and no search request is sent.
  282. - OpenAI models that RubyLLM sends to the Chat Completions API (the search-preview models and models whose name contains `audio` or `realtime`) have no web search tool, so a web search step fails with an error on them. Use a model served through the Responses API (e.g. `gpt-4o`, `gpt-5`).
  283. - For steps that use the Think model, the Think model profile's provider decides. If it does not support web search, the step is answered without searching and shows no sources.
  284. - Gemini returns Google redirect URLs as the source URLs, with the site's domain as the title.
  285. - Search-related provider charges apply (billed by the LLM provider).
  286. ## Think Model Settings
  287. You can optionally configure a separate model profile for tasks that require deeper reasoning, such as project health report generation and issue reply drafting. When not configured, all tasks use the standard model profile.
  288. ## Role and Permission Settings
  289. 1. Go to "Roles and permissions" in the administration menu
  290. 2. Configure the AI Helper permissions for each role as needed
  291. ## Project-specific Settings
  292. 1. Open the settings page for each project where you want to use the plugin
  293. 2. Go to the "Modules" tab
  294. 3. Enable "AI Helper" by checking the box
  295. 4. Click "Save" to apply the changes
  296. ## Data Access Policy
  297. AI Helper never reads or writes more than the requesting user's own Redmine permissions allow, regardless of how it is invoked (chat, chat gateway, or the MCP server). The following rules define which project data it can reach:
  298. - **Never beyond Redmine permissions**: AI Helper only reads or updates data the requesting user themselves can view or edit in Redmine. It cannot bypass Redmine's access control.
  299. - **Module-enabled projects only, by default**: Even if the user has Redmine permission for a project, AI Helper does not access that project's data unless the AI Helper module is enabled there. If you have a project whose content must never be sent to the LLM, simply leave the AI Helper module disabled for it — that project is excluded automatically.
  300. - **Optional cross-project access**: Administrators can enable **"Target all projects"** on the general tab of the AI Helper settings page. Once enabled, AI Helper can also read and update data in projects where the AI Helper module is disabled, as long as the requesting user has the necessary Redmine permissions there. This is useful for instances where sending all project data to the LLM is acceptable and cross-project questions (e.g., "list overdue issues across all projects") are desired. This setting is off by default; enabling it does not change which projects show the AI Helper chat form or other UI — that continues to depend solely on the module setting.
  301. # ⚙️ Advanced Configuration
  302. ## Nginx Reverse Proxy Settings
  303. If you are running Redmine behind an Nginx reverse proxy, you must disable response buffering to allow the plugin's SSE (Server-Sent Events) streaming to work correctly. Without these settings, the plugin may fail to authenticate users properly and behave as if requests are coming from an anonymous user.
  304. Add the following five directives to your existing Nginx location block for Redmine:
  305. ```nginx
  306. proxy_http_version 1.1;
  307. proxy_set_header Connection "";
  308. proxy_buffering off;
  309. proxy_cache off;
  310. proxy_set_header X-Accel-Buffering no;
  311. ```
  312. `proxy_http_version 1.1` and `proxy_set_header Connection ""` are required to enable HTTP/1.1 persistent connections between Nginx and the upstream server. Without them, Nginx defaults to HTTP/1.0, which does not properly support SSE streaming.
  313. For example:
  314. ```nginx
  315. location / {
  316. proxy_pass http://127.0.0.1:3000; # Change to your Redmine server address
  317. # Required for SSE streaming — add these to your existing configuration
  318. proxy_http_version 1.1;
  319. proxy_set_header Connection "";
  320. proxy_buffering off;
  321. proxy_cache off;
  322. proxy_set_header X-Accel-Buffering no;
  323. proxy_set_header Host $host;
  324. proxy_set_header X-Forwarded-Proto $scheme;
  325. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  326. proxy_redirect off;
  327. proxy_read_timeout 300;
  328. }
  329. ```
  330. After applying these changes, reload Nginx:
  331. ```bash
  332. nginx -s reload
  333. ```
  334. ## MCP Server Settings
  335. The "Model Context Protocol (MCP)" is an open standard protocol proposed by Anthropic that allows AI models to interact with external systems such as files, databases, tools, and APIs.
  336. Reference: https://github.com/modelcontextprotocol/servers
  337. The AI Helper Plugin has two independent MCP capabilities:
  338. - **Using External MCP Servers**: Connect to external MCP servers (Slack, GitHub, etc.) and use their tools inside the AI chat.
  339. - **Exposing Redmine as an MCP Server**: Expose Redmine's own data and tools as an MCP endpoint so external MCP clients (e.g., Claude Desktop, other AI agents) can query Redmine directly.
  340. ### Using External MCP Servers
  341. Connect to external MCP servers to perform tasks such as sending issue summaries to Slack or searching GitHub repositories from the AI chat.
  342. 1. Create `config/ai_helper/config.json` under the root directory of Redmine.
  343. 2. Configure the MCP server as follows (example for Slack, GitHub, and Context7):
  344. ```json
  345. {
  346. "mcpServers": {
  347. "slack": {
  348. "type": "stdio",
  349. "command": "npx",
  350. "args": [
  351. "-y",
  352. "@modelcontextprotocol/server-slack"
  353. ],
  354. "env": {
  355. "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
  356. "SLACK_TEAM_ID": "T01234567"
  357. }
  358. },
  359. "github": {
  360. "type": "http",
  361. "url": "https://api.githubcopilot.com/mcp/",
  362. "headers": {
  363. "Authorization": "Bearer github_pat_xxxxxxxxxxxxxxx"
  364. }
  365. }
  366. }
  367. }
  368. ```
  369. 3. Restart Redmine.
  370. ### Transport Types
  371. Two transport types are supported. The `type` field can be omitted — it is inferred automatically from the other keys:
  372. | Type | Auto-detected when | Description |
  373. |------|--------------------|-------------|
  374. | `stdio` | `command` or `args` is present | Spawns a local process and communicates via stdin/stdout |
  375. | `http` | `url` is present (no `type` key) | MCP Streamable HTTP transport |
  376. Notes:
  377. - Plain `http://` URLs are accepted only for loopback hosts (`localhost`, `127.0.0.1`, and `[::1]` written in brackets in the URL). Any other host requires `https://`.
  378. - Do not embed credentials in the URL (`https://user:pass@host/...`). Use the `headers` field instead.
  379. - The legacy SSE transport (`"type": "sse"`) is no longer supported. Servers that use it, and any other unsupported configuration, are skipped and an error is written to the AI Helper log (without the server's credentials). Use the Streamable HTTP transport (`"type": "http"`) instead.
  380. **STDIO example** (local process):
  381. ```json
  382. {
  383. "mcpServers": {
  384. "filesystem": {
  385. "command": "npx",
  386. "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  387. }
  388. }
  389. }
  390. ```
  391. **HTTP example** (remote server with authentication):
  392. ```json
  393. {
  394. "mcpServers": {
  395. "my_api": {
  396. "url": "https://mcp.example.com",
  397. "headers": {
  398. "Authorization": "Bearer your-token"
  399. }
  400. }
  401. }
  402. }
  403. ```
  404. ### Exposing Redmine as an MCP Server
  405. The AI Helper Plugin exposes Redmine's tools as an MCP endpoint. External MCP clients such as Claude Desktop or other AI agents can connect to Redmine and call Redmine tools directly.
  406. **Endpoint:**
  407. ```
  408. POST /ai_helper/mcp — JSON-RPC requests and responses (JSON)
  409. GET /ai_helper/mcp — MCP spec required; not used in stateless mode
  410. DELETE /ai_helper/mcp — MCP spec required; not used in stateless mode
  411. ```
  412. The server uses the MCP Streamable HTTP transport in **stateless, JSON-response mode** (`stateless: true`, `enable_json_response: true`). All communication happens via POST with JSON-RPC — SSE streaming is not used.
  413. **Change notifications are not supported.** This server does not implement change-notification subscription streams (`subscriptions/listen`, SEP-2575) or the related `listChanged`/`subscribe` capabilities. Because the endpoint is stateless with no shared subscription registry, a `subscriptions/listen` request is answered with a JSON-RPC *Method not found* error rather than opening a stream. Clients should poll `tools/list`, `prompts/list`, or `resources/list` instead of subscribing to change notifications.
  414. **Enabling the endpoint:**
  415. 1. Open the AI Helper settings page from the Administration menu.
  416. 2. Enable **"MCP Server"** in the settings.
  417. 3. Restart Redmine if required.
  418. **Authentication:**
  419. All requests must include a Redmine API key in the `X-Redmine-API-Key` header. The API key is validated per-request against the Redmine user account. Requests without a valid key return HTTP 401. If the MCP server is disabled, requests return HTTP 403.
  420. **Example — `.mcp.json` client configuration:**
  421. ```json
  422. {
  423. "mcpServers": {
  424. "redmine": {
  425. "type": "http",
  426. "url": "https://your-redmine-instance.com/ai_helper/mcp",
  427. "headers": {
  428. "X-Redmine-API-Key": "${REDMINE_API_KEY}"
  429. }
  430. }
  431. }
  432. }
  433. ```
  434. **Available tool groups:**
  435. | Tool Group | Example Tools | Description |
  436. |------------|---------------|-------------|
  437. | Issue | `read_issues`, `search_issues`, `create_new_issue`, `update_issue` | Read, search, create, and update issues |
  438. | Project | `list_projects`, `read_project`, `project_members`, `get_metrics` | Project information and metrics |
  439. | Project management | `capable_project_props`, `create_project`, `update_project`, `update_modules`, `add_trackers`, `remove_trackers` | Create and update projects, enable or disable modules, assign or unassign trackers (no delete) |
  440. | Member | `find_member_candidates`, `list_managed_roles`, `add_member`, `update_member_roles`, `remove_member` | Add members, change their roles, remove them |
  441. | Category | `list_categories`, `create_category`, `update_category` | List, create, and update issue categories (no delete) |
  442. | Wiki | `read_wiki_page`, `list_wiki_pages` | Wiki page access |
  443. | Repository | `repository_info`, `read_file`, `read_diff` | Source code and revision access |
  444. | Board | `list_boards`, `read_message` | Forum and message access |
  445. | User | `list_users`, `find_user` | User lookup |
  446. | Version | `list_versions`, `version_info`, `capable_version_props`, `create_version`, `update_version`, `delete_version` | Read, create, update, and delete versions |
  447. | File | `analyze_content_files` | File content analysis via LLM |
  448. | Vector | `find_similar_issues`, `ask_with_filter` | Semantic search (requires vector search setup) |
  449. All tools respect Redmine's permission model. The tools available to an MCP client depend on the permissions of the API key's user account.
  450. ## Vector Search Settings
  451. Configure settings to perform vector searches for issues using Qdrant.
  452. With this configuration, the AI Helper Plugin can use Qdrant to perform vector searches on Redmine issues and wiki data.
  453. **Note:** Vector search functionality is not available when using Anthropic AI models. Please use OpenAI or other supported AI providers for vector search features.
  454. ### Qdrant Setup
  455. Here is an example configuration using Docker Compose.
  456. ```yaml:docker-compose.yml
  457. services:
  458. qdrant:
  459. image: qdrant/qdrant
  460. ports:
  461. - 6333:6333
  462. volumes:
  463. - ./storage:/qdrant/storage
  464. ```
  465. ### Creating the Index
  466. Run the following command to create the index.
  467. ```bash
  468. bundle exec rake redmine:plugins:ai_helper:vector:generate RAILS_ENV=production
  469. ```
  470. Registers ticket data into the index. The initial run may take some time.
  471. ```bash
  472. bundle exec rake redmine:plugins:ai_helper:vector:regist RAILS_ENV=production
  473. ```
  474. Please execute the above commands periodically using cron or a similar tool to reflect ticket updates.
  475. This completes the configuration.
  476. ### Recreating the Index
  477. If you change the embedding model, delete the index and recreate it using the following commands.
  478. ```bash
  479. bundle exec rake redmine:plugins:ai_helper:vector:destroy RAILS_ENV=production
  480. ```
  481. # 🛠️ Build your own Agent
  482. The AI Helper plugin adopts a multi-agent model. You can create your own agent and integrate it into the AI Helper plugin.
  483. To create your own agent, you need to create the following two files:
  484. - **Agent Implementation**
  485. - A class that inherits from `RedmineAiHelper::BaseAgent`
  486. - Override `available_tool_providers` to return an array of your `BaseTools` subclasses
  487. - Override `backstory` to return the agent's system prompt context
  488. - Defines the agent's behavior
  489. - **Tools**
  490. - A class that inherits from `RedmineAiHelper::BaseTools`
  491. - Implements the tools used by the agent
  492. Place these files in any location within Redmine and load them.
  493. As an example, there is a plugin called `redmine_fortune` under the `example` directory. Place this plugin in the `plugins` folder of Redmine. This will add a fortune-telling feature to the AI Helper plugin. When you ask, "Tell me my fortune for today," it will return a fortune-telling result.
  494. # 🪄 Langfuse integration
  495. By integrating with Langfuse, you can track the usage of the AI Helper Plugin. This allows you to monitor the cost of LLM queries and improve prompts effectively.
  496. ![Image](https://github.com/user-attachments/assets/35904911-db39-4da7-baf6-a90fe05d9115)
  497. To configure the integration, add the following to `{REDMINE_ROOT}/config/ai_helper/config.yml`:
  498. ```yaml
  499. langfuse:
  500. public_key: "pk-lf-************"
  501. secret_key: "sk-lf-************"
  502. endpoint: https://us.cloud.langfuse.com # Change this to match your environment
  503. ```
  504. # 🔒 Running Without External Communication
  505. If you do not want the AI Helper to send anything outside your network, configure it as follows:
  506. - **LLM**: Use a locally hosted model through the OpenAI Compatible provider. The OpenAI Compatible provider communicates through the OpenAI Responses API (`/v1/responses`), so the server must support it; servers that only offer Chat Completions do not work.
  507. - **Vector search**: Use a locally hosted Qdrant, together with a local embedding model.
  508. - **Langfuse**: Use a self-hosted Langfuse instance, or leave Langfuse unconfigured.
  509. - **MCP servers**: Use only MCP servers that do not communicate externally.
  510. - **Chat Channel Gateway**: Do not use it. It connects to Slack or Discord.
  511. # ⚠️ Important Notice
  512. Please note that AI responses may not always be 100% accurate. Users should verify and validate AI-provided information at their own discretion.
  513. # 🤝 Contributing
  514. I welcome bug reports and feature improvement suggestions through GitHub Issues. Pull requests are also appreciated.
  515. ⚠️ When creating a pull request, always branch off from the `develop` branch.
  516. This project follows the [A successful Git branching model (git flow)](https://nvie.com/posts/a-successful-git-branching-model/) where the `develop` branch serves as the integration branch for new features and the `main` branch contains production-ready releases.
  517. Please make sure that all tests pass before pushing.
  518. ## How to Run Tests
  519. ### Preparation
  520. Create a test database.
  521. ```bash
  522. bundle exec rake redmine:plugins:migrate RAILS_ENV=test
  523. ```
  524. Create a test Git repository.
  525. ```bash
  526. bundle exec rake redmine:plugins:ai_helper:setup_scm
  527. ```
  528. ### Running the Tests
  529. ```bash
  530. bundle exec rake redmine:plugins:test NAME=redmine_ai_helper
  531. ```
  532. # 🐞 Support
  533. If you encounter any issues or have questions, please open an issue on GitHub.
  534. # 🌟 Credits
  535. Developed and maintained by [Haru Iida](https://github.com/haru).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.