Jason Thistlethwaite
a7d23cd79a
Auto-resolve project_id values that look like human names to canonical project identifiers when there is a clear match. Return actionable guidance with candidate slugs when ambiguous, and cover the behavior with structure tests and docs updates.
132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# 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=...
|
|
MCP_TEXT_SANITIZATION=true
|
|
```
|
|
|
|
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`.
|
|
|
|
When a tool receives `project_id` values that look like human names (spaces or
|
|
uppercase), redMCP attempts to resolve to a slug automatically when there is one
|
|
clear match. For ambiguous names, it returns a guidance error and suggests using
|
|
`redmine_find_project`.
|
|
|
|
## 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."
|
|
}
|
|
}
|
|
```
|