@fluentdata-ai/tempo-mcp-server 1.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ivelin Ivanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,287 @@
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/ivelin-web-tempo-mcp-server-badge.png)](https://mseep.ai/app/ivelin-web-tempo-mcp-server)
+
+# Tempo MCP Server
+
+A Model Context Protocol (MCP) server for managing Tempo worklogs in Jira. This server provides tools for tracking time and managing worklogs through Tempo's API, making it accessible through Claude, Cursor and other MCP-compatible clients.
+
+[![npm version](https://img.shields.io/npm/v/@ivelin-web/tempo-mcp-server.svg)](https://www.npmjs.com/package/@ivelin-web/tempo-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Retrieve Worklogs**: Get all worklogs for a specific date range
+- **Create Worklog**: Log time against Jira issues
+- **Bulk Create**: Create multiple worklogs in a single operation
+- **Edit Worklog**: Modify time spent, dates, and descriptions
+- **Delete Worklog**: Remove existing worklogs
+
+## System Requirements
+
+- Node.js 18+ (LTS recommended)
+- Jira Cloud instance
+- Tempo API token
+- Jira API token
+
+## Usage Options
+
+There are two main ways to use this MCP server:
+
+1. **NPX (Recommended for most users)**: Run directly without installation
+2. **Local Clone**: Clone the repository for development or customization
+
+## Option 1: NPX Usage
+
+The easiest way to use this server is via npx without installation:
+
+### Connecting to Claude Desktop (NPX Method)
+
+1. Open your MCP client configuration file:
+
+   - Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "Jira_Tempo": {
+      "command": "npx",
+      "args": ["-y", "@esalgado/tempo-mcp-server"],
+      "env": {
+        "TEMPO_API_TOKEN": "your_tempo_api_token_here",
+        "JIRA_API_TOKEN": "your_jira_api_token_here",
+        "JIRA_EMAIL": "your_email@example.com",
+        "JIRA_BASE_URL": "https://your-org.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+3. Restart your Claude Desktop client
+
+### One-Click Install for Cursor
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=Jira%20Tempo&config=eyJjb21tYW5kIjoibnB4IC15IEBpdmVsaW4td2ViL3RlbXBvLW1jcC1zZXJ2ZXIiLCJlbnYiOnsiVEVNUE9fQVBJX1RPS0VOIjoieW91cl90ZW1wb19hcGlfdG9rZW5faGVyZSIsIkpJUkFfQVBJX1RPS0VOIjoieW91cl9qaXJhX2FwaV90b2tlbl9oZXJlIiwiSklSQV9FTUFJTCI6InlvdXJfZW1haWxAZXhhbXBsZS5jb20iLCJKSVJBX0JBU0VfVVJMIjoiaHR0cHM6Ly95b3VyLW9yZy5hdGxhc3NpYW4ubmV0In19)
+
+## Option 2: Local Repository Clone
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ivelin-web/tempo-mcp-server.git
+cd tempo-mcp-server
+
+# Install dependencies
+npm install
+
+# Build TypeScript files
+npm run build
+```
+
+### Running Locally
+
+There are two ways to run the server locally:
+
+#### 1. Using the MCP Inspector (for development and debugging)
+
+```bash
+npm run inspect
+```
+
+#### 2. Using Node directly
+
+You can run the server directly with Node by pointing to the built JavaScript file:
+
+### Connecting to Claude Desktop (Local Method)
+
+1. Open your MCP client configuration file
+2. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "Jira_Tempo": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/tempo-mcp-server/build/index.js"],
+      "env": {
+        "TEMPO_API_TOKEN": "your_tempo_api_token_here",
+        "JIRA_API_TOKEN": "your_jira_api_token_here",
+        "JIRA_EMAIL": "your_email@example.com",
+        "JIRA_BASE_URL": "https://your-org.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+3. Restart your Claude Desktop client
+
+## Getting API Tokens
+
+1. **Tempo API Token**:
+
+   - Go to Tempo > Settings > API Integration
+   - Create a new API token with appropriate permissions
+
+2. **Jira API Token**:
+   - Go to [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+   - Create a new API token for your account
+
+## Environment Variables
+
+The server requires the following environment variables:
+
+```
+TEMPO_API_TOKEN     # Your Tempo API token
+JIRA_API_TOKEN      # Your Jira API token
+JIRA_EMAIL          # Your Jira account email (required for basic auth)
+JIRA_BASE_URL       # Your Jira instance URL (e.g., https://your-org.atlassian.net)
+JIRA_AUTH_TYPE      # Optional: 'basic' (default) or 'bearer' for OAuth 2.0 tokens
+JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID     # Optional: Custom field ID for Tempo accounts
+```
+
+You can set these in your environment or provide them in the MCP client configuration.
+
+### Authentication Types
+
+The server supports two authentication methods for the Jira API:
+
+#### Basic Authentication (default)
+
+Uses email and API token. This is the traditional method:
+
+```json
+{
+  "env": {
+    "JIRA_API_TOKEN": "your_api_token",
+    "JIRA_EMAIL": "your_email@example.com",
+    "JIRA_AUTH_TYPE": "basic"
+  }
+}
+```
+
+#### Bearer Token Authentication (OAuth 2.0)
+
+For users who want to use OAuth 2.0 scoped tokens for enhanced security:
+
+```json
+{
+  "env": {
+    "JIRA_API_TOKEN": "your_oauth_access_token",
+    "JIRA_AUTH_TYPE": "bearer"
+  }
+}
+```
+
+Note: When using `bearer` auth, `JIRA_EMAIL` is not required as the user is identified from the token.
+
+## Tempo Account Configuration
+
+If your Tempo instance requires worklogs to be linked to accounts, set the custom field ID that contains the account information:
+
+```bash
+JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID=10234
+```
+
+To find your custom field ID:
+
+1. Go to Jira Settings → Issues → Custom Fields
+2. Find your Tempo account field and note the ID from the URL or field configuration
+
+## Available Tools
+
+### retrieveWorklogs
+
+Fetches worklogs for the configured user between start and end dates.
+
+```
+Parameters:
+- startDate: String (YYYY-MM-DD)
+- endDate: String (YYYY-MM-DD)
+```
+
+### createWorklog
+
+Creates a new worklog for a specific Jira issue.
+
+```
+Parameters:
+- issueKey: String (e.g., "PROJECT-123")
+- timeSpentHours: Number (positive)
+- date: String (YYYY-MM-DD)
+- description: String (optional)
+- startTime: String (HH:MM format, optional)
+```
+
+### bulkCreateWorklogs
+
+Creates multiple worklogs in a single operation.
+
+```
+Parameters:
+- worklogEntries: Array of {
+    issueKey: String
+    timeSpentHours: Number
+    date: String (YYYY-MM-DD)
+    description: String (optional)
+    startTime: String (HH:MM format, optional)
+  }
+```
+
+### editWorklog
+
+Modifies an existing worklog.
+
+```
+Parameters:
+- worklogId: String
+- timeSpentHours: Number (positive)
+- description: String (optional)
+- date: String (YYYY-MM-DD, optional)
+- startTime: String (HH:MM format, optional)
+```
+
+### deleteWorklog
+
+Removes an existing worklog.
+
+```
+Parameters:
+- worklogId: String
+```
+
+## Project Structure
+
+```
+tempo-mcp-server/
+├── src/                  # Source code
+│   ├── config.ts         # Configuration management
+│   ├── index.ts          # MCP server implementation
+│   ├── jira.ts           # Jira API integration
+│   ├── tools.ts          # Tool implementations
+│   ├── types.ts          # TypeScript types and schemas
+│   └── utils.ts          # Utility functions
+├── build/                # Compiled JavaScript (generated)
+├── tsconfig.json         # TypeScript configuration
+└── package.json          # Project metadata and scripts
+```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Check that all environment variables are properly set
+2. Verify your Jira and Tempo API tokens have the correct permissions
+3. Check the console output for error messages
+4. Try running with the inspector: `npm run inspect`
+
+## License
+
+[MIT](LICENSE)
+
+## Credits
+
+This server implements the [Model Context Protocol](https://modelcontextprotocol.io/) specification created by Anthropic.

package/build/config.js

@@ -0,0 +1,57 @@
+/**
+ * Configuration manager for the MCP server
+ * Validates required environment variables and exports config settings
+ */
+import { envSchema } from './types.js';
+import { ZodError } from 'zod';
+import { config as loadEnv } from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// Load environment variables from .env file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const envLoadResult = loadEnv({ path: path.resolve(__dirname, '../.env') });
+if (envLoadResult.error) {
+    console.error('[WARN] Could not load .env file:', envLoadResult.error.message);
+}
+// Validate environment variables
+function validateEnv() {
+    try {
+        // Parse and validate environment variables
+        return envSchema.parse(process.env);
+    }
+    catch (error) {
+        // Format and display validation errors
+        console.error('[ERROR] Environment validation failed:');
+        if (error instanceof ZodError) {
+            error.issues.forEach((err) => {
+                console.error(`- ${err.path.join('.')}: ${err.message}`);
+            });
+        }
+        else {
+            console.error(error instanceof Error ? error.message : String(error));
+        }
+        process.exit(1);
+    }
+}
+// Get validated environment variables
+const env = validateEnv();
+// Application configuration with validated environment variables
+const config = {
+    tempoApi: {
+        baseUrl: 'https://api.tempo.io/4',
+        token: env.TEMPO_API_TOKEN,
+    },
+    jiraApi: {
+        baseUrl: env.JIRA_BASE_URL,
+        token: env.JIRA_API_TOKEN,
+        email: env.JIRA_EMAIL,
+        authType: env.JIRA_AUTH_TYPE,
+        tempoAccountCustomFieldId: env.JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID || undefined,
+    },
+    server: {
+        name: 'tempo-mcp-server',
+        version: '1.0.0',
+    },
+};
+export default config;

package/build/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Tempo MCP Server
+ *
+ * A simple Model Context Protocol server for managing Tempo worklogs with TypeScript.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import config from './config.js';
+import * as tools from './tools.js';
+import { retrieveWorklogsSchema, createWorklogSchema, } from './types.js';
+// Create MCP server instance
+const server = new McpServer({
+    name: config.server.name,
+    version: config.server.version,
+}, {
+    capabilities: { logging: {} },
+});
+// Tool: retrieveWorklogs - fetch worklogs between two dates
+server.registerTool('retrieveWorklogs', {
+    title: 'Retrieve Worklogs',
+    description: 'Retrieve worklogs for a specified date range.',
+    inputSchema: retrieveWorklogsSchema.shape,
+}, async ({ startDate, endDate }) => {
+    try {
+        const result = await tools.retrieveWorklogs(startDate, endDate);
+        return {
+            content: result.content,
+        };
+    }
+    catch (error) {
+        console.error(`[ERROR] retrieveWorklogs failed: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error retrieving worklogs: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: createWorklog - create a single worklog entry
+server.registerTool('createWorklog', {
+    title: 'Create Worklog',
+    description: 'Create a new worklog entry.',
+    inputSchema: createWorklogSchema.shape,
+}, async ({ issueKey, timeSpentHours, date, description, startTime, remainingEstimateHours, }) => {
+    try {
+        const result = await tools.createWorklog(issueKey, timeSpentHours, date, description, startTime, remainingEstimateHours);
+        return {
+            content: result.content,
+        };
+    }
+    catch (error) {
+        console.error(`[ERROR] createWorklog failed: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error creating worklog: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// // Tool: bulkCreateWorklogs - create multiple worklog entries at once
+// server.registerTool(
+//   'bulkCreateWorklogs',
+//   bulkCreateWorklogsSchema.shape,
+//   async ({ worklogEntries }) => {
+//     try {
+//       const result = await tools.bulkCreateWorklogs(worklogEntries);
+//       return {
+//         content: result.content,
+//       };
+//     } catch (error) {
+//       console.error(
+//         `[ERROR] bulkCreateWorklogs failed: ${error instanceof Error ? error.message : String(error)}`,
+//       );
+//       return {
+//         content: [
+//           {
+//             type: 'text',
+//             text: `Error creating multiple worklogs: ${error instanceof Error ? error.message : String(error)}`,
+//           },
+//         ],
+//         isError: true,
+//       };
+//     }
+//   },
+// );
+//
+// // Tool: editWorklog - modify an existing worklog entry
+// server.registerTool(
+//   'editWorklog',
+//   editWorklogSchema.shape,
+//   async ({ worklogId, timeSpentHours, description, date, startTime }) => {
+//     try {
+//       const result = await tools.editWorklog(
+//         worklogId,
+//         timeSpentHours,
+//         description || null,
+//         date || null,
+//         startTime || undefined,
+//       );
+//       return {
+//         content: result.content,
+//       };
+//     } catch (error) {
+//       console.error(
+//         `[ERROR] editWorklog failed: ${error instanceof Error ? error.message : String(error)}`,
+//       );
+//       return {
+//         content: [
+//           {
+//             type: 'text',
+//             text: `Error editing worklog: ${error instanceof Error ? error.message : String(error)}`,
+//           },
+//         ],
+//         isError: true,
+//       };
+//     }
+//   },
+// );
+//
+// // Tool: deleteWorklog - remove an existing worklog entry
+// server.registerTool(
+//   'deleteWorklog',
+//   deleteWorklogSchema.shape,
+//   async ({ worklogId }) => {
+//     try {
+//       const result = await tools.deleteWorklog(worklogId);
+//       return {
+//         content: result.content,
+//       };
+//     } catch (error) {
+//       console.error(
+//         `[ERROR] deleteWorklog failed: ${error instanceof Error ? error.message : String(error)}`,
+//       );
+//       return {
+//         content: [
+//           {
+//             type: 'text',
+//             text: `Error deleting worklog: ${error instanceof Error ? error.message : String(error)}`,
+//           },
+//         ],
+//         isError: true,
+//       };
+//     }
+//   },
+// );
+//
+async function startServer() {
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error('[INFO] MCP Server started successfully');
+    }
+    catch (error) {
+        console.error(`[ERROR] Failed to start MCP Server: ${error instanceof Error ? error.message : String(error)}`);
+        if (error instanceof Error && error.stack) {
+            console.error(`[ERROR] Stack trace: ${error.stack}`);
+        }
+        process.exit(1);
+    }
+}
+startServer().catch((error) => {
+    console.error(`[ERROR] Unhandled exception: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});
+export default server;

package/build/jira.js

@@ -0,0 +1,105 @@
+import axios from 'axios';
+import { issueIdSchema, idOrKeySchema, } from './types.js';
+import config from './config.js';
+// Build authorization header based on auth type
+function getAuthHeader() {
+    if (config.jiraApi.authType === 'bearer') {
+        return `Bearer ${config.jiraApi.token}`;
+    }
+    // Basic auth (default)
+    return `Basic ${Buffer.from(`${config.jiraApi.email}:${config.jiraApi.token}`).toString('base64')}`;
+}
+// Jira API client with authentication
+const jiraApi = axios.create({
+    baseURL: `${config.jiraApi.baseUrl}/rest/api/3`,
+    headers: {
+        Authorization: getAuthHeader(),
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+    },
+});
+// Standardized error handling for Jira API
+function formatJiraError(error, context) {
+    if (axios.isAxiosError(error)) {
+        const statusCode = error.response?.status;
+        const message = error.response?.data?.message ||
+            error.response?.data?.errorMessages?.join(', ') ||
+            error.message;
+        return new Error(`${context}: ${statusCode} - ${message}`);
+    }
+    return new Error(`${context}: ${error.message}`);
+}
+/**
+ * Get user's account ID.
+ * - For Bearer auth: uses /myself endpoint
+ * - For Basic auth: searches by configured email
+ */
+export async function getCurrentUserAccountId() {
+    if (config.jiraApi.authType === 'bearer') {
+        // Bearer auth: get current user directly
+        const response = await jiraApi.get('/myself');
+        return response.data.accountId;
+    }
+    // Basic auth: search by email
+    const response = await jiraApi
+        .get('user/search', {
+        params: { query: config.jiraApi.email },
+    })
+        .catch((error) => {
+        throw new Error(`could not fetch user from jira: ${error}`);
+    });
+    const users = response.data;
+    if (!users || users.length === 0) {
+        throw new Error(`No user found with email: ${config.jiraApi.email}`);
+    }
+    // Find exact email match
+    const user = users.find((u) => u.emailAddress === config.jiraApi.email);
+    if (!user) {
+        throw new Error(`No exact match for email: ${config.jiraApi.email}`);
+    }
+    return user.accountId;
+}
+/**
+ * Get Jira issue key from issue ID
+ */
+export async function getIssueKeyById(issueId) {
+    try {
+        // Validate issue ID using the schema
+        const result = issueIdSchema().safeParse(issueId);
+        if (!result.success) {
+            throw new Error(result.error.issues[0].message || 'Issue ID validation failed');
+        }
+        const response = await jiraApi.get(`/issue/${issueId}`);
+        return response.data.key;
+    }
+    catch (error) {
+        throw formatJiraError(error, `Failed to get issue key for ID ${issueId}`);
+    }
+}
+/**
+ * Get Jira issue from issue ID or key
+ */
+export async function getIssue(idOrKey) {
+    try {
+        // Validate issue ID using the schema
+        const result = idOrKeySchema().safeParse(idOrKey);
+        if (!result.success) {
+            throw new Error(result.error.issues[0].message || 'Issue identifier validation failed');
+        }
+        const response = await jiraApi.get(`/issue/${idOrKey}`);
+        // Find the Tempo account key
+        const tempoAccountId = config.jiraApi.tempoAccountCustomFieldId
+            ? response.data.fields[`customfield_${config.jiraApi.tempoAccountCustomFieldId}`]?.id
+            : undefined;
+        const id = response.data.id;
+        const key = response.data.key;
+        return {
+            id,
+            key,
+            ...(tempoAccountId ? { tempoAccountId } : {}),
+        };
+    }
+    catch (error) {
+        throw formatJiraError(error, `Failed to get issue for ${idOrKey}`);
+    }
+}

package/build/tools.js

@@ -0,0 +1,390 @@
+import axios from 'axios';
+import config from './config.js';
+import { getCurrentUserAccountId, getIssue } from './jira.js';
+import { formatError, getIssueKeysMap, calculateEndTime } from './utils.js';
+// API client for Tempo
+const api = axios.create({
+    baseURL: config.tempoApi.baseUrl,
+    headers: {
+        Authorization: `Bearer ${config.tempoApi.token}`,
+        'Content-Type': 'application/json',
+    },
+});
+/**
+ * Retrieve worklogs for the configured user within a date range
+ */
+export async function retrieveWorklogs(startDate, endDate) {
+    try {
+        const accountId = await getCurrentUserAccountId();
+        // Fetch all pages of worklogs
+        let allWorklogs = [];
+        let nextUrl = null;
+        let isFirstRequest = true;
+        let pageCount = 0;
+        const MAX_PAGES = 500; // Safety limit to prevent infinite loops (25,000 worklogs max)
+        do {
+            if (pageCount >= MAX_PAGES) {
+                console.warn(`Reached maximum page limit (${MAX_PAGES}) while fetching worklogs`);
+                break;
+            }
+            let response;
+            if (isFirstRequest) {
+                response = await api
+                    .get(`/worklogs/user/${accountId}`, {
+                    params: { from: startDate, to: endDate },
+                })
+                    .catch((error) => {
+                    if (error.response?.status === 401) {
+                        throw new Error('Invalid API token. Please check your Tempo API token and try again.');
+                    }
+                    throw error;
+                });
+                isFirstRequest = false;
+            }
+            else {
+                const expectedOrigin = new URL(config.tempoApi.baseUrl).origin;
+                const nextUrlOrigin = new URL(nextUrl).origin;
+                if (nextUrlOrigin !== expectedOrigin) {
+                    throw new Error(`Invalid pagination URL: expected origin ${expectedOrigin}, got ${nextUrlOrigin}`);
+                }
+                response = await axios.get(nextUrl, {
+                    headers: {
+                        Authorization: `Bearer ${config.tempoApi.token}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+            }
+            const pageWorklogs = response.data.results || [];
+            allWorklogs = allWorklogs.concat(pageWorklogs);
+            // Check if there's a next page
+            nextUrl = response?.data?.metadata?.next || null;
+            pageCount++;
+        } while (nextUrl);
+        const worklogs = allWorklogs;
+        // If no worklogs found, return empty content
+        if (worklogs.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No worklogs found for the specified date range.',
+                    },
+                ],
+            };
+        }
+        // Get issue keys for all worklogs
+        const issueIdToKeyMap = await getIssueKeysMap(worklogs);
+        // Format the response
+        const formattedContent = worklogs.map((worklog) => {
+            const tempoWorklogId = worklog.tempoWorklogId || 'Unknown';
+            const issueId = worklog.issue?.id || 'Unknown';
+            const issueKey = issueIdToKeyMap[issueId] || 'Unknown';
+            const description = worklog.description || 'No description';
+            const timeSpentHours = (worklog.timeSpentSeconds / 3600).toFixed(2);
+            const date = worklog.startDate || 'Unknown';
+            const startTime = worklog.startTime || '';
+            return {
+                type: 'text',
+                text: `TempoWorklogId: ${tempoWorklogId} | IssueKey: ${issueKey} | IssueId: ${issueId} | Date: ${date}${startTime ? ` | StartTime: ${startTime}` : ''} | Hours: ${timeSpentHours} | Description: ${description}`,
+            };
+        });
+        return {
+            content: formattedContent,
+            metadata: {
+                totalCount: worklogs.length,
+                pagesProcessed: pageCount,
+                startDate,
+                endDate,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Error retrieving worklogs: ${formatError(error)}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * Create a new worklog
+ */
+export async function createWorklog(issueKey, timeSpentHours, date, description, startTime = undefined, remainingEstimateHours = undefined) {
+    try {
+        // Get issue ID and account ID
+        const issue = await getIssue(issueKey);
+        const accountId = await getCurrentUserAccountId();
+        const { id: issueId } = issue;
+        const account = await fetchTempoAccountFromIssue(issue);
+        const timeSpentSeconds = Math.round(timeSpentHours * 3600);
+        // Prepare payload
+        const payload = {
+            issueId: Number(issueId),
+            timeSpentSeconds,
+            billableSeconds: timeSpentSeconds,
+            startDate: date,
+            authorAccountId: accountId,
+            description: description || null,
+            ...(startTime && { startTime: `${startTime}:00` }),
+            ...(remainingEstimateHours !== undefined && {
+                remainingEstimateSeconds: Math.round(remainingEstimateHours * 3600),
+            }),
+            ...(account && {
+                attributes: [{ key: '_Account_', value: account.key }],
+            }),
+        };
+        // Submit the worklog
+        const response = await api.post('/worklogs', payload);
+        // Calculate end time if start time is provided
+        let timeInfo = '';
+        if (startTime) {
+            const endTime = calculateEndTime(startTime, timeSpentHours);
+            timeInfo = ` starting at ${startTime} and ending at ${endTime}`;
+        }
+        const accountInfo = account ? ` with account '${account.name}'` : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Worklog with ID ${response.data.tempoWorklogId} created successfully for ${issueKey}${accountInfo}. Time logged: ${timeSpentHours} hours on ${date}${timeInfo}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        console.error(error);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to create worklog: ${formatError(error)}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * Create multiple worklogs
+ */
+export async function bulkCreateWorklogs(worklogEntries) {
+    try {
+        // Get user account ID
+        const authorAccountId = await getCurrentUserAccountId();
+        // Group entries by issue key
+        const entriesByIssueKey = {};
+        worklogEntries.forEach((entry) => {
+            if (!entriesByIssueKey[entry.issueKey]) {
+                entriesByIssueKey[entry.issueKey] = [];
+            }
+            entriesByIssueKey[entry.issueKey].push(entry);
+        });
+        const results = [];
+        const errors = [];
+        // Process each issue's entries
+        for (const [issueKey, entries] of Object.entries(entriesByIssueKey)) {
+            try {
+                const issue = await getIssue(issueKey);
+                const account = await fetchTempoAccountFromIssue(issue);
+                // Format entries for API
+                const formattedEntries = entries.map((entry) => ({
+                    timeSpentSeconds: Math.round(entry.timeSpentHours * 3600),
+                    startDate: entry.date,
+                    authorAccountId,
+                    description: entry.description || '',
+                    ...(entry.startTime && { startTime: `${entry.startTime}:00` }),
+                    ...(account && {
+                        attributes: [{ key: '_Account_', value: account.key }],
+                    }),
+                }));
+                const { id: issueId } = issue;
+                // Submit bulk request
+                const response = await api.post(`/worklogs/issue/${Number(issueId)}/bulk`, formattedEntries);
+                const createdWorklogs = response.data || [];
+                // Record results
+                entries.forEach((entry, i) => {
+                    const created = createdWorklogs[i] || null;
+                    // Calculate end time if startTime is provided
+                    let endTime = undefined;
+                    if (entry.startTime && created) {
+                        endTime = calculateEndTime(entry.startTime, entry.timeSpentHours);
+                    }
+                    results.push({
+                        issueKey,
+                        timeSpentHours: entry.timeSpentHours,
+                        date: entry.date,
+                        worklogId: created?.tempoWorklogId || null,
+                        success: !!created,
+                        startTime: entry.startTime,
+                        endTime,
+                        account: account?.name,
+                    });
+                });
+            }
+            catch (error) {
+                const errorMessage = formatError(error);
+                // Record errors
+                entries.forEach((entry) => {
+                    errors.push({
+                        issueKey,
+                        timeSpentHours: entry.timeSpentHours,
+                        date: entry.date,
+                        error: errorMessage,
+                    });
+                });
+            }
+        }
+        // Create content for response
+        const content = [];
+        const successCount = results.filter((r) => r.success).length;
+        // Add success messages
+        if (successCount > 0) {
+            content.push({
+                type: 'text',
+                text: `Successfully created ${successCount} worklogs:`,
+            });
+            results
+                .filter((r) => r.success)
+                .forEach((result) => {
+                let timeInfo = '';
+                if (result.startTime) {
+                    timeInfo = ` starting at ${result.startTime}${result.endTime ? ` and ending at ${result.endTime}` : ''}`;
+                }
+                const accountInfo = result.account
+                    ? ` for account '${result.account}'`
+                    : '';
+                content.push({
+                    type: 'text',
+                    text: `- Issue ${result.issueKey}: ${result.timeSpentHours} hours on ${result.date}${timeInfo}${accountInfo}`,
+                });
+            });
+        }
+        // Add error messages
+        if (errors.length > 0) {
+            content.push({
+                type: 'text',
+                text: `Failed to create ${errors.length} worklogs:`,
+            });
+            errors.forEach((error) => {
+                content.push({
+                    type: 'text',
+                    text: `- Issue ${error.issueKey}: ${error.timeSpentHours} hours on ${error.date}. Error: ${error.error}`,
+                });
+            });
+        }
+        return {
+            content,
+            metadata: {
+                totalSuccess: successCount,
+                totalFailure: errors.length,
+                details: {
+                    successes: results.filter((r) => r.success),
+                    failures: errors,
+                },
+            },
+            isError: errors.length > 0 && successCount === 0,
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Error processing bulk worklogs: ${formatError(error)}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * Edit an existing worklog
+ */
+export async function editWorklog(worklogId, timeSpentHours, description = null, date = null, startTime = undefined) {
+    try {
+        // Get current worklog
+        const response = await api.get(`/worklogs/${worklogId}`);
+        const worklog = response.data;
+        // Prepare update payload
+        const updatePayload = {
+            authorAccountId: worklog.author.accountId,
+            startDate: date || worklog.startDate,
+            timeSpentSeconds: Math.round(timeSpentHours * 3600),
+            billableSeconds: Math.round(timeSpentHours * 3600),
+            ...(description !== null && { description }),
+            ...(startTime && { startTime: `${startTime}:00` }),
+        };
+        // Update the worklog
+        await api.put(`/worklogs/${worklogId}`, updatePayload);
+        // Information about the update
+        let updateInfo = `Worklog updated successfully`;
+        // Calculate and show time info if we have a start time
+        if (startTime) {
+            const endTime = calculateEndTime(startTime, timeSpentHours);
+            updateInfo += `. Time logged: ${timeSpentHours} hours starting at ${startTime} and ending at ${endTime}`;
+        }
+        // Format response
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: updateInfo,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                { type: 'text', text: `Failed to edit worklog: ${formatError(error)}` },
+            ],
+        };
+    }
+}
+/**
+ * Delete a worklog
+ */
+export async function deleteWorklog(worklogId) {
+    try {
+        // Get worklog details for the response
+        let worklogDetails = null;
+        try {
+            const response = await api.get(`/worklogs/${worklogId}`);
+            worklogDetails = response.data;
+        }
+        catch (error) {
+            // Continue with deletion even if we can't get details
+            console.error(`Could not fetch worklog details: ${error.message}`);
+        }
+        // Delete the worklog
+        await api.delete(`/worklogs/${worklogId}`);
+        return {
+            content: [{ type: 'text', text: 'Worklog deleted successfully' }],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to delete worklog: ${formatError(error)}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * @returns The tempo account associated with the issue via the Jira custom field, if any
+ */
+async function fetchTempoAccountFromIssue({ tempoAccountId, }) {
+    if (!tempoAccountId)
+        return undefined;
+    const response = await api.get(`/accounts/${tempoAccountId}`);
+    return response.data;
+}

package/build/types.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+// Common validation schemas
+export const dateSchema = () => z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format');
+export const timeSchema = () => z
+    .string()
+    .regex(/^([01]\d|2[0-3]):([0-5]\d)$/, 'Time must be in HH:MM format');
+export const issueKeySchema = () => z.string().min(1, 'Issue key cannot be empty');
+export const issueIdSchema = () => z.union([
+    z.string().min(1, 'Issue ID cannot be empty'),
+    z.number().int().positive('Issue ID must be a positive integer'),
+]);
+export const idOrKeySchema = () => z.union([issueKeySchema(), issueIdSchema()]);
+// Environment validation
+export const envSchema = z
+    .object({
+    TEMPO_API_TOKEN: z.string().min(1, 'TEMPO_API_TOKEN is required'),
+    JIRA_BASE_URL: z.string().min(1, 'JIRA_BASE_URL is required'),
+    JIRA_API_TOKEN: z.string().min(1, 'JIRA_API_TOKEN is required'),
+    JIRA_EMAIL: z.string().optional(),
+    JIRA_AUTH_TYPE: z.enum(['basic', 'bearer']).optional().default('basic'),
+    JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID: z.string().optional(),
+})
+    .refine((data) => data.JIRA_AUTH_TYPE === 'bearer' || data.JIRA_EMAIL, {
+    message: 'JIRA_EMAIL is required when using basic authentication',
+});
+// Worklog entry schema
+export const worklogEntrySchema = z.object({
+    issueKey: issueKeySchema(),
+    timeSpentHours: z.number().positive('Time spent must be positive'),
+    date: dateSchema(),
+    description: z.string().optional(),
+    startTime: timeSchema().optional(),
+});
+function getToday() {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+function getStartOfWeek() {
+    const d = new Date();
+    const day = d.getDay();
+    const diff = day === 0 ? -6 : 1 - day; // back to Monday
+    d.setDate(d.getDate() + diff);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+// MCP tool schemas
+export const retrieveWorklogsSchema = z.object({
+    startDate: dateSchema().default(getStartOfWeek),
+    endDate: dateSchema().default(getToday),
+});
+export const createWorklogSchema = z.object({
+    issueKey: issueKeySchema(),
+    timeSpentHours: z
+        .number()
+        .positive('Time spent must be positive')
+        .default(1.5),
+    date: dateSchema(),
+    description: z.string(),
+    startTime: timeSchema().optional().default('08:00'),
+    remainingEstimateHours: z
+        .number()
+        .nonnegative('Remaining estimate must be non-negative')
+        .optional(),
+});
+export const bulkCreateWorklogsSchema = z.object({
+    worklogEntries: z
+        .array(worklogEntrySchema)
+        .min(1, 'At least one worklog entry is required'),
+});
+export const editWorklogSchema = z.object({
+    worklogId: z.string().min(1, 'Worklog ID is required'),
+    timeSpentHours: z.number().positive('Time spent must be positive'),
+    description: z.string().optional().nullable(),
+    date: dateSchema().optional().nullable(),
+    startTime: timeSchema().optional(),
+});
+export const deleteWorklogSchema = z.object({
+    worklogId: z.string().min(1, 'Worklog ID is required'),
+});

package/build/utils.js

@@ -0,0 +1,75 @@
+import axios from 'axios';
+import { getIssueKeyById } from './jira.js';
+/**
+ * Standard error handling for API errors
+ * Extracts the most useful error message from Axios errors
+ */
+export function formatError(error) {
+    if (axios.isAxiosError(error)) {
+        const data = error.response?.data;
+        const status = error.response?.status;
+        const parts = [];
+        if (status)
+            parts.push(`[${status}]`);
+        if (data?.errors && Array.isArray(data.errors) && data.errors.length > 0) {
+            const errorMessages = data.errors.map((e) => e.message
+                ? e.field
+                    ? `${e.field}: ${e.message}`
+                    : e.message
+                : JSON.stringify(e));
+            parts.push(errorMessages.join('; '));
+        }
+        else if (data?.message) {
+            parts.push(data.message);
+        }
+        else {
+            parts.push(error.message);
+        }
+        return parts.join(' ');
+    }
+    return error.message;
+}
+/**
+ * Get issue keys for worklogs
+ * Maps Jira issue IDs to their corresponding issue keys
+ */
+export async function getIssueKeysMap(worklogs) {
+    // Extract unique issue IDs
+    const uniqueIssueIds = [
+        ...new Set(worklogs.map((worklog) => worklog.issue?.id).filter((id) => id != null)),
+    ];
+    if (uniqueIssueIds.length === 0)
+        return {};
+    // Create issue ID to key map
+    const issueIdToKeyMap = {};
+    // Fetch issue keys in parallel
+    await Promise.all(uniqueIssueIds.map(async (issueId) => {
+        try {
+            const issueKey = await getIssueKeyById(issueId);
+            issueIdToKeyMap[issueId] = issueKey;
+        }
+        catch (error) {
+            console.error(`Could not get key for issue ID ${issueId}: ${error.message}`);
+        }
+    }));
+    return issueIdToKeyMap;
+}
+/**
+ * Calculate end time
+ * Calculates the end time based on the start time and hours spent
+ * @param startTime Time in format HH:MM
+ * @param hoursSpent Duration in hours (can be decimal)
+ * @returns End time in format HH:MM
+ */
+export function calculateEndTime(startTime, hoursSpent) {
+    // Parse the HH:MM format
+    const [hours, minutes] = startTime.split(':').map((num) => parseInt(num, 10));
+    // Create a Date object with today's date but with the given hours and minutes
+    const startTimeDate = new Date();
+    startTimeDate.setHours(hours, minutes, 0, 0);
+    // Add the duration in milliseconds
+    const endTimeDate = new Date(startTimeDate.getTime() + hoursSpent * 3600 * 1000);
+    // Format the end time as HH:MM
+    const endTime = `${endTimeDate.getHours().toString().padStart(2, '0')}:${endTimeDate.getMinutes().toString().padStart(2, '0')}`;
+    return endTime;
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@fluentdata-ai/tempo-mcp-server",
+  "version": "1.3.3",
+  "description": "MCP server for managing Tempo worklogs in Jira",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "tempo-mcp-server": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "start": "node build/index.js",
+    "dev": "tsx watch src/index.ts",
+    "inspect": "npx @modelcontextprotocol/inspector@latest tsx src/index.ts",
+    "prepare": "npm run build && husky",
+    "lint": "eslint",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "tempo",
+    "jira",
+    "worklogs",
+    "time-tracking",
+    "claude",
+    "cursor",
+    "windsurf",
+    "cline",
+    "ai"
+  ],
+  "author": "Ivelin Ivanov <ivelinivanov1999@gmail.com>",
+  "contributors": [
+    "Edgar Isai Salgado Cortez <edgarisaiwr@gmail.com>"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fluentdata-co/tempo-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fluentdata-co/tempo-mcp-server/issues"
+  },
+  "homepage": "https://github.com/fluentdata-co/tempo-mcp-server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.6.7",
+    "dotenv": "^17.3.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^20.11.0",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.5",
+    "globals": "^16.2.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.0",
+    "prettier": "3.5.3",
+    "tsx": "^4.7.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "lint-staged": {
+    "*.{js,ts}": "eslint --cache --fix --quiet",
+    "*": "prettier . --write"
+  }
+}