backlog-api is a Node Core/CLI straight conversion of the published
Nulab Backlog MCP Server tool
handlers.
Important
This project is currently in beta. Interfaces and behavior may change before the stable release.
The TypeScript implementation removes the MCP transport boundary while preserving upstream tool names, Zod input schemas, handler behavior, Backlog API behavior, and source/test traceability. It adds a JSON CLI envelope, dry-run validation, and confirmation guards for destructive operations.
Agent workflows, working context, user-facing authorization policy, and
integrations belong to the sister
backlog-api-skills
repository.
node bundle/backlog-api.mjs --version
node bundle/backlog-api.mjs tools list
node bundle/backlog-api.mjs trace get_issue
node bundle/backlog-api.mjs call get_issue --input request.jsonThe CLI supports all 58 normal tools registered by the checked upstream
v0.13.2 source. call reads one JSON object and writes one structured JSON
envelope containing the result, diagnostics, and upstream trace information.
Delete operations and broad notification reset require
--confirm-destructive. Use --dry-run to validate input without calling
Backlog.
Use --verbose to write a short event for the start and outcome of each
Backlog API access to stderr. Events identify the operation, Backlog client
method, CRUD category, and whether the default or a named organization was
selected. A strict whitelist also exposes resource identifiers such as
spaceKey, projectId, and issueKey, IDs returned by successful API
operations, duration, changed field names without values, pagination, and an
HTTP failure status when the upstream error exposes one.
Each line starts with verbose: followed by a JSON object. Request and
response bodies, summaries, descriptions, comments, search terms, organization
names, credentials, personal data, and upstream error text are never included.
Stdout remains machine-readable JSON.
verbose: {"type":"backlog-api-access","phase":"success","access":1,"operation":"get_issue","method":"getIssue","permission":"READ","organization":"default","target":{"issueKey":"PROJ-1"},"result":{"issueId":123,"issueKey":"PROJ-1"},"durationMs":184.2}
call permits READ operations by default. Enable other client-side CRUD
categories explicitly with --allow CREATE, --allow UPDATE, or
--allow DELETE. Delete operations require both --allow DELETE and
--confirm-destructive; these are independent safeguards.
Add a top-level fields property to the input JSON to select result fields
with the upstream GraphQL-style syntax:
{"issueKey":"PROJ-1","fields":"{ id issueKey summary createdUser { name } }"}The CLI validates fields before invoking Backlog and always preserves its
JSON result envelope. Upstream token-count truncation is not exposed because
cutting serialized JSON can produce an invalid or ambiguous result; use
fields to reduce output instead.
- Node.js 22 or later
- a Backlog account with API access
BACKLOG_DOMAINandBACKLOG_API_KEY, or the upstream multi-organization environment variables
Credentials are inherited from the execution environment. They are not stored, printed, or bundled by this repository.
When a local Backlog connection file is explicitly requested, create
workplace/backlog.env with this template and replace the example domain:
BACKLOG_DOMAIN=userunique.backlog.com
BACKLOG_API_KEY=Apply the following safety rules:
- create the file only after an explicit request
- set its permissions to
600 - never overwrite an existing file
- never print or copy its values into chat, logs, tracked files, or generated artifacts
- specify
BACKLOG_DOMAINas a host name only, withouthttps://or a trailing slash - confirm that the file remains ignored by Git under
workplace/ - begin a connection test with a read-only operation such as
get_space
The CLI does not automatically load this file. A local operator or Agent workflow must load its values into the process environment immediately before invoking the CLI.
Dependency lifecycle scripts are disabled because the pinned upstream package
enforces pnpm even though this project consumes its published build/
artifacts directly.
npm install
npm run typecheck
npm run trace:refresh
npm test
npm run smoke:nodeGenerated outputs include:
bundle/backlog-api.mjsbundle/backlog-api-runtime.mjsbundle/backlog-api-sources.tgz
Authoritative application sources are TypeScript files under src/. The
compiled dist/ts/ tree and bundled .mjs files are generated artifacts.
The disposable upstream checkout belongs under
workplace/upstream/backlog-mcp-server. Refresh the generated mapping after
intentionally updating that checkout and the pinned package:
npm run trace:refreshSee docs/traceability/ for the upstream source, test,
operation, and compatibility records.
Node-specific planned work is tracked in GitHub Issues.
The sister Skill repository pins a released backlog-api runtime and records
the Node version and artifact identity separately.
This project is MIT licensed. The bundled upstream handler code is also MIT licensed; see THIRD_PARTY_NOTICES.md.