mcp-ts-template 1.5.5 → 1.5.7

package/README.md

@@ -1,9 +1,9 @@
 # MCP TypeScript Template 🚀
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.12.3-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.5.5-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.5.7-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/mcp-ts-template/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/mcp-ts-template?style=social)](https://github.com/cyanheads/mcp-ts-template)
@@ -55,6 +55,7 @@ This template is already powering several MCP servers, demonstrating its flexibi
 | [**obsidian-mcp-server**](https://github.com/cyanheads/obsidian-mcp-server)                   | MCP server for Obsidian, enabling AI agents to read, write, search, and manage notes via the Local REST API plugin.                                                                                                                  | Actively using this template.              |
 | [**atlas-mcp-server**](https://github.com/cyanheads/atlas-mcp-server)                         | Advanced task and knowledge management system with Neo4j backend, enabling structured data organization and complex querying for AI agents.                                                                                          | Aligned with this template (as of v2.8.8). |
 | [**filesystem-mcp-server**](https://github.com/cyanheads/filesystem-mcp-server)               | Offers platform-agnostic file system capabilities for AI agents via MCP. Enables reading, writing, updating, and managing files/directories, featuring advanced search/replace and directory traversal.                              | Actively using this template.              |
+| [**workflows-mcp-server**](https://github.com/cyanheads/workflows-mcp-server)                 | Empowers AI agents with a powerful, declarative workflow engine to discover, understand, and execute complex, multi-step workflows defined in simple YAML files.                                                                     | Actively using this template.              |
 
 _Note: [**toolkit-mcp-server**](https://github.com/cyanheads/toolkit-mcp-server) was initially built using an older version of this template and is pending updates to the latest structure._
 

package/dist/utils/index.d.ts

@@ -9,3 +9,4 @@ export * from "./metrics/index.js";
 export * from "./parsing/index.js";
 export * from "./security/index.js";
 export * from "./network/index.js";
+export * from "./scheduling/index.js";

package/dist/utils/index.js

@@ -10,6 +10,7 @@ export * from "./metrics/index.js";
 export * from "./parsing/index.js";
 export * from "./security/index.js";
 export * from "./network/index.js";
+export * from "./scheduling/index.js";
 // It's good practice to have index.ts files in each subdirectory
 // that export the contents of that directory.
 // Assuming those will be created or already exist.

package/dist/utils/scheduling/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from './scheduler.js';

package/dist/utils/scheduling/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from './scheduler.js';

package/dist/utils/scheduling/scheduler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import { ScheduledTask } from 'node-cron';
+import { RequestContext } from '../internal/index.js';
+/**
+ * Represents a scheduled job managed by the SchedulerService.
+ */
+export interface Job {
+    /** A unique identifier for the job. */
+    id: string;
+    /** The cron pattern defining the job's schedule. */
+    schedule: string;
+    /** A description of what the job does. */
+    description: string;
+    /** The underlying 'node-cron' task instance. */
+    task: ScheduledTask;
+    /** Indicates whether the job is currently running. */
+    isRunning: boolean;
+}
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export declare class SchedulerService {
+    private static instance;
+    private jobs;
+    /** @private */
+    private constructor();
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance(): SchedulerService;
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id: string, schedule: string, taskFunction: (context: RequestContext) => void | Promise<void>, description: string): Job;
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id: string): void;
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id: string): void;
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id: string): void;
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs(): Job[];
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export declare const schedulerService: SchedulerService;

package/dist/utils/scheduling/scheduler.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import cron from 'node-cron';
+import { logger } from '../internal/index.js';
+import { requestContextService } from '../internal/requestContext.js';
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export class SchedulerService {
+    /** @private */
+    constructor() {
+        this.jobs = new Map();
+        logger.info('SchedulerService initialized.', {
+            requestId: 'scheduler-init',
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance() {
+        if (!SchedulerService.instance) {
+            SchedulerService.instance = new SchedulerService();
+        }
+        return SchedulerService.instance;
+    }
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id, schedule, taskFunction, description) {
+        if (this.jobs.has(id)) {
+            throw new Error(`Job with ID '${id}' already exists.`);
+        }
+        if (!cron.validate(schedule)) {
+            throw new Error(`Invalid cron schedule: ${schedule}`);
+        }
+        const task = cron.schedule(schedule, async () => {
+            const job = this.jobs.get(id);
+            if (job && job.isRunning) {
+                logger.warning(`Job '${id}' is already running. Skipping this execution.`, {
+                    requestId: `job-skip-${id}`,
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+            if (job) {
+                job.isRunning = true;
+            }
+            const context = requestContextService.createRequestContext({
+                jobId: id,
+                schedule,
+            });
+            logger.info(`Starting job '${id}'...`, context);
+            try {
+                await Promise.resolve(taskFunction(context));
+                logger.info(`Job '${id}' completed successfully.`, context);
+            }
+            catch (error) {
+                logger.error(`Job '${id}' failed.`, error, context);
+            }
+            finally {
+                if (job) {
+                    job.isRunning = false;
+                }
+            }
+        }, {
+            scheduled: false, // Do not start immediately
+        });
+        const newJob = {
+            id,
+            schedule,
+            description,
+            task,
+            isRunning: false,
+        };
+        this.jobs.set(id, newJob);
+        logger.info(`Job '${id}' scheduled: ${description}`, {
+            requestId: `job-schedule-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+        return newJob;
+    }
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.start();
+        logger.info(`Job '${id}' started.`, {
+            requestId: `job-start-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        logger.info(`Job '${id}' stopped.`, {
+            requestId: `job-stop-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        this.jobs.delete(id);
+        logger.info(`Job '${id}' removed.`, {
+            requestId: `job-remove-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs() {
+        return Array.from(this.jobs.values());
+    }
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export const schedulerService = SchedulerService.getInstance();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "description": "Jumpstart Model Context Protocol (MCP) development with this production-ready TypeScript template. Build robust MCP servers and clients with built-in utilities, authentication, and service integrations.",
   "main": "dist/index.js",
   "files": [
@@ -44,7 +44,7 @@
     "@types/validator": "13.15.2",
     "chrono-node": "^2.8.0",
     "dotenv": "^16.5.0",
-    "hono": "^4.8.1",
+    "hono": "^4.8.2",
     "ignore": "^7.0.5",
     "jose": "^6.0.11",
     "openai": "^5.6.0",
@@ -56,6 +56,7 @@
     "validator": "13.15.15",
     "winston": "^3.17.0",
     "winston-transport": "^4.9.0",
+    "node-cron": "^4.1.1",
     "zod": "^3.25.67"
   },
   "keywords": [
@@ -96,10 +97,11 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
+    "@types/node-cron": "^3.0.11",
     "axios": "^1.10.0",
     "depcheck": "^1.4.7",
     "js-yaml": "^4.1.0",
-    "prettier": "^3.5.3",
+    "prettier": "^3.6.0",
     "typedoc": "^0.28.5"
   }
 }