内容
# Redmine AI Helper Plugin
[](LICENSE.md)
[](https://github.com/haru/redmine_ai_helper/actions/workflows/build.yml)
[](https://qlty.sh/gh/haru/projects/redmine_ai_helper)
[](https://codecov.io/gh/haru/redmine_ai_helper)
[](https://deepwiki.com/haru/redmine_ai_helper)
- [Redmine AI Helper Plugin](#redmine-ai-helper-plugin)
- [✨ Features](#-features)
- [Chat Interface](#chat-interface)
- [Issue Summarization](#issue-summarization)
- [Create a comment draft with AI Helper](#create-a-comment-draft-with-ai-helper)
- [Generate subtasks from issues](#generate-subtasks-from-issues)
- [Similar Issues Search](#similar-issues-search)
- [Duplicate Issue Check](#duplicate-issue-check)
- [Inline Issue Description and Wiki Completion](#inline-issue-description-and-wiki-completion)
- [Typo Checking and Correction Suggestions](#typo-checking-and-correction-suggestions)
- [Assignee Suggestion](#assignee-suggestion)
- [To-Do Suggestions](#to-do-suggestions)
- [Custom Commands](#custom-commands)
- [Project Health Report](#project-health-report)
- [Health Report History](#health-report-history)
- [Health Report REST API](#health-report-rest-api)
- [Chat Channel Gateway](#chat-channel-gateway)
- [Multi-modal File Support](#multi-modal-file-support)
- [📦 Installation](#-installation)
- [⚙️ Basic Configuration](#️-basic-configuration)
- [Plugin Settings](#plugin-settings)
- [Think Model Settings](#think-model-settings)
- [Role and Permission Settings](#role-and-permission-settings)
- [Project-specific Settings](#project-specific-settings)
- [Data Access Policy](#data-access-policy)
- [⚙️ Advanced Configuration](#️-advanced-configuration)
- [Nginx Reverse Proxy Settings](#nginx-reverse-proxy-settings)
- [MCP Server Settings](#mcp-server-settings)
- [Using External MCP Servers](#using-external-mcp-servers)
- [Transport Types](#transport-types)
- [Exposing Redmine as an MCP Server](#exposing-redmine-as-an-mcp-server)
- [Vector Search Settings](#vector-search-settings)
- [Qdrant Setup](#qdrant-setup)
- [Creating the Index](#creating-the-index)
- [Recreating the Index](#recreating-the-index)
- [🛠️ Build your own Agent](#️-build-your-own-agent)
- [🪄 Langfuse integration](#-langfuse-integration)
- [🔒 Running Without External Communication](#-running-without-external-communication)
- [⚠️ Important Notice](#️-important-notice)
- [🤝 Contributing](#-contributing)
- [How to Run Tests](#how-to-run-tests)
- [Preparation](#preparation)
- [Running the Tests](#running-the-tests)
- [🐞 Support](#-support)
- [🌟 Credits](#-credits)
The Redmine AI Helper Plugin adds AI chat functionality to Redmine, enhancing project management efficiency through AI-powered support.
# ✨ Features
- Adds an AI chat sidebar to the right side of your Redmine interface
- Enables various AI-assisted features including:
- Issue search
- Issue and Wiki content summarization
- Repository source code explanation
- Generate subtasks from issues
- Inline issue description and wiki completion
- Other project and Redmine-related inquiries
- Typo checking and correction suggestions
- To-do suggestions based on assigned issues
- Custom commands for reusable prompt shortcuts
- Provides a project health report
- Supports multi-modal file analysis (images, PDFs, text, code, audio attachments)
- 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.
- Supports multiple AI models and services
- MCP server integration
- Vector search using Qdrant
## Chat Interface
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.
## Issue Summarization
Issue summarization allows you to generate concise summaries of issues pages.
## Create a comment draft with AI Helper
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.
## Generate subtasks from issues
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.
## Similar Issues Search
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.
## Duplicate Issue Check
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.
This feature is only available if vector search is set up.
## Inline Issue Description and Wiki Completion
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.
You can accept completion suggestions by pressing the TAB key.
### Completion settings
Inline completion works out of the box. To tune it, add an `autocompletion` section to
`{REDMINE_ROOT}/config/ai_helper/config.yml`. The file, the section and every individual key
are optional.
```yaml
autocompletion:
timeout: 30 # seconds
debounce_delay: 500 # milliseconds
min_length: 5 # characters
wiki_min_length: 5 # characters, wiki pages only
suggestion_color: "#888888"
```
| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `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). |
| `debounce_delay` | Number > 0 (milliseconds) | `500` for issues, `300` for wiki pages | How long typing must pause before a completion is requested. |
| `min_length` | Integer ≥ 0 (characters) | `5` | Minimum body length before completions are requested. |
| `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. |
| `suggestion_color` | `"#RGB"` or `"#RRGGBB"` | `"#888888"` | Colour of the inline suggestion text. Other formats are rejected. |
Invalid values are ignored: the default is used instead and a warning naming the key, the
value and the reason is written to the plugin log. Keys that are not listed above are ignored
and reported the same way. A missing file falls back to the defaults, so an absent
configuration never prevents the edit screen from loading. A file that exists but cannot be
parsed as YAML is a different matter: the plugin reads it while Redmine boots, so a syntax
error there stops the whole instance from starting. Check the plugin log after editing it.
## Typo Checking and Correction Suggestions
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.
## Assignee Suggestion
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.
## To-Do Suggestions
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" menu in the top menu bar (available only within project contexts where you have AI Helper permissions).
## Custom Commands
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.
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.
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.
## Project Health Report
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.
Health reports can be exported to Markdown and PDF formats.
### Health Report History
Health reports are automatically saved and can be reviewed later. You can:
- View past health reports to track project progress over time
- Compare multiple health reports to analyze trends and changes in project health
- Export comparison results to Markdown and PDF formats
This historical tracking helps you understand how your project's health evolves and identify patterns or issues early.
### Health Report REST API
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.
**Endpoint:**
```
POST /projects/:project_id/ai_helper/health_report.json
```
**Authentication:**
Use Redmine's standard API key authentication by including the `X-Redmine-API-Key` header.
**Example Request:**
```bash
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
```
**Response:**
```json
{
"id": 123,
"project_id": 1,
"project_identifier": "your-project",
"health_report": "# Project Health Report\n\n...",
"created_at": "2025-01-15T10:30:00Z"
}
```
**Requirements:**
- The user associated with the API key must have the `view_ai_helper` permission for the project
- The AI Helper module must be enabled for the project
- REST API must be enabled in Redmine administration settings
**Chart directives in the report body:**
A health report body can contain chart directives. A directive is a single line
that is drawn as a chart (from the metrics stored with the report) on screen,
in the PDF export and in the Markdown export. The API returns the body with the
directive lines unchanged, so API clients that render the report themselves must
interpret them (or ignore them).
```
{{ai_helper_chart(<type>, version=<version_id>)}}
{{ai_helper_chart(<type>, period=<period_key>)}}
```
- The directive must occupy a whole line (up to 3 leading spaces) outside fenced
code blocks. Spaces around the comma and `=` are ignored.
- `<type>`: `status`, `tracker`, `priority`, `assignee` (horizontal bars by
count), `progress` (one stacked bar of not started / in progress / completed)
and `open_closed` (a number tile with the completion rate, not a chart).
- `<version_id>`: the numeric id of a version in the report's stored metrics.
- `<period_key>`: `last_week`, `last_month`, `all_time` or `recent`.
- A directive that cannot be drawn (unknown type or target, no stored metrics)
is shown as a message with the reason instead of a chart.
The Markdown export of a health report is a zip file (`<name>.md` plus
`charts/chart-<n>.svg`, where n numbers the charts that can be drawn, in order of
appearance) instead of a single `.md` file. Extract it and open the
`.md` file in a Markdown viewer to see the charts. This is a change from earlier
releases and should be mentioned in the release notes.
**Scheduling with cron:**
To generate health reports automatically every Monday at 9:00 AM, add the following to your crontab:
```bash
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
```
## Chat Channel Gateway
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.
The gateway runs as a separate background process that connects outward to chat services, so **no public URL is required** for your Redmine server.
### Slack Integration
1. Create a Slack App with **Socket Mode** enabled. Generate an App-Level Token (`xapp-`) and note the Bot User OAuth Token (`xoxb-`).
2. Configure the following Bot Token Scopes: `app_mentions:read`, `im:history`, `chat:write`, `reactions:write`.
3. Subscribe to bot events: `app_mention`, `message.im`.
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.
5. Optionally set a **Default project for direct messages**.
6. Under **Channel bindings**, map Slack channels to Redmine projects (each channel maps to one project with the AI Helper module enabled).
See [`docs/slack_gateway_setup.md`](docs/slack_gateway_setup.md) for the full setup guide.
### Running the Gateway
Start the gateway as a long-running process, separate from the Redmine web server:
```bash
cd /path/to/redmine
bundle exec rake redmine:plugins:ai_helper:chat_channel:gateway RAILS_ENV=production
```
### Running under systemd (example)
```ini
[Unit]
Description=Redmine AI Helper chat gateway
After=network.target
[Service]
Type=simple
User=redmine
WorkingDirectory=/path/to/redmine
Environment=RAILS_ENV=production
ExecStart=/usr/bin/bundle exec rake redmine:plugins:ai_helper:chat_channel:gateway
Restart=on-failure
StartLimitIntervalSec=60
StartLimitBurst=5
[Install]
WantedBy=multi-user.target
```
`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.
## Multi-modal File Support
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.
**Supported file types:**
| Category | Extensions |
|----------|------------|
| Images | .jpg, .jpeg, .png, .gif, .webp, .bmp |
| Documents | .pdf, .txt, .md, .csv, .json, .xml |
| Code | .rb, .py, .js, .html, .css, and more |
| Audio | .mp3, .wav, .m4a, .ogg, .flac |
| Office documents | .docx, .odt (and .xlsx, .pptx with Pandoc 3.8.3 or later) |
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.
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.
You can also ask the AI to analyze specific attached files directly in the chat interface using the file analysis tools.
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.
# 📦 Installation
**Requirements**: Redmine 6.0 or later and Ruby 3.2 or later. Ruby 3.1 is no longer supported.
1. Extract the plugin to your Redmine plugins folder:
```bash
cd {REDMINE_ROOT}/plugins/
git clone https://github.com/haru/redmine_ai_helper.git
```
2. Install required dependencies:
```bash
bundle install
```
3. Run database migrations:
```bash
bundle exec rake redmine:plugins:migrate RAILS_ENV=production
```
4. Restart Redmine:
# ⚙️ Basic Configuration
## Plugin Settings
1. Open the AI Helper settings page from the Administration menu.
2. Create a model profile and fill in the following fields:
- Type: Choose the AI model type (e.g., OpenAI, Anthropic. Strongly recommend using OpenAI or Anthropic)
- Name: Enter a name for the model profile
- Access Key: Enter the API key for the AI service
- Model name: Specify the AI model name (e.g., gpt-4.1-mini)
- 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).
- 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`).
3. Select the model profile you created from the dropdown menu and save the settings.
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:
- 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.
- 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.
- 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.
- 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`).
- 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.
- Gemini returns Google redirect URLs as the source URLs, with the site's domain as the title.
- Search-related provider charges apply (billed by the LLM provider).
## Think Model Settings
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.
## Role and Permission Settings
1. Go to "Roles and permissions" in the administration menu
2. Configure the AI Helper permissions for each role as needed
## Project-specific Settings
1. Open the settings page for each project where you want to use the plugin
2. Go to the "Modules" tab
3. Enable "AI Helper" by checking the box
4. Click "Save" to apply the changes
## Data Access Policy
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:
- **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.
- **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.
- **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.
# ⚙️ Advanced Configuration
## Nginx Reverse Proxy Settings
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.
Add the following five directives to your existing Nginx location block for Redmine:
```nginx
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_cache off;
proxy_set_header X-Accel-Buffering no;
```
`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.
For example:
```nginx
location / {
proxy_pass http://127.0.0.1:3000; # Change to your Redmine server address
# Required for SSE streaming — add these to your existing configuration
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_cache off;
proxy_set_header X-Accel-Buffering no;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_redirect off;
proxy_read_timeout 300;
}
```
After applying these changes, reload Nginx:
```bash
nginx -s reload
```
## MCP Server Settings
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.
Reference: https://github.com/modelcontextprotocol/servers
The AI Helper Plugin has two independent MCP capabilities:
- **Using External MCP Servers**: Connect to external MCP servers (Slack, GitHub, etc.) and use their tools inside the AI chat.
- **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.
### Using External MCP Servers
Connect to external MCP servers to perform tasks such as sending issue summaries to Slack or searching GitHub repositories from the AI chat.
1. Create `config/ai_helper/config.json` under the root directory of Redmine.
2. Configure the MCP server as follows (example for Slack, GitHub, and Context7):
```json
{
"mcpServers": {
"slack": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-slack"
],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-bot-token",
"SLACK_TEAM_ID": "T01234567"
}
},
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer github_pat_xxxxxxxxxxxxxxx"
}
}
}
}
```
3. Restart Redmine.
### Transport Types
Two transport types are supported. The `type` field can be omitted — it is inferred automatically from the other keys:
| Type | Auto-detected when | Description |
|------|--------------------|-------------|
| `stdio` | `command` or `args` is present | Spawns a local process and communicates via stdin/stdout |
| `http` | `url` is present (no `type` key) | MCP Streamable HTTP transport |
Notes:
- 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://`.
- Do not embed credentials in the URL (`https://user:pass@host/...`). Use the `headers` field instead.
- 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.
**STDIO example** (local process):
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}
```
**HTTP example** (remote server with authentication):
```json
{
"mcpServers": {
"my_api": {
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer your-token"
}
}
}
}
```
### Exposing Redmine as an MCP Server
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.
**Endpoint:**
```
POST /ai_helper/mcp — JSON-RPC requests and responses (JSON)
GET /ai_helper/mcp — MCP spec required; not used in stateless mode
DELETE /ai_helper/mcp — MCP spec required; not used in stateless mode
```
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.
**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.
**Enabling the endpoint:**
1. Open the AI Helper settings page from the Administration menu.
2. Enable **"MCP Server"** in the settings.
3. Restart Redmine if required.
**Authentication:**
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.
**Example — `.mcp.json` client configuration:**
```json
{
"mcpServers": {
"redmine": {
"type": "http",
"url": "https://your-redmine-instance.com/ai_helper/mcp",
"headers": {
"X-Redmine-API-Key": "${REDMINE_API_KEY}"
}
}
}
}
```
**Available tool groups:**
| Tool Group | Example Tools | Description |
|------------|---------------|-------------|
| Issue | `read_issues`, `search_issues`, `create_new_issue`, `update_issue` | Read, search, create, and update issues |
| Project | `list_projects`, `read_project`, `project_members`, `get_metrics` | Project information and metrics |
| Wiki | `read_wiki_page`, `list_wiki_pages` | Wiki page access |
| Repository | `repository_info`, `read_file`, `read_diff` | Source code and revision access |
| Board | `list_boards`, `read_message` | Forum and message access |
| User | `list_users`, `find_user` | User lookup |
| Version | `list_versions`, `version_info`, `capable_version_props`, `create_version`, `update_version`, `delete_version` | Read, create, update, and delete versions |
| File | `analyze_content_files` | File content analysis via LLM |
| Vector | `find_similar_issues`, `ask_with_filter` | Semantic search (requires vector search setup) |
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.
## Vector Search Settings
Configure settings to perform vector searches for issues using Qdrant.
With this configuration, the AI Helper Plugin can use Qdrant to perform vector searches on Redmine issues and wiki data.
**Note:** Vector search functionality is not available when using Anthropic AI models. Please use OpenAI or other supported AI providers for vector search features.
### Qdrant Setup
Here is an example configuration using Docker Compose.
```yaml:docker-compose.yml
services:
qdrant:
image: qdrant/qdrant
ports:
- 6333:6333
volumes:
- ./storage:/qdrant/storage
```
### Creating the Index
Run the following command to create the index.
```bash
bundle exec rake redmine:plugins:ai_helper:vector:generate RAILS_ENV=production
```
Registers ticket data into the index. The initial run may take some time.
```bash
bundle exec rake redmine:plugins:ai_helper:vector:regist RAILS_ENV=production
```
Please execute the above commands periodically using cron or a similar tool to reflect ticket updates.
This completes the configuration.
### Recreating the Index
If you change the embedding model, delete the index and recreate it using the following commands.
```bash
bundle exec rake redmine:plugins:ai_helper:vector:destroy RAILS_ENV=production
```
# 🛠️ Build your own Agent
The AI Helper plugin adopts a multi-agent model. You can create your own agent and integrate it into the AI Helper plugin.
To create your own agent, you need to create the following two files:
- **Agent Implementation**
- A class that inherits from `RedmineAiHelper::BaseAgent`
- Override `available_tool_providers` to return an array of your `BaseTools` subclasses
- Override `backstory` to return the agent's system prompt context
- Defines the agent's behavior
- **Tools**
- A class that inherits from `RedmineAiHelper::BaseTools`
- Implements the tools used by the agent
Place these files in any location within Redmine and load them.
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.
# 🪄 Langfuse integration
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.
To configure the integration, add the following to `{REDMINE_ROOT}/config/ai_helper/config.yml`:
```yaml
langfuse:
public_key: "pk-lf-************"
secret_key: "sk-lf-************"
endpoint: https://us.cloud.langfuse.com # Change this to match your environment
```
# 🔒 Running Without External Communication
If you do not want the AI Helper to send anything outside your network, configure it as follows:
- **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.
- **Vector search**: Use a locally hosted Qdrant, together with a local embedding model.
- **Langfuse**: Use a self-hosted Langfuse instance, or leave Langfuse unconfigured.
- **MCP servers**: Use only MCP servers that do not communicate externally.
- **Chat Channel Gateway**: Do not use it. It connects to Slack or Discord.
# ⚠️ Important Notice
Please note that AI responses may not always be 100% accurate. Users should verify and validate AI-provided information at their own discretion.
# 🤝 Contributing
I welcome bug reports and feature improvement suggestions through GitHub Issues. Pull requests are also appreciated.
⚠️ When creating a pull request, always branch off from the `develop` branch.
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.
Please make sure that all tests pass before pushing.
## How to Run Tests
### Preparation
Create a test database.
```bash
bundle exec rake redmine:plugins:migrate RAILS_ENV=test
```
Create a test Git repository.
```bash
bundle exec rake redmine:plugins:ai_helper:setup_scm
```
### Running the Tests
```bash
bundle exec rake redmine:plugins:test NAME=redmine_ai_helper
```
# 🐞 Support
If you encounter any issues or have questions, please open an issue on GitHub.
# 🌟 Credits
Developed and maintained by [Haru Iida](https://github.com/haru).
连接信息
猜你喜欢
暂无推荐服务器