ldr/redmine
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add friendly redMCP query options

Browse Source
This commit is contained in:
Jason Thistlethwaite
2026-04-25 04:12:01 +00:00
parent a25361f5fc
commit d8f17ff7e7
7 changed files with 618 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
redMCP/app/ListQueryNormalizer.php
+369
View File
@@ -0,0 +1,369 @@
<?php
declare(strict_types=1);
namespace RedMCP;
use DateTimeImmutable;
use DateTimeZone;
use RuntimeException;
final class ListQueryNormalizer
{
private const DEFAULT_LIMIT = 25;
private const MAX_LIMIT = 100;
/**
* @param array<string,mixed> $arguments
*
* @return array<string,mixed>
*/
public static function listParams(array $arguments): array
{
$params = self::pagingParams($arguments);
self::addSort($params, $arguments['sort'] ?? null);
return array_merge($params, self::objectValue($arguments, 'params'));
}
/**
* @param array<string,mixed> $arguments
*
* @return array<string,mixed>
*/
public static function issueFilters(array $arguments, ?DateTimeImmutable $clock = null): array
{
$filters = self::pagingParams($arguments);
foreach ([
'project_id',
'tracker_id',
'assigned_to_id',
'author_id',
'priority_id',
'category_id',
'query_id',
] as $key) {
if (array_key_exists($key, $arguments)) {
$filters[$key] = $arguments[$key];
}
}
if (array_key_exists('status', $arguments)) {
$filters['status_id'] = self::statusValue($arguments['status']);
} elseif (array_key_exists('status_id', $arguments)) {
$filters['status_id'] = self::statusValue($arguments['status_id']);
}
self::addDateFilter($filters, 'created_on', $arguments['created'] ?? null, $clock);
self::addDateFilter($filters, 'updated_on', $arguments['updated'] ?? null, $clock);
self::addDateFilter($filters, 'due_date', $arguments['due'] ?? null, $clock);
self::addSort($filters, $arguments['sort'] ?? null);
return array_merge($filters, self::objectValue($arguments, 'filters'));
}
/**
* @param array<string,mixed> $arguments
*
* @return array<string,mixed>
*/
public static function userParams(array $arguments): array
{
$params = self::pagingParams($arguments);
foreach (['name', 'group_id'] as $key) {
if (array_key_exists($key, $arguments)) {
$params[$key] = $arguments[$key];
}
}
if (array_key_exists('status', $arguments)) {
$params['status'] = self::userStatusValue($arguments['status']);
}
self::addSort($params, $arguments['sort'] ?? null);
return array_merge($params, self::objectValue($arguments, 'params'));
}
/**
* @param array<string,mixed> $arguments
*
* @return array<string,mixed>
*/
public static function searchParams(array $arguments): array
{
$params = self::pagingParams($arguments);
foreach (['project_id', 'scope'] as $key) {
if (array_key_exists($key, $arguments)) {
$params[$key] = $arguments[$key];
}
}
foreach (['all_words', 'titles_only', 'open_issues'] as $key) {
if (array_key_exists($key, $arguments)) {
$params[$key] = self::booleanString($arguments[$key]);
}
}
self::addSort($params, $arguments['sort'] ?? null);
return array_merge($params, self::objectValue($arguments, 'params'));
}
/**
* @param array<string,mixed> $arguments
*
* @return array<string,mixed>
*/
private static function pagingParams(array $arguments): array
{
$limit = self::positiveInt($arguments['limit'] ?? self::DEFAULT_LIMIT, self::DEFAULT_LIMIT);
$limit = min($limit, self::MAX_LIMIT);
$params = ['limit' => $limit];
if (array_key_exists('offset', $arguments)) {
$params['offset'] = max(0, (int) $arguments['offset']);
return $params;
}
if (array_key_exists('page', $arguments)) {
$page = max(1, (int) $arguments['page']);
$params['offset'] = ($page - 1) * $limit;
}
return $params;
}
private static function positiveInt(mixed $value, int $default): int
{
$value = (int) $value;
return $value > 0 ? $value : $default;
}
/**
* @param array<string,mixed> $params
* @param mixed $sort
*/
private static function addSort(array &$params, $sort): void
{
$normalized = self::sortValue($sort);
if ($normalized !== null) {
$params['sort'] = $normalized;
}
}
/**
* @param mixed $sort
*/
private static function sortValue($sort): ?string
{
if ($sort === null || $sort === '') {
return null;
}
if (is_array($sort)) {
$parts = [];
foreach ($sort as $item) {
if (!is_array($item)) {
continue;
}
$field = trim((string) ($item['field'] ?? ''));
if ($field === '') {
continue;
}
$direction = strtolower((string) ($item['direction'] ?? 'asc')) === 'desc' ? 'desc' : 'asc';
$parts[] = $field . ':' . $direction;
}
return $parts === [] ? null : implode(',', $parts);
}
$sort = trim((string) $sort);
$shortcut = strtolower(str_replace([' ', '-'], '_', $sort));
return [
'newest' => 'updated_on:desc',
'recent' => 'updated_on:desc',
'oldest' => 'created_on:asc',
'created_newest' => 'created_on:desc',
'created_oldest' => 'created_on:asc',
'priority' => 'priority:desc,updated_on:desc',
][$shortcut] ?? $sort;
}
/**
* @param mixed $value
*/
private static function statusValue($value): mixed
{
$status = strtolower(trim((string) $value));
return [
'open' => 'open',
'opened' => 'open',
'active' => 'open',
'closed' => 'closed',
'all' => '*',
'any' => '*',
][$status] ?? $value;
}
/**
* @param mixed $value
*/
private static function userStatusValue($value): mixed
{
$status = strtolower(trim((string) $value));
return [
'active' => 1,
'registered' => 2,
'locked' => 3,
'all' => '*',
'any' => '*',
][$status] ?? $value;
}
/**
* @param array<string,mixed> $params
* @param mixed $value
*/
private static function addDateFilter(array &$params, string $redmineField, $value, ?DateTimeImmutable $clock): void
{
if ($value === null || $value === '') {
return;
}
$params[$redmineField] = self::dateValue($value, $clock);
}
/**
* @param mixed $value
*/
private static function dateValue($value, ?DateTimeImmutable $clock): string
{
$clock = $clock ?? new DateTimeImmutable('now', new DateTimeZone('UTC'));
$clock = $clock->setTimezone(new DateTimeZone('UTC'));
if (is_array($value)) {
$from = self::datePart($value['from'] ?? null, $clock);
$to = self::datePart($value['to'] ?? null, $clock);
return self::rangeValue($from, $to);
}
$text = trim((string) $value);
if ($text === '') {
throw new RuntimeException('Date filter cannot be empty.');
}
if (preg_match('/^(.+)\.\.(.+)$/', $text, $matches)) {
return self::rangeValue(self::datePart($matches[1], $clock), self::datePart($matches[2], $clock));
}
if (preg_match('/^(since|after)\s+(.+)$/i', $text, $matches)) {
return '>=' . self::datePart($matches[2], $clock);
}
if (preg_match('/^(before|until)\s+(.+)$/i', $text, $matches)) {
return '<=' . self::datePart($matches[2], $clock);
}
$preset = strtolower(str_replace(['-', ' '], '_', $text));
if ($preset === 'today') {
return $clock->format('Y-m-d');
}
if ($preset === 'yesterday') {
return $clock->modify('-1 day')->format('Y-m-d');
}
if (preg_match('/^last_(\d+)_days$/', $preset, $matches)) {
$days = max(1, (int) $matches[1]);
return self::rangeValue($clock->modify('-' . ($days - 1) . ' days')->format('Y-m-d'), $clock->format('Y-m-d'));
}
if ($preset === 'this_week') {
return self::rangeValue($clock->modify('monday this week')->format('Y-m-d'), $clock->format('Y-m-d'));
}
if ($preset === 'last_week') {
return self::rangeValue(
$clock->modify('monday last week')->format('Y-m-d'),
$clock->modify('sunday last week')->format('Y-m-d')
);
}
if ($preset === 'this_month') {
return self::rangeValue($clock->modify('first day of this month')->format('Y-m-d'), $clock->format('Y-m-d'));
}
if ($preset === 'last_month') {
return self::rangeValue(
$clock->modify('first day of last month')->format('Y-m-d'),
$clock->modify('last day of last month')->format('Y-m-d')
);
}
return self::datePart($text, $clock);
}
private static function rangeValue(?string $from, ?string $to): string
{
if ($from !== null && $to !== null) {
return '><' . $from . '|' . $to;
}
if ($from !== null) {
return '>=' . $from;
}
if ($to !== null) {
return '<=' . $to;
}
throw new RuntimeException('Date range requires from, to, or both.');
}
/**
* @param mixed $value
*/
private static function datePart($value, DateTimeImmutable $clock): ?string
{
if ($value === null || trim((string) $value) === '') {
return null;
}
$text = trim((string) $value);
$timestamp = strtotime($text, $clock->getTimestamp());
if ($timestamp === false) {
throw new RuntimeException('Could not parse date filter: ' . $text);
}
return gmdate('Y-m-d', $timestamp);
}
/**
* @param mixed $value
*/
private static function booleanString($value): string
{
if (is_string($value)) {
$normalized = strtolower(trim($value));
if (in_array($normalized, ['1', 'true', 'yes', 'on'], true)) {
return '1';
}
if (in_array($normalized, ['0', 'false', 'no', 'off'], true)) {
return '0';
}
}
return $value ? '1' : '0';
}
/**
* @param array<string,mixed> $arguments
*
* @return array<string,mixed>
*/
private static function objectValue(array $arguments, string $key): array
{
return is_array($arguments[$key] ?? null) ? $arguments[$key] : [];
}
}
redMCP/app/McpDispatcher.php
+61 -12
View File
@@ -92,7 +92,11 @@ final class McpDispatcher
{
return [
$this->tool('redmine_list_projects', 'List Redmine projects using native /projects.json.', [
'params' => ['type' => 'object', 'description' => 'Redmine project list params such as include, offset, and limit.'],
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100],
'page' => ['type' => 'integer', 'minimum' => 1],
'offset' => ['type' => 'integer', 'minimum' => 0],
'sort' => ['description' => 'Sort shortcut such as newest, oldest, created_newest, or a Redmine sort string.'],
'params' => ['type' => 'object', 'description' => 'Raw Redmine project list params; overrides friendly fields on conflict.'],
]),
$this->tool('redmine_get_project', 'Fetch one Redmine project by id or identifier.', [
'project_id' => ['type' => ['string', 'integer'], 'description' => 'Redmine numeric project id or identifier.'],
@@ -100,25 +104,70 @@ final class McpDispatcher
], ['project_id']),
$this->tool('redmine_list_project_memberships', 'List users/groups and roles for a Redmine project.', [
'project_id' => ['type' => ['string', 'integer'], 'description' => 'Redmine numeric project id or identifier.'],
'params' => ['type' => 'object', 'description' => 'Redmine membership list params such as offset and limit.'],
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100],
'page' => ['type' => 'integer', 'minimum' => 1],
'offset' => ['type' => 'integer', 'minimum' => 0],
'sort' => ['description' => 'Sort shortcut such as newest, oldest, created_newest, or a Redmine sort string.'],
'params' => ['type' => 'object', 'description' => 'Raw Redmine membership list params; overrides friendly fields on conflict.'],
], ['project_id']),
$this->tool('redmine_list_users', 'List Redmine users using native /users.json.', [
'params' => ['type' => 'object', 'description' => 'Redmine user list params such as status, name, group_id, offset, and limit.'],
'status' => ['description' => 'User status such as active, registered, locked, all, or a Redmine status id.'],
'name' => ['type' => 'string', 'description' => 'Filter users by name.'],
'group_id' => ['type' => ['string', 'integer'], 'description' => 'Filter users by group id.'],
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100],
'page' => ['type' => 'integer', 'minimum' => 1],
'offset' => ['type' => 'integer', 'minimum' => 0],
'sort' => ['description' => 'Sort shortcut such as newest, oldest, created_newest, or a Redmine sort string.'],
'params' => ['type' => 'object', 'description' => 'Raw Redmine user list params; overrides friendly fields on conflict.'],
]),
$this->tool('redmine_get_user', 'Fetch one Redmine user by id.', [
'user_id' => ['type' => 'integer'],
'params' => ['type' => 'object', 'description' => 'Optional Redmine user params such as include=memberships,groups.'],
], ['user_id']),
$this->tool('redmine_list_issues', 'List Redmine issues using native /issues.json filters.', [
'filters' => ['type' => 'object', 'description' => 'Redmine issue list filters such as project_id, status_id, query_id, sort, offset, and limit.'],
'project_id' => ['type' => ['string', 'integer']],
'status' => ['description' => 'Issue status such as open, closed, all, or a Redmine status id.'],
'status_id' => ['description' => 'Raw Redmine status id or status token.'],
'tracker_id' => ['type' => ['string', 'integer']],
'assigned_to_id' => ['type' => ['string', 'integer']],
'author_id' => ['type' => ['string', 'integer']],
'priority_id' => ['type' => ['string', 'integer']],
'category_id' => ['type' => ['string', 'integer']],
'query_id' => ['type' => ['string', 'integer']],
'created' => ['description' => 'Friendly created_on date filter such as today, last 7 days, since 2026-04-01, or {from,to}.'],
'updated' => ['description' => 'Friendly updated_on date filter such as today, last 7 days, since 2026-04-01, or {from,to}.'],
'due' => ['description' => 'Friendly due_date filter such as today, last 7 days, since 2026-04-01, or {from,to}.'],
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100],
'page' => ['type' => 'integer', 'minimum' => 1],
'offset' => ['type' => 'integer', 'minimum' => 0],
'sort' => ['description' => 'Sort shortcut such as newest, oldest, priority, or a Redmine sort string.'],
'filters' => ['type' => 'object', 'description' => 'Raw Redmine issue list filters; overrides friendly fields on conflict.'],
]),
$this->tool('redmine_search', 'Search Redmine using native /search.json.', [
'query' => ['type' => 'string'],
'params' => ['type' => 'object', 'description' => 'Redmine search params such as project_id, all_words, titles_only, offset, and limit.'],
'project_id' => ['type' => ['string', 'integer']],
'scope' => ['type' => 'string'],
'all_words' => ['type' => ['boolean', 'string', 'integer']],
'titles_only' => ['type' => ['boolean', 'string', 'integer']],
'open_issues' => ['type' => ['boolean', 'string', 'integer']],
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100],
'page' => ['type' => 'integer', 'minimum' => 1],
'offset' => ['type' => 'integer', 'minimum' => 0],
'sort' => ['description' => 'Sort shortcut such as newest, oldest, created_newest, or a Redmine sort string.'],
'params' => ['type' => 'object', 'description' => 'Raw Redmine search params; overrides friendly fields on conflict.'],
], ['query']),
$this->tool('redmine_search_issues', 'Search only issues using native /search.json.', [
'query' => ['type' => 'string'],
'params' => ['type' => 'object', 'description' => 'Additional Redmine search params.'],
'project_id' => ['type' => ['string', 'integer']],
'scope' => ['type' => 'string'],
'all_words' => ['type' => ['boolean', 'string', 'integer']],
'titles_only' => ['type' => ['boolean', 'string', 'integer']],
'open_issues' => ['type' => ['boolean', 'string', 'integer']],
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100],
'page' => ['type' => 'integer', 'minimum' => 1],
'offset' => ['type' => 'integer', 'minimum' => 0],
'sort' => ['description' => 'Sort shortcut such as newest, oldest, created_newest, or a Redmine sort string.'],
'params' => ['type' => 'object', 'description' => 'Raw Redmine search params; overrides friendly fields on conflict.'],
], ['query']),
$this->tool('redmine_get_issue', 'Fetch one Redmine issue.', [
'issue_id' => ['type' => 'integer'],
@@ -180,28 +229,28 @@ final class McpDispatcher
switch ($name) {
case 'redmine_list_projects':
$result = $this->redmine->listProjects($this->objectArg($arguments, 'params'));
$result = $this->redmine->listProjects(ListQueryNormalizer::listParams($arguments));
break;
case 'redmine_get_project':
$result = $this->redmine->project($this->projectIdArg($arguments, 'project_id'), $this->objectArg($arguments, 'params'));
break;
case 'redmine_list_project_memberships':
$result = $this->redmine->projectMemberships($this->projectIdArg($arguments, 'project_id'), $this->objectArg($arguments, 'params'));
$result = $this->redmine->projectMemberships($this->projectIdArg($arguments, 'project_id'), ListQueryNormalizer::listParams($arguments));
break;
case 'redmine_list_users':
$result = $this->redmine->listUsers($this->objectArg($arguments, 'params'));
$result = $this->redmine->listUsers(ListQueryNormalizer::userParams($arguments));
break;
case 'redmine_get_user':
$result = $this->redmine->user($this->intArg($arguments, 'user_id'), $this->objectArg($arguments, 'params'));
break;
case 'redmine_list_issues':
$result = $this->redmine->filterIssues($this->objectArg($arguments, 'filters'));
$result = $this->redmine->filterIssues(ListQueryNormalizer::issueFilters($arguments));
break;
case 'redmine_search':
$result = $this->redmine->search($this->stringArg($arguments, 'query'), $this->objectArg($arguments, 'params'));
$result = $this->redmine->search($this->stringArg($arguments, 'query'), ListQueryNormalizer::searchParams($arguments));
break;
case 'redmine_search_issues':
$result = $this->redmine->searchIssues($this->stringArg($arguments, 'query'), $this->objectArg($arguments, 'params'));
$result = $this->redmine->searchIssues($this->stringArg($arguments, 'query'), ListQueryNormalizer::searchParams($arguments));
break;
case 'redmine_get_issue':
$result = $this->redmine->issue($this->intArg($arguments, 'issue_id'), $this->stringListArg($arguments, 'include', ['journals', 'attachments']));