@blackenedd18/planio-connector 2026.623.2

package/src/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { RedmineServer } from './server.js';
+
+async function main() {
+  const app = new RedmineServer();
+  await app.run();
+}
+
+main().catch((error) => {
+  console.error('[MCP Error] Fatal startup error', {
+    message: error?.message,
+    stack: error?.stack,
+  });
+  process.exit(1);
+});

package/src/modules/hours/index.js

@@ -0,0 +1,195 @@
+import { logDebug, logError, logWarn } from '../../shared/logger.js';
+import { makeRequest } from '../../shared/request.js';
+import { ensureOptionalIsoDate, resolveDateAlias } from '../../shared/date-validation.js';
+
+const SHARED_OPTIONAL_FIELDS = ['project_id', 'issue_id', 'limit'];
+const USER_AWARE_FIELDS = [...SHARED_OPTIONAL_FIELDS, 'user_id'];
+const DATE_FIELDS = ['from', 'to', 'from_date', 'to_date'];
+
+export const TOOLS = [
+  {
+    name: 'get_total_hours_by_weekly',
+    description: 'Return weekly total hours with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number' },
+        project_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+        from_date: { type: 'string' },
+        to_date: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_total_hours_by_monthly',
+    description: 'Return monthly total hours with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number' },
+        project_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+        from_date: { type: 'string' },
+        to_date: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_total_hours_by_weekly_per_people',
+    description: 'Return weekly totals per user with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+        from_date: { type: 'string' },
+        to_date: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_total_hours_by_monthly_per_people',
+    description: 'Return monthly totals per user with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+        from_date: { type: 'string' },
+        to_date: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_total_hours_by_day',
+    description: 'Return total hours by day with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number' },
+        project_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+        from_date: { type: 'string' },
+        to_date: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function logToolStart(name, args) {
+  logDebug('[hours.dispatch] Handling tool', {
+    toolName: name,
+    argumentKeys: Object.keys(args || {}),
+  });
+}
+
+function buildParams(args, fields) {
+  const params = {};
+
+  for (const field of fields) {
+    if (args[field] !== undefined && args[field] !== null) {
+      params[field] = args[field];
+    }
+  }
+
+  const fromDate = resolveDateAlias(args, 'from', 'from_date');
+  const toDate = resolveDateAlias(args, 'to', 'to_date');
+
+  if (fromDate.value !== undefined && fromDate.value !== null) {
+    ensureOptionalIsoDate({ from: fromDate.value }, 'from');
+    params.from = fromDate.value;
+  }
+
+  if (toDate.value !== undefined && toDate.value !== null) {
+    ensureOptionalIsoDate({ to: toDate.value }, 'to');
+    params.to = toDate.value;
+  }
+
+  if (fromDate.conflict || toDate.conflict) {
+    logWarn('[hours.dispatch] Conflicting canonical and legacy date aliases', {
+      fromConflict: fromDate.conflict,
+      toConflict: toDate.conflict,
+    });
+  }
+
+  logDebug('[hours.dispatch] Date aliases mapped', {
+    fromSource: fromDate.source,
+    toSource: toDate.source,
+    hadLegacyFromDate: fromDate.hadLegacy,
+    hadLegacyToDate: toDate.hadLegacy,
+    mappedKeys: Object.keys(params),
+  });
+
+  return params;
+}
+
+export async function dispatch(name, args = {}) {
+  try {
+    switch (name) {
+      case 'get_total_hours_by_weekly':
+        logToolStart(name, args);
+        return makeRequest(
+          'GET',
+          'hours/list-total-weeks',
+          buildParams(args, [...USER_AWARE_FIELDS, ...DATE_FIELDS])
+        );
+      case 'get_total_hours_by_monthly':
+        logToolStart(name, args);
+        return makeRequest(
+          'GET',
+          'hours/list-total-monthly',
+          buildParams(args, [...USER_AWARE_FIELDS, ...DATE_FIELDS])
+        );
+      case 'get_total_hours_by_weekly_per_people':
+        logToolStart(name, args);
+        return makeRequest(
+          'GET',
+          'hours/list-total-weeks-per-people',
+          buildParams(args, [...SHARED_OPTIONAL_FIELDS, ...DATE_FIELDS])
+        );
+      case 'get_total_hours_by_monthly_per_people':
+        logToolStart(name, args);
+        return makeRequest(
+          'GET',
+          'hours/list-total-monthly-per-people',
+          buildParams(args, [...SHARED_OPTIONAL_FIELDS, ...DATE_FIELDS])
+        );
+      case 'get_total_hours_by_day':
+        logToolStart(name, args);
+        return makeRequest(
+          'GET',
+          'hours/list-total',
+          buildParams(args, [...USER_AWARE_FIELDS, ...DATE_FIELDS])
+        );
+      default:
+        return null;
+    }
+  } catch (error) {
+    logError('[hours.dispatch] Tool execution failed', {
+      toolName: name,
+      message: error?.message,
+    });
+    throw error;
+  }
+}

package/src/modules/issues/index.js

@@ -0,0 +1,281 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { logDebug, logError } from '../../shared/logger.js';
+import { makeRequest } from '../../shared/request.js';
+import { ensureOptionalIsoDate } from '../../shared/date-validation.js';
+
+const OPTIONAL_NUMBER_FIELDS_FOR_UPDATE = [
+  'status_id',
+  'tracker_id',
+  'priority_id',
+  'assigned_to_id',
+  'parent_id',
+  'estimated_hours',
+];
+
+const OPTIONAL_STRING_FIELDS_FOR_UPDATE = ['subject', 'description', 'start_date', 'due_date'];
+
+// Mirrors IssueController validation rules.
+const STATUS_IDS = [1, 4, 27, 8, 34, 39, 2, 38, 36, 3, 29, 10, 7, 37, 5, 6, 9, 11, 15, 16, 19, 20, 21, 22, 23, 24, 25, 26, 41, 42];
+const TRACKER_IDS = [14, 8, 1];
+const PRIORITY_IDS = [3, 4, 5];
+
+export const TOOLS = [
+  {
+    name: 'get_all_issue_statuses',
+    description: 'Returns a list of all defined issue statuses within the system.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_all_issue_trackers',
+    description: 'Retrieves a list of all issue trackers available in the system.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_all_issue_priorities',
+    description: 'Retrieves a list of all defined issue priorities in the system.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_my_issues',
+    description:
+      'Retrieves all issues currently assigned to the authenticated user. Optional filters: project_id, status_id, subject (partial match), description (partial match), created_on_from / created_on_to (YYYY-MM-DD), and limit (default 100). Each item includes type, project_name, status_name, priority_name, author_name, assigned_to_name, dates, spent hours and a link.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+        status_id: { type: 'number' },
+        subject: { type: 'string' },
+        description: { type: 'string' },
+        created_on_from: { type: 'string', description: 'YYYY-MM-DD' },
+        created_on_to: { type: 'string', description: 'YYYY-MM-DD' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_issues_with_filter',
+    description:
+      'Returns all issues filtered by project_id, status_id, author_id, assigned_to_id, subject (partial match), description (partial match), created_on_from / created_on_to (YYYY-MM-DD), and limit (default 100).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+        status_id: { type: 'number' },
+        author_id: { type: 'number' },
+        assigned_to_id: { type: 'number' },
+        subject: { type: 'string' },
+        description: { type: 'string' },
+        created_on_from: { type: 'string', description: 'YYYY-MM-DD' },
+        created_on_to: { type: 'string', description: 'YYYY-MM-DD' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_issue_by_id',
+    description: 'Retrieve full information about an issue by its ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        issue_id: { type: 'number' },
+      },
+      required: ['issue_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'update_issue_by_id',
+    description: 'Update the details of an issue by its ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        issue_id: { type: 'number' },
+        subject: { type: 'string' },
+        status_id: { type: 'number', enum: STATUS_IDS, description: 'Issue status. Get from get_all_issue_statuses.' },
+        tracker_id: { type: 'number', enum: TRACKER_IDS, description: 'Issue tracker. Get from get_all_issue_trackers.' },
+        priority_id: { type: 'number', enum: PRIORITY_IDS, description: 'Issue priority. Get from get_all_issue_priorities.' },
+        description: { type: 'string' },
+        assigned_to_id: { type: 'number' },
+        parent_id: { type: 'number' },
+        start_date: { type: 'string', description: 'YYYY-MM-DD' },
+        due_date: { type: 'string', description: 'YYYY-MM-DD' },
+        estimated_hours: { type: 'number' },
+      },
+      required: ['issue_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'create_issue',
+    description: 'Create a new issue in the system.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+        subject: { type: 'string' },
+        status_id: { type: 'number', enum: STATUS_IDS, description: 'Issue status. Get from get_all_issue_statuses.' },
+        tracker_id: { type: 'number', enum: TRACKER_IDS, description: 'Issue tracker. Get from get_all_issue_trackers.' },
+        priority_id: { type: 'number', enum: PRIORITY_IDS, description: 'Issue priority. Get from get_all_issue_priorities.' },
+        description: { type: 'string' },
+        assigned_to_id: { type: 'number' },
+        parent_id: { type: 'number' },
+        start_date: { type: 'string', description: 'YYYY-MM-DD' },
+        due_date: { type: 'string', description: 'YYYY-MM-DD' },
+        estimated_hours: { type: 'number' },
+      },
+      required: ['project_id', 'subject'],
+      additionalProperties: false,
+    },
+  },
+];
+
+function logToolStart(name, args) {
+  logDebug('[issues.dispatch] Handling tool', {
+    toolName: name,
+    argumentKeys: Object.keys(args || {}),
+  });
+}
+
+function ensureRequiredNumber(args, fieldName) {
+  if (typeof args[fieldName] !== 'number') {
+    throw new McpError(ErrorCode.InvalidParams, `Tool requires numeric field "${fieldName}".`);
+  }
+}
+
+function ensureRequiredString(args, fieldName) {
+  if (typeof args[fieldName] !== 'string' || !args[fieldName].trim()) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Tool requires non-empty string field "${fieldName}".`
+    );
+  }
+}
+
+function pickOptionalParams(args, keys) {
+  const result = {};
+  for (const key of keys) {
+    if (args[key] !== undefined && args[key] !== null) {
+      result[key] = args[key];
+    }
+  }
+  return result;
+}
+
+function buildIssueUpdatePayload(args) {
+  const payload = {};
+
+  for (const key of OPTIONAL_NUMBER_FIELDS_FOR_UPDATE) {
+    if (args[key] !== undefined && args[key] !== null) {
+      payload[key] = args[key];
+    }
+  }
+
+  for (const key of OPTIONAL_STRING_FIELDS_FOR_UPDATE) {
+    if (args[key] !== undefined && args[key] !== null) {
+      payload[key] = args[key];
+    }
+  }
+
+  return payload;
+}
+
+function validateDateFilters(args) {
+  ensureOptionalIsoDate(args, 'created_on_from');
+  ensureOptionalIsoDate(args, 'created_on_to');
+}
+
+function validateIssueDates(args) {
+  ensureOptionalIsoDate(args, 'start_date');
+  ensureOptionalIsoDate(args, 'due_date');
+}
+
+export async function dispatch(name, args = {}) {
+  try {
+    switch (name) {
+      case 'get_all_issue_statuses':
+        logToolStart(name, args);
+        return makeRequest('GET', 'issues/statuses');
+      case 'get_all_issue_trackers':
+        logToolStart(name, args);
+        return makeRequest('GET', 'issues/trackers');
+      case 'get_all_issue_priorities':
+        logToolStart(name, args);
+        return makeRequest('GET', 'issues/priorities');
+      case 'get_my_issues': {
+        logToolStart(name, args);
+        validateDateFilters(args);
+        const params = pickOptionalParams(args, [
+          'project_id',
+          'status_id',
+          'subject',
+          'description',
+          'created_on_from',
+          'created_on_to',
+          'limit',
+        ]);
+        return makeRequest('GET', 'issues/my', params);
+      }
+      case 'get_issues_with_filter': {
+        logToolStart(name, args);
+        validateDateFilters(args);
+        const params = pickOptionalParams(args, [
+          'project_id',
+          'status_id',
+          'author_id',
+          'assigned_to_id',
+          'subject',
+          'description',
+          'created_on_from',
+          'created_on_to',
+          'limit',
+        ]);
+        return makeRequest('GET', 'issues/filter', params);
+      }
+      case 'get_issue_by_id':
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'issue_id');
+        return makeRequest('GET', `issues/${args.issue_id}`);
+      case 'update_issue_by_id': {
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'issue_id');
+        validateIssueDates(args);
+        const payload = buildIssueUpdatePayload(args);
+        return makeRequest('PUT', `issues/${args.issue_id}`, undefined, payload);
+      }
+      case 'create_issue': {
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'project_id');
+        ensureRequiredString(args, 'subject');
+        validateIssueDates(args);
+        const payload = {
+          project_id: args.project_id,
+          subject: args.subject,
+          ...buildIssueUpdatePayload(args),
+        };
+        return makeRequest('POST', 'issues', undefined, payload);
+      }
+      default:
+        return null;
+    }
+  } catch (error) {
+    logError('[issues.dispatch] Tool execution failed', {
+      toolName: name,
+      message: error?.message,
+    });
+    throw error;
+  }
+}

package/src/modules/projects/index.js

@@ -0,0 +1,62 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { logDebug, logError } from '../../shared/logger.js';
+import { makeRequest } from '../../shared/request.js';
+
+export const TOOLS = [
+  {
+    name: 'get_all_projects',
+    description: 'Returns all available projects.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_project_by_id',
+    description: 'Return a project by its unique ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+      },
+      required: ['project_id'],
+      additionalProperties: false,
+    },
+  },
+];
+
+function logToolStart(name, args) {
+  logDebug('[projects.dispatch] Handling tool', {
+    toolName: name,
+    argumentKeys: Object.keys(args || {}),
+  });
+}
+
+function ensureRequiredNumber(args, fieldName) {
+  if (typeof args[fieldName] !== 'number') {
+    throw new McpError(ErrorCode.InvalidParams, `Tool requires numeric field "${fieldName}".`);
+  }
+}
+
+export async function dispatch(name, args = {}) {
+  try {
+    switch (name) {
+      case 'get_all_projects':
+        logToolStart(name, args);
+        return makeRequest('GET', 'projects/all');
+      case 'get_project_by_id':
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'project_id');
+        return makeRequest('GET', `projects/${args.project_id}`);
+      default:
+        return null;
+    }
+  } catch (error) {
+    logError('[projects.dispatch] Tool execution failed', {
+      toolName: name,
+      message: error?.message,
+    });
+    throw error;
+  }
+}