@blackenedd18/planio-connector 2026.623.2

package/src/modules/time-entries/index.js

@@ -0,0 +1,267 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getRuntimeConfig } from '../../shared/config.js';
+import { logDebug, logError, logInfo, logWarn } from '../../shared/logger.js';
+import { makeRequest } from '../../shared/request.js';
+import { ensureOptionalIsoDate, resolveDateAlias } from '../../shared/date-validation.js';
+
+export const TOOLS = [
+  {
+    name: 'get_time_entry_activities',
+    description: 'Get available time entry activities.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_all_time_entries',
+    description: 'Return all time entries with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        user_id: { type: 'number' },
+        from: { type: 'string', description: 'YYYY-MM-DD' },
+        to: { type: 'string', description: 'YYYY-MM-DD' },
+        from_date: { type: 'string' },
+        to_date: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_time_entry_by_id',
+    description: 'Return a single time entry by id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        time_entry_id: { type: 'number' },
+      },
+      required: ['time_entry_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'update_time_entry',
+    description: 'Update a time entry by id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        time_entry_id: { type: 'number' },
+        issue_id: { type: 'number' },
+        hours: { type: 'number' },
+        comments: { type: 'string' },
+        spent_on: { type: 'string', description: 'YYYY-MM-DD' },
+        activity_name: {
+          type: 'string',
+          enum: ['design', 'development', 'management', 'support', 'testing'],
+          description: 'Time entry activity. Get from get_time_entry_activities.',
+        },
+      },
+      required: ['time_entry_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'delete_time_entry',
+    description: 'Delete a time entry by id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        time_entry_id: { type: 'number' },
+      },
+      required: ['time_entry_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'create_time_entry',
+    description:
+      'Create a new time entry. Requires issue_id, hours and activity_name. project_id is derived from the issue, user_id defaults to the authenticated user, and spent_on defaults to today when omitted.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        issue_id: { type: 'number' },
+        hours: { type: 'number' },
+        activity_name: {
+          type: 'string',
+          enum: ['design', 'development', 'management', 'support', 'testing'],
+          description: 'Time entry activity. Get from get_time_entry_activities.',
+        },
+        project_id: { type: 'number', description: 'Optional. Defaults to the issue project.' },
+        user_id: { type: 'number', description: 'Optional. Defaults to the authenticated user.' },
+        spent_on: { type: 'string', description: 'Optional. YYYY-MM-DD. Defaults to today.' },
+        comments: { type: 'string' },
+      },
+      required: ['issue_id', 'hours', 'activity_name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'health',
+    description: 'Health check of server configuration.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+];
+
+function logToolStart(name, args) {
+  logDebug('[timeEntries.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 buildTimeEntryFilters(args) {
+  const params = {};
+  const fields = ['project_id', 'issue_id', 'user_id', 'limit'];
+
+  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('[timeEntries.dispatch] Conflicting canonical and legacy date aliases', {
+      fromConflict: fromDate.conflict,
+      toConflict: toDate.conflict,
+    });
+  }
+
+  logDebug('[timeEntries.dispatch] Date aliases mapped', {
+    fromSource: fromDate.source,
+    toSource: toDate.source,
+    hadLegacyFromDate: fromDate.hadLegacy,
+    hadLegacyToDate: toDate.hadLegacy,
+    mappedKeys: Object.keys(params),
+  });
+
+  return params;
+}
+
+function buildUpdatePayload(args) {
+  const payload = {};
+  const fields = ['issue_id', 'hours', 'comments', 'spent_on', 'activity_name'];
+
+  for (const field of fields) {
+    if (args[field] !== undefined && args[field] !== null) {
+      payload[field] = args[field];
+    }
+  }
+
+  return payload;
+}
+
+export async function dispatch(name, args = {}) {
+  try {
+    switch (name) {
+      case 'get_time_entry_activities':
+        logToolStart(name, args);
+        return makeRequest('GET', 'time_entries/activities');
+      case 'get_all_time_entries':
+        logToolStart(name, args);
+        return makeRequest('GET', 'time_entries/list', buildTimeEntryFilters(args));
+      case 'get_time_entry_by_id':
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'time_entry_id');
+        return makeRequest('GET', `time_entries/${args.time_entry_id}`);
+      case 'update_time_entry': {
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'time_entry_id');
+        ensureOptionalIsoDate(args, 'spent_on');
+        const payload = buildUpdatePayload(args);
+        return makeRequest('PUT', `time_entries/${args.time_entry_id}`, undefined, payload);
+      }
+      case 'delete_time_entry':
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'time_entry_id');
+        return makeRequest('DELETE', `time_entries/${args.time_entry_id}`);
+      case 'create_time_entry': {
+        logToolStart(name, args);
+        ensureRequiredNumber(args, 'issue_id');
+        ensureRequiredNumber(args, 'hours');
+        ensureRequiredString(args, 'activity_name');
+        ensureOptionalIsoDate(args, 'spent_on');
+
+        const payload = {
+          issue_id: args.issue_id,
+          hours: args.hours,
+          activity_name: args.activity_name,
+        };
+
+        for (const field of ['project_id', 'user_id', 'spent_on', 'comments']) {
+          if (args[field] !== undefined && args[field] !== null) {
+            payload[field] = args[field];
+          }
+        }
+
+        return makeRequest('POST', 'time_entries', undefined, payload);
+      }
+      case 'health': {
+        logToolStart(name, args);
+        getRuntimeConfig();
+        logInfo('[timeEntries.dispatch] Health check passed');
+        const payload = { status: 'ok' };
+        return {
+          content: [{ type: 'text', text: JSON.stringify(payload) }],
+          structuredContent: payload,
+        };
+      }
+      default:
+        return null;
+    }
+  } catch (error) {
+    logError('[timeEntries.dispatch] Tool execution failed', {
+      toolName: name,
+      message: error?.message,
+    });
+
+    if (name === 'health') {
+      const payload = {
+        status: 'error',
+        message: error?.message || 'Health check failed',
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+        structuredContent: payload,
+      };
+    }
+
+    throw error;
+  }
+}

package/src/modules/users/index.js

@@ -0,0 +1,87 @@
+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_current_date_api',
+    description:
+      'Returns the current date (YYYY-MM-DD), the current day name, and the current week number.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_my_user_id',
+    description: 'Returns the unique identifier of the authenticated user.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_my_user_info',
+    description: 'Returns detailed information about the authenticated user.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_all_users_ids',
+    description: 'Retrieves a complete list of all users in the system.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+];
+
+function logToolStart(name, args) {
+  logDebug('[users.dispatch] Handling tool', {
+    toolName: name,
+    argumentKeys: Object.keys(args || {}),
+  });
+}
+
+function ensureNoArgs(args) {
+  if (Object.keys(args || {}).length > 0) {
+    throw new McpError(ErrorCode.InvalidParams, 'This tool does not accept any arguments.');
+  }
+}
+
+export async function dispatch(name, args = {}) {
+  try {
+    switch (name) {
+      case 'get_current_date_api':
+        logToolStart(name, args);
+        ensureNoArgs(args);
+        return makeRequest('GET', 'data/current-date');
+      case 'get_my_user_id':
+        logToolStart(name, args);
+        ensureNoArgs(args);
+        return makeRequest('GET', 'users/my-id');
+      case 'get_my_user_info':
+        logToolStart(name, args);
+        ensureNoArgs(args);
+        return makeRequest('GET', 'users/my');
+      case 'get_all_users_ids':
+        logToolStart(name, args);
+        ensureNoArgs(args);
+        return makeRequest('GET', 'users/all');
+      default:
+        return null;
+    }
+  } catch (error) {
+    logError('[users.dispatch] Tool execution failed', {
+      toolName: name,
+      message: error?.message,
+    });
+    throw error;
+  }
+}

package/src/server.js

@@ -0,0 +1,87 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'node:module';
+import { logError, logInfo } from './shared/logger.js';
+import { validateRuntimeConfig } from './shared/config.js';
+import * as users from './modules/users/index.js';
+import * as issues from './modules/issues/index.js';
+import * as projects from './modules/projects/index.js';
+import * as hours from './modules/hours/index.js';
+import * as timeEntries from './modules/time-entries/index.js';
+
+const { version: SERVER_VERSION } = createRequire(import.meta.url)('../package.json');
+const SERVER_NAME = 'planio-connector-mcp';
+const MODULES = [users, issues, projects, hours, timeEntries];
+
+export class RedmineServer {
+  constructor() {
+    this.modules = MODULES;
+    this.server = new Server(
+      {
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+    this.setupErrorHandling();
+  }
+
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: this.modules.flatMap((moduleRef) => moduleRef.TOOLS),
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+      const { name, arguments: args } = params;
+
+      for (const moduleRef of this.modules) {
+        const result = await moduleRef.dispatch(name, args ?? {});
+        if (result !== null) {
+          return result;
+        }
+      }
+
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    });
+  }
+
+  setupErrorHandling() {
+    this.server.onerror = (error) => {
+      logError('[MCP Error] Server error', {
+        message: error?.message,
+        stack: error?.stack,
+      });
+    };
+
+    process.on('SIGINT', async () => {
+      try {
+        await this.server.close();
+      } catch (error) {
+        logError('[MCP Error] Error during shutdown', {
+          message: error?.message,
+        });
+      }
+      process.exit(0);
+    });
+  }
+
+  async run() {
+    validateRuntimeConfig();
+    const transport = new StdioServerTransport();
+    logInfo('[server.run] Connecting MCP stdio transport');
+    await this.server.connect(transport);
+    logInfo('[server.run] MCP server connected');
+  }
+}

package/src/shared/config.js

@@ -0,0 +1,84 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { logDebug, logError, logInfo } from './logger.js';
+
+const VALID_LOG_LEVELS = new Set(['debug', 'info', 'warn', 'error']);
+
+/**
+ * Returns the value of a CLI flag (--flag value) from process.argv, or null if absent.
+ */
+function getArgValue(flag) {
+  const idx = process.argv.indexOf(flag);
+  if (idx !== -1 && process.argv[idx + 1] && !process.argv[idx + 1].startsWith('-')) {
+    return process.argv[idx + 1];
+  }
+  return null;
+}
+
+function requireApiKey() {
+  const fromArg = getArgValue('--api-key');
+  if (fromArg && fromArg.trim()) {
+    logDebug('[FIX] REDMINE_API_KEY resolved from --api-key CLI argument');
+    return fromArg.trim();
+  }
+  const fromEnv = process.env.REDMINE_API_KEY;
+  if (fromEnv && fromEnv.trim()) {
+    return fromEnv.trim();
+  }
+  throw new McpError(
+    ErrorCode.InvalidRequest,
+    'Missing API key. Provide it via --api-key <key> argument or REDMINE_API_KEY env var.'
+  );
+}
+
+function requireRedmineUrl() {
+  const fromArg = getArgValue('--redmine-url');
+  if (fromArg && fromArg.trim()) {
+    logDebug('[config] REDMINE_URL resolved from --redmine-url CLI argument');
+    return fromArg.trim().replace(/\/$/, '');
+  }
+  const fromEnv = process.env.REDMINE_URL;
+  if (fromEnv && fromEnv.trim()) {
+    return fromEnv.trim().replace(/\/$/, '');
+  }
+  throw new McpError(
+    ErrorCode.InvalidRequest,
+    'Missing Redmine URL. Provide it via --redmine-url <url> argument or REDMINE_URL env var.'
+  );
+}
+
+function getLogLevel() {
+  const raw = (process.env.LOG_LEVEL || 'debug').toLowerCase();
+  if (!VALID_LOG_LEVELS.has(raw)) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      'Invalid LOG_LEVEL. Expected one of: debug, info, warn, error.'
+    );
+  }
+  return raw;
+}
+
+export function getRuntimeConfig() {
+  return {
+    redmineApiKey: requireApiKey(),
+    redmineUrl: requireRedmineUrl(),
+    logLevel: getLogLevel(),
+  };
+}
+
+export function validateRuntimeConfig() {
+  try {
+    const config = getRuntimeConfig();
+    logDebug('[config.validateRuntimeConfig] Runtime config valid', {
+      hasApiKey: Boolean(config.redmineApiKey),
+      hasRedmineUrl: Boolean(config.redmineUrl),
+      logLevel: config.logLevel,
+    });
+    logInfo('[config.validateRuntimeConfig] Runtime configuration loaded');
+    return config;
+  } catch (error) {
+    logError('[config.validateRuntimeConfig] Runtime config invalid', {
+      message: error?.message,
+    });
+    throw error;
+  }
+}

package/src/shared/date-validation.js

@@ -0,0 +1,45 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+export function isIsoDate(value) {
+  return typeof value === 'string' && ISO_DATE_PATTERN.test(value);
+}
+
+export function ensureOptionalIsoDate(args, fieldName) {
+  const value = args?.[fieldName];
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  if (!isIsoDate(value)) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Field "${fieldName}" must be a date string in YYYY-MM-DD format.`
+    );
+  }
+}
+
+export function resolveDateAlias(args, canonicalName, legacyName) {
+  const canonicalValue = args?.[canonicalName];
+  const legacyValue = args?.[legacyName];
+
+  if (canonicalValue !== undefined && canonicalValue !== null) {
+    return {
+      value: canonicalValue,
+      source: canonicalName,
+      hadLegacy: legacyValue !== undefined && legacyValue !== null,
+      conflict:
+        legacyValue !== undefined &&
+        legacyValue !== null &&
+        String(legacyValue) !== String(canonicalValue),
+    };
+  }
+
+  return {
+    value: legacyValue,
+    source: legacyValue !== undefined && legacyValue !== null ? legacyName : null,
+    hadLegacy: legacyValue !== undefined && legacyValue !== null,
+    conflict: false,
+  };
+}

package/src/shared/logger.js

@@ -0,0 +1,48 @@
+const LOG_LEVEL = (process.env.LOG_LEVEL || 'debug').toLowerCase();
+
+const LEVELS = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+function shouldLog(level) {
+  return (LEVELS[level] || LEVELS.info) >= (LEVELS[LOG_LEVEL] || LEVELS.debug);
+}
+
+function sanitizeMeta(meta) {
+  if (!meta || typeof meta !== 'object') {
+    return meta;
+  }
+
+  const clone = { ...meta };
+  if (clone.apiKey) {
+    clone.apiKey = '***';
+  }
+  if (clone.headers && clone.headers['X-Redmine-API-Key']) {
+    clone.headers = { ...clone.headers, 'X-Redmine-API-Key': '***' };
+  }
+
+  return clone;
+}
+
+export function logDebug(message, meta = {}) {
+  if (!shouldLog('debug')) return;
+  console.error('[DEBUG]', message, sanitizeMeta(meta));
+}
+
+export function logInfo(message, meta = {}) {
+  if (!shouldLog('info')) return;
+  console.error('[INFO]', message, sanitizeMeta(meta));
+}
+
+export function logWarn(message, meta = {}) {
+  if (!shouldLog('warn')) return;
+  console.error('[WARN]', message, sanitizeMeta(meta));
+}
+
+export function logError(message, meta = {}) {
+  if (!shouldLog('error')) return;
+  console.error('[ERROR]', message, sanitizeMeta(meta));
+}

package/src/shared/redmine-functions-adapter.js

@@ -0,0 +1,58 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { executeRequest, listHandlers } from './redmine-functions-entry.js';
+import { REDMINE_FUNCTIONS_CONTRACT } from './redmine-functions-contract.js';
+import { logDebug, logError } from './logger.js';
+
+let handlersLogged = false;
+
+function ensureContract() {
+  const missing = REDMINE_FUNCTIONS_CONTRACT.requiredExports.filter((name) => {
+    if (name === 'executeRequest') return typeof executeRequest !== 'function';
+    if (name === 'listHandlers') return typeof listHandlers !== 'function';
+    return false;
+  });
+
+  if (missing.length > 0) {
+    logError('[redmineFunctionsAdapter.ensureContract] Missing required exports', {
+      missing,
+    });
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Redmine-functions contract mismatch. Missing exports: ${missing.join(', ')}`
+    );
+  }
+}
+
+export async function callRedmineFunctionAdapter({ method, endpoint, params, body, apiKey, redmineUrl }) {
+  ensureContract();
+
+  if (!handlersLogged) {
+    logDebug('[FIX] [redmineFunctionsAdapter.call] Using in-package Redmine-functions source', {
+      source: 'Redmine-functions/index.js',
+    });
+    logDebug('[redmineFunctionsAdapter.call] Adapter initialized', {
+      contract: REDMINE_FUNCTIONS_CONTRACT.executeSignature,
+      handlers: listHandlers(),
+    });
+    handlersLogged = true;
+  }
+
+  logDebug('[redmineFunctionsAdapter.call] Mapping request to local function', {
+    method,
+    endpoint,
+    paramKeys: params ? Object.keys(params) : [],
+    noNetworkMode: true,
+  });
+
+  try {
+    return await executeRequest({ method, endpoint, params, body, apiKey, redmineUrl });
+  } catch (error) {
+    logError('[redmineFunctionsAdapter.call] Local function execution failed', {
+      method,
+      endpoint,
+      status: error?.status,
+      message: error?.message,
+    });
+    throw error;
+  }
+}

package/src/shared/redmine-functions-contract.js

@@ -0,0 +1,4 @@
+export const REDMINE_FUNCTIONS_CONTRACT = {
+  executeSignature: 'executeRequest({ method, endpoint, params, body, apiKey, redmineUrl })',
+  requiredExports: ['executeRequest', 'listHandlers'],
+};

package/src/shared/redmine-functions-entry.js

@@ -0,0 +1,3 @@
+import { executeRequest, listHandlers } from '../../Redmine-functions/index.js';
+
+export { executeRequest, listHandlers };