backlog-mcp-server 0.10.0 → 0.11.1

package/README.md

@@ -139,6 +139,30 @@ npm run dev
 }
 ```
 
+### HTTP transport (Streamable HTTP)
+
+By default the server uses **stdio**. To run the [MCP Streamable HTTP](https://modelcontextprotocol.io/) transport instead (JSON-RPC over HTTP, same tools as stdio), start with `--transport http` or set `MCP_TRANSPORT=http`.
+
+```bash
+npm run build
+MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
+```
+
+- **Endpoint:** `POST`, `GET`, and `DELETE` on `http://<host>:<port><path>` (default path `/mcp`).
+- **Session:** After `initialize`, clients must send the `mcp-session-id` header on later requests (as returned by the server).
+- **Security:** Default bind is `127.0.0.1`. Do not expose the HTTP port to untrusted networks without authentication and TLS; it allows full use of your Backlog API key via MCP tools.
+
+Environment variables (CLI flags override when both are set):
+
+| Variable | Description |
+| -------- | ----------- |
+| `MCP_TRANSPORT` | `stdio` (default) or `http` |
+| `MCP_HTTP_HOST` | Bind address (default `127.0.0.1`) |
+| `MCP_HTTP_PORT` | Port (default `3333`) |
+| `MCP_HTTP_PATH` | URL path (default `/mcp`) |
+| `MCP_HTTP_JSON_RESPONSE` | `true` to prefer JSON responses over SSE when supported |
+| `MCP_HTTP_ALLOWED_HOSTS` | Comma-separated allowed `Host` values when binding to `0.0.0.0` (DNS rebinding protection) |
+
 ## Tool Configuration
 
 You can selectively enable or disable specific **toolsets** using the `--enable-toolsets` command-line flag or the `ENABLE_TOOLSETS` environment variable. This allows better control over which tools are available to the AI agent and helps reduce context size.
@@ -573,6 +597,10 @@ npm test
 
 The server supports several command line options:
 
+- `--transport stdio|http`: MCP transport (default: stdio). Use `http` for Streamable HTTP.
+- `--http-host`, `--http-port`, `--http-path`: HTTP bind address, port, and path (defaults: `127.0.0.1`, `3333`, `/mcp`).
+- `--http-json-response`: Prefer JSON responses over SSE when the transport supports it.
+- `--http-allowed-hosts`: Comma-separated allowed `Host` headers when binding to all interfaces.
 - `--export-translations`: Export all translation keys and values
 - `--optimize-response`: Enable GraphQL-style field selection
 - `--max-tokens=NUMBER`: Set maximum token limit for responses
@@ -587,6 +615,12 @@ Example:
 node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
 ```
 
+HTTP example:
+
+```bash
+node build/index.js --transport http --http-port 3333 --http-path /mcp
+```
+
 ## Multi-Organization Support
 
 This server can be configured to access multiple Backlog organizations from a single MCP server instance.

package/build/createBacklogMcpServer.js

@@ -0,0 +1,29 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerDynamicTools, registerTools } from './registerTools.js';
+import { organizationTools } from './tools/dynamicTools/organizations.js';
+import { dynamicTools } from './tools/dynamicTools/toolsets.js';
+import { createToolRegistrar } from './utils/toolRegistrar.js';
+import { buildToolsetGroup } from './utils/toolsetUtils.js';
+import { wrapServerWithToolRegistry, } from './utils/wrapServerWithToolRegistry.js';
+/**
+ * Builds a fresh MCP server instance with all Backlog tools registered.
+ * Used once for stdio; one instance per HTTP session for Streamable HTTP.
+ */
+export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, }) {
+    const server = wrapServerWithToolRegistry(new McpServer({
+        name: 'backlog',
+        title: useFields ? 'backlog (field selection enabled)' : 'backlog',
+        version,
+    }));
+    const toolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
+    registerTools(server, toolsetGroup, mcpOption);
+    registerDynamicTools(server, organizationTools(clientRegistry, transHelper), mcpOption.prefix);
+    if (dynamicToolsets) {
+        const registrar = createToolRegistrar(server, toolsetGroup, mcpOption);
+        const dynamicToolsetGroup = dynamicTools(registrar, transHelper, toolsetGroup);
+        registerDynamicTools(server, dynamicToolsetGroup, mcpOption.prefix);
+    }
+    return server;
+}

package/build/handlers/builders/composeToolHandler.js

@@ -14,10 +14,8 @@ export function composeToolHandler(tool, options) {
         : undefined;
     tool.schema = extendSchema(tool.schema, fieldDesc);
     // Step 2: Compose
-    let handler = wrapWithErrorHandling(wrapWithOrganizationContext(tool.handler), errorHandler);
-    if (useFields) {
-        handler = wrapWithFieldPicking(handler);
-    }
+    const baseHandler = wrapWithErrorHandling(wrapWithOrganizationContext(tool.handler), errorHandler);
+    const handler = useFields ? wrapWithFieldPicking(baseHandler) : baseHandler;
     return wrapWithToolResult(wrapWithTokenLimit(handler, maxTokens));
 }
 function extendSchema(schema, desc) {

package/build/httpMcpServer.js

@@ -0,0 +1,120 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+import { randomUUID } from 'node:crypto';
+import { serve } from '@hono/node-server';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { Hono } from 'hono';
+import { logger } from './utils/logger.js';
+const jsonRpcError = (code, message) => {
+    return { jsonrpc: '2.0', error: { code, message }, id: null };
+};
+const bodyContainsInitialize = (body) => {
+    return (Array.isArray(body) ? body : [body]).some(isInitializeRequest);
+};
+const buildAllowedHostnames = (host, allowedHosts) => {
+    if (allowedHosts?.length)
+        return allowedHosts;
+    const localhostHosts = ['127.0.0.1', 'localhost', '::1'];
+    return localhostHosts.includes(host)
+        ? ['localhost', '127.0.0.1', '[::1]']
+        : undefined;
+};
+const parseHostname = (hostHeader) => {
+    try {
+        return new URL(`http://${hostHeader}`).hostname;
+    }
+    catch {
+        return null;
+    }
+};
+const checkHostHeader = (hostHeader, allowedHostnames) => {
+    if (!hostHeader)
+        return jsonRpcError(-32000, 'Missing Host header');
+    const hostname = parseHostname(hostHeader);
+    if (hostname === null) {
+        return jsonRpcError(-32000, `Invalid Host header: ${hostHeader}`);
+    }
+    return allowedHostnames.includes(hostname)
+        ? null
+        : jsonRpcError(-32000, `Invalid Host: ${hostname}`);
+};
+const startNewSession = async (req, body, enableJsonResponse, transports, createServer) => {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse,
+        onsessioninitialized: (sid) => {
+            transports[sid] = transport;
+        },
+    });
+    transport.onclose = () => {
+        const sid = transport.sessionId;
+        if (sid)
+            delete transports[sid];
+    };
+    await createServer().connect(transport);
+    return transport.handleRequest(req, { parsedBody: body });
+};
+export const runHttpMcpServer = async (options) => {
+    const { host, port, path: mcpPath, version, enableJsonResponse, allowedHosts, createServer, } = options;
+    if ((host === '0.0.0.0' || host === '::') && !allowedHosts?.length) {
+        logger.warn('Binding to all interfaces without --http-allowed-hosts. ' +
+            'Set allowed Host values to prevent DNS rebinding attacks.');
+    }
+    const app = new Hono();
+    const transports = {};
+    const allowedHostnames = buildAllowedHostnames(host, allowedHosts);
+    app.get('/health', (c) => c.json({ status: 'healthy', timestamp: new Date().toISOString(), version }));
+    app.all(mcpPath, async (c) => {
+        const req = c.req.raw;
+        if (allowedHostnames) {
+            const hostError = checkHostHeader(req.headers.get('host'), allowedHostnames);
+            if (hostError)
+                return c.json(hostError, 403);
+        }
+        const sessionId = req.headers.get('mcp-session-id');
+        try {
+            if (sessionId && transports[sessionId]) {
+                return transports[sessionId].handleRequest(req);
+            }
+            if (sessionId) {
+                return c.json(jsonRpcError(-32000, 'Bad Request: Unknown or expired session ID. Send a new initialize request without mcp-session-id.'), 400);
+            }
+            if (req.method !== 'POST') {
+                return c.json(jsonRpcError(-32000, 'Bad Request: No mcp-session-id header.'), 400);
+            }
+            const parsed = await req.json().then((body) => ({ body }), () => null);
+            if (!parsed) {
+                return c.json(jsonRpcError(-32700, 'Parse error: Invalid JSON'), 400);
+            }
+            const { body } = parsed;
+            if (!bodyContainsInitialize(body)) {
+                const err = jsonRpcError(-32000, 'Bad Request: No mcp-session-id header and body is not an initialize request.');
+                return c.json(Array.isArray(body) ? [err] : err, 400);
+            }
+            return startNewSession(req, body, enableJsonResponse, transports, createServer);
+        }
+        catch (error) {
+            logger.error({ err: error }, 'Error handling MCP request');
+            return c.json(jsonRpcError(-32603, 'Internal server error'), 500);
+        }
+    });
+    const httpServer = await new Promise((resolve, reject) => {
+        const srv = serve({ fetch: app.fetch, port, hostname: host }, () => resolve(srv));
+        srv.on('error', reject);
+    });
+    const shutdown = async () => {
+        for (const sid of Object.keys(transports)) {
+            try {
+                await transports[sid].close();
+            }
+            catch {
+                /* ignore */
+            }
+            delete transports[sid];
+        }
+        httpServer.closeAllConnections();
+        await new Promise((resolve) => httpServer.close(() => resolve()));
+    };
+    return { httpServer, shutdown };
+};

package/build/index.js

@@ -1,25 +1,74 @@
 #!/usr/bin/env node
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import dotenv from 'dotenv';
 import { default as env } from 'env-var';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { createTranslationHelper } from './createTranslationHelper.js';
-import { registerDynamicTools, registerTools } from './registerTools.js';
-import { organizationTools } from './tools/dynamicTools/organizations.js';
-import { dynamicTools } from './tools/dynamicTools/toolsets.js';
+import { createBacklogMcpServer } from './createBacklogMcpServer.js';
+import { runHttpMcpServer } from './httpMcpServer.js';
 import { createBacklogClientRegistry } from './utils/backlogClientRegistry.js';
 import { logger } from './utils/logger.js';
-import { createToolRegistrar } from './utils/toolRegistrar.js';
-import { buildToolsetGroup } from './utils/toolsetUtils.js';
-import { wrapServerWithToolRegistry } from './utils/wrapServerWithToolRegistry.js';
 import packageJson from '../package.json' with { type: 'json' };
 const { version } = packageJson;
+// Swallow SIGPIPE and stdout/stderr EPIPE so the process doesn't crash when a
+// client disconnects mid-stream. Node.js emits EPIPE as both a Unix signal and
+// as an error event on stdout/stderr streams — both must be handled.
+process.on('SIGPIPE', () => { });
+process.stdout.on('error', (err) => {
+    if (err.code !== 'EPIPE')
+        throw err;
+});
+process.stderr.on('error', (err) => {
+    if (err.code !== 'EPIPE')
+        throw err;
+});
+process.on('uncaughtException', (error) => {
+    logger.error({ err: error }, 'Uncaught exception');
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    logger.error({ err: reason }, 'Unhandled rejection');
+    process.exit(1);
+});
 dotenv.config();
 const argv = yargs(hideBin(process.argv))
+    .option('transport', {
+    type: 'string',
+    choices: ['stdio', 'http'],
+    describe: 'MCP transport: stdio (default) or Streamable HTTP',
+    default: env.get('MCP_TRANSPORT').default('stdio').asString().toLowerCase() ===
+        'http'
+        ? 'http'
+        : 'stdio',
+})
+    .option('http-host', {
+    type: 'string',
+    describe: 'Host to bind for HTTP transport',
+    default: env.get('MCP_HTTP_HOST').default('127.0.0.1').asString(),
+})
+    .option('http-port', {
+    type: 'number',
+    describe: 'Port for HTTP transport',
+    default: env.get('MCP_HTTP_PORT').default(3333).asPortNumber(),
+})
+    .option('http-path', {
+    type: 'string',
+    describe: 'URL path for MCP endpoint (must start with /)',
+    default: env.get('MCP_HTTP_PATH').default('/mcp').asString(),
+})
+    .option('http-json-response', {
+    type: 'boolean',
+    describe: 'Prefer JSON responses over SSE streams when supported (Streamable HTTP)',
+    default: env.get('MCP_HTTP_JSON_RESPONSE').default('false').asBool(),
+})
+    .option('http-allowed-hosts', {
+    type: 'string',
+    describe: 'Comma-separated allowed Host header values when binding to all interfaces (recommended with 0.0.0.0)',
+    default: env.get('MCP_HTTP_ALLOWED_HOSTS').default('').asString(),
+})
     .option('max-tokens', {
     type: 'number',
     describe: 'Maximum number of tokens allowed in the response',
@@ -61,37 +110,75 @@ Available toolsets:
 const clientRegistry = createBacklogClientRegistry();
 const backlog = clientRegistry.createScopedClient();
 const useFields = argv.optimizeResponse;
-const server = wrapServerWithToolRegistry(new McpServer({
-    name: 'backlog',
-    title: useFields ? 'backlog (field selection enabled)' : 'backlog',
-    version,
-}));
 const transHelper = createTranslationHelper();
 const maxTokens = argv.maxTokens;
 const prefix = argv.prefix;
-let enabledToolsets = argv.enableToolsets;
-// If dynamic toolsets are enabled, remove "all" to allow for selective enabling via commands
-if (argv.dynamicToolsets) {
-    enabledToolsets = enabledToolsets.filter((a) => a != 'all');
-}
+const enabledToolsets = argv.dynamicToolsets
+    ? argv.enableToolsets.filter((a) => a !== 'all')
+    : argv.enableToolsets;
 const mcpOption = { useFields: useFields, maxTokens, prefix };
-const toolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
-// Register all tools
-registerTools(server, toolsetGroup, mcpOption);
-registerDynamicTools(server, organizationTools(clientRegistry, transHelper), prefix);
-// Register dynamic tool management tools if enabled
-if (argv.dynamicToolsets) {
-    const registrar = createToolRegistrar(server, toolsetGroup, mcpOption);
-    const dynamicToolsetGroup = dynamicTools(registrar, transHelper, toolsetGroup);
-    registerDynamicTools(server, dynamicToolsetGroup, prefix);
-}
+// Factory: creates a fresh MCP server with all tools registered.
+// Used once for stdio; one fresh instance per HTTP session for Streamable HTTP.
+const createServer = () => createBacklogMcpServer({
+    version,
+    useFields,
+    backlog,
+    clientRegistry,
+    transHelper,
+    enabledToolsets,
+    mcpOption,
+    dynamicToolsets: argv.dynamicToolsets,
+});
 if (argv.exportTranslations) {
     const data = transHelper.dump();
     // eslint-disable-next-line no-console
     console.log(JSON.stringify(data, null, 2));
     process.exit(0);
 }
+function normalizeHttpPath(p) {
+    if (!p.startsWith('/')) {
+        return `/${p}`;
+    }
+    return p;
+}
 async function main() {
+    if (argv.transport === 'http') {
+        const httpPath = normalizeHttpPath(argv.httpPath);
+        const allowedHostsRaw = argv.httpAllowedHosts;
+        const allowedHosts = allowedHostsRaw && allowedHostsRaw.trim().length > 0
+            ? allowedHostsRaw
+                .split(',')
+                .map((h) => h.trim())
+                .filter(Boolean)
+            : undefined;
+        const { shutdown } = await runHttpMcpServer({
+            host: argv.httpHost,
+            port: argv.httpPort,
+            path: httpPath,
+            version,
+            enableJsonResponse: argv.httpJsonResponse,
+            allowedHosts,
+            createServer,
+        });
+        process.once('SIGINT', () => {
+            void shutdown()
+                .catch((err) => logger.error({ err }, 'Error during shutdown'))
+                .finally(() => process.exit(0));
+        });
+        process.once('SIGTERM', () => {
+            void shutdown()
+                .catch((err) => logger.error({ err }, 'Error during shutdown'))
+                .finally(() => process.exit(0));
+        });
+        logger.info({
+            transport: 'http',
+            host: argv.httpHost,
+            port: argv.httpPort,
+            path: httpPath,
+        }, 'Backlog MCP Server listening (Streamable HTTP)');
+        return;
+    }
+    const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logger.info('Backlog MCP Server running on stdio');

package/build/tools/addIssue.js

@@ -67,9 +67,14 @@ const addIssueSchema = buildToolSchema((t) => ({
             .number()
             .describe(t('TOOL_ADD_ISSUE_CUSTOM_FIELD_ID', 'The ID of the custom field (e.g., 12345)')),
         value: z
-            .union([z.number(), z.array(z.number())])
+            .union([
+            z.string(),
+            z.number(),
+            z.array(z.string()),
+            z.array(z.number()),
+        ])
             .optional()
-            .describe('The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'),
+            .describe(t('TOOL_ADD_ISSUE_CUSTOM_FIELD_VALUE', 'Value of the custom field. For text/date fields, provide a string. For numeric fields, provide a number. For list fields, provide an array of strings or numbers.')),
         otherValue: z
             .string()
             .optional()

package/build/tools/updateIssue.js

@@ -86,9 +86,14 @@ const updateIssueSchema = buildToolSchema((t) => ({
             .number()
             .describe(t('TOOL_UPDATE_ISSUE_CUSTOM_FIELD_ID', 'The ID of the custom field (e.g., 12345)')),
         value: z
-            .union([z.number(), z.array(z.number())])
+            .union([
+            z.string(),
+            z.number(),
+            z.array(z.string()),
+            z.array(z.number()),
+        ])
             .optional()
-            .describe('The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'),
+            .describe(t('TOOL_UPDATE_ISSUE_CUSTOM_FIELD_VALUE', 'Value of the custom field. For text/date fields, provide a string. For numeric fields, provide a number. For list fields, provide an array of strings or numbers.')),
         otherValue: z
             .string()
             .optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -27,12 +27,14 @@
     "build"
   ],
   "dependencies": {
+    "@hono/node-server": "^1.19.14",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "backlog-js": "^0.16.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.5.0",
     "env-var": "^7.5.0",
     "graphql": "^16.11.0",
+    "hono": "^4.12.18",
     "pino": "^9.9.0",
     "pino-pretty": "^13.1.1",
     "yargs": "^18.0.0",