Backlog Integration Service Gateway

Last Code Update

📖 ガイド (Japanese)

This service acts as an MCP intermediary layer designed to interface robustly with the Backlog API. It empowers sophisticated autonomous agents (e.g., Claude Desktop, Cline, Cursor) to execute complex operations within the Backlog ecosystem.

Core Functionalities

Project Administration: Comprehensive CRUD operations for organizational units.
Task & Defect Management: Full lifecycle control over tickets, associated commentary, and status transitions.
Milestone/Version Control: Management of release targets and timeframes.
Knowledge Base Access: Operations on structured wiki content.
Source Control Interface: Tools for inspecting and managing Git repositories and code review artifacts (Pull Requests).
Alert Handling: Utility functions for retrieving user notifications.
Data Shaping: Support for fine-grained response shaping, mimicking GraphQL selection syntax, to minimize payload size.
Context Guardrails: Mechanisms to enforce token limits on outputs.

Deployment Instructions

Prerequisites

Docker Runtime Environment
Valid Backlog Subscription
Active API Access Credential (Key)

Deployment Method A: Containerized Execution (Docker)

The most streamlined deployment path utilizes Docker for immediate service launch:

Access your agent's MCP configuration panel.
Introduce a new server definition:

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "--pull", "always",
        "-i",
        "--rm",
        "-e", "BACKLOG_DOMAIN",
        "-e", "BACKLOG_API_KEY",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-instance.backlog.com",
        "BACKLOG_API_KEY": "your-secret-key"
      }
    }
  }
}

Remember to substitute placeholders with your actual Backlog URL segment and secret key.

Self-Update Note: If --pull always is prohibited by your setup, update the image manually via docker pull ghcr.io/nulab/backlog-mcp-server:latest.

Deployment Method B: Direct Execution (npx)

Run without persistent installation via Node Package Execute:

Open MCP settings interface.
Register the configuration:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": [
        "backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-instance.backlog.com",
        "BACKLOG_API_KEY": "your-secret-key"
      }
    }
  }
}

Deployment Method C: Source Checkout (Node.js Runtime)

For environments requiring local compilation or deep customization:

Clone the repository and install dependencies: bash git clone https://github.com/nulab/backlog-mcp-server.git cd backlog-mcp-server npm install npm run build
Configure MCP to invoke the compiled entry point: json { "mcpServers": { "backlog": { "command": "node", "args": [ "your-repository-location/build/index.js" ], "env": { "BACKLOG_DOMAIN": "your-instance.backlog.com", "BACKLOG_API_KEY": "your-secret-key" } } } }

Toolset Management

Tool availability can be tailored using the --enable-toolsets flag or the ENABLE_TOOLSETS environmental variable. This granular control is vital for minimizing the context footprint presented to the LLM.

Supported Tool Categories

Category	Scope	Default Status
`space`	Workspace configuration and user directory access.	Enabled
`project`	Organization of work units, including types, fields, and groupings.	Enabled
`issue`	Core task management, commentary, and resolution tracking.	Enabled
`wiki`	Documentation system operations.	Enabled
`git`	Repository browsing and Pull Request lifecycle management.	Enabled
`notifications`	User alert retrieval and acknowledgement.	Enabled
`document`	Hierarchical document structure retrieval.	Enabled

Customizing Activation

Via Command Line:

--enable-toolsets space,project,issue

Via Environment Variable:

ENABLE_TOOLSETS="space,project,issue"

If explicitly set to "all", all categories become active (the default state). Pruning unnecessary toolsets enhances stability when agent context windows are constrained.

💡 Recommendation: The project utility is foundational, as many other functions require project context as an initial parameter.

Runtime Discovery (Beta)

Agents can query for available toolsets dynamically:

CLI Activation:

--dynamic-toolsets

Environment Variable Activation:

-e DYNAMIC_TOOLSETS=1 \

When active, the LLM can invoke a tool to discover and load additional capabilities on the fly.

Available Tools Inventory

Category: `space`

Manages high-level workspace metadata. - get_space: Fetch workspace configuration details. - get_users: List all active workspace members. - get_myself: Retrieve credentials owner's profile information.

Category: `project`

Governs project entities and their structural metadata. - get_project_list: Retrieve catalog of accessible projects. - add_project: Initiate the creation of a new project container. - get_project: Fetch attributes for a specific project identifier. - update_project: Modify configuration parameters of an existing project. - delete_project: Archive or remove a project entity.

Category: `issue`

Tools dedicated to issue item management, including related attributes like priority schemes, category mappings, and resolution statuses. - get_issue: Retrieve singular ticket details. - get_issues: Query for a collection of tickets based on filters. - count_issues: Determine the total number of issues matching criteria. - add_issue: Submit a new ticket entry. - update_issue: Modify an existing ticket's attributes. - delete_issue: Remove an issue record. - get_issue_comments: Fetch all associated comments. - add_issue_comment: Append new commentary to an issue thread. - get_priorities: List defined issue priority levels. - get_categories: Fetch project-specific categorical tags. - get_custom_fields: Return definitions for project-scoped custom data fields. - get_issue_types: List recognized ticket classifications. - get_resolutions: Fetch available resolution states (e.g., Fixed, Won't Fix). - get_watching_list_items: View items the user is subscribed to for updates. - get_watching_list_count: Count subscribed items. - get_version_milestone_list: List associated version targets for a project. - add_version_milestone: Define a new target release. - update_version_milestone: Adjust a target release's parameters. - delete_version_milestone: Retire a target release.

Category: `wiki`

Utilities for managing Backlog's internal documentation assets. - get_wiki_pages: Retrieve a summary list of all pages. - get_wikis_count: Obtain the total page count within a project context. - get_wiki: Access the full content and metadata of a single page. - add_wiki: Draft and publish a new documentation page.

Category: `git`

Interface for repository management and code review coordination. - get_git_repositories: List project-affiliated code repositories. - get_git_repository: Retrieve details for a named repository. - get_pull_requests: Fetch a list of submitted PRs. - get_pull_requests_count: Count outstanding PRs. - get_pull_request: Examine a specific PR. - add_pull_request: Initiate a new merge request. - update_pull_request: Modify an active PR's settings. - get_pull_request_comments: View discussion threads on a PR. - add_pull_request_comment: Post commentary on a PR. - update_pull_request_comment: Modify an existing PR comment.

Category: `notifications`

Handles interaction with the user's activity feed. - get_notifications: Retrieve recent activity alerts. - get_notifications_count: Report the current tally of unread alerts. - reset_unread_notification_count: Clear all unread markers. - mark_notification_as_read: Archive a specific alert.

Category: `document`

Tools for navigating and retrieving structured project documents. - get_document_tree: Return the nested folder and document hierarchy for a project. - get_documents: Fetch a flat inventory of documents within a specified scope. - get_document: Retrieve complete metadata and content for an individual document entry.

Practical Application Scenarios

Once the gateway is integrated into an LLM environment, interactions become direct:

Project Indexing

Query all Backlog projects accessible to me.

New Defect Creation

In the project designated 'PROJ-KEY', register a new defect labeled 'Critical' titled "Authentication failure post-update".

Project Metadata Retrieval

Display the configuration parameters for project PROJ-KEY.

Source Control Inquiry

List all repositories associated with project PROJ-KEY.

PR Review Status

Summarize all open merge requests against the 'master' branch in repository 'backend-service' under PROJ-KEY.

Draft a new merge request transitioning from 'feature/refactor-x' to 'develop' in 'backend-service' within project PROJ-KEY.

Subscription Review

What items am I currently monitoring for updates?

Configuration Overrides via JSON Resource

Descriptions can be customized by placing a file named .backlog-mcp-serverrc.json in the execution agent's designated home directory. This file should map tool identifiers to new descriptive strings. For instance:

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "Inject a new comment into an existing ticket thread.",
  "TOOL_CREATE_PROJECT_DESCRIPTION": "Establish a novel project space within the organization."
}

The final description resolution follows this precedence: 1. Environment Variables (e.g., BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION) 2. Configuration file (.backlog-mcp-serverrc.json - supports JSON, YAML, YML formats) 3. Intrinsic built-in default values (English)

Sample Volume Mount for Configuration Sharing:

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "BACKLOG_DOMAIN",
        "-e", "BACKLOG_API_KEY",
        "-v", "/path/to/config/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-instance.backlog.com",
        "BACKLOG_API_KEY": "your-secret-key"
      }
    }
  }
}

Exporting Current Language Definitions

To extract all currently active descriptions (including local overrides), execute the binary with the --export-translations argument, which streams the output to standard output.

Example invocation:

docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations

npx github:nulab/backlog-mcp-server --export-translations

Utilizing Translation Templates

A reference template localized for Japanese is stored at:

translationConfig/.backlog-mcp-serverrc.json.example

Copy this file to your runtime environment's expected location (~/.backlog-mcp-serverrc.json) to start localization.

Environment Variable Descriptions

Tool descriptions can alternatively be set via environment variables. The variable name must be the tool key, prefixed with BACKLOG_MCP_ and converted to uppercase.

Example override for comment addition description:

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "BACKLOG_DOMAIN",
        "-e", "BACKLOG_API_KEY",
        "-e", "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION"
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-instance.backlog.com",
        "BACKLOG_API_KEY": "your-secret-key",
        "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "Customized text for adding ticket notes."
      }
    }
  }
}

The service reads the static configuration file during its initial startup sequence.

Advanced Operational Parameters

Tool Naming Prefixing

To mitigate function name conflicts when combining tools from multiple MCP sources, prefixes can be applied:

CLI Argument:

--prefix backlog_

Environment Variable:

PREFIX="backlog_"

This transforms get_project into backlog_get_project.

Output Efficiency Tuning and Payload Constraints

Field Projection (GraphQL Paradigm)

Activate selective data fetching via:

CLI Argument:

--optimize-response

Environment Variable:

OPTIMIZE_RESPONSE=1

Agents should then specify fields explicitly:

get_project(projectIdOrKey: "PROJ-KEY", fields: "{ name key summary }")

Advantages: - Drastically reduced payload volume by excluding unnecessary attributes. - Enhanced signal-to-noise ratio in responses. - Faster network transit times.

Response Token Cap

To prevent LLM context overflow, responses are subject to a truncation limit: - Default limit is set to 50,000 tokens. - Adjustable using the MAX_TOKENS environment variable. - Outputs surpassing this threshold are cut short, appended with a notification regarding the clipping.

You can set a lower threshold, e.g.:

MAX_TOKENS=10000

Warning: This mechanism is a heuristic safeguard and cannot guarantee absolute token adherence.

Consolidated Advanced Environment Setup

This example shows combined advanced settings. Note: These parameters are service-specific extensions beyond the core MCP specification and should be deployed cautiously.

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "BACKLOG_DOMAIN",
        "-e", "BACKLOG_API_KEY",
        "-e", "MAX_TOKENS",
        "-e", "OPTIMIZE_RESPONSE",
        "-e", "PREFIX",
        "-e", "ENABLE_TOOLSETS",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-instance.backlog.com",
        "BACKLOG_API_KEY": "your-secret-key",
        "MAX_TOKENS": "10000",
        "OPTIMIZE_RESPONSE": "1",
        "PREFIX": "bklg_",
        "ENABLE_TOOLSETS": "space,project,issue",
        "ENABLE_DYNAMIC_TOOLSETS": "1"
      }
    }
  }
}

Development Workflow

Testing Suite Execution

npm test

Adding New Tool Interfaces

Define the new functionality within a dedicated file in src/tools/.
Develop corresponding unit tests for validation.
Integrate the new tool definition into the central registry file: src/tools/tools.ts.
Rebuild the service and verify functionality.

Runtime Command Line Parameters

The executable accepts the following direct arguments:

--export-translations: Dump all localization strings to stdout.
--optimize-response: Activate fine-grained field selection capability.
--max-tokens=NUMBER: Specify the ceiling for response payload size (e.g., 100000).
--prefix=STRING: Prepend this text to every tool name (default: empty).
--enable-toolsets <list>: Define the active set of tool categories (comma-separated or repeated arguments). Defaults to all. Example: --enable-toolsets wiki,git or --enable-toolsets space --enable-toolsets issue

Example combination:

node build/index.js --optimize-response --max-tokens=100000 --prefix="bklg_" --enable-toolsets space,issue

Governing Agreement

This software is distributed under the terms of the MIT License.

Disclaimer: This utility is provided strictly "AS IS," without any guarantee, warranty, or commitment from the developers. Deployment implies acceptance of full responsibility for its use and integration. Potential anomalies should be reported through the GitHub Issue Tracker.

WIKIPEDIA CONTEXT: Business orchestration systems encompass the applications, frameworks, and methodologies employed by entities to navigate market volatility, maintain competitive posture, and elevate operational efficacy. Categorizations often align with functional units: strategic forecasting, relationship management (CRM), process governance, and centralized data analysis for executive choices. The rapid technological advancement mandates a strategic, adaptive approach to selecting and customizing these tools, rather than adopting them wholesale.

== Primary Management Constructs == Survey data indicates prevalent use of constructs such as Strategic Roadmapping, Stakeholder Alignment Mapping (Balanced Scorecard), Talent Development Metrics (Engagement Surveys), and core competency identification across leading global firms.

== Software Ecosystem Evolution == Business software has advanced from basic MIS architectures through ERP integration, incorporating CRM, culminating in modern cloud-native SaaS platforms. Maximizing ROI from these IT investments relies critically on implementation quality and the fitness-for-purpose selection of the technology stack.

backlog-integration-service-gateway

Author

nulab

Quick Info

Actions

Tags