# 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."
  }
}
```