@comunica/utils-mcp 1.0.0 → 1.1.0

package/lib/BinHelpers.d.ts

@@ -1,3 +1,10 @@
 import type { QueryEngineBase } from '@comunica/actor-init-query';
 import type { QueryStringContext } from '@comunica/types';
-export declare function runCli(queryEngine: QueryEngineBase, version: string, customContext?: Partial<QueryStringContext>): void;
+/**
+ * Run the CLI of an MCP server.
+ * @param queryEngine The query engine to expose, or a factory creating it.
+ *                    A factory is preferred, as it avoids initializing an engine inside the primary process.
+ * @param version The version of the MCP server.
+ * @param customContext An optional query context to apply to all queries.
+ */
+export declare function runCli(queryEngine: QueryEngineBase | (() => QueryEngineBase), version: string, customContext?: Partial<QueryStringContext>): void;

package/lib/BinHelpers.js

@@ -4,6 +4,18 @@ exports.runCli = runCli;
 const yargs_1 = require("yargs");
 const helpers_1 = require("yargs/helpers");
 const SparqlMcpServer_1 = require("./SparqlMcpServer");
+const WorkerPool_1 = require("./WorkerPool");
+// The cluster module only has a default export, which can not be imported
+// as such within this CommonJS package, so it is required instead.
+// eslint-disable-next-line ts/no-require-imports,ts/no-var-requires
+const cluster = require('node:cluster');
+/**
+ * Run the CLI of an MCP server.
+ * @param queryEngine The query engine to expose, or a factory creating it.
+ *                    A factory is preferred, as it avoids initializing an engine inside the primary process.
+ * @param version The version of the MCP server.
+ * @param customContext An optional query context to apply to all queries.
+ */
 function runCli(queryEngine, version, customContext) {
     (async () => {
         const argv = await (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
@@ -20,17 +32,57 @@ function runCli(queryEngine, version, customContext) {
             type: 'number',
             default: 3123,
             description: 'Port to run the MCP server on (only for http mode)',
+        })
+            .option('workers', {
+            alias: 'w',
+            type: 'number',
+            default: 1,
+            description: 'Number of worker processes to run queries in (only for http mode)',
+        })
+            .option('timeout', {
+            alias: 't',
+            type: 'number',
+            default: 60_000,
+            description: 'Maximum query execution time in milliseconds (0 to disable)',
         })
             .example([
             ['$0 --mode stdio', 'Start MCP server in stdio mode without default sources'],
             ['$0 --mode http --port 3000', 'Start MCP server in HTTP mode on port 3000'],
+            ['$0 --mode http --port 3000 --workers 4', 'Start MCP server with 4 worker processes'],
+            ['$0 --mode http --port 3000 --timeout 300000', 'Start with a query timeout of 5 minutes'],
             ['$0 --mode stdio https://dbpedia.org/sparql', 'Start with a default SPARQL endpoint'],
             ['$0 --mode stdio https://example.org/data.ttl file@/path/to/local.ttl', 'Start with multiple default sources'],
         ])
             .parse();
+        // In http mode, queries are executed inside worker processes that are supervised by this primary process.
+        // Queries that block the event loop can not be aborted by the worker they run in,
+        // as no timeout inside that worker would be able to fire anymore.
+        // The primary process detects such workers, and kills and replaces them.
+        // In stdio mode, the server is not clustered, as workers can not share a single stdin stream,
+        // and restarting a worker would invalidate the MCP session of the connected client.
+        if (argv.mode === 'http' && cluster.isPrimary) {
+            const workerPool = new WorkerPool_1.WorkerPool({
+                workers: Math.max(1, argv.workers),
+                unresponsiveTimeout: argv.timeout > 0 ? Math.max(argv.timeout, WorkerPool_1.MIN_UNRESPONSIVE_TIMEOUT) : 0,
+                stderr: process.stderr,
+            });
+            workerPool.start();
+            for (const signal of ['SIGINT', 'SIGTERM']) {
+                process.on(signal, () => workerPool.stop(signal));
+            }
+            return;
+        }
+        // Let the primary process know that this worker is still responsive.
+        // This is a no-op in stdio mode, where there is no primary process.
+        (0, WorkerPool_1.startHeartbeat)();
         // Extract positional arguments as default sources
         const defaultSources = argv._.length > 0 ? argv._.map(String) : undefined;
-        const server = new SparqlMcpServer_1.SparqlMcpServer(argv.mode, argv.port, queryEngine, version, process.stderr, defaultSources, customContext);
+        const server = new SparqlMcpServer_1.SparqlMcpServer(argv.mode, argv.port, typeof queryEngine === 'function' ? queryEngine() : queryEngine, version, process.stderr, defaultSources, customContext, undefined, {
+            queryTimeout: argv.timeout,
+            // Comunica can not abort a running query, so the only way to reclaim the resources
+            // of a timed out query is to let the primary process replace this worker.
+            onQueryTimeout: () => (0, WorkerPool_1.requestRecycle)(),
+        });
         server.start().catch((error) => {
             process.stderr.write(`Server error: ${error.message}\n`);
             if (error.stack) {

package/lib/BinHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"BinHelpers.js","sourceRoot":"","sources":["BinHelpers.ts"],"names":[],"mappings":";;AAOA,wBAuDC;AA3DD,iCAA0B;AAC1B,2CAAwC;AACxC,uDAAoD;AAEpD,SAAgB,MAAM,CACpB,WAA4B,EAC5B,OAAe,EACf,aAA2C;IAE3C,CAAC,KAAK,IAAG,EAAE;QACT,MAAM,IAAI,GAAG,MAAM,IAAA,eAAK,EAAC,IAAA,iBAAO,EAAC,OAAO,CAAC,IAAI,CAAC,CAAC;aAC5C,KAAK,CAAC,kCAAkC,CAAC;aACzC,MAAM,CAAC,MAAM,EAAE;YACd,KAAK,EAAE,GAAG;YACV,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,CAAE,OAAO,EAAE,MAAM,CAAE;YAC5B,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,mCAAmC;SACjD,CAAC;aACD,MAAM,CAAC,MAAM,EAAE;YACd,KAAK,EAAE,GAAG;YACV,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,oDAAoD;SAClE,CAAC;aACD,OAAO,CAAC;YACP,CAAE,iBAAiB,EAAE,wDAAwD,CAAE;YAC/E,CAAE,4BAA4B,EAAE,4CAA4C,CAAE;YAC9E,CAAE,4CAA4C,EAAE,sCAAsC,CAAE;YACxF,CAAE,sEAAsE,EAAE,qCAAqC,CAAE;SAClH,CAAC;aACD,KAAK,EAAE,CAAC;QAEX,kDAAkD;QAClD,MAAM,cAAc,GAAyB,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEhG,MAAM,MAAM,GAAG,IAAI,iCAAe,CACb,IAAI,CAAC,IAAI,EAC5B,IAAI,CAAC,IAAI,EACT,WAAW,EACX,OAAO,EACP,OAAO,CAAC,MAAM,EACd,cAAc,EACd,aAAa,CACd,CAAC;QACF,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;YACzD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/* eslint-disable unicorn/no-process-exit */\nimport type { QueryEngineBase } from '@comunica/actor-init-query';\nimport type { QueryStringContext } from '@comunica/types';\nimport yargs from 'yargs';\nimport { hideBin } from 'yargs/helpers';\nimport { SparqlMcpServer } from './SparqlMcpServer';\n\nexport function runCli(\n  queryEngine: QueryEngineBase,\n  version: string,\n  customContext?: Partial<QueryStringContext>,\n): void {\n  (async() => {\n    const argv = await yargs(hideBin(process.argv))\n      .usage('Usage: $0 [options] [sources...]')\n      .option('mode', {\n        alias: 'm',\n        type: 'string',\n        choices: [ 'stdio', 'http' ],\n        demandOption: true,\n        description: 'Transport mode for the MCP server',\n      })\n      .option('port', {\n        alias: 'p',\n        type: 'number',\n        default: 3123,\n        description: 'Port to run the MCP server on (only for http mode)',\n      })\n      .example([\n        [ '$0 --mode stdio', 'Start MCP server in stdio mode without default sources' ],\n        [ '$0 --mode http --port 3000', 'Start MCP server in HTTP mode on port 3000' ],\n        [ '$0 --mode stdio https://dbpedia.org/sparql', 'Start with a default SPARQL endpoint' ],\n        [ '$0 --mode stdio https://example.org/data.ttl file@/path/to/local.ttl', 'Start with multiple default sources' ],\n      ])\n      .parse();\n\n    // Extract positional arguments as default sources\n    const defaultSources: string[] | undefined = argv._.length > 0 ? argv._.map(String) : undefined;\n\n    const server = new SparqlMcpServer(\n      <'stdio' | 'http'> argv.mode,\n      argv.port,\n      queryEngine,\n      version,\n      process.stderr,\n      defaultSources,\n      customContext,\n    );\n    server.start().catch((error) => {\n      process.stderr.write(`Server error: ${error.message}\\n`);\n      if (error.stack) {\n        process.stderr.write(`${error.stack}\\n`);\n      }\n      process.exit(1);\n    });\n  })().catch((error) => {\n    process.stderr.write(`Initialization error: ${error.message}\\n`);\n    if (error.stack) {\n      process.stderr.write(`${error.stack}\\n`);\n    }\n    process.exit(1);\n  });\n}\n"]}
+{"version":3,"file":"BinHelpers.js","sourceRoot":"","sources":["BinHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable unicorn/no-process-exit,import/no-nodejs-modules */\nimport type { Cluster } from 'node:cluster';\nimport type { QueryEngineBase } from '@comunica/actor-init-query';\nimport type { QueryStringContext } from '@comunica/types';\nimport yargs from 'yargs';\nimport { hideBin } from 'yargs/helpers';\nimport { SparqlMcpServer } from './SparqlMcpServer';\nimport { MIN_UNRESPONSIVE_TIMEOUT, requestRecycle, startHeartbeat, WorkerPool } from './WorkerPool';\n\n// The cluster module only has a default export, which can not be imported\n// as such within this CommonJS package, so it is required instead.\n// eslint-disable-next-line ts/no-require-imports,ts/no-var-requires\nconst cluster: Cluster = require('node:cluster');\n\n/**\n * Run the CLI of an MCP server.\n * @param queryEngine The query engine to expose, or a factory creating it.\n *                    A factory is preferred, as it avoids initializing an engine inside the primary process.\n * @param version The version of the MCP server.\n * @param customContext An optional query context to apply to all queries.\n */\nexport function runCli(\n  queryEngine: QueryEngineBase | (() => QueryEngineBase),\n  version: string,\n  customContext?: Partial<QueryStringContext>,\n): void {\n  (async() => {\n    const argv = await yargs(hideBin(process.argv))\n      .usage('Usage: $0 [options] [sources...]')\n      .option('mode', {\n        alias: 'm',\n        type: 'string',\n        choices: [ 'stdio', 'http' ],\n        demandOption: true,\n        description: 'Transport mode for the MCP server',\n      })\n      .option('port', {\n        alias: 'p',\n        type: 'number',\n        default: 3123,\n        description: 'Port to run the MCP server on (only for http mode)',\n      })\n      .option('workers', {\n        alias: 'w',\n        type: 'number',\n        default: 1,\n        description: 'Number of worker processes to run queries in (only for http mode)',\n      })\n      .option('timeout', {\n        alias: 't',\n        type: 'number',\n        default: 60_000,\n        description: 'Maximum query execution time in milliseconds (0 to disable)',\n      })\n      .example([\n        [ '$0 --mode stdio', 'Start MCP server in stdio mode without default sources' ],\n        [ '$0 --mode http --port 3000', 'Start MCP server in HTTP mode on port 3000' ],\n        [ '$0 --mode http --port 3000 --workers 4', 'Start MCP server with 4 worker processes' ],\n        [ '$0 --mode http --port 3000 --timeout 300000', 'Start with a query timeout of 5 minutes' ],\n        [ '$0 --mode stdio https://dbpedia.org/sparql', 'Start with a default SPARQL endpoint' ],\n        [ '$0 --mode stdio https://example.org/data.ttl file@/path/to/local.ttl', 'Start with multiple default sources' ],\n      ])\n      .parse();\n\n    // In http mode, queries are executed inside worker processes that are supervised by this primary process.\n    // Queries that block the event loop can not be aborted by the worker they run in,\n    // as no timeout inside that worker would be able to fire anymore.\n    // The primary process detects such workers, and kills and replaces them.\n    // In stdio mode, the server is not clustered, as workers can not share a single stdin stream,\n    // and restarting a worker would invalidate the MCP session of the connected client.\n    if (argv.mode === 'http' && cluster.isPrimary) {\n      const workerPool = new WorkerPool({\n        workers: Math.max(1, argv.workers),\n        unresponsiveTimeout: argv.timeout > 0 ? Math.max(argv.timeout, MIN_UNRESPONSIVE_TIMEOUT) : 0,\n        stderr: process.stderr,\n      });\n      workerPool.start();\n      for (const signal of <NodeJS.Signals[]> [ 'SIGINT', 'SIGTERM' ]) {\n        process.on(signal, () => workerPool.stop(signal));\n      }\n      return;\n    }\n\n    // Let the primary process know that this worker is still responsive.\n    // This is a no-op in stdio mode, where there is no primary process.\n    startHeartbeat();\n\n    // Extract positional arguments as default sources\n    const defaultSources: string[] | undefined = argv._.length > 0 ? argv._.map(String) : undefined;\n\n    const server = new SparqlMcpServer(\n      <'stdio' | 'http'> argv.mode,\n      argv.port,\n      typeof queryEngine === 'function' ? queryEngine() : queryEngine,\n      version,\n      process.stderr,\n      defaultSources,\n      customContext,\n      undefined,\n      {\n        queryTimeout: argv.timeout,\n        // Comunica can not abort a running query, so the only way to reclaim the resources\n        // of a timed out query is to let the primary process replace this worker.\n        onQueryTimeout: () => requestRecycle(),\n      },\n    );\n    server.start().catch((error) => {\n      process.stderr.write(`Server error: ${error.message}\\n`);\n      if (error.stack) {\n        process.stderr.write(`${error.stack}\\n`);\n      }\n      process.exit(1);\n    });\n  })().catch((error) => {\n    process.stderr.write(`Initialization error: ${error.message}\\n`);\n    if (error.stack) {\n      process.stderr.write(`${error.stack}\\n`);\n    }\n    process.exit(1);\n  });\n}\n"]}

package/lib/SparqlMcpServer.d.ts

@@ -2,6 +2,19 @@ import type { Writable } from 'node:stream';
 import type { QueryEngineBase } from '@comunica/actor-init-query';
 import type { IQuerySourceUnidentifiedExpanded, QueryStringContext } from '@comunica/types';
 import type { Context, FastMCPSessionAuth } from 'fastmcp';
+export interface ISparqlMcpServerOptions {
+    /**
+     * The maximum time in milliseconds a query may take before it is aborted. A value of 0 disables the timeout.
+     *
+     * Note that Comunica offers no way to abort a running query,
+     * so timed out queries keep consuming resources in the background until the process is replaced.
+     */
+    queryTimeout?: number;
+    /**
+     * Invoked when a query exceeded {@link ISparqlMcpServerOptions.queryTimeout}.
+     */
+    onQueryTimeout?: () => void;
+}
 /**
  * An MCP server for querying over one or more Knowledge Graphs using SPARQL queries.
  */
@@ -9,12 +22,13 @@ export declare class SparqlMcpServer {
     private readonly mode;
     private readonly port;
     private readonly queryEngine;
+    private readonly options;
     private readonly server;
     private readonly stderr;
     private readonly defaultSources?;
     private readonly customContext?;
     private queryId;
-    constructor(mode: 'stdio' | 'http', port: number, queryEngine: QueryEngineBase, version: string, stderr: Writable, defaultSources?: string[], customContext?: Partial<QueryStringContext>, additionalSourcesDescription?: string);
+    constructor(mode: 'stdio' | 'http', port: number, queryEngine: QueryEngineBase, version: string, stderr: Writable, defaultSources?: string[], customContext?: Partial<QueryStringContext>, additionalSourcesDescription?: string, options?: ISparqlMcpServerOptions);
     /**
      * Start the MCP server in the configured mode (stdio or HTTP stream).
      */
@@ -48,6 +62,17 @@ export declare class SparqlMcpServer {
         httpRetryCount?: number;
     }): Partial<QueryStringContext>;
     protected registerTools(additionalSourcesDescription?: string): void;
+    /**
+     * Reject the given promise if it does not settle within the configured query timeout.
+     *
+     * Note that this can only interrupt queries that leave the event loop free.
+     * Queries that block the event loop are handled by the primary process,
+     * which kills and restarts unresponsive workers.
+     * @param promise The promise wrapping the query execution.
+     * @param queryId The query ID for logging.
+     * @returns The value of the given promise.
+     */
+    protected withQueryTimeout<T>(promise: Promise<T>, queryId: number): Promise<T>;
     /**
      * Execute a SPARQL query and stream the results back to the client.
      * This method contains the common logic for executing queries and handling results.

package/lib/SparqlMcpServer.js

@@ -10,15 +10,17 @@ class SparqlMcpServer {
     mode;
     port;
     queryEngine;
+    options;
     server;
     stderr;
     defaultSources;
     customContext;
     queryId = 0;
-    constructor(mode, port, queryEngine, version, stderr, defaultSources, customContext, additionalSourcesDescription) {
+    constructor(mode, port, queryEngine, version, stderr, defaultSources, customContext, additionalSourcesDescription, options = {}) {
         this.mode = mode;
         this.port = port;
         this.queryEngine = queryEngine;
+        this.options = options;
         this.stderr = stderr;
         this.server = new fastmcp_1.FastMCP({
             name: 'sparql-mcp',
@@ -185,6 +187,38 @@ class SparqlMcpServer {
             execute: (args, context) => this.executeQuerySparqlRdf(args, context),
         });
     }
+    /**
+     * Reject the given promise if it does not settle within the configured query timeout.
+     *
+     * Note that this can only interrupt queries that leave the event loop free.
+     * Queries that block the event loop are handled by the primary process,
+     * which kills and restarts unresponsive workers.
+     * @param promise The promise wrapping the query execution.
+     * @param queryId The query ID for logging.
+     * @returns The value of the given promise.
+     */
+    async withQueryTimeout(promise, queryId) {
+        const queryTimeout = this.options.queryTimeout ?? 0;
+        if (queryTimeout <= 0) {
+            return promise;
+        }
+        let timer;
+        const timeout = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                this.stderr.write(`[Query ${queryId}] Timed out after ${queryTimeout}ms\n`);
+                reject(new Error(`Query timed out after ${queryTimeout}ms. \
+Consider making the query more selective, restricting it to fewer sources, \
+or increasing the timeout of the MCP server.`));
+                this.options.onQueryTimeout?.();
+            }, queryTimeout);
+        });
+        try {
+            return await Promise.race([promise, timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     /**
      * Execute a SPARQL query and stream the results back to the client.
      * This method contains the common logic for executing queries and handling results.
@@ -197,27 +231,36 @@ class SparqlMcpServer {
      */
     async executeQuery(query, sources, queryId, context, queryContext = {}) {
         await context.streamContent({ type: 'text', text: `Streaming SPARQL query results hereafter:` });
+        // Kept outside of the query execution, so that a timed out query can be cancelled
+        let resultStream;
         try {
-            const promises = [];
-            const chunks = [];
-            // Merge custom context with provided query context
-            const mergedContext = { sources, ...this.customContext, ...queryContext };
-            const queryResult = await this.queryEngine.query(query, mergedContext);
-            const { data } = await this.queryEngine.resultToString(queryResult);
-            data.on('data', (chunk) => {
-                chunks.push(chunk);
-                promises.push(context.streamContent({ type: 'text', text: chunk.toString() }));
-            });
-            await new Promise((resolve, reject) => {
-                data.on('error', reject);
-                data.on('end', resolve);
-            });
-            await Promise.all(promises);
+            const executeInner = async () => {
+                const promises = [];
+                const chunks = [];
+                // Merge custom context with provided query context
+                const mergedContext = { sources, ...this.customContext, ...queryContext };
+                const queryResult = await this.queryEngine.query(query, mergedContext);
+                const { data } = await this.queryEngine.resultToString(queryResult);
+                resultStream = data;
+                data.on('data', (chunk) => {
+                    chunks.push(chunk);
+                    promises.push(context.streamContent({ type: 'text', text: chunk.toString() }));
+                });
+                await new Promise((resolve, reject) => {
+                    data.on('error', reject);
+                    data.on('end', resolve);
+                });
+                await Promise.all(promises);
+                return chunks.join('');
+            };
+            const results = await this.withQueryTimeout(executeInner(), queryId);
             // Log successful completion
             this.stderr.write(`[Query ${queryId}] Successfully completed\n`);
-            return chunks.join('');
+            return results;
         }
         catch (error) {
+            // Make sure that a timed out or failed query stops consuming resources
+            resultStream?.destroy();
             // Log query failure
             this.stderr.write(`[Query ${queryId}] Failed: ${error.stack}\n`);
             return {

package/lib/SparqlMcpServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"SparqlMcpServer.js","sourceRoot":"","sources":["SparqlMcpServer.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable import/no-nodejs-modules */\nimport type { Writable } from 'node:stream';\nimport type { QueryEngineBase } from '@comunica/actor-init-query';\nimport type { IQuerySourceSerialized, IQuerySourceUnidentifiedExpanded, QueryStringContext } from '@comunica/types';\nimport type { Context, FastMCPSessionAuth } from 'fastmcp';\nimport { FastMCP } from 'fastmcp';\nimport { z } from 'zod';\n\n/**\n * An MCP server for querying over one or more Knowledge Graphs using SPARQL queries.\n */\nexport class SparqlMcpServer {\n  private readonly server: FastMCP;\n  private readonly stderr: Writable;\n  private readonly defaultSources?: IQuerySourceUnidentifiedExpanded[];\n  private readonly customContext?: Partial<QueryStringContext>;\n  private queryId = 0;\n\n  public constructor(\n    private readonly mode: 'stdio' | 'http',\n    private readonly port: number,\n    private readonly queryEngine: QueryEngineBase,\n    version: string,\n    stderr: Writable,\n    defaultSources?: string[],\n    customContext?: Partial<QueryStringContext>,\n    additionalSourcesDescription?: string,\n  ) {\n    this.stderr = stderr;\n    this.server = new FastMCP({\n      name: 'sparql-mcp',\n      version: <any> version,\n    });\n\n    // Parse default sources if provided\n    if (defaultSources && defaultSources.length > 0) {\n      this.defaultSources = defaultSources.map(source => this.parseSourceString(source));\n    }\n\n    // Store custom context to be merged with query context\n    this.customContext = customContext;\n\n    this.registerTools(additionalSourcesDescription);\n  }\n\n  /**\n   * Start the MCP server in the configured mode (stdio or HTTP stream).\n   */\n  public async start(): Promise<void> {\n    if (this.mode === 'stdio') {\n      await this.server.start({\n        transportType: 'stdio',\n      });\n      this.stderr.write(`SPARQL MCP Server running in stdio mode\\n`);\n      if (this.defaultSources) {\n        this.stderr.write(`Default sources: ${this.defaultSources.map(s => s.value).join(', ')}\\n`);\n      }\n    } else {\n      await this.server.start({\n        transportType: 'httpStream',\n        httpStream: {\n          port: this.port,\n          stateless: true,\n        },\n      });\n      this.stderr.write(`SPARQL MCP Server listening on port ${this.port}\\n`);\n      if (this.defaultSources) {\n        this.stderr.write(`Default sources: ${this.defaultSources.map(s => s.value).join(', ')}\\n`);\n      }\n    }\n  }\n\n  /**\n   * Parse a source string that may contain a type prefix (e.g., 'sparql@https://example.org/sparql').\n   * This follows the same syntax as the Comunica CLI for forcing source types.\n   * @param sourceString A source URL that may be prefixed with a type annotation.\n   * @returns An object with 'value' and optionally 'type' properties.\n   */\n  protected parseSourceString(sourceString: string): IQuerySourceUnidentifiedExpanded {\n    const source: IQuerySourceUnidentifiedExpanded = { value: '' };\n    const typeRegex = /^([^:]*)@/u;\n    const typeMatches = typeRegex.exec(sourceString);\n    if (typeMatches) {\n      source.type = typeMatches[1];\n      sourceString = sourceString.slice((source.type.length) + 1);\n    }\n    source.value = sourceString;\n    return source;\n  }\n\n  /**\n   * Build a query context from optional parameters.\n   * @param options Optional parameters for the query context\n   * @param options.queryFormatLanguage The query language (e.g., 'sparql')\n   * @param options.queryFormatVersion The query language version (e.g., '1.1')\n   * @param options.baseIRI Base IRI for resolving relative IRIs\n   * @param options.httpProxy HTTP proxy URL\n   * @param options.httpAuth HTTP basic authentication credentials\n   * @param options.httpTimeout HTTP request timeout in milliseconds\n   * @param options.httpRetryCount Number of HTTP request retries\n   * @returns A partial query context object\n   */\n  protected buildQueryContext(options: {\n    queryFormatLanguage?: string;\n    queryFormatVersion?: string;\n    baseIRI?: string;\n    httpProxy?: string;\n    httpAuth?: string;\n    httpTimeout?: number;\n    httpRetryCount?: number;\n  }): Partial<QueryStringContext> {\n    const context: Partial<QueryStringContext> = {};\n\n    if (options.queryFormatLanguage !== undefined || options.queryFormatVersion !== undefined) {\n      context.queryFormat = {\n        language: options.queryFormatLanguage ?? 'sparql',\n        version: options.queryFormatVersion ?? '1.1',\n      };\n    }\n    if (options.baseIRI) {\n      context.baseIRI = options.baseIRI;\n    }\n    if (options.httpProxy) {\n      const proxyUrl = options.httpProxy;\n      context.httpProxyHandler = {\n        getProxy: async(request): Promise<any> => ({\n          input: proxyUrl,\n          init: request.init,\n        }),\n      };\n    }\n    if (options.httpAuth) {\n      context.httpAuth = options.httpAuth;\n    }\n    if (options.httpTimeout !== undefined) {\n      context.httpTimeout = options.httpTimeout;\n    }\n    if (options.httpRetryCount !== undefined) {\n      context.httpRetryCount = options.httpRetryCount;\n    }\n\n    return context;\n  }\n\n  protected registerTools(additionalSourcesDescription?: string): void {\n    // Common query format parameters shared between tools\n    const queryFormatParams = {\n      queryFormatLanguage: z.string().optional()\n        .describe(\n          'Query language (e.g., sparql, graphql). ' +\n          'Allows you to specify alternative query languages supported by Comunica',\n        ),\n      queryFormatVersion: z.string().optional()\n        .describe(\n          'Query language version (e.g., 1.0, 1.1, 1.2). ' +\n          'Specifies the version of the query language to use',\n        ),\n    };\n\n    // Build description for query_sparql tool\n    let querySparqlDescription = `Execute a SPARQL query over one or more sources. When sending a SELECT query, results are serialized as 'application/sparql-results+json', CONSTRUCT and DESCRIBE results are in 'application/trig', and ASK queries return true or false. Update queries (INSERT/DELETE) can also be passed, which in most cases will only work on private Knowledge Graphs or by passing authentication.`;\n\n    if (this.defaultSources) {\n      // If default sources are provided, mention them in the description\n      const sourceList = this.defaultSources.map(s => s.value).join(', ');\n      querySparqlDescription += ` Default sources: ${sourceList}`;\n    }\n\n    // Build parameters for query_sparql tool\n    const querySparqlParams: any = {\n      query: z.string().describe('SPARQL query string'),\n    };\n\n    // Only add sources parameter if no default sources are provided\n    if (!this.defaultSources) {\n      querySparqlParams.sources = z.array(z.string()).describe(`List of SPARQL endpoint URLs, TPF interface URLs, or Linked Data (RDF) file paths. You can optionally force a source type by prefixing the URL with a type annotation (e.g., 'sparql@https://example.org/sparql', 'file@/path/to/file.ttl', 'hypermedia@https://example.org/'). This is useful when the source type is already known to avoid auto-detection overhead.${additionalSourcesDescription ?? ''}`);\n    }\n\n    // Add common parameters\n    Object.assign(querySparqlParams, {\n      ...queryFormatParams,\n      baseIRI: z.string().optional().describe('Base IRI for resolving relative IRIs in the query'),\n      httpProxy: z.string().optional().describe('HTTP proxy URL (e.g., http://proxy.example.com:8080)'),\n      httpAuth: z.string().optional().describe('HTTP basic authentication in the format username:password'),\n      httpTimeout: z.number().optional().describe('HTTP request timeout in milliseconds'),\n      httpRetryCount: z.number().optional().describe('Number of HTTP request retries on failure'),\n    });\n\n    this.server.addTool({\n      name: 'query_sparql',\n      description: querySparqlDescription,\n      parameters: z.object(querySparqlParams),\n      annotations: {\n        // Signals this tool uses streaming\n        streamingHint: true,\n        readOnlyHint: true,\n      },\n      // Type assertion is needed because we dynamically construct the parameters object\n      // based on whether default sources are provided. The runtime behavior is type-safe.\n      execute: (args, context) => this.executeQuerySparql(<any>args, context),\n    });\n\n    this.server.addTool({\n      name: 'query_sparql_rdf',\n      description: `Execute a SPARQL query over a serialized RDF dataset provided as a string. This is useful for querying RDF data that is already available as a string (e.g., Turtle, N-Triples, etc.). When sending a SELECT query, results are serialized as 'application/sparql-results+json', CONSTRUCT and DESCRIBE results are in 'application/trig', and ASK queries return true or false.`,\n      parameters: z.object({\n        query: z.string().describe('SPARQL query string'),\n        value: z.string().describe('Serialized RDF dataset as a string'),\n        mediaType: z.string().describe(`Media type of the serialized RDF dataset (e.g., 'text/turtle', 'application/n-triples', 'application/ld+json', 'application/rdf+xml', 'application/n-quads', 'application/trig')`),\n        fileBaseIRI: z.string().optional().describe('Base IRI for resolving relative IRIs in the RDF dataset'),\n        baseIRI: z.string().optional().describe('Base IRI for resolving relative IRIs in the query'),\n        ...queryFormatParams,\n      }),\n      annotations: {\n        // Signals this tool uses streaming\n        streamingHint: true,\n        readOnlyHint: true,\n      },\n      execute: (args, context) => this.executeQuerySparqlRdf(args, context),\n    });\n  }\n\n  /**\n   * Execute a SPARQL query and stream the results back to the client.\n   * This method contains the common logic for executing queries and handling results.\n   * @param query The SPARQL query string\n   * @param sources Array of query sources\n   * @param queryId The query ID for logging\n   * @param context The MCP context for streaming results\n   * @param queryContext Optional query context parameters\n   * @returns The query results as a string or an error object\n   */\n  protected async executeQuery(\n    query: string,\n    sources: IQuerySourceUnidentifiedExpanded[],\n    queryId: number,\n    context: Context<FastMCPSessionAuth>,\n    queryContext: Partial<QueryStringContext> = {},\n  ): Promise<any> {\n    await context.streamContent({ type: 'text', text: `Streaming SPARQL query results hereafter:` });\n\n    try {\n      const promises: Promise<any>[] = [];\n      const chunks: string[] = [];\n      // Merge custom context with provided query context\n      const mergedContext = { sources, ...this.customContext, ...queryContext };\n      const queryResult = await this.queryEngine.query(query, mergedContext);\n      const { data } = await this.queryEngine.resultToString(queryResult);\n      data.on('data', (chunk: string) => {\n        chunks.push(chunk);\n        promises.push(context.streamContent({ type: 'text', text: chunk.toString() }));\n      });\n      await new Promise((resolve, reject) => {\n        data.on('error', reject);\n        data.on('end', resolve);\n      });\n      await Promise.all(promises);\n\n      // Log successful completion\n      this.stderr.write(`[Query ${queryId}] Successfully completed\\n`);\n\n      return chunks.join('');\n    } catch (error: any) {\n      // Log query failure\n      this.stderr.write(`[Query ${queryId}] Failed: ${error.stack}\\n`);\n\n      return {\n        isError: true,\n        content: [\n          {\n            type: 'text',\n            text: `Query failed: ${error.message}`,\n          },\n        ],\n      };\n    }\n  }\n\n  protected async executeQuerySparql(\n    args: {\n      query: string;\n      sources?: string[];\n      queryFormatLanguage?: string;\n      queryFormatVersion?: string;\n      baseIRI?: string;\n      httpProxy?: string;\n      httpAuth?: string;\n      httpTimeout?: number;\n      httpRetryCount?: number;\n    },\n    context: Context<FastMCPSessionAuth>,\n  ): Promise<any> {\n    const currentQueryId = this.queryId++;\n\n    // Use default sources if provided, otherwise use sources from args\n    let parsedSources: IQuerySourceUnidentifiedExpanded[];\n    if (this.defaultSources) {\n      parsedSources = this.defaultSources;\n    } else if (args.sources) {\n      parsedSources = args.sources.map(sourceString => this.parseSourceString(sourceString));\n    } else {\n      throw new Error('No sources provided and no default sources configured');\n    }\n\n    // Build query context from optional parameters\n    const queryContext = this.buildQueryContext(args);\n\n    // Log query start\n    this.stderr.write(`[Query ${currentQueryId}] Starting SPARQL query\\n`);\n    this.stderr.write(`[Query ${currentQueryId}] Sources: ${parsedSources.map(s => s.value).join(', ')}\\n`);\n    this.stderr.write(`[Query ${currentQueryId}] Query: ${args.query}\\n`);\n\n    return this.executeQuery(args.query, parsedSources, currentQueryId, context, queryContext);\n  }\n\n  protected async executeQuerySparqlRdf(\n    args: {\n      query: string;\n      value: string;\n      mediaType: string;\n      fileBaseIRI?: string;\n      baseIRI?: string;\n      queryFormatLanguage?: string;\n      queryFormatVersion?: string;\n    },\n    context: Context<FastMCPSessionAuth>,\n  ): Promise<any> {\n    const currentQueryId = this.queryId++;\n\n    // Create a serialized source\n    const source: IQuerySourceSerialized = {\n      type: 'serialized',\n      value: args.value,\n      mediaType: args.mediaType,\n      ...(args.fileBaseIRI && { baseIRI: args.fileBaseIRI }),\n    };\n\n    // Build query context from optional parameters\n    const queryContext = this.buildQueryContext(args);\n\n    // Log query start\n    this.stderr.write(`[Query ${currentQueryId}] Starting SPARQL query on serialized RDF (media type: ${args.mediaType})\\n`);\n    this.stderr.write(`[Query ${currentQueryId}] Query: ${args.query}\\n`);\n\n    return this.executeQuery(args.query, [ source ], currentQueryId, context, queryContext);\n  }\n}\n"]}
+{"version":3,"file":"SparqlMcpServer.js","sourceRoot":"","sources":["SparqlMcpServer.ts"],"names":[],"mappings":";;;AAKA,qCAAkC;AAClC,6BAAwB;AAgBxB;;GAEG;AACH,MAAa,eAAe;IAQP;IACA;IACA;IAMA;IAfF,MAAM,CAAU;IAChB,MAAM,CAAW;IACjB,cAAc,CAAsC;IACpD,aAAa,CAA+B;IACrD,OAAO,GAAG,CAAC,CAAC;IAEpB,YACmB,IAAsB,EACtB,IAAY,EACZ,WAA4B,EAC7C,OAAe,EACf,MAAgB,EAChB,cAAyB,EACzB,aAA2C,EAC3C,4BAAqC,EACpB,UAAmC,EAAE;QARrC,SAAI,GAAJ,IAAI,CAAkB;QACtB,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAiB;QAM5B,YAAO,GAAP,OAAO,CAA8B;QAEtD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,iBAAO,CAAC;YACxB,IAAI,EAAE,YAAY;YAClB,OAAO,EAAQ,OAAO;SACvB,CAAC,CAAC;QAEH,oCAAoC;QACpC,IAAI,cAAc,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;QACrF,CAAC;QAED,uDAAuD;QACvD,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QAEnC,IAAI,CAAC,aAAa,CAAC,4BAA4B,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,KAAK;QAChB,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC1B,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;gBACtB,aAAa,EAAE,OAAO;aACvB,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC/D,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;gBACtB,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAE;oBACV,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,SAAS,EAAE,IAAI;iBAChB;aACF,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;YACxE,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACO,iBAAiB,CAAC,YAAoB;QAC9C,MAAM,MAAM,GAAqC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC/D,MAAM,SAAS,GAAG,YAAY,CAAC;QAC/B,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACjD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;YAC7B,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,CAAC,KAAK,GAAG,YAAY,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;OAWG;IACO,iBAAiB,CAAC,OAQ3B;QACC,MAAM,OAAO,GAAgC,EAAE,CAAC;QAEhD,IAAI,OAAO,CAAC,mBAAmB,KAAK,SAAS,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YAC1F,OAAO,CAAC,WAAW,GAAG;gBACpB,QAAQ,EAAE,OAAO,CAAC,mBAAmB,IAAI,QAAQ;gBACjD,OAAO,EAAE,OAAO,CAAC,kBAAkB,IAAI,KAAK;aAC7C,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACpC,CAAC;QACD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;YACnC,OAAO,CAAC,gBAAgB,GAAG;gBACzB,QAAQ,EAAE,KAAK,EAAC,OAAO,EAAgB,EAAE,CAAC,CAAC;oBACzC,KAAK,EAAE,QAAQ;oBACf,IAAI,EAAE,OAAO,CAAC,IAAI;iBACnB,CAAC;aACH,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACtC,CAAC;QACD,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QAC5C,CAAC;QACD,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACzC,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAClD,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAES,aAAa,CAAC,4BAAqC;QAC3D,sDAAsD;QACtD,MAAM,iBAAiB,GAAG;YACxB,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;iBACvC,QAAQ,CACP,0CAA0C;gBAC1C,yEAAyE,CAC1E;YACH,kBAAkB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;iBACtC,QAAQ,CACP,gDAAgD;gBAChD,oDAAoD,CACrD;SACJ,CAAC;QAEF,0CAA0C;QAC1C,IAAI,sBAAsB,GAAG,4XAA4X,CAAC;QAE1Z,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,mEAAmE;YACnE,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpE,sBAAsB,IAAI,qBAAqB,UAAU,EAAE,CAAC;QAC9D,CAAC;QAED,yCAAyC;QACzC,MAAM,iBAAiB,GAAQ;YAC7B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;SAClD,CAAC;QAEF,gEAAgE;QAChE,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,iBAAiB,CAAC,OAAO,GAAG,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,yWAAyW,4BAA4B,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1c,CAAC;QAED,wBAAwB;QACxB,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE;YAC/B,GAAG,iBAAiB;YACpB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;YAC5F,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;YACjG,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2DAA2D,CAAC;YACrG,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;YACnF,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;SAC5F,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAClB,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,sBAAsB;YACnC,UAAU,EAAE,OAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;YACvC,WAAW,EAAE;gBACX,mCAAmC;gBACnC,aAAa,EAAE,IAAI;gBACnB,YAAY,EAAE,IAAI;aACnB;YACD,kFAAkF;YAClF,oFAAoF;YACpF,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAM,IAAI,EAAE,OAAO,CAAC;SACxE,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAClB,IAAI,EAAE,kBAAkB;YACxB,WAAW,EAAE,kXAAkX;YAC/X,UAAU,EAAE,OAAC,CAAC,MAAM,CAAC;gBACnB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;gBACjD,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;gBAChE,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kLAAkL,CAAC;gBAClN,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;gBACtG,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;gBAC5F,GAAG,iBAAiB;aACrB,CAAC;YACF,WAAW,EAAE;gBACX,mCAAmC;gBACnC,aAAa,EAAE,IAAI;gBACnB,YAAY,EAAE,IAAI;aACnB;YACD,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC;SACtE,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACO,KAAK,CAAC,gBAAgB,CAAI,OAAmB,EAAE,OAAe;QACtE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC;QACpD,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,IAAI,KAAiC,CAAC;QACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,qBAAqB,YAAY,MAAM,CAAC,CAAC;gBAC5E,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,YAAY;;6CAEjB,CAAC,CAAC,CAAC;gBACxC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;YAClC,CAAC,EAAE,YAAY,CAAC,CAAC;QACnB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAE,OAAO,EAAE,OAAO,CAAE,CAAC,CAAC;QAClD,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACO,KAAK,CAAC,YAAY,CAC1B,KAAa,EACb,OAA2C,EAC3C,OAAe,EACf,OAAoC,EACpC,eAA4C,EAAE;QAE9C,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,2CAA2C,EAAE,CAAC,CAAC;QAEjG,kFAAkF;QAClF,IAAI,YAAkC,CAAC;QAEvC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,KAAK,IAAoB,EAAE;gBAC9C,MAAM,QAAQ,GAAmB,EAAE,CAAC;gBACpC,MAAM,MAAM,GAAa,EAAE,CAAC;gBAC5B,mDAAmD;gBACnD,MAAM,aAAa,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,YAAY,EAAE,CAAC;gBAC1E,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;gBACvE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;gBACpE,YAAY,GAAc,IAAI,CAAC;gBAC/B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;oBAChC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACnB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;gBACjF,CAAC,CAAC,CAAC;gBACH,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;oBACpC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBACzB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAC1B,CAAC,CAAC,CAAC;gBACH,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAE5B,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzB,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;YAErE,4BAA4B;YAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,4BAA4B,CAAC,CAAC;YAEjE,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,uEAAuE;YACvE,YAAY,EAAE,OAAO,EAAE,CAAC;YAExB,oBAAoB;YACpB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,aAAa,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;YAEjE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,iBAAiB,KAAK,CAAC,OAAO,EAAE;qBACvC;iBACF;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IAES,KAAK,CAAC,kBAAkB,CAChC,IAUC,EACD,OAAoC;QAEpC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAEtC,mEAAmE;QACnE,IAAI,aAAiD,CAAC;QACtD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC;QACtC,CAAC;aAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxB,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC;QACzF,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QAED,+CAA+C;QAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAElD,kBAAkB;QAClB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,cAAc,2BAA2B,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,cAAc,cAAc,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,cAAc,YAAY,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAEtE,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC7F,CAAC;IAES,KAAK,CAAC,qBAAqB,CACnC,IAQC,EACD,OAAoC;QAEpC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAEtC,6BAA6B;QAC7B,MAAM,MAAM,GAA2B;YACrC,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;SACvD,CAAC;QAEF,+CAA+C;QAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAElD,kBAAkB;QAClB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,cAAc,0DAA0D,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC;QACzH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,cAAc,YAAY,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAEtE,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,CAAE,MAAM,CAAE,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC1F,CAAC;CACF;AA9XD,0CA8XC","sourcesContent":["/* eslint-disable import/no-nodejs-modules */\nimport type { Readable, Writable } from 'node:stream';\nimport type { QueryEngineBase } from '@comunica/actor-init-query';\nimport type { IQuerySourceSerialized, IQuerySourceUnidentifiedExpanded, QueryStringContext } from '@comunica/types';\nimport type { Context, FastMCPSessionAuth } from 'fastmcp';\nimport { FastMCP } from 'fastmcp';\nimport { z } from 'zod';\n\nexport interface ISparqlMcpServerOptions {\n  /**\n   * The maximum time in milliseconds a query may take before it is aborted. A value of 0 disables the timeout.\n   *\n   * Note that Comunica offers no way to abort a running query,\n   * so timed out queries keep consuming resources in the background until the process is replaced.\n   */\n  queryTimeout?: number;\n  /**\n   * Invoked when a query exceeded {@link ISparqlMcpServerOptions.queryTimeout}.\n   */\n  onQueryTimeout?: () => void;\n}\n\n/**\n * An MCP server for querying over one or more Knowledge Graphs using SPARQL queries.\n */\nexport class SparqlMcpServer {\n  private readonly server: FastMCP;\n  private readonly stderr: Writable;\n  private readonly defaultSources?: IQuerySourceUnidentifiedExpanded[];\n  private readonly customContext?: Partial<QueryStringContext>;\n  private queryId = 0;\n\n  public constructor(\n    private readonly mode: 'stdio' | 'http',\n    private readonly port: number,\n    private readonly queryEngine: QueryEngineBase,\n    version: string,\n    stderr: Writable,\n    defaultSources?: string[],\n    customContext?: Partial<QueryStringContext>,\n    additionalSourcesDescription?: string,\n    private readonly options: ISparqlMcpServerOptions = {},\n  ) {\n    this.stderr = stderr;\n    this.server = new FastMCP({\n      name: 'sparql-mcp',\n      version: <any> version,\n    });\n\n    // Parse default sources if provided\n    if (defaultSources && defaultSources.length > 0) {\n      this.defaultSources = defaultSources.map(source => this.parseSourceString(source));\n    }\n\n    // Store custom context to be merged with query context\n    this.customContext = customContext;\n\n    this.registerTools(additionalSourcesDescription);\n  }\n\n  /**\n   * Start the MCP server in the configured mode (stdio or HTTP stream).\n   */\n  public async start(): Promise<void> {\n    if (this.mode === 'stdio') {\n      await this.server.start({\n        transportType: 'stdio',\n      });\n      this.stderr.write(`SPARQL MCP Server running in stdio mode\\n`);\n      if (this.defaultSources) {\n        this.stderr.write(`Default sources: ${this.defaultSources.map(s => s.value).join(', ')}\\n`);\n      }\n    } else {\n      await this.server.start({\n        transportType: 'httpStream',\n        httpStream: {\n          port: this.port,\n          stateless: true,\n        },\n      });\n      this.stderr.write(`SPARQL MCP Server listening on port ${this.port}\\n`);\n      if (this.defaultSources) {\n        this.stderr.write(`Default sources: ${this.defaultSources.map(s => s.value).join(', ')}\\n`);\n      }\n    }\n  }\n\n  /**\n   * Parse a source string that may contain a type prefix (e.g., 'sparql@https://example.org/sparql').\n   * This follows the same syntax as the Comunica CLI for forcing source types.\n   * @param sourceString A source URL that may be prefixed with a type annotation.\n   * @returns An object with 'value' and optionally 'type' properties.\n   */\n  protected parseSourceString(sourceString: string): IQuerySourceUnidentifiedExpanded {\n    const source: IQuerySourceUnidentifiedExpanded = { value: '' };\n    const typeRegex = /^([^:]*)@/u;\n    const typeMatches = typeRegex.exec(sourceString);\n    if (typeMatches) {\n      source.type = typeMatches[1];\n      sourceString = sourceString.slice((source.type.length) + 1);\n    }\n    source.value = sourceString;\n    return source;\n  }\n\n  /**\n   * Build a query context from optional parameters.\n   * @param options Optional parameters for the query context\n   * @param options.queryFormatLanguage The query language (e.g., 'sparql')\n   * @param options.queryFormatVersion The query language version (e.g., '1.1')\n   * @param options.baseIRI Base IRI for resolving relative IRIs\n   * @param options.httpProxy HTTP proxy URL\n   * @param options.httpAuth HTTP basic authentication credentials\n   * @param options.httpTimeout HTTP request timeout in milliseconds\n   * @param options.httpRetryCount Number of HTTP request retries\n   * @returns A partial query context object\n   */\n  protected buildQueryContext(options: {\n    queryFormatLanguage?: string;\n    queryFormatVersion?: string;\n    baseIRI?: string;\n    httpProxy?: string;\n    httpAuth?: string;\n    httpTimeout?: number;\n    httpRetryCount?: number;\n  }): Partial<QueryStringContext> {\n    const context: Partial<QueryStringContext> = {};\n\n    if (options.queryFormatLanguage !== undefined || options.queryFormatVersion !== undefined) {\n      context.queryFormat = {\n        language: options.queryFormatLanguage ?? 'sparql',\n        version: options.queryFormatVersion ?? '1.1',\n      };\n    }\n    if (options.baseIRI) {\n      context.baseIRI = options.baseIRI;\n    }\n    if (options.httpProxy) {\n      const proxyUrl = options.httpProxy;\n      context.httpProxyHandler = {\n        getProxy: async(request): Promise<any> => ({\n          input: proxyUrl,\n          init: request.init,\n        }),\n      };\n    }\n    if (options.httpAuth) {\n      context.httpAuth = options.httpAuth;\n    }\n    if (options.httpTimeout !== undefined) {\n      context.httpTimeout = options.httpTimeout;\n    }\n    if (options.httpRetryCount !== undefined) {\n      context.httpRetryCount = options.httpRetryCount;\n    }\n\n    return context;\n  }\n\n  protected registerTools(additionalSourcesDescription?: string): void {\n    // Common query format parameters shared between tools\n    const queryFormatParams = {\n      queryFormatLanguage: z.string().optional()\n        .describe(\n          'Query language (e.g., sparql, graphql). ' +\n          'Allows you to specify alternative query languages supported by Comunica',\n        ),\n      queryFormatVersion: z.string().optional()\n        .describe(\n          'Query language version (e.g., 1.0, 1.1, 1.2). ' +\n          'Specifies the version of the query language to use',\n        ),\n    };\n\n    // Build description for query_sparql tool\n    let querySparqlDescription = `Execute a SPARQL query over one or more sources. When sending a SELECT query, results are serialized as 'application/sparql-results+json', CONSTRUCT and DESCRIBE results are in 'application/trig', and ASK queries return true or false. Update queries (INSERT/DELETE) can also be passed, which in most cases will only work on private Knowledge Graphs or by passing authentication.`;\n\n    if (this.defaultSources) {\n      // If default sources are provided, mention them in the description\n      const sourceList = this.defaultSources.map(s => s.value).join(', ');\n      querySparqlDescription += ` Default sources: ${sourceList}`;\n    }\n\n    // Build parameters for query_sparql tool\n    const querySparqlParams: any = {\n      query: z.string().describe('SPARQL query string'),\n    };\n\n    // Only add sources parameter if no default sources are provided\n    if (!this.defaultSources) {\n      querySparqlParams.sources = z.array(z.string()).describe(`List of SPARQL endpoint URLs, TPF interface URLs, or Linked Data (RDF) file paths. You can optionally force a source type by prefixing the URL with a type annotation (e.g., 'sparql@https://example.org/sparql', 'file@/path/to/file.ttl', 'hypermedia@https://example.org/'). This is useful when the source type is already known to avoid auto-detection overhead.${additionalSourcesDescription ?? ''}`);\n    }\n\n    // Add common parameters\n    Object.assign(querySparqlParams, {\n      ...queryFormatParams,\n      baseIRI: z.string().optional().describe('Base IRI for resolving relative IRIs in the query'),\n      httpProxy: z.string().optional().describe('HTTP proxy URL (e.g., http://proxy.example.com:8080)'),\n      httpAuth: z.string().optional().describe('HTTP basic authentication in the format username:password'),\n      httpTimeout: z.number().optional().describe('HTTP request timeout in milliseconds'),\n      httpRetryCount: z.number().optional().describe('Number of HTTP request retries on failure'),\n    });\n\n    this.server.addTool({\n      name: 'query_sparql',\n      description: querySparqlDescription,\n      parameters: z.object(querySparqlParams),\n      annotations: {\n        // Signals this tool uses streaming\n        streamingHint: true,\n        readOnlyHint: true,\n      },\n      // Type assertion is needed because we dynamically construct the parameters object\n      // based on whether default sources are provided. The runtime behavior is type-safe.\n      execute: (args, context) => this.executeQuerySparql(<any>args, context),\n    });\n\n    this.server.addTool({\n      name: 'query_sparql_rdf',\n      description: `Execute a SPARQL query over a serialized RDF dataset provided as a string. This is useful for querying RDF data that is already available as a string (e.g., Turtle, N-Triples, etc.). When sending a SELECT query, results are serialized as 'application/sparql-results+json', CONSTRUCT and DESCRIBE results are in 'application/trig', and ASK queries return true or false.`,\n      parameters: z.object({\n        query: z.string().describe('SPARQL query string'),\n        value: z.string().describe('Serialized RDF dataset as a string'),\n        mediaType: z.string().describe(`Media type of the serialized RDF dataset (e.g., 'text/turtle', 'application/n-triples', 'application/ld+json', 'application/rdf+xml', 'application/n-quads', 'application/trig')`),\n        fileBaseIRI: z.string().optional().describe('Base IRI for resolving relative IRIs in the RDF dataset'),\n        baseIRI: z.string().optional().describe('Base IRI for resolving relative IRIs in the query'),\n        ...queryFormatParams,\n      }),\n      annotations: {\n        // Signals this tool uses streaming\n        streamingHint: true,\n        readOnlyHint: true,\n      },\n      execute: (args, context) => this.executeQuerySparqlRdf(args, context),\n    });\n  }\n\n  /**\n   * Reject the given promise if it does not settle within the configured query timeout.\n   *\n   * Note that this can only interrupt queries that leave the event loop free.\n   * Queries that block the event loop are handled by the primary process,\n   * which kills and restarts unresponsive workers.\n   * @param promise The promise wrapping the query execution.\n   * @param queryId The query ID for logging.\n   * @returns The value of the given promise.\n   */\n  protected async withQueryTimeout<T>(promise: Promise<T>, queryId: number): Promise<T> {\n    const queryTimeout = this.options.queryTimeout ?? 0;\n    if (queryTimeout <= 0) {\n      return promise;\n    }\n\n    let timer: NodeJS.Timeout | undefined;\n    const timeout = new Promise<never>((resolve, reject) => {\n      timer = setTimeout(() => {\n        this.stderr.write(`[Query ${queryId}] Timed out after ${queryTimeout}ms\\n`);\n        reject(new Error(`Query timed out after ${queryTimeout}ms. \\\nConsider making the query more selective, restricting it to fewer sources, \\\nor increasing the timeout of the MCP server.`));\n        this.options.onQueryTimeout?.();\n      }, queryTimeout);\n    });\n\n    try {\n      return await Promise.race([ promise, timeout ]);\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  /**\n   * Execute a SPARQL query and stream the results back to the client.\n   * This method contains the common logic for executing queries and handling results.\n   * @param query The SPARQL query string\n   * @param sources Array of query sources\n   * @param queryId The query ID for logging\n   * @param context The MCP context for streaming results\n   * @param queryContext Optional query context parameters\n   * @returns The query results as a string or an error object\n   */\n  protected async executeQuery(\n    query: string,\n    sources: IQuerySourceUnidentifiedExpanded[],\n    queryId: number,\n    context: Context<FastMCPSessionAuth>,\n    queryContext: Partial<QueryStringContext> = {},\n  ): Promise<any> {\n    await context.streamContent({ type: 'text', text: `Streaming SPARQL query results hereafter:` });\n\n    // Kept outside of the query execution, so that a timed out query can be cancelled\n    let resultStream: Readable | undefined;\n\n    try {\n      const executeInner = async(): Promise<string> => {\n        const promises: Promise<any>[] = [];\n        const chunks: string[] = [];\n        // Merge custom context with provided query context\n        const mergedContext = { sources, ...this.customContext, ...queryContext };\n        const queryResult = await this.queryEngine.query(query, mergedContext);\n        const { data } = await this.queryEngine.resultToString(queryResult);\n        resultStream = <Readable> data;\n        data.on('data', (chunk: string) => {\n          chunks.push(chunk);\n          promises.push(context.streamContent({ type: 'text', text: chunk.toString() }));\n        });\n        await new Promise((resolve, reject) => {\n          data.on('error', reject);\n          data.on('end', resolve);\n        });\n        await Promise.all(promises);\n\n        return chunks.join('');\n      };\n      const results = await this.withQueryTimeout(executeInner(), queryId);\n\n      // Log successful completion\n      this.stderr.write(`[Query ${queryId}] Successfully completed\\n`);\n\n      return results;\n    } catch (error: any) {\n      // Make sure that a timed out or failed query stops consuming resources\n      resultStream?.destroy();\n\n      // Log query failure\n      this.stderr.write(`[Query ${queryId}] Failed: ${error.stack}\\n`);\n\n      return {\n        isError: true,\n        content: [\n          {\n            type: 'text',\n            text: `Query failed: ${error.message}`,\n          },\n        ],\n      };\n    }\n  }\n\n  protected async executeQuerySparql(\n    args: {\n      query: string;\n      sources?: string[];\n      queryFormatLanguage?: string;\n      queryFormatVersion?: string;\n      baseIRI?: string;\n      httpProxy?: string;\n      httpAuth?: string;\n      httpTimeout?: number;\n      httpRetryCount?: number;\n    },\n    context: Context<FastMCPSessionAuth>,\n  ): Promise<any> {\n    const currentQueryId = this.queryId++;\n\n    // Use default sources if provided, otherwise use sources from args\n    let parsedSources: IQuerySourceUnidentifiedExpanded[];\n    if (this.defaultSources) {\n      parsedSources = this.defaultSources;\n    } else if (args.sources) {\n      parsedSources = args.sources.map(sourceString => this.parseSourceString(sourceString));\n    } else {\n      throw new Error('No sources provided and no default sources configured');\n    }\n\n    // Build query context from optional parameters\n    const queryContext = this.buildQueryContext(args);\n\n    // Log query start\n    this.stderr.write(`[Query ${currentQueryId}] Starting SPARQL query\\n`);\n    this.stderr.write(`[Query ${currentQueryId}] Sources: ${parsedSources.map(s => s.value).join(', ')}\\n`);\n    this.stderr.write(`[Query ${currentQueryId}] Query: ${args.query}\\n`);\n\n    return this.executeQuery(args.query, parsedSources, currentQueryId, context, queryContext);\n  }\n\n  protected async executeQuerySparqlRdf(\n    args: {\n      query: string;\n      value: string;\n      mediaType: string;\n      fileBaseIRI?: string;\n      baseIRI?: string;\n      queryFormatLanguage?: string;\n      queryFormatVersion?: string;\n    },\n    context: Context<FastMCPSessionAuth>,\n  ): Promise<any> {\n    const currentQueryId = this.queryId++;\n\n    // Create a serialized source\n    const source: IQuerySourceSerialized = {\n      type: 'serialized',\n      value: args.value,\n      mediaType: args.mediaType,\n      ...(args.fileBaseIRI && { baseIRI: args.fileBaseIRI }),\n    };\n\n    // Build query context from optional parameters\n    const queryContext = this.buildQueryContext(args);\n\n    // Log query start\n    this.stderr.write(`[Query ${currentQueryId}] Starting SPARQL query on serialized RDF (media type: ${args.mediaType})\\n`);\n    this.stderr.write(`[Query ${currentQueryId}] Query: ${args.query}\\n`);\n\n    return this.executeQuery(args.query, [ source ], currentQueryId, context, queryContext);\n  }\n}\n"]}

package/lib/WorkerPool.d.ts

@@ -0,0 +1,142 @@
+import type { Cluster, Worker } from 'node:cluster';
+import type { Writable } from 'node:stream';
+/**
+ * The message workers periodically send to the primary process to indicate that their event loop is responsive.
+ */
+export declare const MESSAGE_HEARTBEAT = "comunica-mcp:heartbeat";
+/**
+ * The message workers send to the primary process to ask to be replaced by a fresh worker.
+ */
+export declare const MESSAGE_RECYCLE = "comunica-mcp:recycle";
+/**
+ * The interval in milliseconds at which workers send a heartbeat to the primary process.
+ */
+export declare const HEARTBEAT_INTERVAL = 1000;
+/**
+ * The lower bound in milliseconds on the time a worker may block its event loop before it is considered stuck.
+ * Workers are never killed faster than this, so that slow startups are not mistaken for hangs.
+ */
+export declare const MIN_UNRESPONSIVE_TIMEOUT = 30000;
+export interface IWorkerPoolArgs {
+    /**
+     * The number of workers that must be kept alive at all times.
+     */
+    workers: number;
+    /**
+     * The time in milliseconds a worker may block its event loop before it is killed and restarted.
+     * A value of 0 disables this watchdog.
+     */
+    unresponsiveTimeout: number;
+    /**
+     * The stream to write log messages to.
+     */
+    stderr: Writable;
+    /**
+     * The cluster instance to manage workers with. Defaults to the Node.js cluster module.
+     */
+    cluster?: Cluster;
+    /**
+     * The interval in milliseconds at which worker liveness is checked. Defaults to {@link HEARTBEAT_INTERVAL}.
+     */
+    checkInterval?: number;
+    /**
+     * The time in milliseconds a worker must stay alive before its startup is considered successful.
+     */
+    healthyUptime?: number;
+    /**
+     * The number of consecutive failed startups after which the primary process gives up.
+     */
+    maxRapidRestarts?: number;
+    /**
+     * The time in milliseconds workers are given to shut down gracefully before they are killed.
+     */
+    shutdownGrace?: number;
+    /**
+     * Invoked when the primary process must terminate with the given exit code.
+     */
+    exit?: (code: number) => void;
+}
+/**
+ * Maintains a pool of worker processes that each run an MCP server, and replaces them when needed.
+ *
+ * Workers are needed because SPARQL queries can not always be cancelled from within the process that runs them:
+ * * Queries that block the event loop make any timeout inside that worker unable to fire in the first place.
+ *   Such workers stop sending {@link MESSAGE_HEARTBEAT} messages, upon which they are killed and replaced.
+ * * Queries that did time out keep consuming CPU and memory in the background, as Comunica offers no way to
+ *   abort an ongoing query. Workers therefore ask to be replaced via {@link MESSAGE_RECYCLE} after a timeout,
+ *   which lets them finish their pending responses while a fresh worker takes over.
+ */
+export declare class WorkerPool {
+    private readonly workers;
+    private readonly unresponsiveTimeout;
+    private readonly stderr;
+    private readonly cluster;
+    private readonly checkInterval;
+    private readonly healthyUptime;
+    private readonly maxRapidRestarts;
+    private readonly shutdownGrace;
+    private readonly exit;
+    private readonly states;
+    private rapidRestarts;
+    private checkTimer;
+    private shuttingDown;
+    constructor(args: IWorkerPoolArgs);
+    /**
+     * Fork the configured number of workers, and start monitoring them.
+     */
+    start(): void;
+    /**
+     * Terminate all workers, and exit as soon as they are all gone.
+     * @param signal The signal to send to the workers.
+     */
+    stop(signal: NodeJS.Signals): void;
+    /**
+     * Get all workers that are currently registered within the cluster.
+     */
+    protected getWorkers(): Worker[];
+    /**
+     * Start a new worker process.
+     */
+    protected fork(): void;
+    /**
+     * Handle a message that was sent by a worker.
+     * @param worker The worker that sent the message.
+     * @param message The message that was sent.
+     */
+    protected onWorkerMessage(worker: Worker, message: unknown): void;
+    /**
+     * Replace a worker by a fresh one, and let the old worker finish its pending responses in the meantime.
+     * @param worker The worker to replace.
+     */
+    protected recycleWorker(worker: Worker): void;
+    /**
+     * Restart a worker that died, unless workers keep dying immediately after startup.
+     * @param worker The worker that died.
+     * @param code The exit code of the worker.
+     * @param signal The signal that terminated the worker.
+     */
+    protected onWorkerExit(worker: Worker, code: number, signal: string | null): void;
+    /**
+     * Kill all workers of which the event loop has been blocked for too long.
+     */
+    protected checkWorkers(): void;
+    /**
+     * Forcefully kill the given workers if they are still alive after the shutdown grace period.
+     * @param workers The workers to kill.
+     * @param callback An optional callback to invoke afterwards.
+     */
+    protected killLater(workers: Worker[], callback?: () => void): void;
+}
+/**
+ * Periodically inform the primary process that the event loop of this worker is not blocked.
+ * This is a no-op when the current process is not a cluster worker.
+ * @param interval The interval in milliseconds at which heartbeats are sent.
+ * @returns The heartbeat timer, or undefined if the current process is not a cluster worker.
+ */
+export declare function startHeartbeat(interval?: number): NodeJS.Timeout | undefined;
+/**
+ * Ask the primary process to replace this worker by a fresh one.
+ * This is a no-op when the current process is not a cluster worker.
+ * @returns If the request was sent.
+ */
+export declare function requestRecycle(): boolean;

package/lib/WorkerPool.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = exports.MIN_UNRESPONSIVE_TIMEOUT = exports.HEARTBEAT_INTERVAL = exports.MESSAGE_RECYCLE = exports.MESSAGE_HEARTBEAT = void 0;
+exports.startHeartbeat = startHeartbeat;
+exports.requestRecycle = requestRecycle;
+// The cluster module only has a default export, which can not be imported
+// as such within this CommonJS package, so it is required instead.
+// eslint-disable-next-line ts/no-require-imports,ts/no-var-requires
+const nodeCluster = require('node:cluster');
+/**
+ * The message workers periodically send to the primary process to indicate that their event loop is responsive.
+ */
+exports.MESSAGE_HEARTBEAT = 'comunica-mcp:heartbeat';
+/**
+ * The message workers send to the primary process to ask to be replaced by a fresh worker.
+ */
+exports.MESSAGE_RECYCLE = 'comunica-mcp:recycle';
+/**
+ * The interval in milliseconds at which workers send a heartbeat to the primary process.
+ */
+exports.HEARTBEAT_INTERVAL = 1_000;
+/**
+ * The lower bound in milliseconds on the time a worker may block its event loop before it is considered stuck.
+ * Workers are never killed faster than this, so that slow startups are not mistaken for hangs.
+ */
+exports.MIN_UNRESPONSIVE_TIMEOUT = 30_000;
+/**
+ * Maintains a pool of worker processes that each run an MCP server, and replaces them when needed.
+ *
+ * Workers are needed because SPARQL queries can not always be cancelled from within the process that runs them:
+ * * Queries that block the event loop make any timeout inside that worker unable to fire in the first place.
+ *   Such workers stop sending {@link MESSAGE_HEARTBEAT} messages, upon which they are killed and replaced.
+ * * Queries that did time out keep consuming CPU and memory in the background, as Comunica offers no way to
+ *   abort an ongoing query. Workers therefore ask to be replaced via {@link MESSAGE_RECYCLE} after a timeout,
+ *   which lets them finish their pending responses while a fresh worker takes over.
+ */
+class WorkerPool {
+    workers;
+    unresponsiveTimeout;
+    stderr;
+    cluster;
+    checkInterval;
+    healthyUptime;
+    maxRapidRestarts;
+    shutdownGrace;
+    exit;
+    states = {};
+    rapidRestarts = 0;
+    checkTimer;
+    shuttingDown = false;
+    constructor(args) {
+        this.workers = args.workers;
+        this.unresponsiveTimeout = args.unresponsiveTimeout;
+        this.stderr = args.stderr;
+        this.cluster = args.cluster ?? nodeCluster;
+        this.checkInterval = args.checkInterval ?? exports.HEARTBEAT_INTERVAL;
+        this.healthyUptime = args.healthyUptime ?? 5_000;
+        this.maxRapidRestarts = args.maxRapidRestarts ?? 5;
+        this.shutdownGrace = args.shutdownGrace ?? 10_000;
+        this.exit = args.exit ?? (code => process.exit(code));
+    }
+    /**
+     * Fork the configured number of workers, and start monitoring them.
+     */
+    start() {
+        this.stderr.write(`Primary ${process.pid} started, spawning ${this.workers} worker(s)\n`);
+        this.cluster.on('exit', (worker, code, signal) => this.onWorkerExit(worker, code, signal));
+        this.cluster.on('message', (worker, message) => this.onWorkerMessage(worker, message));
+        for (let i = 0; i < this.workers; i++) {
+            this.fork();
+        }
+        if (this.unresponsiveTimeout > 0) {
+            this.checkTimer = setInterval(() => this.checkWorkers(), this.checkInterval);
+        }
+    }
+    /**
+     * Terminate all workers, and exit as soon as they are all gone.
+     * @param signal The signal to send to the workers.
+     */
+    stop(signal) {
+        if (this.shuttingDown) {
+            return;
+        }
+        this.shuttingDown = true;
+        clearInterval(this.checkTimer);
+        const workers = this.getWorkers();
+        for (const worker of workers) {
+            worker.process.kill(signal);
+        }
+        if (workers.length === 0) {
+            this.exit(0);
+            return;
+        }
+        // Make sure we never hang on workers that refuse to shut down
+        this.killLater(workers, () => this.exit(0));
+    }
+    /**
+     * Get all workers that are currently registered within the cluster.
+     */
+    getWorkers() {
+        const workers = [];
+        for (const worker of Object.values(this.cluster.workers ?? {})) {
+            if (worker) {
+                workers.push(worker);
+            }
+        }
+        return workers;
+    }
+    /**
+     * Start a new worker process.
+     */
+    fork() {
+        const worker = this.cluster.fork();
+        const now = Date.now();
+        this.states[worker.id] = { startedAt: now, lastSeen: now, replaced: false, terminated: false };
+    }
+    /**
+     * Handle a message that was sent by a worker.
+     * @param worker The worker that sent the message.
+     * @param message The message that was sent.
+     */
+    onWorkerMessage(worker, message) {
+        const state = this.states[worker.id];
+        if (!state) {
+            return;
+        }
+        if (message === exports.MESSAGE_HEARTBEAT) {
+            state.lastSeen = Date.now();
+        }
+        else if (message === exports.MESSAGE_RECYCLE) {
+            this.recycleWorker(worker);
+        }
+    }
+    /**
+     * Replace a worker by a fresh one, and let the old worker finish its pending responses in the meantime.
+     * @param worker The worker to replace.
+     */
+    recycleWorker(worker) {
+        const state = this.states[worker.id];
+        if (state.replaced || this.shuttingDown) {
+            return;
+        }
+        this.stderr.write(`Worker ${worker.process.pid} requested to be replaced. Spawning a fresh worker...\n`);
+        // Fork the replacement before stopping the old worker, so that requests keep being handled
+        state.replaced = true;
+        state.terminated = true;
+        this.fork();
+        // Stop the old worker from accepting new connections, and kill it once its pending responses were sent.
+        // Disconnected workers are removed from the cluster, so they must be killed by reference.
+        worker.disconnect();
+        this.killLater([worker]);
+    }
+    /**
+     * Restart a worker that died, unless workers keep dying immediately after startup.
+     * @param worker The worker that died.
+     * @param code The exit code of the worker.
+     * @param signal The signal that terminated the worker.
+     */
+    onWorkerExit(worker, code, signal) {
+        const state = this.states[worker.id];
+        delete this.states[worker.id];
+        if (this.shuttingDown) {
+            if (this.getWorkers().length === 0) {
+                this.exit(0);
+            }
+            return;
+        }
+        // A replacement for this worker was already forked
+        if (state?.replaced) {
+            this.stderr.write(`Replaced worker ${worker.process.pid} exited (${signal ?? code})\n`);
+            return;
+        }
+        // Workers that die before they could ever become healthy indicate a startup failure,
+        // such as a port that is already in use, in which case restarting in a loop is pointless.
+        if (state && !state.terminated && Date.now() - state.startedAt < this.healthyUptime) {
+            this.rapidRestarts++;
+            if (this.rapidRestarts >= this.maxRapidRestarts) {
+                this.stderr.write(`Worker ${worker.process.pid} died (${signal ?? code}) during startup, ${this.rapidRestarts} times in a row. Giving up.\n`);
+                this.shuttingDown = true;
+                clearInterval(this.checkTimer);
+                this.exit(1);
+                return;
+            }
+        }
+        else {
+            this.rapidRestarts = 0;
+        }
+        this.stderr.write(`Worker ${worker.process.pid} died (${signal ?? code}). Restarting...\n`);
+        this.fork();
+    }
+    /**
+     * Kill all workers of which the event loop has been blocked for too long.
+     */
+    checkWorkers() {
+        const now = Date.now();
+        for (const worker of this.getWorkers()) {
+            const state = this.states[worker.id];
+            if (state && !state.terminated && now - state.lastSeen > this.unresponsiveTimeout) {
+                this.stderr.write(`Worker ${worker.process.pid} was unresponsive for more than ${this.unresponsiveTimeout}ms. Killing it...\n`);
+                state.terminated = true;
+                worker.process.kill('SIGKILL');
+            }
+        }
+    }
+    /**
+     * Forcefully kill the given workers if they are still alive after the shutdown grace period.
+     * @param workers The workers to kill.
+     * @param callback An optional callback to invoke afterwards.
+     */
+    killLater(workers, callback) {
+        setTimeout(() => {
+            for (const worker of workers) {
+                worker.process.kill('SIGKILL');
+            }
+            callback?.();
+        }, this.shutdownGrace).unref();
+    }
+}
+exports.WorkerPool = WorkerPool;
+/**
+ * Periodically inform the primary process that the event loop of this worker is not blocked.
+ * This is a no-op when the current process is not a cluster worker.
+ * @param interval The interval in milliseconds at which heartbeats are sent.
+ * @returns The heartbeat timer, or undefined if the current process is not a cluster worker.
+ */
+function startHeartbeat(interval = exports.HEARTBEAT_INTERVAL) {
+    if (!process.send) {
+        return;
+    }
+    const timer = setInterval(() => sendToPrimary(exports.MESSAGE_HEARTBEAT), interval);
+    // The heartbeat must never keep the worker process alive by itself
+    timer.unref();
+    return timer;
+}
+/**
+ * Ask the primary process to replace this worker by a fresh one.
+ * This is a no-op when the current process is not a cluster worker.
+ * @returns If the request was sent.
+ */
+function requestRecycle() {
+    return sendToPrimary(exports.MESSAGE_RECYCLE);
+}
+/**
+ * Send a message to the primary process, if this process is a cluster worker that is still connected to it.
+ *
+ * Workers stay alive for a while after being disconnected, so that they can finish their pending responses.
+ * Any message sent during that period would make the worker crash on an unhandled error event,
+ * which is why the connection is checked, and remaining errors are swallowed by passing a callback.
+ * @param message The message to send.
+ * @returns If the message was sent.
+ */
+function sendToPrimary(message) {
+    if (!process.send || !process.connected) {
+        return false;
+    }
+    return process.send(message, undefined, undefined, () => {
+        // Ignore errors that occur when the IPC channel closes while sending
+    });
+}
+//# sourceMappingURL=WorkerPool.js.map

package/lib/WorkerPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerPool.js","sourceRoot":"","sources":["WorkerPool.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable import/no-nodejs-modules,unicorn/no-process-exit */\nimport type { Cluster, Worker } from 'node:cluster';\nimport type { Writable } from 'node:stream';\n\n// The cluster module only has a default export, which can not be imported\n// as such within this CommonJS package, so it is required instead.\n// eslint-disable-next-line ts/no-require-imports,ts/no-var-requires\nconst nodeCluster: Cluster = require('node:cluster');\n\n/**\n * The message workers periodically send to the primary process to indicate that their event loop is responsive.\n */\nexport const MESSAGE_HEARTBEAT = 'comunica-mcp:heartbeat';\n\n/**\n * The message workers send to the primary process to ask to be replaced by a fresh worker.\n */\nexport const MESSAGE_RECYCLE = 'comunica-mcp:recycle';\n\n/**\n * The interval in milliseconds at which workers send a heartbeat to the primary process.\n */\nexport const HEARTBEAT_INTERVAL = 1_000;\n\n/**\n * The lower bound in milliseconds on the time a worker may block its event loop before it is considered stuck.\n * Workers are never killed faster than this, so that slow startups are not mistaken for hangs.\n */\nexport const MIN_UNRESPONSIVE_TIMEOUT = 30_000;\n\nexport interface IWorkerPoolArgs {\n  /**\n   * The number of workers that must be kept alive at all times.\n   */\n  workers: number;\n  /**\n   * The time in milliseconds a worker may block its event loop before it is killed and restarted.\n   * A value of 0 disables this watchdog.\n   */\n  unresponsiveTimeout: number;\n  /**\n   * The stream to write log messages to.\n   */\n  stderr: Writable;\n  /**\n   * The cluster instance to manage workers with. Defaults to the Node.js cluster module.\n   */\n  cluster?: Cluster;\n  /**\n   * The interval in milliseconds at which worker liveness is checked. Defaults to {@link HEARTBEAT_INTERVAL}.\n   */\n  checkInterval?: number;\n  /**\n   * The time in milliseconds a worker must stay alive before its startup is considered successful.\n   */\n  healthyUptime?: number;\n  /**\n   * The number of consecutive failed startups after which the primary process gives up.\n   */\n  maxRapidRestarts?: number;\n  /**\n   * The time in milliseconds workers are given to shut down gracefully before they are killed.\n   */\n  shutdownGrace?: number;\n  /**\n   * Invoked when the primary process must terminate with the given exit code.\n   */\n  exit?: (code: number) => void;\n}\n\n/**\n * The state that the primary process keeps for each of its workers.\n */\ninterface IWorkerState {\n  /**\n   * The time at which the worker was forked.\n   */\n  startedAt: number;\n  /**\n   * The last time at which the worker was known to be responsive.\n   */\n  lastSeen: number;\n  /**\n   * If a replacement for this worker was already forked, so that its exit must not trigger another fork.\n   */\n  replaced: boolean;\n  /**\n   * If this worker was terminated on purpose.\n   */\n  terminated: boolean;\n}\n\n/**\n * Maintains a pool of worker processes that each run an MCP server, and replaces them when needed.\n *\n * Workers are needed because SPARQL queries can not always be cancelled from within the process that runs them:\n * * Queries that block the event loop make any timeout inside that worker unable to fire in the first place.\n *   Such workers stop sending {@link MESSAGE_HEARTBEAT} messages, upon which they are killed and replaced.\n * * Queries that did time out keep consuming CPU and memory in the background, as Comunica offers no way to\n *   abort an ongoing query. Workers therefore ask to be replaced via {@link MESSAGE_RECYCLE} after a timeout,\n *   which lets them finish their pending responses while a fresh worker takes over.\n */\nexport class WorkerPool {\n  private readonly workers: number;\n  private readonly unresponsiveTimeout: number;\n  private readonly stderr: Writable;\n  private readonly cluster: Cluster;\n  private readonly checkInterval: number;\n  private readonly healthyUptime: number;\n  private readonly maxRapidRestarts: number;\n  private readonly shutdownGrace: number;\n  private readonly exit: (code: number) => void;\n\n  private readonly states: Record<number, IWorkerState> = {};\n  private rapidRestarts = 0;\n  private checkTimer: NodeJS.Timeout | undefined;\n  private shuttingDown = false;\n\n  public constructor(args: IWorkerPoolArgs) {\n    this.workers = args.workers;\n    this.unresponsiveTimeout = args.unresponsiveTimeout;\n    this.stderr = args.stderr;\n    this.cluster = args.cluster ?? nodeCluster;\n    this.checkInterval = args.checkInterval ?? HEARTBEAT_INTERVAL;\n    this.healthyUptime = args.healthyUptime ?? 5_000;\n    this.maxRapidRestarts = args.maxRapidRestarts ?? 5;\n    this.shutdownGrace = args.shutdownGrace ?? 10_000;\n    this.exit = args.exit ?? (code => process.exit(code));\n  }\n\n  /**\n   * Fork the configured number of workers, and start monitoring them.\n   */\n  public start(): void {\n    this.stderr.write(`Primary ${process.pid} started, spawning ${this.workers} worker(s)\\n`);\n\n    this.cluster.on('exit', (worker, code, signal) => this.onWorkerExit(worker, code, signal));\n    this.cluster.on('message', (worker, message) => this.onWorkerMessage(worker, message));\n\n    for (let i = 0; i < this.workers; i++) {\n      this.fork();\n    }\n\n    if (this.unresponsiveTimeout > 0) {\n      this.checkTimer = setInterval(() => this.checkWorkers(), this.checkInterval);\n    }\n  }\n\n  /**\n   * Terminate all workers, and exit as soon as they are all gone.\n   * @param signal The signal to send to the workers.\n   */\n  public stop(signal: NodeJS.Signals): void {\n    if (this.shuttingDown) {\n      return;\n    }\n    this.shuttingDown = true;\n    clearInterval(this.checkTimer);\n\n    const workers = this.getWorkers();\n    for (const worker of workers) {\n      worker.process.kill(signal);\n    }\n    if (workers.length === 0) {\n      this.exit(0);\n      return;\n    }\n\n    // Make sure we never hang on workers that refuse to shut down\n    this.killLater(workers, () => this.exit(0));\n  }\n\n  /**\n   * Get all workers that are currently registered within the cluster.\n   */\n  protected getWorkers(): Worker[] {\n    const workers: Worker[] = [];\n    for (const worker of Object.values(this.cluster.workers ?? {})) {\n      if (worker) {\n        workers.push(worker);\n      }\n    }\n    return workers;\n  }\n\n  /**\n   * Start a new worker process.\n   */\n  protected fork(): void {\n    const worker = this.cluster.fork();\n    const now = Date.now();\n    this.states[worker.id] = { startedAt: now, lastSeen: now, replaced: false, terminated: false };\n  }\n\n  /**\n   * Handle a message that was sent by a worker.\n   * @param worker The worker that sent the message.\n   * @param message The message that was sent.\n   */\n  protected onWorkerMessage(worker: Worker, message: unknown): void {\n    const state = this.states[worker.id];\n    if (!state) {\n      return;\n    }\n    if (message === MESSAGE_HEARTBEAT) {\n      state.lastSeen = Date.now();\n    } else if (message === MESSAGE_RECYCLE) {\n      this.recycleWorker(worker);\n    }\n  }\n\n  /**\n   * Replace a worker by a fresh one, and let the old worker finish its pending responses in the meantime.\n   * @param worker The worker to replace.\n   */\n  protected recycleWorker(worker: Worker): void {\n    const state = this.states[worker.id];\n    if (state.replaced || this.shuttingDown) {\n      return;\n    }\n    this.stderr.write(`Worker ${worker.process.pid} requested to be replaced. Spawning a fresh worker...\\n`);\n\n    // Fork the replacement before stopping the old worker, so that requests keep being handled\n    state.replaced = true;\n    state.terminated = true;\n    this.fork();\n\n    // Stop the old worker from accepting new connections, and kill it once its pending responses were sent.\n    // Disconnected workers are removed from the cluster, so they must be killed by reference.\n    worker.disconnect();\n    this.killLater([ worker ]);\n  }\n\n  /**\n   * Restart a worker that died, unless workers keep dying immediately after startup.\n   * @param worker The worker that died.\n   * @param code The exit code of the worker.\n   * @param signal The signal that terminated the worker.\n   */\n  protected onWorkerExit(worker: Worker, code: number, signal: string | null): void {\n    const state = this.states[worker.id];\n    delete this.states[worker.id];\n\n    if (this.shuttingDown) {\n      if (this.getWorkers().length === 0) {\n        this.exit(0);\n      }\n      return;\n    }\n\n    // A replacement for this worker was already forked\n    if (state?.replaced) {\n      this.stderr.write(`Replaced worker ${worker.process.pid} exited (${signal ?? code})\\n`);\n      return;\n    }\n\n    // Workers that die before they could ever become healthy indicate a startup failure,\n    // such as a port that is already in use, in which case restarting in a loop is pointless.\n    if (state && !state.terminated && Date.now() - state.startedAt < this.healthyUptime) {\n      this.rapidRestarts++;\n      if (this.rapidRestarts >= this.maxRapidRestarts) {\n        this.stderr.write(`Worker ${worker.process.pid} died (${signal ?? code}) during startup, ${this.rapidRestarts} times in a row. Giving up.\\n`);\n        this.shuttingDown = true;\n        clearInterval(this.checkTimer);\n        this.exit(1);\n        return;\n      }\n    } else {\n      this.rapidRestarts = 0;\n    }\n\n    this.stderr.write(`Worker ${worker.process.pid} died (${signal ?? code}). Restarting...\\n`);\n    this.fork();\n  }\n\n  /**\n   * Kill all workers of which the event loop has been blocked for too long.\n   */\n  protected checkWorkers(): void {\n    const now = Date.now();\n    for (const worker of this.getWorkers()) {\n      const state = this.states[worker.id];\n      if (state && !state.terminated && now - state.lastSeen > this.unresponsiveTimeout) {\n        this.stderr.write(`Worker ${worker.process.pid} was unresponsive for more than ${this.unresponsiveTimeout}ms. Killing it...\\n`);\n        state.terminated = true;\n        worker.process.kill('SIGKILL');\n      }\n    }\n  }\n\n  /**\n   * Forcefully kill the given workers if they are still alive after the shutdown grace period.\n   * @param workers The workers to kill.\n   * @param callback An optional callback to invoke afterwards.\n   */\n  protected killLater(workers: Worker[], callback?: () => void): void {\n    setTimeout(() => {\n      for (const worker of workers) {\n        worker.process.kill('SIGKILL');\n      }\n      callback?.();\n    }, this.shutdownGrace).unref();\n  }\n}\n\n/**\n * Periodically inform the primary process that the event loop of this worker is not blocked.\n * This is a no-op when the current process is not a cluster worker.\n * @param interval The interval in milliseconds at which heartbeats are sent.\n * @returns The heartbeat timer, or undefined if the current process is not a cluster worker.\n */\nexport function startHeartbeat(interval = HEARTBEAT_INTERVAL): NodeJS.Timeout | undefined {\n  if (!process.send) {\n    return;\n  }\n  const timer = setInterval(() => sendToPrimary(MESSAGE_HEARTBEAT), interval);\n  // The heartbeat must never keep the worker process alive by itself\n  timer.unref();\n  return timer;\n}\n\n/**\n * Ask the primary process to replace this worker by a fresh one.\n * This is a no-op when the current process is not a cluster worker.\n * @returns If the request was sent.\n */\nexport function requestRecycle(): boolean {\n  return sendToPrimary(MESSAGE_RECYCLE);\n}\n\n/**\n * Send a message to the primary process, if this process is a cluster worker that is still connected to it.\n *\n * Workers stay alive for a while after being disconnected, so that they can finish their pending responses.\n * Any message sent during that period would make the worker crash on an unhandled error event,\n * which is why the connection is checked, and remaining errors are swallowed by passing a callback.\n * @param message The message to send.\n * @returns If the message was sent.\n */\nfunction sendToPrimary(message: string): boolean {\n  if (!process.send || !process.connected) {\n    return false;\n  }\n  return process.send(message, undefined, undefined, () => {\n    // Ignore errors that occur when the IPC channel closes while sending\n  });\n}\n"]}

package/lib/index.d.ts

@@ -1,2 +1,3 @@
 export * from './SparqlMcpServer';
 export * from './BinHelpers';
+export * from './WorkerPool';

package/lib/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./SparqlMcpServer"), exports);
 __exportStar(require("./BinHelpers"), exports);
+__exportStar(require("./WorkerPool"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,+CAA6B","sourcesContent":["export * from './SparqlMcpServer';\nexport * from './BinHelpers';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,+CAA6B;AAC7B,+CAA6B","sourcesContent":["export * from './SparqlMcpServer';\nexport * from './BinHelpers';\nexport * from './WorkerPool';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comunica/utils-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP helpers for Comunica",
   "license": "MIT",
   "funding": {
@@ -46,5 +46,5 @@
     "yargs": "^17.7.2",
     "zod": "^4.3.6"
   },
-  "gitHead": "8a35a73d61cf1066bb1181761884d84d3b932932"
+  "gitHead": "4d3c6e5233ec89ceeb45bd2a478652e7f74d5cd2"
 }