This is page 1 of 2. Use http://codebase.md/nulab/backlog-mcp-server?page={x} to view the full context.
# Directory Structure
```
├── .clineigonre
├── .clinerules
│ └── commit-conventional-format.md
├── .env.example
├── .github
│ └── workflows
│ ├── ci.yml
│ └── release.yml
├── .gitignore
├── .prettierignore
├── .prettierrc
├── .release-it.json
├── .tool-versions
├── CHANGELOG.md
├── Dockerfile
├── eslint.config.js
├── jest.config.js
├── LICENSE
├── memory-bank
│ ├── activeContext.md
│ ├── productContext.md
│ ├── progress.md
│ ├── projectbrief.md
│ ├── systemPatterns.md
│ ├── techContext.md
│ └── URLlist.md
├── package-lock.json
├── package.json
├── README.ja.md
├── README.md
├── scripts
│ └── replace-version.js
├── src
│ ├── backlog
│ │ ├── backlogErrorHandler.ts
│ │ ├── customFields.test.ts
│ │ ├── customFields.ts
│ │ └── parseBacklogAPIError.ts
│ ├── createTranslationHelper.test.ts
│ ├── createTranslationHelper.ts
│ ├── handlers
│ │ ├── builders
│ │ │ ├── composeToolHandler.test.ts
│ │ │ └── composeToolHandler.ts
│ │ └── transformers
│ │ ├── wrapWithErrorHandling.test.ts
│ │ ├── wrapWithErrorHandling.ts
│ │ ├── wrapWithFieldPicking.test.ts
│ │ ├── wrapWithFieldPicking.ts
│ │ ├── wrapWithTokenLimit.test.ts
│ │ ├── wrapWithTokenLimit.ts
│ │ ├── wrapWithToolResult.test.ts
│ │ └── wrapWithToolResult.ts
│ ├── index.ts
│ ├── registerTools.test.ts
│ ├── registerTools.ts
│ ├── tools
│ │ ├── addIssue.test.ts
│ │ ├── addIssue.ts
│ │ ├── addIssueComment.test.ts
│ │ ├── addIssueComment.ts
│ │ ├── addProject.test.ts
│ │ ├── addProject.ts
│ │ ├── addPullRequest.test.ts
│ │ ├── addPullRequest.ts
│ │ ├── addPullRequestComment.test.ts
│ │ ├── addPullRequestComment.ts
│ │ ├── addVersionMilestone.test.ts
│ │ ├── addVersionMilestone.ts
│ │ ├── addWiki.test.ts
│ │ ├── addWiki.ts
│ │ ├── countIssues.test.ts
│ │ ├── countIssues.ts
│ │ ├── deleteIssue.test.ts
│ │ ├── deleteIssue.ts
│ │ ├── deleteProject.test.ts
│ │ ├── deleteProject.ts
│ │ ├── deleteVersion.test.ts
│ │ ├── deleteVersion.ts
│ │ ├── dynamicTools
│ │ │ ├── toolsets.test.ts
│ │ │ └── toolsets.ts
│ │ ├── getCategories.test.ts
│ │ ├── getCategories.ts
│ │ ├── getCustomFields.test.ts
│ │ ├── getCustomFields.ts
│ │ ├── getDocument.test.ts
│ │ ├── getDocument.ts
│ │ ├── getDocuments.test.ts
│ │ ├── getDocuments.ts
│ │ ├── getDocumentTree.test.ts
│ │ ├── getDocumentTree.ts
│ │ ├── getGitRepositories.test.ts
│ │ ├── getGitRepositories.ts
│ │ ├── getGitRepository.test.ts
│ │ ├── getGitRepository.ts
│ │ ├── getIssue.test.ts
│ │ ├── getIssue.ts
│ │ ├── getIssueComments.test.ts
│ │ ├── getIssueComments.ts
│ │ ├── getIssues.test.ts
│ │ ├── getIssues.ts
│ │ ├── getIssueTypes.test.ts
│ │ ├── getIssueTypes.ts
│ │ ├── getMyself.test.ts
│ │ ├── getMyself.ts
│ │ ├── getNotifications.test.ts
│ │ ├── getNotifications.ts
│ │ ├── getNotificationsCount.test.ts
│ │ ├── getNotificationsCount.ts
│ │ ├── getPriorities.test.ts
│ │ ├── getPriorities.ts
│ │ ├── getProject.test.ts
│ │ ├── getProject.ts
│ │ ├── getProjectList.test.ts
│ │ ├── getProjectList.ts
│ │ ├── getPullRequest.test.ts
│ │ ├── getPullRequest.ts
│ │ ├── getPullRequestComments.test.ts
│ │ ├── getPullRequestComments.ts
│ │ ├── getPullRequests.test.ts
│ │ ├── getPullRequests.ts
│ │ ├── getPullRequestsCount.test.ts
│ │ ├── getPullRequestsCount.ts
│ │ ├── getResolutions.test.ts
│ │ ├── getResolutions.ts
│ │ ├── getSpace.test.ts
│ │ ├── getSpace.ts
│ │ ├── getUsers.test.ts
│ │ ├── getUsers.ts
│ │ ├── getVersionMilestoneList.test.ts
│ │ ├── getVersionMilestoneList.ts
│ │ ├── getWatchingListCount.test.ts
│ │ ├── getWatchingListCount.ts
│ │ ├── getWatchingListItems.test.ts
│ │ ├── getWatchingListItems.ts
│ │ ├── getWiki.test.ts
│ │ ├── getWiki.ts
│ │ ├── getWikiPages.test.ts
│ │ ├── getWikiPages.ts
│ │ ├── getWikisCount.test.ts
│ │ ├── getWikisCount.ts
│ │ ├── markNotificationAsRead.test.ts
│ │ ├── markNotificationAsRead.ts
│ │ ├── resetUnreadNotificationCount.test.ts
│ │ ├── resetUnreadNotificationCount.ts
│ │ ├── tools.ts
│ │ ├── updateIssue.test.ts
│ │ ├── updateIssue.ts
│ │ ├── updateProject.test.ts
│ │ ├── updateProject.ts
│ │ ├── updatePullRequest.test.ts
│ │ ├── updatePullRequest.ts
│ │ ├── updatePullRequestComment.test.ts
│ │ ├── updatePullRequestComment.ts
│ │ ├── updateVersionMilestone.test.ts
│ │ └── updateVersionMilestone.ts
│ ├── types
│ │ ├── mcp.ts
│ │ ├── result.ts
│ │ ├── tool.ts
│ │ ├── toolsets.ts
│ │ └── zod
│ │ └── backlogOutputDefinition.ts
│ ├── utils
│ │ ├── generateFieldsDescription.test.ts
│ │ ├── generateFieldsDescription.ts
│ │ ├── logger.ts
│ │ ├── resolveIdOrKey.test.ts
│ │ ├── resolveIdOrKey.ts
│ │ ├── runToolSafely.test.ts
│ │ ├── runToolSafely.ts
│ │ ├── tokenCounter.test.ts
│ │ ├── tokenCounter.ts
│ │ ├── toolRegistrar.test.ts
│ │ ├── toolRegistrar.ts
│ │ ├── toolsetUtils.test.ts
│ │ ├── toolsetUtils.ts
│ │ ├── wrapServerWithToolRegistry.test.ts
│ │ └── wrapServerWithToolRegistry.ts
│ └── version.template.ts
├── translationConfig
│ └── .backlog-mcp-serverrc.json.example
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.tool-versions:
--------------------------------------------------------------------------------
```
nodejs 22.0.0
```
--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
```
build
node_modules
```
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
BACKLOG_API_KEY=
BACKLOG_DOMAIN=
```
--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
```
{
"singleQuote": true,
"semi": true,
"trailingComma": "es5"
}
```
--------------------------------------------------------------------------------
/.clineigonre:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
**/node_modules/
.pnp
.pnp.js
# Build outputs
/build/
/dist/
/.next/
/out/
# Testing
/coverage/
# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# Large data files
*.csv
*.xlsx
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
package-lock.json
yarn.lock
# TypeScript build output
build/
dist/
*.tsbuildinfo
# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# Editor directories and files
.idea/
.vscode/*
!.vscode/extensions.json
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
# OS specific
.DS_Store
Thumbs.db
Desktop.ini
# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Testing
coverage/
.nyc_output/
# Temporary files
tmp/
temp/
src/version.ts
```
--------------------------------------------------------------------------------
/.release-it.json:
--------------------------------------------------------------------------------
```json
{
"git": {
"tagName": "v${version}",
"commitMessage": "chore(bump): v${version}",
"requireCleanWorkingDir": true
},
"plugins": {
"@release-it/conventional-changelog": {
"preset": "conventionalcommits",
"infile": "CHANGELOG.md",
"changelogHeader": "# Changelog"
}
},
"github": {
"release": true,
"releaseName": "v${version}",
"tokenRef": "GITHUB_TOKEN"
},
"npm": false,
"bumpFiles": ["package.json"],
"hooks": {
"after:bump": "docker buildx build --platform linux/amd64,linux/arm64 --provenance=false --sbom=false --build-arg VERSION=${version} -t ghcr.io/nulab/backlog-mcp-server:v${version} -t ghcr.io/nulab/backlog-mcp-server:latest --push ."
}
}
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# Backlog MCP Server
[📘 日本語でのご利用ガイド](./README.ja.md)
A Model Context Protocol (MCP) server for interacting with the Backlog API. This server provides tools for managing projects, issues, wiki pages, and more in Backlog through AI agents like Claude Desktop / Cline / Cursor etc.
## Features
- Project tools (create, read, update, delete)
- Issue tracking and comments (create, update, delete, list)
- Version/Milestone management (create, read, update, delete)
- Wiki page support
- Git repository and pull request tools
- Notification tools
- GraphQL-style field selection for optimized responses
- Token limiting for large responses
## Getting Started
### Requirements
- Docker
- A Backlog account with API access
- API key from your Backlog account
### Option 1: Install via Docker
The easiest way to use this MCP server is through MCP configurations:
1. Open MCP settings
2. Navigate to the MCP configuration section
3. Add the following configuration:
```json
{
"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-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key"
}
}
}
}
```
Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.
✅ If you cannot use --pull always, you can manually update the image using:
```
docker pull ghcr.io/nulab/backlog-mcp-server:latest
```
### Option 2: Install via npx
You can also run the server directly using `npx` without cloning the repository. This is a convenient way to run the server without a full installation.
1. Open MCP settings
2. Navigate to the MCP configuration section
3. Add the following configuration:
```json
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": [
"backlog-mcp-server"
],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key"
}
}
}
}
```
Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.
### Option 3: Manual Setup (Node.js)
1. Clone and install:
```bash
git clone https://github.com/nulab/backlog-mcp-server.git
cd backlog-mcp-server
npm install
npm run build
```
2. Set your json to use as MCP
```json
{
"mcpServers": {
"backlog": {
"command": "node",
"args": [
"your-repository-location/build/index.js"
],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key"
}
}
}
}
```
## 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.
### Available Toolsets
The following toolsets are available (enabled by default when `"all"` is used):
| Toolset | Description |
|-----------------|--------------------------------------------------------------------------------------|
| `space` | Tools for managing Backlog space settings and general information |
| `project` | Tools for managing projects, categories, custom fields, and issue types |
| `issue` | Tools for managing issues and their comments, version milestones |
| `wiki` | Tools for managing wiki pages |
| `git` | Tools for managing Git repositories and pull requests |
| `notifications` | Tools for managing user notifications |
| `document` | Tools for viewing documents and document trees |
### Specifying Toolsets
You can control toolset activation in the following ways:
Using via CLI:
```bash
--enable-toolsets space,project,issue
```
Or via environment variable:
```
ENABLE_TOOLSETS="space,project,issue"
```
If all is specified, all available toolsets will be enabled. This is also the default behavior.
Using selective toolsets can be helpful if the toolset list is too large for your AI agent or if certain tools are causing performance issues. In such cases, disabling unused toolsets may improve stability.
> 🧩 Tip: `project` toolset is highly recommended, as many other tools rely on project data as an entry point.
### Dynamic Toolset Discovery (Experimental)
If you're using the MCP server with AI agents, you can enable dynamic discovery of toolsets at runtime:
Enabling via CLI:
```
--dynamic-toolsets
```
Or via environment variable::
```
-e DYNAMIC_TOOLSETS=1 \
```
With dynamic toolsets enabled, the LLM will be able to list and activate toolsets on demand via tool interface.
## Available Tools
### Toolset: `space`
Tools for managing Backlog space settings and general information.
- `get_space`: Returns information about the Backlog space.
- `get_users`: Returns list of users in the Backlog space.
- `get_myself`: Returns information about the authenticated user.
### Toolset: `project`
Tools for managing projects, categories, custom fields, and issue types.
- `get_project_list`: Returns list of projects.
- `add_project`: Creates a new project.
- `get_project`: Returns information about a specific project.
- `update_project`: Updates an existing project.
- `delete_project`: Deletes a project.
### Toolset: `issue`
Tools for managing issues, their comments, and related items like priorities, categories, custom fields, issue types, resolutions, and watching lists.
- `get_issue`: Returns information about a specific issue.
- `get_issues`: Returns list of issues.
- `count_issues`: Returns count of issues.
- `add_issue`: Creates a new issue in the specified project.
- `update_issue`: Updates an existing issue.
- `delete_issue`: Deletes an issue.
- `get_issue_comments`: Returns list of comments for an issue.
- `add_issue_comment`: Adds a comment to an issue.
- `get_priorities`: Returns list of priorities.
- `get_categories`: Returns list of categories for a project.
- `get_custom_fields`: Returns list of custom fields for a project.
- `get_issue_types`: Returns list of issue types for a project.
- `get_resolutions`: Returns list of issue resolutions.
- `get_watching_list_items`: Returns list of watching items for a user.
- `get_watching_list_count`: Returns count of watching items for a user.
- `get_version_milestone_list`: Returns list of version milestones for a project.
- `add_version_milestone`: Creates a new version milestone for a project.
- `update_version_milestone`: Updates an existing version milestone.
- `delete_version_milestone`: Deletes a version milestone.
### Toolset: `wiki`
Tools for managing wiki pages.
- `get_wiki_pages`: Returns list of Wiki pages.
- `get_wikis_count`: Returns count of wiki pages in a project.
- `get_wiki`: Returns information about a specific wiki page.
- `add_wiki`: Creates a new wiki page.
### Toolset: `git`
Tools for managing Git repositories and pull requests.
- `get_git_repositories`: Returns list of Git repositories for a project.
- `get_git_repository`: Returns information about a specific Git repository.
- `get_pull_requests`: Returns list of pull requests for a repository.
- `get_pull_requests_count`: Returns count of pull requests for a repository.
- `get_pull_request`: Returns information about a specific pull request.
- `add_pull_request`: Creates a new pull request.
- `update_pull_request`: Updates an existing pull request.
- `get_pull_request_comments`: Returns list of comments for a pull request.
- `add_pull_request_comment`: Adds a comment to a pull request.
- `update_pull_request_comment`: Updates a comment on a pull request.
### Toolset: `notifications`
Tools for managing user notifications.
- `get_notifications`: Returns list of notifications.
- `get_notifications_count`: Returns count of notifications.
- `reset_unread_notification_count`: Resets unread notification count.
- `mark_notification_as_read`: Marks a notification as read.
### Toolset: `document`
Tools for managing documents and document trees in Backlog projects.
- `get_document_tree`: Returns the hierarchical tree of documents for a project, including folders and ne
- `get_documents`: Returns a flat list of documents in a project or folder.
- `get_document`: Returns detailed information about a specific document, including metadata, content, an
## Usage Examples
Once the MCP server is configured in AI agents, you can use the tools directly in your conversations. Here are some examples:
- Listing Projects
```
Could you list all my Backlog projects?
```
- Creating a New Issue
```
Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"
```
- Getting Project Details
```
Show me the details of the PROJECT-KEY project
```
- Working with Git Repositories
```
List all Git repositories in the PROJECT-KEY project
```
- Managing Pull Requests
```
Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project
```
```
Create a new pull request from branch "feature/new-feature" to "main" in the repository "repo-name" of PROJECT-KEY project
```
- Watching Items
```
Show me all items I'm watching
```
### i18n / Overriding Descriptions
You can override the descriptions of tools by creating a `.backlog-mcp-serverrc.json` file in your **home directory**.
The file should contain a JSON object with the tool names as keys and the new descriptions as values.
For example:
```json
{
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description",
"TOOL_CREATE_PROJECT_DESCRIPTION": "Create a new project in Backlog"
}
```
When the server starts, it determines the final description for each tool based on the following priority:
1. Environment variables (e.g., `BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION`)
2. Entries in `.backlog-mcp-serverrc.json` - Supported configuration file formats: .json, .yaml, .yml
3. Built-in fallback values (English)
Sample config:
```json
{
"mcpServers": {
"backlog": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "BACKLOG_DOMAIN",
"-e", "BACKLOG_API_KEY",
"-v", "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
"ghcr.io/nulab/backlog-mcp-server"
],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key"
}
}
}
}
```
### Exporting Current Translations
You can export the current default translations (including any overrides) by running the binary with the --export-translations flag.
This will print all tool descriptions to stdout, including any customizations you have made.
Example:
```bash
docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
```
or
```bash
npx github:nulab/backlog-mcp-server --export-translations
```
### Using a Japanese Translation Template
A sample Japanese configuration file is provided at:
```bash
translationConfig/.backlog-mcp-serverrc.json.example
```
To use it, copy it to your home directory as .backlog-mcp-serverrc.json:
You can then edit the file to customize the descriptions as needed.
### Using Environment Variables
Alternatively, you can override tool descriptions via environment variables.
The environment variable names are based on the tool keys, prefixed with BACKLOG_MCP_ and written in uppercase.
Example:
To override the TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:
```json
{
"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-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key",
"BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description"
}
}
}
}
```
The server loads the config file synchronously at startup.
Environment variables always take precedence over the config file.
## Advanced Features
### Tool Name Prefixing
Add prefix to tool names with:
```
--prefix backlog_
```
or via environment variable:
```
PREFIX="backlog_"
```
This is especially useful if you're using multiple MCP servers or tools in the same environment and want to avoid name collisions. For example, get_project can become backlog_get_project to distinguish it from similarly named tools provided by other services.
### Response Optimization & Token Limits
#### Field Selection (GraphQL-style)
```
--optimize-response
```
Or environment variable:
```
OPTIMIZE_RESPONSE=1
```
Then, request only specific fields:
```
get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
```
The AI will use field selection to optimize the response:
```
get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
```
Benefits:
- Reduce response size by requesting only needed fields
- Focus on specific data points
- Improve performance for large responses
#### Token Limiting
Large responses are automatically limited to prevent exceeding token limits:
- Default limit: 50,000 tokens
- Configurable via `MAX_TOKENS` environment variable
- Responses exceeding the limit are truncated with a message
You can change this using:
```
MAX_TOKENS=10000
```
If a response exceeds the limit, it will be truncated with a warning.
> Note: This is a best-effort mitigation, not a guaranteed enforcement.
### Full Custom Configuration Example
This section demonstrates advanced configuration using multiple environment variables. These are experimental features and may not be supported across all MCP clients. This is not part of the MCP standard specification and should be used with caution.
```json
{
"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-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key",
"MAX_TOKENS": "10000",
"OPTIMIZE_RESPONSE": "1",
"PREFIX": "backlog_",
"ENABLE_TOOLSETS": "space,project,issue",
"ENABLE_DYNAMIC_TOOLSETS": "1"
}
}
}
}
```
## Development
### Running Tests
```bash
npm test
```
### Adding New Tools
1. Create a new file in `src/tools/` following the pattern of existing tools
2. Create a corresponding test file
3. Add the new tool to `src/tools/tools.ts`
4. Build and test your changes
### Command Line Options
The server supports several command line options:
- `--export-translations`: Export all translation keys and values
- `--optimize-response`: Enable GraphQL-style field selection
- `--max-tokens=NUMBER`: Set maximum token limit for responses
- `--prefix=STRING`: Optional string prefix to prepend to all tool names (default: "")
- `--enable-toolsets <toolsets...>`: Specify which toolsets to enable (comma-separated or multiple arguments). Defaults to "all".
Example: `--enable-toolsets space,project` or `--enable-toolsets issue --enable-toolsets git`
Available toolsets: `space`, `project`, `issue`, `wiki`, `git`, `notifications`.
Example:
```bash
node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
```
## License
This project is licensed under the [MIT License](./LICENSE).
Please note: This tool is provided under the MIT License **without any warranty or official support**.
Use it at your own risk after reviewing the contents and determining its suitability for your needs.
If you encounter any issues, please report them via [GitHub Issues](../../issues).
```
--------------------------------------------------------------------------------
/src/version.template.ts:
--------------------------------------------------------------------------------
```typescript
export const VERSION = '__VERSION__';
```
--------------------------------------------------------------------------------
/src/types/mcp.ts:
--------------------------------------------------------------------------------
```typescript
export type MCPOptions = {
useFields: boolean;
maxTokens: number;
prefix: string;
};
```
--------------------------------------------------------------------------------
/src/types/result.ts:
--------------------------------------------------------------------------------
```typescript
export type ErrorLike = {
kind: 'error';
message: string;
};
export type Success<T> = {
kind: 'ok';
data: T;
};
export type SafeResult<T> = Success<T> | ErrorLike;
export function isErrorLike<T>(res: SafeResult<T>): res is ErrorLike {
return res.kind === 'error';
}
```
--------------------------------------------------------------------------------
/src/backlog/backlogErrorHandler.ts:
--------------------------------------------------------------------------------
```typescript
import { ErrorLike } from '../types/result.js';
import { parseBacklogAPIError } from './parseBacklogAPIError.js';
export const backlogErrorHandler = (err: unknown): ErrorLike => {
const parsed = parseBacklogAPIError(err);
return {
kind: 'error',
message: parsed.message,
};
};
```
--------------------------------------------------------------------------------
/jest.config.js:
--------------------------------------------------------------------------------
```javascript
// jest.config.js
export default {
preset: 'ts-jest/presets/default-esm',
transform: {
'^.+\\.tsx?$': ['ts-jest', { useESM: true }],
},
extensionsToTreatAsEsm: ['.ts'],
testEnvironment: 'node',
moduleNameMapper: {
'^(\\.{1,2}/.*)\\.js$': '$1',
},
};
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithErrorHandling.ts:
--------------------------------------------------------------------------------
```typescript
import { ErrorLike, SafeResult } from '../../types/result.js';
import { runToolSafely } from '../../utils/runToolSafely.js';
export function wrapWithErrorHandling<I, O>(
fn: (input: I) => Promise<O>,
onError?: (err: unknown) => ErrorLike
): (input: I) => Promise<SafeResult<O>> {
return runToolSafely(fn, onError);
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Build stage
FROM node:22 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Runtime stage
FROM node:22-slim AS runner
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/build ./build
COPY --from=builder /app/package.json ./
ARG VERSION
ENV APP_VERSION=$VERSION
CMD ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"types": ["@jest/globals"],
"isolatedModules": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "src/**/*.test.ts"]
}
```
--------------------------------------------------------------------------------
/src/utils/tokenCounter.ts:
--------------------------------------------------------------------------------
```typescript
export function countTokens(text: string): number {
// Normalize whitespace (convert tabs and newlines to spaces)
const normalized = text
.replace(/\s+/g, ' ') // Replace multiple whitespace with a single space
.replace(/[\n\t]/g, ' ') // Replace newlines and tabs with a space
.trim();
// Split into words and individual symbols
const tokens = normalized.match(/\w+|[^\s\w]/g);
// Return the number of tokens
return tokens ? tokens.length : 0;
}
```
--------------------------------------------------------------------------------
/scripts/replace-version.js:
--------------------------------------------------------------------------------
```javascript
import { readFileSync, writeFileSync, copyFileSync } from "fs";
const pkg = JSON.parse(readFileSync("./package.json", "utf8"));
const version = pkg.version;
const templatePath = "./src/version.template.ts";
const outputPath = "./src/version.ts";
// Always reset from template before injecting
copyFileSync(templatePath, outputPath);
const content = readFileSync(outputPath, "utf8");
const replaced = content.replace(/__VERSION__/, version);
writeFileSync(outputPath, replaced);
console.log(`✔ Injected VERSION=${version} into ${outputPath}`);
```
--------------------------------------------------------------------------------
/src/types/toolsets.ts:
--------------------------------------------------------------------------------
```typescript
import { DynamicToolDefinition, ToolDefinition } from './tool.js';
type BaseToolset<TTool> = {
name: string;
description: string;
enabled: boolean;
tools: TTool[];
};
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type Toolset = BaseToolset<ToolDefinition<any, any>>;
export type ToolsetGroup = { toolsets: Toolset[] };
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type DynamicToolset = BaseToolset<DynamicToolDefinition<any>>;
export type DynamicToolsetGroup = { toolsets: DynamicToolset[] };
```
--------------------------------------------------------------------------------
/src/utils/logger.ts:
--------------------------------------------------------------------------------
```typescript
import pino from 'pino';
if (!process.env.NODE_ENV) {
process.env.NODE_ENV = 'production';
}
const isProd = process.env.NODE_ENV === 'production';
export const logger = pino(
{
level: isProd ? 'error' : 'debug',
transport: isProd
? undefined
: {
target: 'pino-pretty',
options: {
destination: 2,
colorize: true,
translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l',
ignore: 'pid,hostname',
singleLine: true,
},
},
},
isProd ? pino.destination({ dest: 2, sync: false }) : undefined
);
```
--------------------------------------------------------------------------------
/src/utils/runToolSafely.ts:
--------------------------------------------------------------------------------
```typescript
import { ErrorLike, SafeResult } from '../types/result.js';
/**
* Runs a tool handler safely, catching any errors and converting to SafeResult.
* The `onError` handler defines how to turn unknown errors into ErrorLike objects.
*/
export function runToolSafely<I, O>(
fn: (input: I) => Promise<O>,
onError?: (err: unknown) => ErrorLike
): (input: I) => Promise<SafeResult<O>> {
return async (input: I) => {
try {
const data = await fn(input);
return { kind: 'ok', data };
} catch (err) {
if (onError) {
return onError(err);
}
return { kind: 'error', message: 'Unknown: ' + err };
}
};
}
```
--------------------------------------------------------------------------------
/src/backlog/customFields.ts:
--------------------------------------------------------------------------------
```typescript
export type CustomFieldInput = {
id: number;
value: string | number | string[];
otherValue?: string;
};
/**
* Converts Backlog-style customFields array into proper payload format
*/
export function customFieldsToPayload(
customFields: CustomFieldInput[] | undefined
): Record<string, string | number | string[] | undefined> {
if (customFields == null) {
return {};
}
const result: Record<string, string | number | string[] | undefined> = {};
for (const field of customFields) {
result[`customField_${field.id}`] = field.value;
if (field.otherValue) {
result[`customField_${field.id}_otherValue`] = field.otherValue;
}
}
return result;
}
```
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
name: CI
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
ci:
if: github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/')
runs-on: ubuntu-latest
name: 🧪 Lint, Test, Build
steps:
- name: 📥 Checkout
uses: actions/checkout@v3
- name: 🟢 Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
cache: 'npm'
- name: 📦 Install deps
run: npm ci
- name: 🔍 Lint (if exists)
run: npm run lint
- name: 🎨 Format check (Prettier)
run: npm run format
- name: 🧪 Run tests
run: npm test
- name: 🛠 Build
run: npm run build
```
--------------------------------------------------------------------------------
/src/utils/toolRegistrar.ts:
--------------------------------------------------------------------------------
```typescript
import { registerTools } from '../registerTools.js';
import { MCPOptions } from '../types/mcp.js';
import { ToolRegistrar } from '../types/tool.js';
import { ToolsetGroup } from '../types/toolsets.js';
import { enableToolset } from '../utils/toolsetUtils.js';
import { BacklogMCPServer } from './wrapServerWithToolRegistry.js';
export function createToolRegistrar(
server: BacklogMCPServer,
toolsetGroup: ToolsetGroup,
options: MCPOptions
): ToolRegistrar {
return {
async enableToolsetAndRefresh(toolset: string): Promise<string> {
const msg = enableToolset(toolsetGroup, toolset);
registerTools(server, toolsetGroup, options);
await server.server.sendToolListChanged();
return msg;
},
};
}
```
--------------------------------------------------------------------------------
/src/tools/getPriorities.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { PrioritySchema } from '../types/zod/backlogOutputDefinition.js';
const getPrioritiesSchema = buildToolSchema((_t) => ({}));
export const getPrioritiesTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getPrioritiesSchema>,
(typeof PrioritySchema)['shape']
> => {
return {
name: 'get_priorities',
description: t(
'TOOL_GET_PRIORITIES_DESCRIPTION',
'Returns list of priorities'
),
schema: z.object(getPrioritiesSchema(t)),
outputSchema: PrioritySchema,
handler: async () => backlog.getPriorities(),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getResolutions.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { ResolutionSchema } from '../types/zod/backlogOutputDefinition.js';
const getResolutionsSchema = buildToolSchema((_t) => ({}));
export const getResolutionsTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getResolutionsSchema>,
(typeof ResolutionSchema)['shape']
> => {
return {
name: 'get_resolutions',
description: t(
'TOOL_GET_RESOLUTIONS_DESCRIPTION',
'Returns list of issue resolutions'
),
schema: z.object(getResolutionsSchema(t)),
outputSchema: ResolutionSchema,
handler: async () => backlog.getResolutions(),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getUsers.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { UserSchema } from '../types/zod/backlogOutputDefinition.js';
const getUsersSchema = buildToolSchema((_t) => ({}));
export const getUsersTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getUsersSchema>,
(typeof UserSchema)['shape']
> => {
return {
name: 'get_users',
description: t(
'TOOL_GET_USERS_DESCRIPTION',
'Returns list of users in the Backlog space'
),
schema: z.object(getUsersSchema(t)),
outputSchema: UserSchema,
importantFields: ['userId', 'name', 'roleType', 'lang'],
handler: async () => backlog.getUsers(),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getSpace.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { SpaceSchema } from '../types/zod/backlogOutputDefinition.js';
const getSpaceSchema = buildToolSchema((_t) => ({}));
export const getSpaceTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getSpaceSchema>,
(typeof SpaceSchema)['shape']
> => {
return {
name: 'get_space',
description: t(
'TOOL_GET_SPACE_DESCRIPTION',
'Returns information about the Backlog space'
),
schema: z.object(getSpaceSchema(t)),
outputSchema: SpaceSchema,
importantFields: ['spaceKey', 'name', 'lang', 'timezone'],
handler: async () => backlog.getSpace(),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getMyself.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { UserSchema } from '../types/zod/backlogOutputDefinition.js';
const getMyselfSchema = buildToolSchema((_t) => ({}));
export const getMyselfTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getMyselfSchema>,
(typeof UserSchema)['shape']
> => {
return {
name: 'get_myself',
description: t(
'TOOL_GET_MYSELF_DESCRIPTION',
'Returns information about the authenticated user'
),
schema: z.object(getMyselfSchema(t)),
outputSchema: UserSchema,
importantFields: ['id', 'userId', 'name', 'roleType'],
handler: async () => backlog.getMyself(),
};
};
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithTokenLimit.ts:
--------------------------------------------------------------------------------
```typescript
import { SafeResult } from '../../types/result.js';
import { countTokens } from '../../utils/tokenCounter.js';
export function wrapWithTokenLimit<I, O>(
fn: (input: I) => Promise<SafeResult<O>>,
maxTokens: number
): (input: I) => Promise<SafeResult<string>> {
return async (input: I) => {
const result = await fn(input);
if (
result == null ||
typeof result !== 'object' ||
result.kind == 'error'
) {
return result;
}
const fullText = JSON.stringify(result.data, null, 2);
const tokenCount = countTokens(fullText);
if (tokenCount > maxTokens) {
const roughCut = fullText.slice(0, Math.floor(maxTokens * 4));
return {
kind: 'ok',
data: `${roughCut}\n...(output truncated due to token limit)`,
};
}
return { kind: 'ok', data: fullText };
};
}
```
--------------------------------------------------------------------------------
/src/tools/resetUnreadNotificationCount.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { NotificationCountSchema } from '../types/zod/backlogOutputDefinition.js';
const resetUnreadNotificationCountSchema = buildToolSchema((_t) => ({}));
export const resetUnreadNotificationCountTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof resetUnreadNotificationCountSchema>,
(typeof NotificationCountSchema)['shape']
> => {
return {
name: 'reset_unread_notification_count',
description: t(
'TOOL_RESET_UNREAD_NOTIFICATION_COUNT_DESCRIPTION',
'Reset unread notification count'
),
schema: z.object(resetUnreadNotificationCountSchema(t)),
outputSchema: NotificationCountSchema,
handler: async () => backlog.resetNotificationsMarkAsRead(),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getDocument.ts:
--------------------------------------------------------------------------------
```typescript
import { Backlog } from 'backlog-js';
import { z } from 'zod';
import { TranslationHelper } from '../createTranslationHelper.js';
import { DocumentItemSchema } from '../types/zod/backlogOutputDefinition.js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
const getDocumentSchema = buildToolSchema((t) => ({
documentId: z
.string()
.describe(t('TOOL_GET_DOCUMENT_DOCUMENT_ID', 'Document ID')),
}));
export const getDocumentTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getDocumentSchema>,
(typeof DocumentItemSchema)['shape']
> => {
return {
name: 'get_document',
description: t(
'TOOL_GET_DOCUMENT_DESCRIPTION',
'Gets information about a document.'
),
schema: z.object(getDocumentSchema(t)),
outputSchema: DocumentItemSchema,
importantFields: ['id', 'title', 'createdUser'],
handler: async ({ documentId }) => {
return backlog.getDocument(documentId);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getWatchingListItems.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { WatchingListItemSchema } from '../types/zod/backlogOutputDefinition.js';
const getWatchingListItemsSchema = buildToolSchema((t) => ({
userId: z
.number()
.describe(t('TOOL_GET_WATCHING_LIST_ITEMS_USER_ID', 'User ID')),
}));
export const getWatchingListItemsTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getWatchingListItemsSchema>,
(typeof WatchingListItemSchema)['shape']
> => {
return {
name: 'get_watching_list_items',
description: t(
'TOOL_GET_WATCHING_LIST_ITEMS_DESCRIPTION',
'Returns list of watching items for a user'
),
schema: z.object(getWatchingListItemsSchema(t)),
outputSchema: WatchingListItemSchema,
handler: async ({ userId }) => backlog.getWatchingListItems(userId),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getWatchingListCount.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { WatchingListCountSchema } from '../types/zod/backlogOutputDefinition.js';
const getWatchingListCountSchema = buildToolSchema((t) => ({
userId: z
.number()
.describe(t('TOOL_GET_WATCHING_LIST_COUNT_USER_ID', 'User ID')),
}));
export const getWatchingListCountTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getWatchingListCountSchema>,
(typeof WatchingListCountSchema)['shape']
> => {
return {
name: 'get_watching_list_count',
description: t(
'TOOL_GET_WATCHING_LIST_COUNT_DESCRIPTION',
'Returns count of watching items for a user'
),
schema: z.object(getWatchingListCountSchema(t)),
outputSchema: WatchingListCountSchema,
handler: async ({ userId }) => backlog.getWatchingListCount(userId),
};
};
```
--------------------------------------------------------------------------------
/src/types/tool.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { TranslationHelper } from '../createTranslationHelper.js';
import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
export type ToolDefinition<
Shape extends z.ZodRawShape,
OutputShape extends z.ZodRawShape,
> = {
name: string;
description: string;
schema: z.ZodObject<Shape>;
outputSchema: z.ZodObject<OutputShape>;
handler: (
input: z.infer<z.ZodObject<Shape>> & { fields?: string }
) => Promise<
z.infer<z.ZodObject<OutputShape>> | z.infer<z.ZodObject<OutputShape>>[]
>;
importantFields?: (keyof z.infer<z.ZodObject<OutputShape>>)[];
};
export const buildToolSchema = <T extends z.ZodRawShape>(
fn: (t: TranslationHelper['t']) => T
) => fn;
export type DynamicToolDefinition<Shape extends z.ZodRawShape> = {
name: string;
description: string;
schema: z.ZodObject<Shape>;
handler: (input: z.infer<z.ZodObject<Shape>>) => Promise<CallToolResult>;
};
export interface ToolRegistrar {
enableToolsetAndRefresh(toolset: string): Promise<string>;
}
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithToolResult.ts:
--------------------------------------------------------------------------------
```typescript
import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import { isErrorLike, SafeResult } from '../../types/result.js';
/**
* Convert SafeResult<T> to CallToolResult
*/
export function wrapWithToolResult<I, T>(
fn: (input: I) => Promise<SafeResult<string | T>>
): (input: I, extra: RequestHandlerExtra) => Promise<CallToolResult> {
return async (input: I, _extra) => {
const result = await fn(input);
if (isErrorLike(result)) {
return {
isError: true,
content: [
{
type: 'text',
text: result.message,
},
],
};
}
const data = result.data;
if (typeof data === 'string') {
return {
content: [
{
type: 'text',
text: data,
},
],
};
}
return {
content: [
{
type: 'text',
text: JSON.stringify(data, null, 2),
},
],
};
};
}
```
--------------------------------------------------------------------------------
/src/tools/getWiki.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { WikiSchema } from '../types/zod/backlogOutputDefinition.js';
const getWikiSchema = buildToolSchema((t) => ({
wikiId: z
.union([z.string(), z.number()])
.describe(t('TOOL_GET_WIKI_ID', 'Wiki ID')),
}));
export const getWikiTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getWikiSchema>,
(typeof WikiSchema)['shape']
> => {
return {
name: 'get_wiki',
description: t(
'TOOL_GET_WIKI_DESCRIPTION',
'Returns information about a specific wiki page'
),
schema: z.object(getWikiSchema(t)),
outputSchema: WikiSchema,
importantFields: ['id', 'projectId', 'name', 'content'],
handler: async ({ wikiId }) => {
const wikiIdNumber =
typeof wikiId === 'string' ? parseInt(wikiId, 10) : wikiId;
return backlog.getWiki(wikiIdNumber);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/resetUnreadNotificationCount.test.ts:
--------------------------------------------------------------------------------
```typescript
import { resetUnreadNotificationCountTool } from './resetUnreadNotificationCount.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('resetUnreadNotificationCountTool', () => {
const mockBacklog: Partial<Backlog> = {
resetNotificationsMarkAsRead: jest
.fn<() => Promise<any>>()
.mockResolvedValue({
count: 0,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = resetUnreadNotificationCountTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns reset result as formatted JSON text', async () => {
const result = await tool.handler({});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.count).toEqual(0);
});
it('calls backlog.resetNotificationsMarkAsRead', async () => {
await tool.handler({});
expect(mockBacklog.resetNotificationsMarkAsRead).toHaveBeenCalled();
});
});
```
--------------------------------------------------------------------------------
/src/tools/getWatchingListCount.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getWatchingListCountTool } from './getWatchingListCount.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getWatchingListCountTool', () => {
const mockBacklog: Partial<Backlog> = {
getWatchingListCount: jest.fn<() => Promise<any>>().mockResolvedValue({
count: 42,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getWatchingListCountTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns watching list count as formatted JSON text', async () => {
const result = await tool.handler({
userId: 1,
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.count).toEqual(42);
});
it('calls backlog.getWatchingListCount with correct params', async () => {
await tool.handler({
userId: 1,
});
expect(mockBacklog.getWatchingListCount).toHaveBeenCalledWith(1);
});
});
```
--------------------------------------------------------------------------------
/src/tools/markNotificationAsRead.test.ts:
--------------------------------------------------------------------------------
```typescript
import { markNotificationAsReadTool } from './markNotificationAsRead.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('markNotificationAsReadTool', () => {
const mockBacklog: Partial<Backlog> = {
markAsReadNotification: jest
.fn<() => Promise<void>>()
.mockResolvedValue(undefined),
};
const mockTranslationHelper = createTranslationHelper();
const tool = markNotificationAsReadTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns success message as formatted JSON text', async () => {
const result = await tool.handler({
id: 123,
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.success).toBe(true);
});
it('calls backlog.markAsReadNotification with correct params', async () => {
await tool.handler({
id: 123,
});
expect(mockBacklog.markAsReadNotification).toHaveBeenCalledWith(123);
});
});
```
--------------------------------------------------------------------------------
/eslint.config.js:
--------------------------------------------------------------------------------
```javascript
import js from '@eslint/js';
import parser from '@typescript-eslint/parser';
import plugin from '@typescript-eslint/eslint-plugin';
/** @type {import("eslint").Linter.FlatConfig[]} */
export default [
{
ignores: ['build/**', 'node_modules/**'],
},
js.configs.recommended,
{
files: ['**/*.ts'],
languageOptions: {
parser: parser,
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module',
},
globals: {
process: 'readonly',
console: 'readonly',
},
},
plugins: {
'@typescript-eslint': plugin,
},
rules: {
...plugin.configs.recommended.rules,
'@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
'no-console': ['warn', { allow: ['warn', 'error'] }]
},
},
{
files: ['**/*.test.ts'],
rules: {
'@typescript-eslint/no-explicit-any': 'off', // Allow on unit tests
},
},
{
files: ['**/*.js'],
languageOptions: {
ecmaVersion: 'latest',
sourceType: 'module',
globals: {
console: 'readonly',
},
},
}
];
```
--------------------------------------------------------------------------------
/src/tools/getDocumentTree.ts:
--------------------------------------------------------------------------------
```typescript
import { Backlog } from 'backlog-js';
import { z } from 'zod';
import { TranslationHelper } from '../createTranslationHelper.js';
import {
DocumentTreeFullSchema,
DocumentTreeFullSchemaZ,
} from '../types/zod/backlogOutputDefinition.js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
const getDocumentTreeSchema = buildToolSchema((t) => ({
projectIdOrKey: z
.union([z.string(), z.number()])
.describe(
t('TOOL_GET_DOCUMENT_TREE_PROJECT_ID_OR_KEY', 'Project ID or Key')
),
}));
export const getDocumentTreeTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getDocumentTreeSchema>,
typeof DocumentTreeFullSchema
> => {
return {
name: 'get_document_tree',
description: t(
'TOOL_GET_DOCUMENT_TREE_DESCRIPTION',
'Gets the document tree of a project.'
),
schema: z.object(getDocumentTreeSchema(t)),
outputSchema: DocumentTreeFullSchemaZ,
importantFields: ['projectId', 'activeTree', 'trashTree'],
handler: async ({ projectIdOrKey }) => {
return backlog.getDocumentTree(projectIdOrKey);
},
};
};
```
--------------------------------------------------------------------------------
/src/utils/wrapServerWithToolRegistry.ts:
--------------------------------------------------------------------------------
```typescript
import {
McpServer,
ToolCallback,
} from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
// Extended type that has the MCP core, a set of registered tool names, and a registration function
export interface BacklogMCPServer extends McpServer {
__registeredToolNames?: Set<string>;
registerOnce: (
name: string,
description: string,
schema: z.ZodRawShape,
handler: ToolCallback<z.ZodRawShape>
) => void;
}
// This function takes an McpServer instance and extends it with a tool registration mechanism that prevents duplicate tool registrations.
export function wrapServerWithToolRegistry(
server: McpServer
): BacklogMCPServer {
const s = server as BacklogMCPServer;
if (!s.__registeredToolNames) {
s.__registeredToolNames = new Set();
}
s.registerOnce = (
name: string,
description: string,
schema: z.ZodRawShape,
handler: ToolCallback<z.ZodRawShape>
) => {
if (s.__registeredToolNames!.has(name)) {
console.warn(`Skipping duplicate tool registration: ${name}`);
return;
}
s.__registeredToolNames!.add(name);
s.tool(name, description, schema, handler);
};
return s;
}
```
--------------------------------------------------------------------------------
/src/createTranslationHelper.ts:
--------------------------------------------------------------------------------
```typescript
import { cosmiconfigSync } from 'cosmiconfig';
import os from 'os';
export interface TranslationHelper {
t: (key: string, fallback: string) => string;
dump: () => Record<string, string>;
}
export function createTranslationHelper(options?: {
configName?: string;
searchDir?: string;
}): TranslationHelper {
const usedKeys: Record<string, string> = {};
const configName = options?.configName ?? 'backlog-mcp-server';
// Load config file
const explorer = cosmiconfigSync(configName);
const searchPath = options?.searchDir ?? os.homedir();
const configResult = explorer.search(searchPath);
const config = configResult?.config || {};
function toEnvKey(key: string): string {
return `BACKLOG_MCP_${key}`;
}
function t(key: string, fallback: string): string {
const upperKey = key.toUpperCase();
if (usedKeys[upperKey]) {
return usedKeys[upperKey];
}
// Priority：ENV → config → fallback
const value =
process.env[toEnvKey(upperKey)] || config[upperKey] || fallback;
usedKeys[upperKey] = value;
return value;
}
function dump(): Record<string, string> {
return { ...usedKeys };
}
return { t, dump };
}
```
--------------------------------------------------------------------------------
/src/tools/markNotificationAsRead.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
const markNotificationAsReadSchema = buildToolSchema((t) => ({
id: z
.number()
.describe(
t('TOOL_MARK_NOTIFICATION_AS_READ_ID', 'Notification ID to mark as read')
),
}));
export const MarkNotificationAsReadResultSchema = z.object({
success: z.boolean(),
message: z.string(),
});
export const markNotificationAsReadTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof markNotificationAsReadSchema>,
(typeof MarkNotificationAsReadResultSchema)['shape']
> => {
return {
name: 'mark_notification_as_read',
description: t(
'TOOL_MARK_NOTIFICATION_AS_READ_DESCRIPTION',
'Mark a notification as read'
),
schema: z.object(markNotificationAsReadSchema(t)),
outputSchema: MarkNotificationAsReadResultSchema,
handler: async ({ id }) => {
await backlog.markAsReadNotification(id);
return {
success: true,
message: `Notification ${id} marked as read`,
};
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getNotificationsCount.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getNotificationsCountTool } from './getNotificationsCount.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getNotificationsCountTool', () => {
const mockBacklog: Partial<Backlog> = {
getNotificationsCount: jest.fn<() => Promise<any>>().mockResolvedValue({
count: 42,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getNotificationsCountTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns notification count as formatted JSON text', async () => {
const result = await tool.handler({
alreadyRead: false,
resourceAlreadyRead: false,
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.count).toEqual(42);
});
it('calls backlog.getNotificationsCount with correct params', async () => {
const params = {
alreadyRead: true,
resourceAlreadyRead: false,
};
await tool.handler(params);
expect(mockBacklog.getNotificationsCount).toHaveBeenCalledWith(params);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getSpace.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getSpaceTool } from './getSpace.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getSpaceTool', () => {
const mockBacklog: Partial<Backlog> = {
getSpace: jest.fn<() => Promise<any>>().mockResolvedValue({
spaceKey: 'demo',
name: 'Demo Space',
ownerId: 1,
lang: 'en',
timezone: 'Asia/Tokyo',
reportSendTime: '08:00:00',
textFormattingRule: 'backlog',
created: '2023-01-01T00:00:00Z',
updated: '2023-01-01T00:00:00Z',
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getSpaceTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns space information as formatted JSON text', async () => {
const result = await tool.handler({});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.name).toEqual('Demo Space');
expect(result.spaceKey).toEqual('demo');
});
it('calls backlog.getSpace', async () => {
await tool.handler({});
expect(mockBacklog.getSpace).toHaveBeenCalled();
});
});
```
--------------------------------------------------------------------------------
/src/tools/getDocuments.ts:
--------------------------------------------------------------------------------
```typescript
import { Backlog } from 'backlog-js';
import { z } from 'zod';
import { TranslationHelper } from '../createTranslationHelper.js';
import { DocumentItemSchema } from '../types/zod/backlogOutputDefinition.js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
const getDocumentsSchema = buildToolSchema((t) => ({
projectIds: z
.array(z.number())
.describe(t('TOOL_GET_DOCUMENTS_PROJECT_ID_LIST', 'Project ID List')),
offset: z
.number()
.optional()
.default(0)
.describe(
t('TOOL_GET_DOCUMENTS_OFFSET', 'Offset for pagination (default is 0)')
),
}));
export const getDocumentsTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getDocumentsSchema>,
(typeof DocumentItemSchema)['shape']
> => {
return {
name: 'get_documents',
description: t(
'TOOL_GET_DOCUMENTS_DESCRIPTION',
'Gets a list of documents in a project.'
),
schema: z.object(getDocumentsSchema(t)),
outputSchema: DocumentItemSchema,
importantFields: ['id', 'projectId', 'title', 'plain'],
handler: async ({ projectIds, offset }) => {
return backlog.getDocuments({ projectId: projectIds, offset });
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getPriorities.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getPrioritiesTool } from './getPriorities.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getPrioritiesTool', () => {
const mockBacklog: Partial<Backlog> = {
getPriorities: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 2,
name: 'High',
},
{
id: 3,
name: 'Normal',
},
{
id: 4,
name: 'Low',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getPrioritiesTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns priorities list as formatted JSON text', async () => {
const result = await tool.handler({});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(3);
expect(result[0].name).toContain('High');
expect(result[1].name).toContain('Normal');
expect(result[2].name).toContain('Low');
});
it('calls backlog.getPriorities', async () => {
await tool.handler({});
expect(mockBacklog.getPriorities).toHaveBeenCalled();
});
});
```
--------------------------------------------------------------------------------
/src/tools/getNotificationsCount.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { NotificationCountSchema } from '../types/zod/backlogOutputDefinition.js';
const getNotificationsCountSchema = buildToolSchema((t) => ({
alreadyRead: z
.boolean()
.describe(
t(
'TOOL_GET_NOTIFICATIONS_COUNT_ALREADY_READ',
'Whether to include already read notifications'
)
),
resourceAlreadyRead: z
.boolean()
.describe(
t(
'TOOL_GET_NOTIFICATIONS_COUNT_RESOURCE_ALREADY_READ',
'Whether to include notifications for already read resources'
)
),
}));
export const getNotificationsCountTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getNotificationsCountSchema>,
(typeof NotificationCountSchema)['shape']
> => {
return {
name: 'count_notifications',
description: t(
'TOOL_COUNT_NOTIFICATIONS_DESCRIPTION',
'Returns count of notifications'
),
schema: z.object(getNotificationsCountSchema(t)),
outputSchema: NotificationCountSchema,
handler: async (params) => backlog.getNotificationsCount(params),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getMyself.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getMyselfTool } from './getMyself.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getMyselfTool', () => {
const mockBacklog: Partial<Backlog> = {
getMyself: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
userId: 'current_user',
name: 'Current User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
nulabAccount: {
nulabId: '12345',
name: 'Current User',
uniqueId: 'current_user',
},
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getMyselfTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns current user information as formatted JSON text', async () => {
const result = await tool.handler({});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.name).toContain('Current User');
expect(result.mailAddress).toContain('[email protected]');
});
it('calls backlog.getMyself', async () => {
await tool.handler({});
expect(mockBacklog.getMyself).toHaveBeenCalled();
});
});
```
--------------------------------------------------------------------------------
/src/utils/tokenCounter.test.ts:
--------------------------------------------------------------------------------
```typescript
import { countTokens } from './tokenCounter.js';
import { describe, it, expect } from '@jest/globals';
describe('countTokens', () => {
it('returns 0 for empty string', () => {
expect(countTokens('')).toBe(0);
});
it('counts simple words', () => {
expect(countTokens('hello world')).toBe(2);
expect(countTokens('one two three')).toBe(3);
});
it('ignores multiple spaces/tabs/newlines', () => {
expect(countTokens('hello world')).toBe(2);
expect(countTokens('hello\tworld')).toBe(2);
expect(countTokens('hello\nworld')).toBe(2);
expect(countTokens('hello \n\t world')).toBe(2);
});
it('counts punctuation as separate tokens', () => {
expect(countTokens('hello, world!')).toBe(4);
expect(countTokens('foo(bar)')).toBe(4);
});
it('handles mixed text', () => {
const input = "This is great, isn't it?";
// Tokens: ['This', 'is', 'great', ',', 'isn', "'", 't', 'it', '?']
expect(countTokens(input)).toBe(9);
});
it('trims leading/trailing whitespace', () => {
expect(countTokens(' hello world ')).toBe(2);
});
it('counts digits and symbols', () => {
expect(countTokens('123 + 456 = 579')).toBe(5); // ['123', '+', '456', '=', '579']
});
it('counts Japanese', () => {
expect(countTokens('こんにちは')).toBe(5);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getIssue.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { IssueSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getIssueSchema = buildToolSchema((t) => ({
issueId: z
.number()
.optional()
.describe(
t('TOOL_GET_ISSUE_ISSUE_ID', 'The numeric ID of the issue (e.g., 12345)')
),
issueKey: z
.string()
.optional()
.describe(
t('TOOL_GET_ISSUE_ISSUE_KEY', "The key of the issue (e.g., 'PROJ-123')")
),
}));
export const getIssueTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getIssueSchema>,
(typeof IssueSchema)['shape']
> => {
return {
name: 'get_issue',
description: t(
'TOOL_GET_ISSUE_DESCRIPTION',
'Returns information about a specific issue'
),
outputSchema: IssueSchema,
schema: z.object(getIssueSchema(t)),
handler: async ({ issueId, issueKey }) => {
const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
if (!result.ok) {
throw result.error;
}
return backlog.getIssue(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/deleteIssue.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { IssueSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const deleteIssueSchema = buildToolSchema((t) => ({
issueId: z
.number()
.optional()
.describe(
t(
'TOOL_DELETE_ISSUE_ISSUE_ID',
'The numeric ID of the issue (e.g., 12345)'
)
),
issueKey: z
.string()
.optional()
.describe(
t('TOOL_GET_ISSUE_ISSUE_KEY', "The key of the issue (e.g., 'PROJ-123')")
),
}));
export const deleteIssueTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof deleteIssueSchema>,
(typeof IssueSchema)['shape']
> => {
return {
name: 'delete_issue',
description: t('TOOL_DELETE_ISSUE_DESCRIPTION', 'Deletes an issue'),
schema: z.object(deleteIssueSchema(t)),
outputSchema: IssueSchema,
handler: async ({ issueId, issueKey }) => {
const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
if (!result.ok) {
throw result.error;
}
return backlog.deleteIssue(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithErrorHandling.test.ts:
--------------------------------------------------------------------------------
```typescript
import { wrapWithErrorHandling } from './wrapWithErrorHandling';
import { isErrorLike, type ErrorLike } from '../../types/result';
import { describe, it, expect } from '@jest/globals';
describe('wrapWithErrorHandling', () => {
it('returns success result when function resolves', async () => {
const fn = async (input: number) => input + 1;
const wrapped = wrapWithErrorHandling(fn);
const result = await wrapped(1);
expect(result).toEqual({ kind: 'ok', data: 2 });
});
it('returns error result with default handler when function throws', async () => {
const fn = async () => {
throw new Error('fail');
};
const wrapped = wrapWithErrorHandling(fn);
const result = await wrapped(undefined as never);
expect(result.kind).toBe('error');
if (isErrorLike(result)) {
expect(result.message).toMatch(/fail/);
}
});
it('uses custom error handler if provided', async () => {
const fn = async () => {
throw new Error('original');
};
const customHandler = (_: unknown): ErrorLike => ({
kind: 'error',
message: 'custom error handled',
});
const wrapped = wrapWithErrorHandling(fn, customHandler);
const result = await wrapped(undefined as never);
expect(result).toEqual({ kind: 'error', message: 'custom error handled' });
});
});
```
--------------------------------------------------------------------------------
/src/tools/addWiki.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { WikiSchema } from '../types/zod/backlogOutputDefinition.js';
const addWikiSchema = buildToolSchema((t) => ({
projectId: z.number().describe(t('TOOL_ADD_WIKI_PROJECT_ID', 'Project ID')),
name: z.string().describe(t('TOOL_ADD_WIKI_NAME', 'Name of the wiki page')),
content: z
.string()
.describe(t('TOOL_ADD_WIKI_CONTENT', 'Content of the wiki page')),
mailNotify: z
.boolean()
.optional()
.describe(
t(
'TOOL_ADD_WIKI_MAIL_NOTIFY',
'Whether to send notification emails (default: false)'
)
),
}));
export const addWikiTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof addWikiSchema>,
(typeof WikiSchema)['shape']
> => {
return {
name: 'add_wiki',
description: t('TOOL_ADD_WIKI_DESCRIPTION', 'Creates a new wiki page'),
schema: z.object(addWikiSchema(t)),
outputSchema: WikiSchema,
importantFields: ['id', 'name', 'content', 'createdUser'],
handler: async ({ projectId, name, content, mailNotify }) =>
backlog.postWiki({
projectId,
name,
content,
mailNotify,
}),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getResolutions.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getResolutionsTool } from './getResolutions.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getResolutionsTool', () => {
const mockBacklog: Partial<Backlog> = {
getResolutions: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 0,
name: 'Fixed',
},
{
id: 1,
name: "Won't Fix",
},
{
id: 2,
name: 'Invalid',
},
{
id: 3,
name: 'Duplicate',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getResolutionsTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns resolutions list as formatted JSON text', async () => {
const result = await tool.handler({});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(4);
expect(result[0].name).toContain('Fixed');
expect(result[1].name).toContain("Won't Fix");
expect(result[2].name).toContain('Invalid');
expect(result[3].name).toContain('Duplicate');
});
it('calls backlog.getResolutions', async () => {
await tool.handler({});
expect(mockBacklog.getResolutions).toHaveBeenCalled();
});
});
```
--------------------------------------------------------------------------------
/src/tools/deleteProject.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const deleteProjectSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_DELETE_PROJECT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_DELETE_PROJECT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const deleteProjectTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof deleteProjectSchema>,
(typeof ProjectSchema)['shape']
> => {
return {
name: 'delete_project',
description: t('TOOL_DELETE_PROJECT_DESCRIPTION', 'Deletes a project'),
schema: z.object(deleteProjectSchema(t)),
outputSchema: ProjectSchema,
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.deleteProject(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getUsers.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getUsersTool } from './getUsers.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getUsersTool', () => {
const mockBacklog: Partial<Backlog> = {
getUsers: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
{
id: 2,
userId: 'user1',
name: 'Regular User',
roleType: 2,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-02T00:00:00Z',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getUsersTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns users list as formatted JSON text', async () => {
const result = await tool.handler({});
if (!Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result).toHaveLength(2);
expect(result[0].name).toContain('Admin User');
expect(result[1].name).toContain('Regular User');
});
it('calls backlog.getUsers', async () => {
await tool.handler({});
expect(mockBacklog.getUsers).toHaveBeenCalled();
});
});
```
--------------------------------------------------------------------------------
/src/tools/getNotifications.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { NotificationSchema } from '../types/zod/backlogOutputDefinition.js';
const getNotificationsSchema = buildToolSchema((t) => ({
minId: z
.number()
.optional()
.describe(t('TOOL_GET_NOTIFICATIONS_MIN_ID', 'Minimum notification ID')),
maxId: z
.number()
.optional()
.describe(t('TOOL_GET_NOTIFICATIONS_MAX_ID', 'Maximum notification ID')),
count: z
.number()
.optional()
.describe(
t('TOOL_GET_NOTIFICATIONS_COUNT', 'Number of notifications to retrieve')
),
order: z
.enum(['asc', 'desc'])
.optional()
.describe(t('TOOL_GET_NOTIFICATIONS_ORDER', 'Sort order')),
}));
export const getNotificationsTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getNotificationsSchema>,
(typeof NotificationSchema)['shape']
> => {
return {
name: 'get_notifications',
description: t(
'TOOL_GET_NOTIFICATIONS_DESCRIPTION',
'Returns list of notifications'
),
schema: z.object(getNotificationsSchema(t)),
outputSchema: NotificationSchema,
handler: async ({ minId, maxId, count, order }) =>
backlog.getNotifications({
minId,
maxId,
count,
order,
}),
};
};
```
--------------------------------------------------------------------------------
/src/tools/getProject.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getProjectSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_PROJECT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_PROJECT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const getProjectTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getProjectSchema>,
(typeof ProjectSchema)['shape']
> => {
return {
name: 'get_project',
description: t(
'TOOL_GET_PROJECT_DESCRIPTION',
'Returns information about a specific project'
),
schema: z.object(getProjectSchema(t)),
outputSchema: ProjectSchema,
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getProject(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getProjectList.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
const getProjectListSchema = buildToolSchema((t) => ({
archived: z
.boolean()
.optional()
.describe(
t(
'TOOL_GET_PROJECT_LIST_ARCHIVED',
'For unspecified parameters, this form returns all projects. For ‘false’ parameters, it returns unarchived projects. For ‘true’ parameters, it returns archived projects.'
)
),
all: z
.boolean()
.optional()
.describe(
t(
'TOOL_GET_PROJECT_LIST_ALL',
'Only applies to administrators. If ‘true,’ it returns all projects. If ‘false,’ it returns only projects they have joined.'
)
),
}));
export const getProjectListTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getProjectListSchema>,
(typeof ProjectSchema)['shape']
> => {
return {
name: 'get_project_list',
description: t(
'TOOL_GET_PROJECT_LIST_DESCRIPTION',
'Returns list of projects'
),
schema: z.object(getProjectListSchema(t)),
outputSchema: ProjectSchema,
importantFields: ['id', 'projectKey', 'name'],
handler: async ({ archived, all }) =>
backlog.getProjects({ archived, all }),
};
};
```
--------------------------------------------------------------------------------
/src/utils/runToolSafely.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, expect, it } from '@jest/globals';
import { ErrorLike, isErrorLike } from '../types/result.js';
import { runToolSafely } from './runToolSafely.js';
describe('runToolSafely', () => {
it('returns ok result when handler succeeds', async () => {
const mockFn = async (input: number) => input * 2;
const safeFn = runToolSafely<number, number>(mockFn);
const result = await safeFn(3);
expect(result).toEqual({ kind: 'ok', data: 6 });
});
it('returns error result when handler throws (default handler)', async () => {
const mockFn = async () => {
throw new Error('Boom');
};
const safeFn = runToolSafely(mockFn);
const result = await safeFn(undefined as never);
expect(result.kind).toBe('error');
if (isErrorLike(result)) {
expect(result.message).toMatch(/Boom/);
} else {
throw new Error('Expected error result, but got success');
}
});
it('uses custom error handler when provided', async () => {
const mockFn = async () => {
throw new Error('Something went wrong');
};
const customErrorHandler = (err: unknown): ErrorLike => ({
kind: 'error',
message: 'Custom: ' + (err as Error).message,
});
const safeFn = runToolSafely(mockFn, customErrorHandler);
const result = await safeFn(undefined as never);
expect(result).toEqual({
kind: 'error',
message: 'Custom: Something went wrong',
});
});
});
```
--------------------------------------------------------------------------------
/src/tools/getWikisCount.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { WikiCountSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getWikisCountSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_WIKIS_COUNT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_WIKIS_COUNT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const getWikisCountTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getWikisCountSchema>,
(typeof WikiCountSchema)['shape']
> => {
return {
name: 'get_wikis_count',
description: t(
'TOOL_GET_WIKIS_COUNT_DESCRIPTION',
'Returns count of wiki pages in a project'
),
schema: z.object(getWikisCountSchema(t)),
outputSchema: WikiCountSchema,
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getWikisCount(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getWikisCount.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getWikisCountTool } from './getWikisCount.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getWikisCountTool', () => {
const mockBacklog: Partial<Backlog> = {
getWikisCount: jest.fn<() => Promise<any>>().mockResolvedValue({
count: 42,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getWikisCountTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns wiki count as formatted JSON text', async () => {
const result = await tool.handler({
projectKey: 'TEST',
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.count).toEqual(42);
});
it('calls backlog.getWikisCount with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
});
expect(mockBacklog.getWikisCount).toHaveBeenCalledWith('TEST');
});
it('calls backlog.getWikisCount with correct params when using project ID', async () => {
await tool.handler({
projectId: 100,
});
expect(mockBacklog.getWikisCount).toHaveBeenCalledWith(100);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {}; // No identifier provided
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/memory-bank/projectbrief.md:
--------------------------------------------------------------------------------
```markdown
# Project Overview
## Purpose
- Build an MCP server to connect with the Backlog API
- Use backlog-js for connecting to Backlog
- The BacklogJS interface is published [here](https://github.com/nulab/backlog-js/blob/master/src/backlog.ts)
## Implementation Approach
- Create tools corresponding to each API endpoint and place them in `./src/tools/${endpointName}.ts`
- Write endpoint names in camelCase (e.g., `getProjectList`)
- Create corresponding test files (`${endpointName}.test.ts`) for each tool
- Refer to the API endpoints listed in URLlist.md for implementation
## Basic Tool Structure
1. Tool Definition
- Name: Name representing the API endpoint (e.g., `get_space`)
- Description: Description of the tool's functionality (in English)
- Schema: Definition of input parameters (using Zod)
- Handler: Function that performs the actual processing
2. Internationalization
- Descriptions are defined in a translatable format
- Descriptions can be customized via the `.backlog-mcp-serverrc.json` file
3. Testing
- Create test files corresponding to each tool
- Use mocks to simulate Backlog API calls
## Deployment Method
- Provided as a Docker container
- Published to GitHub Container Registry (ghcr.io)
- Configuration injected via environment variables (`BACKLOG_DOMAIN`, `BACKLOG_API_KEY`)
## Usage
- Register as an MCP server in Claude settings
- Set necessary environment variables when running Docker
- Multi-language support available through translation files
```
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
```yaml
name: Release
on:
workflow_dispatch:
inputs:
version:
description: 'Release version (e.g. 2.3.0). Leave empty for auto.'
required: false
permissions:
contents: write
packages: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set Git user
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
- name: Install dependencies
run: npm ci
- name: Set up QEMU for cross-platform builds
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to GitHub Container Registry (ghcr.io)
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Run release-it
run: |
if [ -n "${{ github.event.inputs.version }}" ]; then
echo "Manual version input: ${{ github.event.inputs.version }}"
npx release-it ${{ github.event.inputs.version }} -y --ci
else
echo "Auto version release"
npx release-it -y --ci
fi
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
--------------------------------------------------------------------------------
/src/tools/getCategories.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { CategorySchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getCategoriesSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_CATEGORIES_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_CATEGORIES_PROJECT_ID',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const getCategoriesTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getCategoriesSchema>,
(typeof CategorySchema)['shape']
> => {
return {
name: 'get_categories',
description: t(
'TOOL_GET_CATEGORIES_DESCRIPTION',
'Returns list of categories for a project'
),
schema: z.object(getCategoriesSchema(t)),
importantFields: ['id', 'projectId', 'name'],
outputSchema: CategorySchema,
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getCategories(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getIssueTypes.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { IssueTypeSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getIssueTypesSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_GIT_REPOSITORIES_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_GIT_REPOSITORIES_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const getIssueTypesTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getIssueTypesSchema>,
(typeof IssueTypeSchema)['shape']
> => {
return {
name: 'get_issue_types',
description: t(
'TOOL_GET_ISSUE_TYPES_DESCRIPTION',
'Returns list of issue types for a project'
),
schema: z.object(getIssueTypesSchema(t)),
outputSchema: IssueTypeSchema,
importantFields: ['id', 'name'],
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getIssueTypes(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getGitRepositories.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { GitRepositorySchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getGitRepositoriesSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_GIT_REPOSITORIES_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_GIT_REPOSITORIES_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const getGitRepositoriesTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getGitRepositoriesSchema>,
(typeof GitRepositorySchema)['shape']
> => {
return {
name: 'get_git_repositories',
description: t(
'TOOL_GET_GIT_REPOSITORIES_DESCRIPTION',
'Returns list of Git repositories for a project'
),
schema: z.object(getGitRepositoriesSchema(t)),
outputSchema: GitRepositorySchema,
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getGitRepositories(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/utils/generateFieldsDescription.test.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { generateFieldsDescription } from './generateFieldsDescription';
import { describe, it, expect } from '@jest/globals';
describe('generateFieldsDescription', () => {
const schema = z.object({
id: z.number(),
name: z.string(),
active: z.boolean(),
nested: z
.object({
foo: z.string(),
bar: z.number(),
})
.optional(),
});
it('should generate correct GraphQL description with importantFields', () => {
const desc = generateFieldsDescription(schema, []);
expect(desc).toContain('Example (query):');
expect(desc).toContain('id');
expect(desc).toContain('name');
expect(desc).toContain('type Output {');
expect(desc).toContain('id: Int!');
expect(desc).toContain('name: String!');
expect(desc).toContain('active: Boolean!');
expect(desc).toContain('nested: JSON');
});
it('should include all fields in SDL even if not in importantFields', () => {
const desc = generateFieldsDescription(schema, ['id']);
expect(desc).toContain('id');
expect(desc).toContain('name: String!');
expect(desc).toContain('active: Boolean!');
expect(desc).toContain('nested: JSON');
});
it('should not duplicate fields in SDL and example', () => {
const desc = generateFieldsDescription(schema, ['id', 'name']);
const examplePart = desc.split('Output schema')[0];
expect(examplePart).toContain('id');
expect(examplePart).toContain('name');
expect(examplePart).not.toContain('active');
});
});
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithToolResult.test.ts:
--------------------------------------------------------------------------------
```typescript
import { wrapWithToolResult } from './wrapWithToolResult.js';
import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
import { describe, it, expect } from '@jest/globals';
describe('wrapWithToolResult', () => {
const dummyExtra = {} as RequestHandlerExtra;
it('returns error result when SafeResult is error', async () => {
const fn = async () =>
({ kind: 'error', message: 'Something went wrong' }) as const;
const wrapped = wrapWithToolResult(fn);
const result = await wrapped({}, dummyExtra);
expect(result).toEqual({
isError: true,
content: [
{
type: 'text',
text: 'Something went wrong',
},
],
});
});
it('returns plain text when result data is string', async () => {
const fn = async () => ({ kind: 'ok', data: 'Hello, world' }) as const;
const wrapped = wrapWithToolResult(fn);
const result = await wrapped({}, dummyExtra);
expect(result).toEqual({
content: [
{
type: 'text',
text: 'Hello, world',
},
],
});
});
it('returns JSON text when result data is object', async () => {
const fn = async () =>
({ kind: 'ok', data: { id: 1, name: 'Test' } }) as const;
const wrapped = wrapWithToolResult(fn);
const result = await wrapped({}, dummyExtra);
expect(result).toEqual({
content: [
{
type: 'text',
text: JSON.stringify({ id: 1, name: 'Test' }, null, 2),
},
],
});
});
});
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithTokenLimit.test.ts:
--------------------------------------------------------------------------------
```typescript
import { wrapWithTokenLimit } from './wrapWithTokenLimit.js';
import { describe, it, expect } from '@jest/globals';
import { SafeResult } from '../../types/result.js';
describe('wrapWithTokenLimit', () => {
it('returns full JSON string if under maxTokens', async () => {
const obj = { id: 1, name: 'Short' };
const handler = async () =>
({ kind: 'ok', data: obj }) satisfies SafeResult<typeof obj>;
const wrapped = wrapWithTokenLimit(handler, 1000); // 十分余裕あり
const result = await wrapped({});
expect(result.kind).toBe('ok');
if (result.kind === 'ok') {
expect(result.data).toBe(JSON.stringify(obj, null, 2));
}
});
it('streams and truncates if over maxTokens', async () => {
const obj = {
description: 'A '.repeat(5000), // 長文でトークン制限に引っかかる
};
const handler = async () =>
({ kind: 'ok', data: obj }) satisfies SafeResult<typeof obj>;
const wrapped = wrapWithTokenLimit(handler, 100); // 小さな上限
const result = await wrapped({});
expect(result.kind).toBe('ok');
if (result.kind === 'ok') {
expect(result.data.length).toBeLessThanOrEqual(500); // 字数でざっくり
expect(result.data).toMatch(/truncated/i); // デフォルトの切り詰めメッセージが含まれるはず
}
});
it('passes through error result unchanged', async () => {
const handler = async () =>
({ kind: 'error', message: 'Boom' }) satisfies SafeResult<unknown>;
const wrapped = wrapWithTokenLimit(handler, 1000);
const result = await wrapped({});
expect(result).toEqual({ kind: 'error', message: 'Boom' });
});
});
```
--------------------------------------------------------------------------------
/src/handlers/builders/composeToolHandler.ts:
--------------------------------------------------------------------------------
```typescript
/* eslint-disable @typescript-eslint/no-explicit-any */
import { wrapWithErrorHandling } from '../transformers/wrapWithErrorHandling.js';
import { wrapWithFieldPicking } from '../transformers/wrapWithFieldPicking.js';
import { wrapWithTokenLimit } from '../transformers/wrapWithTokenLimit.js';
import { wrapWithToolResult } from '../transformers/wrapWithToolResult.js';
import { z } from 'zod';
import { generateFieldsDescription } from '../../utils/generateFieldsDescription.js';
import { ErrorLike } from '../../types/result.js';
import { ToolDefinition } from '../../types/tool.js';
interface ComposeOptions {
useFields: boolean;
errorHandler?: (err: unknown) => ErrorLike;
maxTokens: number;
}
export function composeToolHandler(
tool: ToolDefinition<any, any>,
options: ComposeOptions
) {
const { useFields, errorHandler, maxTokens } = options;
// Step 1: Add `fields` to schema if needed
if (useFields) {
const fieldDesc = generateFieldsDescription(
tool.outputSchema,
(tool.importantFields as string[]) ?? [],
tool.name
);
tool.schema = extendSchema(tool.schema, fieldDesc);
}
// Step 2: Compose
let handler = wrapWithErrorHandling(tool.handler, errorHandler);
if (useFields) {
handler = wrapWithFieldPicking(handler);
}
return wrapWithToolResult(wrapWithTokenLimit(handler, maxTokens));
}
function extendSchema<I extends z.ZodRawShape>(
schema: z.ZodObject<I>,
desc: string
): z.ZodObject<I & { fields: z.ZodString }> {
return schema.extend({
fields: z.string().describe(desc),
}) as z.ZodObject<I & { fields: z.ZodString }>;
}
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "backlog-mcp-server",
"version": "0.4.0",
"type": "module",
"bin": {
"backlog-mcp-server": "./build/index.js"
},
"license": "MIT",
"scripts": {
"dev": "NODE_ENV=development node --loader ts-node/esm src/index.ts",
"prebuild": "node scripts/replace-version.js",
"build": "tsc && chmod 755 build/index.js",
"test": "NODE_OPTIONS=--experimental-vm-modules jest",
"test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
"lint": "eslint . --ext .ts",
"lint:fix": "eslint . --ext .ts --fix",
"format": "prettier --check \"**/*.{ts,tsx}\"",
"format:fix": "prettier --write \"**/*.{ts,tsx}\""
},
"files": [
"build"
],
"dependencies": {
"@modelcontextprotocol/sdk": "^1.9.0",
"backlog-js": "^0.13.6",
"cosmiconfig": "^9.0.0",
"dotenv": "^16.5.0",
"env-var": "^7.5.0",
"graphql": "^16.11.0",
"node-fetch": "^3.3.2",
"pino": "^9.9.0",
"pino-pretty": "^13.1.1",
"yargs": "^18.0.0",
"zod": "^3.24.3"
},
"devDependencies": {
"@eslint/js": "^9.24.0",
"@release-it/conventional-changelog": "^10.0.1",
"@types/jest": "^29.5.14",
"@types/node": "^22.14.1",
"@types/yargs": "^17.0.33",
"@typescript-eslint/eslint-plugin": "^8.30.1",
"@typescript-eslint/parser": "^8.30.1",
"@typescript-eslint/utils": "^8.30.1",
"eslint": "^9.24.0",
"eslint-config-prettier": "^10.1.2",
"eslint-plugin-prettier": "^5.2.6",
"jest": "^29.7.0",
"prettier": "^3.5.3",
"release-it": "^19.0.0",
"ts-jest": "^29.3.2",
"ts-node": "^10.9.2",
"typescript": "^5.8.3"
}
}
```
--------------------------------------------------------------------------------
/src/backlog/parseBacklogAPIError.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Converts a BacklogError (or unknown error) into Output format for MCP response
*/
type MaybeBacklogErrorObject = {
_name?: string;
_status?: number;
_url?: string;
_body?: {
errors?: {
message?: string;
code?: number;
moreInfo?: string;
}[];
};
};
export type ParsedBacklogAPIError = {
type:
| 'BacklogAuthError'
| 'BacklogApiError'
| 'UnexpectedError'
| 'UnknownError';
message: string;
status?: number;
code?: number;
url?: string;
};
export function parseBacklogAPIError(err: unknown): ParsedBacklogAPIError {
const e = err as MaybeBacklogErrorObject;
if (e._name && e._status && e._url) {
const status = e._status;
const url = e._url;
const code = e._body?.errors?.[0]?.code;
const message =
e._body?.errors?.[0]?.message ?? 'An unknown error occurred.';
if (e._name === 'BacklogAuthError') {
return {
type: 'BacklogAuthError',
message: `Authentication failed (HTTP ${status}). Please check your API key or permissions.`,
status,
url,
};
}
if (e._name === 'BacklogApiError') {
return {
type: 'BacklogApiError',
message: `Backlog API error (code: ${code}, status: ${status})\n${message}`,
status,
code,
url,
};
}
if (e._name === 'UnexpectedError') {
return {
type: 'UnexpectedError',
message: `Unexpected error (HTTP ${status}) while accessing ${url}.`,
status,
url,
};
}
}
return {
type: 'UnknownError',
message: (err as Error)?.message ?? 'An unknown error occurred.',
};
}
```
--------------------------------------------------------------------------------
/src/utils/generateFieldsDescription.ts:
--------------------------------------------------------------------------------
```typescript
import { z, ZodRawShape, ZodTypeAny } from 'zod';
/**
* Generate GraphQL like fields and type specs from Zod types
*/
export function generateFieldsDescription(
outputSchema: z.ZodObject<ZodRawShape>,
importantFields: string[] = [],
typeName = 'Output'
): string {
const allFields = Object.keys(outputSchema.shape);
// Generate Example Query
const exampleQueryFields =
importantFields.length > 0 ? importantFields : allFields;
// Generate Output Schema
const gqlTypeDef = generateGraphQLType(typeName, outputSchema);
return `
Specify the fields to retrieve using GraphQL query syntax.
Example (query):
{
${exampleQueryFields.join('\n ')}
}
Output schema (type definition):
${gqlTypeDef}
`.trim();
}
function generateGraphQLType(
typeName: string,
schema: z.ZodObject<ZodRawShape>
): string {
const lines: string[] = [`type ${typeName} {`];
for (const [key, value] of Object.entries(schema.shape)) {
lines.push(` ${key}: ${mapZodTypeToGraphQLType(value as ZodTypeAny)}`);
}
lines.push('}');
return lines.join('\n');
}
/**
* Zod to graphql
*/
function mapZodTypeToGraphQLType(zodType: z.ZodTypeAny): string {
if (zodType instanceof z.ZodString) return 'String!';
if (zodType instanceof z.ZodNumber) return 'Int!';
if (zodType instanceof z.ZodBoolean) return 'Boolean!';
if (zodType instanceof z.ZodNullable)
return mapZodTypeToGraphQLType(zodType.unwrap()).replace(/!$/, '');
if (zodType instanceof z.ZodOptional)
return mapZodTypeToGraphQLType(zodType.unwrap()).replace(/!$/, '');
// Spec: a nested part is JSON
if (zodType instanceof z.ZodObject) return 'JSON';
return 'String';
}
```
--------------------------------------------------------------------------------
/src/tools/deleteVersion.test.ts:
--------------------------------------------------------------------------------
```typescript
import { deleteVersionTool } from './deleteVersion.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('deleteVersionTool', () => {
const mockBacklog: Partial<Backlog> = {
deleteVersions: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectId: 100,
name: 'Test Version',
description: '',
startDate: null,
releaseDueDate: null,
archived: false,
displayOrder: 0,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = deleteVersionTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns deleted version information', async () => {
const result = await tool.handler({
projectKey: 'TEST',
id: 1,
});
expect(result).toHaveProperty('id', 1);
expect(result).toHaveProperty('name', 'Test Version');
});
it('calls backlog.deleteVersions with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
id: 1,
});
expect(mockBacklog.deleteVersions).toHaveBeenCalledWith('TEST', 1);
});
it('calls backlog.deleteVersions with correct params when using project ID', async () => {
await tool.handler({
projectId: 100,
id: 1,
});
expect(mockBacklog.deleteVersions).toHaveBeenCalledWith(100, 1);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = { id: 1 }; // No identifier provided
await expect(tool.handler(params)).rejects.toThrowError(Error);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getVersionMilestoneList.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getVersionMilestoneListSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_VERSION_MILESTONE_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_VERSION_MILESTONE_PROJECT_KEY',
'The key of the project (e.g., TEST_PROJECT)'
)
),
}));
export const getVersionMilestoneListTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getVersionMilestoneListSchema>,
(typeof VersionSchema)['shape']
> => {
return {
name: 'get_version_milestone_list',
description: t(
'TOOL_GET_VERSION_MILESTONE_LIST_DESCRIPTION',
'Returns list of versions/milestones in the Backlog space'
),
schema: z.object(getVersionMilestoneListSchema(t)),
outputSchema: VersionSchema,
importantFields: [
'id',
'name',
'description',
'startDate',
'releaseDueDate',
'archived',
],
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getVersions(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getWikiPages.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { WikiListItemSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getWikiPagesSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_WIKI_PAGES_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_WIKI_PAGES_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
keyword: z
.string()
.optional()
.describe(
t('TOOL_GET_WIKI_PAGES_KEYWORD', 'Keyword to search for in Wiki pages')
),
}));
export const getWikiPagesTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getWikiPagesSchema>,
(typeof WikiListItemSchema)['shape']
> => {
return {
name: 'get_wiki_pages',
description: t(
'TOOL_GET_WIKI_PAGES_DESCRIPTION',
'Returns list of Wiki pages'
),
schema: z.object(getWikiPagesSchema(t)),
outputSchema: WikiListItemSchema,
importantFields: ['projectId', 'name', 'tags'],
handler: async ({ projectId, projectKey, keyword }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getWikis({
projectIdOrKey: result.value,
keyword,
});
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getWiki.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getWikiTool } from './getWiki.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getWikiTool', () => {
const mockBacklog: Partial<Backlog> = {
getWiki: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1234,
projectId: 100,
name: 'Sample Wiki',
content: '# Sample Wiki Content\n\nThis is a sample wiki page.',
tags: [
{ id: 1, name: 'documentation' },
{ id: 2, name: 'guide' },
],
attachments: [],
sharedFiles: [],
stars: [],
createdUser: {
id: 1,
userId: 'user1',
name: 'User One',
},
created: '2023-01-01T00:00:00Z',
updated: '2023-01-02T00:00:00Z',
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getWikiTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns wiki information as formatted JSON text', async () => {
const result = await tool.handler({
wikiId: 1234,
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.name).toEqual('Sample Wiki');
expect(result.content).toContain('Sample Wiki Content');
});
it('calls backlog.getWiki with correct params when using number ID', async () => {
await tool.handler({
wikiId: 1234,
});
expect(mockBacklog.getWiki).toHaveBeenCalledWith(1234);
});
it('calls backlog.getWiki with correct params when using string ID', async () => {
await tool.handler({
wikiId: '1234',
});
expect(mockBacklog.getWiki).toHaveBeenCalledWith(1234);
});
});
```
--------------------------------------------------------------------------------
/src/tools/deleteVersion.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const deleteVersionSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_DELETE_VERSION_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_DELETE_VERSION_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
id: z
.number()
.describe(
t(
'TOOL_DELETE_VERSION_ID',
'The numeric ID of the version to delete (e.g., 67890)'
)
),
}));
export const deleteVersionTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof deleteVersionSchema>,
(typeof VersionSchema)['shape']
> => {
return {
name: 'delete_version',
description: t(
'TOOL_DELETE_VERSION_DESCRIPTION',
'Deletes a version from a project'
),
schema: z.object(deleteVersionSchema(t)),
outputSchema: VersionSchema,
handler: async ({ projectId, projectKey, id }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
if (!id) {
throw new Error(
t('TOOL_DELETE_VERSION_MISSING_ID', 'Version ID is required')
);
}
return backlog.deleteVersions(result.value, id);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getProject.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getProjectTool } from './getProject.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getProjectTool', () => {
const mockBacklog: Partial<Backlog> = {
getProject: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectKey: 'TEST',
name: 'Test Project',
chartEnabled: true,
subtaskingEnabled: true,
projectLeaderCanEditProjectLeader: false,
textFormattingRule: 'backlog',
archived: false,
displayOrder: 0,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getProjectTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns project information as formatted JSON text', async () => {
const result = await tool.handler({
projectKey: 'TEST',
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.name).toContain('Test Project');
expect(result.projectKey).toContain('TEST');
});
it('calls backlog.getProject with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
});
expect(mockBacklog.getProject).toHaveBeenCalledWith('TEST');
});
it('calls backlog.getProject with correct params when using project ID', async () => {
await tool.handler({
projectId: 1,
});
expect(mockBacklog.getProject).toHaveBeenCalledWith(1);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {}; // No identifier provided
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getCustomFields.ts:
--------------------------------------------------------------------------------
```typescript
import { Backlog } from 'backlog-js';
import { z } from 'zod';
import { ToolDefinition, buildToolSchema } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { CustomFieldSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getCustomFieldsInputSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_CUSTOM_FIELDS_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_CUSTOM_FIELDS_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
}));
export const getCustomFieldsTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getCustomFieldsInputSchema>, // Shape for input schema
(typeof CustomFieldSchema)['shape'] // Shape for output schema (single item)
> => {
const inputSchemaObject = z.object(getCustomFieldsInputSchema(t)); // Create the ZodObject for input
return {
name: 'get_custom_fields',
description: t(
'TOOL_GET_CUSTOM_FIELDS_DESCRIPTION',
'Returns list of custom fields for a project'
),
schema: inputSchemaObject,
outputSchema: CustomFieldSchema,
importantFields: [
'id',
'name',
'typeId',
'required',
'applicableIssueTypes',
],
handler: async ({ projectId, projectKey }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.getCustomFields(result.value);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/deleteProject.test.ts:
--------------------------------------------------------------------------------
```typescript
import { deleteProjectTool } from './deleteProject.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('deleteProjectTool', () => {
const mockBacklog: Partial<Backlog> = {
deleteProject: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectKey: 'TEST',
name: 'Test Project',
chartEnabled: true,
subtaskingEnabled: true,
projectLeaderCanEditProjectLeader: false,
textFormattingRule: 'backlog',
archived: false,
displayOrder: 0,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = deleteProjectTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns deleted project information', async () => {
const result = await tool.handler({
projectKey: 'TEST',
});
expect(result).toHaveProperty('projectKey', 'TEST');
expect(result).toHaveProperty('name', 'Test Project');
});
it('calls backlog.deleteProject with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
});
expect(mockBacklog.deleteProject).toHaveBeenCalledWith('TEST');
});
it('calls backlog.deleteProject with correct params when using project ID', async () => {
await tool.handler({
projectId: 1,
});
expect(mockBacklog.deleteProject).toHaveBeenCalledWith(1);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {}; // No identifier provided
// Assuming resolveIdOrKey for "project" entity throws "Project ID or key is required"
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/createTranslationHelper.test.ts:
--------------------------------------------------------------------------------
```typescript
import { createTranslationHelper } from './createTranslationHelper';
import { writeFileSync, unlinkSync } from 'fs';
import { describe, it, expect, beforeEach } from '@jest/globals';
import path from 'path';
const TEMP_CONFIG_PATH = path.resolve(
process.cwd(),
'.backlog-mcp-serverrc.json'
);
describe('createTranslationHelper', () => {
beforeEach(() => {
delete process.env.BACKLOG_MCP_HELLO;
try {
unlinkSync(TEMP_CONFIG_PATH);
} catch {
// noop: cannot do anything
}
});
it('returns fallback if no env or config is present', () => {
const { t } = createTranslationHelper({ searchDir: process.cwd() });
expect(t('HELLO', 'Fallback')).toBe('Fallback');
});
it('returns value from config file if present', () => {
writeFileSync(
TEMP_CONFIG_PATH,
JSON.stringify({ HELLO: 'From config' }, null, 2),
'utf-8'
);
const { t } = createTranslationHelper({ searchDir: process.cwd() });
expect(t('HELLO', 'Fallback')).toBe('From config');
});
it('returns value from environment variable over config', () => {
writeFileSync(
TEMP_CONFIG_PATH,
JSON.stringify({ HELLO: 'From config' }, null, 2),
'utf-8'
);
process.env.BACKLOG_MCP_HELLO = 'From env';
const { t } = createTranslationHelper({ searchDir: process.cwd() });
expect(t('HELLO', 'Fallback')).toBe('From env');
});
it('caches the first call to a key', () => {
process.env.BACKLOG_MCP_HELLO = 'Cached value';
const { t } = createTranslationHelper({ searchDir: process.cwd() });
const first = t('HELLO', 'Fallback');
process.env.BACKLOG_MCP_HELLO = 'Modified value';
const second = t('HELLO', 'Fallback');
expect(first).toBe('Cached value');
expect(second).toBe('Cached value');
});
});
```
--------------------------------------------------------------------------------
/src/backlog/customFields.test.ts:
--------------------------------------------------------------------------------
```typescript
import {
customFieldsToPayload,
type CustomFieldInput,
} from './customFields.js';
import { describe, it, expect } from '@jest/globals';
describe('customFieldsToPayload', () => {
it('returns an empty object when input is undefined', () => {
const result = customFieldsToPayload(undefined);
expect(result).toEqual({});
});
it('returns an empty object when input is null', () => {
const result = customFieldsToPayload(null as any);
expect(result).toEqual({});
});
it('converts single field with string value', () => {
const input: CustomFieldInput[] = [{ id: 100, value: 'test value' }];
const result = customFieldsToPayload(input);
expect(result).toEqual({
customField_100: 'test value',
});
});
it('converts single field with number value', () => {
const input: CustomFieldInput[] = [{ id: 101, value: 42 }];
const result = customFieldsToPayload(input);
expect(result).toEqual({
customField_101: 42,
});
});
it('converts single field with array value and otherValue', () => {
const input: CustomFieldInput[] = [
{
id: 102,
value: ['OptionA', 'OptionB'],
otherValue: 'custom input',
},
];
const result = customFieldsToPayload(input);
expect(result).toEqual({
customField_102: ['OptionA', 'OptionB'],
customField_102_otherValue: 'custom input',
});
});
it('converts multiple fields of mixed types', () => {
const input: CustomFieldInput[] = [
{ id: 201, value: 'text' },
{ id: 202, value: 123 },
{ id: 203, value: '', otherValue: 'detail' },
];
const result = customFieldsToPayload(input);
expect(result).toEqual({
customField_201: 'text',
customField_202: 123,
customField_203: '',
customField_203_otherValue: 'detail',
});
});
});
```
--------------------------------------------------------------------------------
/src/tools/getWatchingListItems.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getWatchingListItemsTool } from './getWatchingListItems.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getWatchingListItemsTool', () => {
const mockBacklog: Partial<Backlog> = {
getWatchingListItems: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
resourceAlreadyRead: false,
note: 'Important issue',
type: 'issue',
issue: {
id: 1000,
projectId: 100,
issueKey: 'TEST-1',
summary: 'Test issue',
},
created: '2023-01-01T00:00:00Z',
updated: '2023-01-01T00:00:00Z',
},
{
id: 2,
resourceAlreadyRead: true,
note: 'Important wiki',
type: 'wiki',
wiki: {
id: 2000,
projectId: 100,
name: 'Test wiki',
content: 'Wiki content',
},
created: '2023-01-02T00:00:00Z',
updated: '2023-01-02T00:00:00Z',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getWatchingListItemsTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns watching list items as formatted JSON text', async () => {
const result = await tool.handler({
userId: 1,
});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(2);
expect(result[0].note).toContain('Important issue');
expect(result[1].note).toContain('Important wiki');
});
it('calls backlog.getWatchingListItems with correct params', async () => {
await tool.handler({
userId: 1,
});
expect(mockBacklog.getWatchingListItems).toHaveBeenCalledWith(1);
});
});
```
--------------------------------------------------------------------------------
/src/utils/resolveIdOrKey.ts:
--------------------------------------------------------------------------------
```typescript
import { TranslationHelper } from '../createTranslationHelper.js';
export type EntityName = 'issue' | 'project' | 'repository';
type ResolveResult =
| { ok: true; value: string | number }
| { ok: false; error: Error };
type ResolveIdOrFieldInput<F extends string> = {
id?: number;
} & {
[K in F]?: string;
};
/**
* Generic resolver for entity identification by ID or named field (e.g., key, name, slug).
* @param entity - The entity name, e.g., "project"
* @param fieldName - The name of the alternative to `id`, e.g., "key", "name", "slug"
* @param values - An object with `id?: number` and `[fieldName]?: string`
* @param t - Translator
*/
function resolveIdOrField<E extends EntityName, F extends string>(
entity: E,
fieldName: F,
values: ResolveIdOrFieldInput<F>,
t: TranslationHelper['t']
): ResolveResult {
const value = tryResolveIdOrField(fieldName, values);
if (value === undefined) {
return {
ok: false,
error: new Error(
t(
`${entity.toUpperCase()}_ID_OR_${fieldName.toUpperCase()}_REQUIRED`,
`${capitalize(entity)} ID or ${fieldName} is required`
)
),
};
}
return { ok: true, value };
}
function tryResolveIdOrField<F extends string>(
fieldName: F,
values: ResolveIdOrFieldInput<F>
): string | number | undefined {
return values.id !== undefined ? values.id : values[fieldName];
}
export const resolveIdOrKey = <E extends EntityName>(
entity: E,
values: { id?: number; key?: string },
t: TranslationHelper['t']
): ResolveResult => resolveIdOrField(entity, 'key', values, t);
export const resolveIdOrName = <E extends EntityName>(
entity: E,
values: { id?: number; name?: string },
t: TranslationHelper['t']
): ResolveResult => resolveIdOrField(entity, 'name', values, t);
function capitalize(str: string): string {
return str.charAt(0).toUpperCase() + str.slice(1);
}
```
--------------------------------------------------------------------------------
/src/tools/addIssueComment.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { IssueCommentSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const addIssueCommentSchema = buildToolSchema((t) => ({
issueId: z
.number()
.optional()
.describe(
t(
'TOOL_ADD_ISSUE_COMMENT_ID',
'The numeric ID of the issue (e.g., 12345)'
)
),
issueKey: z
.string()
.optional()
.describe(
t('TOOL_ADD_ISSUE_COMMENT_KEY', "The key of the issue (e.g., 'PROJ-123')")
),
content: z
.string()
.describe(t('TOOL_ADD_ISSUE_COMMENT_CONTENT', 'Comment content')),
notifiedUserId: z
.array(z.number())
.optional()
.describe(
t('TOOL_ADD_ISSUE_COMMENT_NOTIFIED_USER_ID', 'User IDs to notify')
),
attachmentId: z
.array(z.number())
.optional()
.describe(t('TOOL_ADD_ISSUE_COMMENT_ATTACHMENT_ID', 'Attachment IDs')),
}));
export const addIssueCommentTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof addIssueCommentSchema>,
(typeof IssueCommentSchema)['shape']
> => {
return {
name: 'add_issue_comment',
description: t(
'TOOL_ADD_ISSUE_COMMENT_DESCRIPTION',
'Adds a comment to an issue'
),
schema: z.object(addIssueCommentSchema(t)),
outputSchema: IssueCommentSchema,
handler: async ({
issueId,
issueKey,
content,
notifiedUserId,
attachmentId,
}) => {
const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
if (!result.ok) {
throw result.error;
}
return backlog.postIssueComments(result.value, {
content,
notifiedUserId,
attachmentId,
});
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/getIssueTypes.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getIssueTypesTool } from './getIssueTypes.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getIssueTypesTool', () => {
const mockBacklog: Partial<Backlog> = {
getIssueTypes: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
projectId: 100,
name: 'Bug',
color: '#990000',
},
{
id: 2,
projectId: 100,
name: 'Task',
color: '#7ea800',
},
{
id: 3,
projectId: 100,
name: 'Request',
color: '#ff9200',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getIssueTypesTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns issue types list as formatted JSON text', async () => {
const result = await tool.handler({
projectKey: 'TEST',
});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(3);
expect(result[0].name).toContain('Bug');
expect(result[1].name).toContain('Task');
expect(result[2].name).toContain('Request');
});
it('calls backlog.getIssueTypes with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
});
expect(mockBacklog.getIssueTypes).toHaveBeenCalledWith('TEST');
});
it('calls backlog.getIssueTypes with correct params when using project ID', async () => {
await tool.handler({
projectId: 100,
});
expect(mockBacklog.getIssueTypes).toHaveBeenCalledWith(100);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {}; // No identifier provided
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/utils/toolsetUtils.ts:
--------------------------------------------------------------------------------
```typescript
import { Backlog } from 'backlog-js';
import { ToolsetGroup, Toolset } from '../types/toolsets.js';
import { allTools } from '../tools/tools.js';
import { TranslationHelper } from '../createTranslationHelper.js';
export function getToolset(
group: ToolsetGroup,
name: string
): Toolset | undefined {
return group.toolsets.find((t) => t.name === name);
}
export function enableToolset(group: ToolsetGroup, name: string): string {
const ts = getToolset(group, name);
if (!ts) return `Toolset ${name} not found`;
if (ts.enabled) return `Toolset ${name} is already enabled`;
ts.enabled = true;
return `Toolset ${name} enabled`;
}
export function getEnabledTools(group: ToolsetGroup) {
return group.toolsets.filter((ts) => ts.enabled).flatMap((ts) => ts.tools);
}
export function listAvailableToolsets(group: ToolsetGroup) {
return group.toolsets.map((ts) => ({
name: ts.name,
description: ts.description,
currentlyEnabled: ts.enabled,
canEnable: true,
}));
}
export function listToolsetTools(group: ToolsetGroup, name: string) {
const ts = getToolset(group, name);
return (
ts?.tools.map((tool) => ({
name: tool.name,
description: tool.description,
toolset: name,
canEnable: true,
})) ?? []
);
}
export const buildToolsetGroup = (
backlog: Backlog,
helper: TranslationHelper,
enabledToolsets: string[]
): ToolsetGroup => {
const toolsetGroup = allTools(backlog, helper);
const knownNames = toolsetGroup.toolsets.map((ts) => ts.name);
const unknown = enabledToolsets.filter(
(name) => name !== 'all' && !knownNames.includes(name)
);
if (unknown.length > 0) {
console.warn(`⚠️ Unknown toolsets: ${unknown.join(', ')}`);
}
const allEnabled = enabledToolsets.includes('all');
return {
toolsets: toolsetGroup.toolsets.map((ts) => ({
...ts,
enabled: allEnabled || enabledToolsets.includes(ts.name),
})),
};
};
```
--------------------------------------------------------------------------------
/src/tools/deleteIssue.test.ts:
--------------------------------------------------------------------------------
```typescript
import { deleteIssueTool } from './deleteIssue.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('deleteIssueTool', () => {
const mockBacklog: Partial<Backlog> = {
deleteIssue: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectId: 100,
issueKey: 'TEST-1',
keyId: 1,
issueType: {
id: 2,
projectId: 100,
name: 'Bug',
color: '#990000',
displayOrder: 0,
},
summary: 'Test Issue',
description: 'This is a test issue',
status: {
id: 1,
name: 'Open',
projectId: 100,
color: '#ff0000',
displayOrder: 0,
},
priority: {
id: 3,
name: 'Normal',
},
created: '2023-01-01T00:00:00Z',
updated: '2023-01-01T00:00:00Z',
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = deleteIssueTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns deleted issue information', async () => {
const result = await tool.handler({
issueKey: 'TEST-1',
});
expect(result).toHaveProperty('issueKey', 'TEST-1');
expect(result).toHaveProperty('summary', 'Test Issue');
});
it('calls backlog.deleteIssue with correct params when using issue key', async () => {
await tool.handler({
issueKey: 'TEST-1',
});
expect(mockBacklog.deleteIssue).toHaveBeenCalledWith('TEST-1');
});
it('calls backlog.deleteIssue with correct params when using issue ID', async () => {
await tool.handler({
issueId: 1,
});
expect(mockBacklog.deleteIssue).toHaveBeenCalledWith(1); // Expect number
});
it('throws an error if neither issueId nor issueKey is provided', async () => {
await expect(tool.handler({})).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getIssueComments.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { IssueCommentSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const getIssueCommentsSchema = buildToolSchema((t) => ({
issueId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_ISSUE_COMMENTS_ISSUE_ID',
'The numeric ID of the issue (e.g., 12345)'
)
),
issueKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_ISSUE_COMMENTS_ISSUE_KEY',
"The key of the issue (e.g., 'PROJ-123')"
)
),
minId: z
.number()
.optional()
.describe(t('TOOL_GET_ISSUE_COMMENTS_MIN_ID', 'Minimum comment ID')),
maxId: z
.number()
.optional()
.describe(t('TOOL_GET_ISSUE_COMMENTS_MAX_ID', 'Maximum comment ID')),
count: z
.number()
.optional()
.describe(
t('TOOL_GET_ISSUE_COMMENTS_COUNT', 'Number of comments to retrieve')
),
order: z
.enum(['asc', 'desc'])
.optional()
.describe(t('TOOL_GET_ISSUE_COMMENTS_ORDER', 'Sort order')),
}));
export const getIssueCommentsTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getIssueCommentsSchema>,
(typeof IssueCommentSchema)['shape']
> => {
return {
name: 'get_issue_comments',
description: t(
'TOOL_GET_ISSUE_COMMENTS_DESCRIPTION',
'Returns list of comments for an issue'
),
schema: z.object(getIssueCommentsSchema(t)),
outputSchema: IssueCommentSchema,
handler: async ({ issueId, issueKey, ...params }) => {
const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
if (!result.ok) {
throw result.error;
}
return backlog.getIssueComments(result.value, params);
},
};
};
```
--------------------------------------------------------------------------------
/.clinerules/commit-conventional-format.md:
--------------------------------------------------------------------------------
```markdown
# Conventional Commit Format Guide
This document describes the conventional commit message format. Use this as a reference for generating or validating commit messages via an LLM (Large Language Model).
## Format
Each commit message should follow the structure:
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
### Examples
```
feat: add login button component
fix(auth): handle token expiration error
docs(readme): update setup instructions
refactor(api): simplify request handler logic
```
## Types
Use the following standard types:
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation-only changes
- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc)
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `perf`: A code change that improves performance
- `test`: Adding missing tests or correcting existing tests
- `chore`: Changes to the build process or auxiliary tools and libraries
- `ci`: Changes to CI configuration files and scripts
- `build`: Changes that affect the build system or external dependencies
## Scope (Optional)
The scope specifies the module or area affected by the change, such as `auth`, `api`, `db`, etc.
Example:
```
fix(auth): re-validate session token after refresh
```
## Description
Keep it short and imperative, like a commit title.
Do not capitalize the first letter unless it's a proper noun, and do not add a period at the end.
## Body (Optional)
Explain what and why, not how.
Use bullet points if helpful.
## Footer (Optional)
Used for breaking changes or issue references.
Examples:
```
BREAKING CHANGE: auth tokens are now rotated every hour
```
```
Closes #123
```
## Summary
Follow this format strictly when generating commit messages programmatically or interacting with a Git workflow tool powered by LLMs. This helps ensure consistent, parsable, and meaningful commit history.
```
--------------------------------------------------------------------------------
/src/tools/getCategories.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getCategoriesTool } from './getCategories.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getCategoriesTool', () => {
const mockBacklog: Partial<Backlog> = {
getCategories: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
name: 'Bug',
displayOrder: 0,
},
{
id: 2,
name: 'Feature',
displayOrder: 1,
},
{
id: 3,
name: 'Support',
displayOrder: 2,
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getCategoriesTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns categories list as formatted JSON text', async () => {
const result = await tool.handler({
projectKey: 'TEST',
});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(3);
expect(result[0].name).toContain('Bug');
expect(result[1].name).toContain('Feature');
expect(result[2].name).toContain('Support');
});
it('calls backlog.getCategories with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
});
expect(mockBacklog.getCategories).toHaveBeenCalledWith('TEST');
});
it('calls backlog.getCategories with correct params when using project ID', async () => {
await tool.handler({
projectId: 100,
});
expect(mockBacklog.getCategories).toHaveBeenCalledWith(100);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {}; // No identifier provided
// Assuming resolveIdOrKey for "project" entity (as categories are project-specific)
// throws "Project ID or key is required"
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getGitRepository.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { GitRepositorySchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey, resolveIdOrName } from '../utils/resolveIdOrKey.js';
const getGitRepositorySchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_GIT_REPOSITORY_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_GIT_REPOSITORY_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
repoId: z
.number()
.optional()
.describe(t('TOOL_GET_GIT_REPOSITORY_REPO_ID', 'Repository ID')),
repoName: z
.string()
.optional()
.describe(t('TOOL_GET_GIT_REPOSITORY_REPO_NAME', 'Repository name')),
}));
export const getGitRepositoryTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getGitRepositorySchema>,
(typeof GitRepositorySchema)['shape']
> => {
return {
name: 'get_git_repository',
description: t(
'TOOL_GET_GIT_REPOSITORY_DESCRIPTION',
'Returns information about a specific Git repository'
),
schema: z.object(getGitRepositorySchema(t)),
outputSchema: GitRepositorySchema,
handler: async ({ projectId, projectKey, repoId, repoName }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
const repoResult = resolveIdOrName(
'repository',
{ id: repoId, name: repoName },
t
);
if (!repoResult.ok) {
throw repoResult.error;
}
return backlog.getGitRepository(result.value, String(repoResult.value));
},
};
};
```
--------------------------------------------------------------------------------
/src/utils/toolsetUtils.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, expect, it } from '@jest/globals';
import { ToolsetGroup } from '../types/toolsets.js';
import {
enableToolset,
getEnabledTools,
getToolset,
listAvailableToolsets,
listToolsetTools,
} from '../utils/toolsetUtils.js';
const mockTool = {
name: 'mock_tool',
description: 'A mock tool',
schema: { shape: {} },
handler: async () => ({ content: [] }),
outputSchema: {},
};
const toolsetGroup: ToolsetGroup = {
toolsets: [
{
name: 'test_set',
description: 'Test set',
enabled: false,
tools: [mockTool as unknown as any],
},
],
};
describe('Toolset Utils', () => {
it('getToolset returns correct toolset', () => {
const ts = getToolset(toolsetGroup, 'test_set');
expect(ts).toBeDefined();
expect(ts?.name).toBe('test_set');
});
it('enableToolset enables a toolset', () => {
const msg = enableToolset(toolsetGroup, 'test_set');
expect(msg).toContain('enabled');
expect(getToolset(toolsetGroup, 'test_set')?.enabled).toBe(true);
});
it('enableToolset returns already enabled message', () => {
const msg = enableToolset(toolsetGroup, 'test_set');
expect(msg).toContain('already enabled');
});
it('getEnabledTools returns enabled tools', () => {
const tools = getEnabledTools(toolsetGroup);
expect(tools.length).toBe(1);
expect(tools[0].name).toBe('mock_tool');
});
it('listAvailableToolsets returns all toolsets', () => {
const list = listAvailableToolsets(toolsetGroup);
expect(list.length).toBe(1);
expect(list[0].name).toBe('test_set');
expect(list[0].currentlyEnabled).toBe(true);
});
it('listToolsetTools returns tools of a toolset', () => {
const tools = listToolsetTools(toolsetGroup, 'test_set');
expect(tools.length).toBe(1);
expect(tools[0].name).toBe('mock_tool');
});
it('listToolsetTools returns empty for unknown toolset', () => {
const tools = listToolsetTools(toolsetGroup, 'unknown');
expect(tools.length).toBe(0);
});
});
```
--------------------------------------------------------------------------------
/src/tools/addWiki.test.ts:
--------------------------------------------------------------------------------
```typescript
import { addWikiTool } from './addWiki.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('addWikiTool', () => {
const mockBacklog: Partial<Backlog> = {
postWiki: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectId: 100,
name: 'Getting Started',
content: '# Welcome to the project\n\nThis is a wiki page.',
createdUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
},
created: '2023-01-01T00:00:00Z',
updatedUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
},
updated: '2023-01-01T00:00:00Z',
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = addWikiTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns created wiki as formatted JSON text', async () => {
const result = await tool.handler({
projectId: 100,
name: 'Getting Started',
content: '# Welcome to the project\n\nThis is a wiki page.',
mailNotify: false,
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.name).toEqual('Getting Started');
expect(result.content).toContain('Welcome to the project');
});
it('calls backlog.postWiki with correct params', async () => {
const params = {
projectId: 100,
name: 'Getting Started',
content: '# Welcome to the project\n\nThis is a wiki page.',
mailNotify: false,
};
await tool.handler(params);
expect(mockBacklog.postWiki).toHaveBeenCalledWith({
projectId: 100,
name: 'Getting Started',
content: '# Welcome to the project\n\nThis is a wiki page.',
mailNotify: false,
});
});
});
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithFieldPicking.ts:
--------------------------------------------------------------------------------
```typescript
import { parse, SelectionSetNode } from 'graphql';
import { isErrorLike, SafeResult } from '../../types/result.js';
export function wrapWithFieldPicking<I extends { fields?: string }, O>(
fn: (input: I) => Promise<SafeResult<O>>
): (input: I) => Promise<SafeResult<O>> {
return async (input: I) => {
const { fields, ...rest } = input;
const result = await fn(rest as I);
if (!fields || isErrorLike(result)) {
return result;
}
const selectionSet = parseFieldsSelection(fields);
const resultData = result.data;
if (Array.isArray(resultData)) {
return {
kind: 'ok',
data: resultData.map((item) =>
pickFieldsFromData(item, selectionSet)
) as unknown as O,
};
} else if (typeof result === 'object' && result !== null) {
return {
kind: 'ok',
data: pickFieldsFromData(
resultData as Record<string, unknown>,
selectionSet
) as O,
};
} else {
return result;
}
};
}
function parseFieldsSelection(fieldsString: string): SelectionSetNode {
const query = `query Dummy ${fieldsString}`;
const ast = parse(query);
const opDef = ast.definitions[0];
if (opDef.kind !== 'OperationDefinition' || !opDef.selectionSet) {
throw new Error('Invalid GraphQL fields');
}
return opDef.selectionSet;
}
function pickFieldsFromData(
data: Record<string, unknown> | null | undefined,
selectionSet: SelectionSetNode
): Record<string, unknown> {
const result: Record<string, unknown> = {};
for (const selection of selectionSet.selections) {
if (selection.kind === 'Field') {
const key = selection.name.value;
if (data != null && key in data) {
const value = data[key];
if (selection.selectionSet && value != null) {
result[key] = pickFieldsFromData(
data[key] as Record<string, unknown>,
selection.selectionSet
);
} else {
result[key] = data[key];
}
}
}
}
return result;
}
```
--------------------------------------------------------------------------------
/src/tools/getDocumentTree.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getDocumentTreeTool } from './getDocumentTree.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
// export const DocumentTreeFullSchema = z.object({
// projectId: z.string(),
// activeTree: ActiveTrashTreeSchema.optional(),
// trashTree: ActiveTrashTreeSchema.optional(),
// });
describe('getDocumentTreeTool', () => {
const mockBacklog: Partial<Backlog> = {
getDocumentTree: jest.fn<() => Promise<any>>().mockResolvedValue({
projectId: 1,
activeTree: {
id: 'Active',
children: [
{
id: '01934345404771adb2113d7792bb4351',
name: 'local test',
children: [
{
id: '019347fc760c7b0abff04b44628c94d7',
name: 'test2',
children: [
{
id: '0192ff5990da76c289dee06b1f11fa01',
name: 'aaatest234',
children: [],
emoji: '',
},
],
emoji: '',
},
],
emoji: '',
},
],
},
trashTree: {},
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getDocumentTreeTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns document tree as formatted JSON text', async () => {
const result = await tool.handler({ projectIdOrKey: 'TEST_PROJECT' });
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.projectId).toEqual(1);
expect(result.activeTree?.children).toHaveLength(1);
expect(result.activeTree?.children[0].children).toHaveLength(1);
});
it('calls backlog.getDocumentTree with correct params', async () => {
await tool.handler({ projectIdOrKey: 'TEST_PROJECT' });
expect(mockBacklog.getDocumentTree).toHaveBeenCalledWith('TEST_PROJECT');
});
});
```
--------------------------------------------------------------------------------
/src/tools/addProject.test.ts:
--------------------------------------------------------------------------------
```typescript
import { addProjectTool } from './addProject.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('addProjectTool', () => {
const mockBacklog: Partial<Backlog> = {
postProject: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectKey: 'TEST',
name: 'Test Project',
chartEnabled: true,
subtaskingEnabled: true,
projectLeaderCanEditProjectLeader: false,
textFormattingRule: 'backlog',
archived: false,
displayOrder: 0,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = addProjectTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns created project as formatted JSON text', async () => {
const result = await tool.handler({
name: 'Test Project',
key: 'TEST',
chartEnabled: true,
subtaskingEnabled: true,
});
if (Array.isArray(result)) {
throw new Error('Unexpected array result');
}
expect(result.name).toEqual('Test Project');
expect(result.projectKey).toEqual('TEST');
});
it('calls backlog.postProject with correct params', async () => {
await tool.handler({
name: 'Test Project',
key: 'TEST',
chartEnabled: true,
subtaskingEnabled: true,
});
expect(mockBacklog.postProject).toHaveBeenCalledWith({
name: 'Test Project',
key: 'TEST',
chartEnabled: true,
subtaskingEnabled: true,
projectLeaderCanEditProjectLeader: false,
textFormattingRule: 'backlog',
});
});
it('uses default values for optional parameters', async () => {
await tool.handler({
name: 'Test Project',
key: 'TEST',
});
expect(mockBacklog.postProject).toHaveBeenCalledWith({
name: 'Test Project',
key: 'TEST',
chartEnabled: false,
subtaskingEnabled: false,
projectLeaderCanEditProjectLeader: false,
textFormattingRule: 'backlog',
});
});
});
```
--------------------------------------------------------------------------------
/src/tools/addVersionMilestone.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const addVersionMilestoneSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(t('TOOL_ADD_VERSION_MILESTONE_PROJECT_ID', 'Project ID')),
projectKey: z
.string()
.optional()
.describe(t('TOOL_ADD_VERSION_MILESTONE_PROJECT_KEY', 'Project key')),
name: z
.string()
.describe(t('TOOL_ADD_VERSION_MILESTONE_NAME', 'Version name')),
description: z
.string()
.optional()
.describe(
t('TOOL_ADD_VERSION_MILESTONE_DESCRIPTION', 'Version description')
),
startDate: z
.string()
.optional()
.describe(
t('TOOL_ADD_VERSION_MILESTONE_START_DATE', 'Start date of the version')
),
releaseDueDate: z
.string()
.optional()
.describe(
t(
'TOOL_ADD_VERSION_MILESTONE_RELEASE_DUE_DATE',
'Release due date of the version'
)
),
}));
export const addVersionMilestoneTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof addVersionMilestoneSchema>,
(typeof VersionSchema)['shape']
> => {
return {
name: 'add_version_milestone',
description: t(
'TOOL_ADD_VERSION_MILESTONE_DESCRIPTION',
'Creates a new version milestone'
),
schema: z.object(addVersionMilestoneSchema(t)),
outputSchema: VersionSchema,
importantFields: [
'id',
'name',
'description',
'startDate',
'releaseDueDate',
],
handler: async ({ projectId, projectKey, ...params }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.postVersions(result.value, params);
},
};
};
```
--------------------------------------------------------------------------------
/src/registerTools.ts:
--------------------------------------------------------------------------------
```typescript
import { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
import { composeToolHandler } from './handlers/builders/composeToolHandler.js';
import { MCPOptions } from './types/mcp.js';
import { DynamicToolDefinition, ToolDefinition } from './types/tool.js';
import { DynamicToolsetGroup, ToolsetGroup } from './types/toolsets.js';
import { BacklogMCPServer } from './utils/wrapServerWithToolRegistry.js';
type ToolsetSource = ToolsetGroup | DynamicToolsetGroup;
type RegisterOptions = {
server: BacklogMCPServer;
toolsetGroup: ToolsetSource;
prefix: string;
onlyEnabled?: boolean;
handlerStrategy: (
// eslint-disable-next-line @typescript-eslint/no-explicit-any
tool: ToolDefinition<any, any> | DynamicToolDefinition<any>
// eslint-disable-next-line @typescript-eslint/no-explicit-any
) => (...args: any[]) => any;
};
export function registerTools(
server: BacklogMCPServer,
toolsetGroup: ToolsetGroup,
options: MCPOptions
) {
const { useFields, maxTokens, prefix } = options;
registerToolsets({
server,
toolsetGroup,
prefix,
handlerStrategy: (tool) =>
// eslint-disable-next-line @typescript-eslint/no-explicit-any
composeToolHandler(tool as ToolDefinition<any, any>, {
useFields,
errorHandler: backlogErrorHandler,
maxTokens,
}),
});
}
export function registerDyamicTools(
server: BacklogMCPServer,
dynamicToolsetGroup: DynamicToolsetGroup,
prefix: string
) {
registerToolsets({
server,
toolsetGroup: dynamicToolsetGroup,
prefix,
handlerStrategy: (tool) => tool.handler,
});
}
function registerToolsets({
server,
toolsetGroup,
prefix,
handlerStrategy,
}: RegisterOptions) {
for (const toolset of toolsetGroup.toolsets) {
if (!toolset.enabled) {
continue;
}
for (const tool of toolset.tools) {
const toolNameWithPrefix = `${prefix}${tool.name}`;
const handler = handlerStrategy(tool);
server.registerOnce(
toolNameWithPrefix,
tool.description,
tool.schema.shape,
handler
);
}
}
}
```
--------------------------------------------------------------------------------
/src/tools/getPullRequest.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { PullRequestSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey, resolveIdOrName } from '../utils/resolveIdOrKey.js';
const getPullRequestSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_PULL_REQUEST_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_PULL_REQUEST_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
repoId: z
.number()
.optional()
.describe(t('TOOL_GET_PULL_REQUEST_REPO_ID', 'Repository ID')),
repoName: z
.string()
.optional()
.describe(t('TOOL_GET_PULL_REQUEST_REPO_NAME', 'Repository name')),
number: z
.number()
.describe(t('TOOL_GET_PULL_REQUEST_NUMBER', 'Pull request number')),
}));
export const getPullRequestTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getPullRequestSchema>,
(typeof PullRequestSchema)['shape']
> => {
return {
name: 'get_pull_request',
description: t(
'TOOL_GET_PULL_REQUEST_DESCRIPTION',
'Returns information about a specific pull request'
),
schema: z.object(getPullRequestSchema(t)),
outputSchema: PullRequestSchema,
handler: async ({ projectId, projectKey, repoId, repoName, number }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
const repoRes = resolveIdOrName(
'repository',
{ id: repoId, name: repoName },
t
);
if (!repoRes.ok) {
throw repoRes.error;
}
return backlog.getPullRequest(
result.value,
String(repoRes.value),
number
);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/addProject.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
const addProjectSchema = buildToolSchema((t) => ({
name: z.string().describe(t('TOOL_ADD_PROJECT_NAME', 'Project name')),
key: z.string().describe(t('TOOL_ADD_PROJECT_KEY', 'Project key')),
chartEnabled: z
.boolean()
.optional()
.describe(
t(
'TOOL_ADD_PROJECT_CHART_ENABLED',
'Whether to enable chart (default: false)'
)
),
subtaskingEnabled: z
.boolean()
.optional()
.describe(
t(
'TOOL_ADD_PROJECT_SUBTASKING_ENABLED',
'Whether to enable subtasking (default: false)'
)
),
projectLeaderCanEditProjectLeader: z
.boolean()
.optional()
.describe(
t(
'TOOL_ADD_PROJECT_LEADER_CAN_EDIT',
'Whether project leaders can edit other project leaders (default: false)'
)
),
textFormattingRule: z
.enum(['backlog', 'markdown'])
.optional()
.describe(
t(
'TOOL_ADD_PROJECT_TEXT_FORMATTING',
"Text formatting rule (default: 'backlog')"
)
),
}));
export const addProjectTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof addProjectSchema>,
(typeof ProjectSchema)['shape']
> => {
return {
name: 'add_project',
description: t('TOOL_ADD_PROJECT_DESCRIPTION', 'Creates a new project'),
schema: z.object(addProjectSchema(t)),
outputSchema: ProjectSchema,
handler: async ({
name,
key,
chartEnabled,
subtaskingEnabled,
projectLeaderCanEditProjectLeader,
textFormattingRule,
}) =>
backlog.postProject({
name,
key,
chartEnabled: chartEnabled ?? false,
subtaskingEnabled: subtaskingEnabled ?? false,
projectLeaderCanEditProjectLeader:
projectLeaderCanEditProjectLeader ?? false,
textFormattingRule: textFormattingRule ?? 'backlog',
}),
};
};
```
--------------------------------------------------------------------------------
/src/utils/toolRegistrar.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, expect, it, jest } from '@jest/globals';
import { MCPOptions } from '../types/mcp';
import { ToolsetGroup } from '../types/toolsets';
import { createToolRegistrar } from '../utils/toolRegistrar';
import { BacklogMCPServer } from './wrapServerWithToolRegistry';
jest.mock('../registerTools', () => ({
registerTools: jest.fn(),
}));
const mockSendToolListChanged = jest.fn();
const serverMock = {
server: {
sendToolListChanged: mockSendToolListChanged,
},
tool: jest.fn(),
__registeredToolNames: new Set<string>(),
registerOnce: () => {},
} as unknown as BacklogMCPServer;
const options: MCPOptions = {
useFields: true,
maxTokens: 5000,
prefix: '',
};
describe('createToolRegistrar', () => {
it('enables a toolset and refreshes tool list', async () => {
const toolsetGroup: ToolsetGroup = {
toolsets: [
{
name: 'issue',
description: 'Issue toolset',
enabled: false,
tools: [],
},
],
};
const registrar = createToolRegistrar(serverMock, toolsetGroup, options);
const msg = await registrar.enableToolsetAndRefresh('issue');
expect(msg).toBe('Toolset issue enabled');
expect(toolsetGroup.toolsets[0].enabled).toBe(true);
expect(mockSendToolListChanged).toHaveBeenCalled();
});
it('returns already enabled message if toolset is already enabled', async () => {
const toolsetGroup: ToolsetGroup = {
toolsets: [
{
name: 'project',
description: 'Project toolset',
enabled: true,
tools: [],
},
],
};
const registrar = createToolRegistrar(serverMock, toolsetGroup, options);
const msg = await registrar.enableToolsetAndRefresh('project');
expect(msg).toBe('Toolset project is already enabled');
});
it('returns not found message if toolset does not exist', async () => {
const toolsetGroup: ToolsetGroup = {
toolsets: [],
};
const registrar = createToolRegistrar(serverMock, toolsetGroup, options);
const msg = await registrar.enableToolsetAndRefresh('unknown');
expect(msg).toBe('Toolset unknown not found');
});
});
```
--------------------------------------------------------------------------------
/src/tools/getNotifications.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getNotificationsTool } from './getNotifications.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getNotificationsTool', () => {
const mockBacklog: Partial<Backlog> = {
getNotifications: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
alreadyRead: false,
resourceAlreadyRead: false,
reason: 1,
user: {
id: 1,
userId: 'user1',
name: 'User One',
},
project: {
id: 1,
projectKey: 'TEST',
name: 'Test Project',
},
issue: {
id: 1,
issueKey: 'TEST-1',
summary: 'Test Issue',
},
comment: {
id: 1,
content: 'Test comment',
},
created: '2023-01-01T00:00:00Z',
},
{
id: 2,
alreadyRead: true,
resourceAlreadyRead: true,
reason: 2,
user: {
id: 2,
userId: 'user2',
name: 'User Two',
},
project: {
id: 1,
projectKey: 'TEST',
name: 'Test Project',
},
issue: {
id: 2,
issueKey: 'TEST-2',
summary: 'Another Issue',
},
created: '2023-01-02T00:00:00Z',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getNotificationsTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns notifications list as formatted JSON text', async () => {
const result = await tool.handler({});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result[0].issue?.summary).toContain('Test Issue');
expect(result[1].issue?.summary).toContain('Another Issue');
});
it('calls backlog.getNotifications with correct params', async () => {
const params = {
minId: 100,
maxId: 200,
count: 20,
order: 'desc' as const,
};
await tool.handler(params);
expect(mockBacklog.getNotifications).toHaveBeenCalledWith(params);
});
});
```
--------------------------------------------------------------------------------
/memory-bank/productContext.md:
--------------------------------------------------------------------------------
```markdown
# Product Context
## Project Purpose
The Backlog MCP Server is a server that integrates Backlog's API with the [Model Context Protocol (MCP)](https://github.com/anthropics/model-context-protocol), allowing Claude AI assistant to directly access Backlog's project management features.
## Problems Solved
1. **AI and Backlog Integration**
- Provides a means for large language models (LLMs) like Claude to access and manipulate Backlog data
- Allows users to operate Backlog through AI assistants
2. **Project Management Efficiency**
- Enables Backlog operations through natural language, reducing UI operations
- Allows complex queries and batch operations to be delegated to AI
3. **Simplified Information Access**
- Provides a unified access method to project, issue, Wiki, and Git information
- Makes it easier to retrieve information across multiple Backlog features
## Key Use Cases
1. **Project Management**
- Creating, updating, and deleting projects
- Retrieving and analyzing project information
2. **Issue Management**
- Creating, updating, and deleting issues
- Searching and listing issues
- Adding comments to issues
3. **Wiki Management**
- Retrieving and searching Wiki pages
- Analyzing Wiki information
4. **Git/Pull Request Management**
- Retrieving repository information
- Creating, updating, and commenting on pull requests
- Retrieving and analyzing pull request lists
5. **Notification Management**
- Retrieving and marking notifications as read
- Counting and resetting notification counts
6. **Watch Management**
- Retrieving lists of watched items
- Counting watches
## User Experience Goals
1. **Seamless Integration**
- Natural operation of Backlog from within Claude etc
- Operation without being conscious of complex API details
2. **Multi-language Support**
- Support for tool descriptions in multiple languages including Japanese and English
- Providing a user experience tailored to the user's language environment
3. **Flexible Deployment**
- Easy deployment via Docker
- Customization of settings through environment variables
4. **Extensibility**
- Easy adaptation to new Backlog API endpoints
- Customization of functionality through custom descriptions
```
--------------------------------------------------------------------------------
/src/tools/getVersionMilestoneList.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getVersionMilestoneListTool } from './getVersionMilestoneList.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getVersionMilestoneTool', () => {
const mockBacklog: Partial<Backlog> = {
getVersions: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
projectId: 1,
name: 'wait for release',
description: '',
startDate: null,
releaseDueDate: null,
archived: false,
displayOrder: 0,
},
{
id: 2,
projectId: 1,
name: 'v1.0.0',
description: 'First release',
startDate: '2025-01-01',
releaseDueDate: '2025-03-01',
archived: false,
displayOrder: 1,
},
{
id: 3,
projectId: 1,
name: 'v1.1.0',
description: 'Minor update',
startDate: '2025-03-01',
releaseDueDate: '2025-05-01',
archived: false,
displayOrder: 2,
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getVersionMilestoneListTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns versions list as formatted JSON text', async () => {
const result = await tool.handler({ projectId: 123 });
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(3);
expect(result[0].name).toContain('wait for release');
expect(result[1].name).toContain('v1.0.0');
expect(result[2].name).toContain('v1.1.0');
});
it('calls backlog.getVersions with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST_PROJECT',
});
expect(mockBacklog.getVersions).toHaveBeenCalledWith('TEST_PROJECT');
});
it('calls backlog.getVersions with correct params when using project ID', async () => {
await tool.handler({
projectId: 123,
});
expect(mockBacklog.getVersions).toHaveBeenCalledWith(123);
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {}; // No identifier provided
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/handlers/transformers/wrapWithFieldPicking.test.ts:
--------------------------------------------------------------------------------
```typescript
import { wrapWithFieldPicking } from './wrapWithFieldPicking';
import type { SafeResult } from '../../types/result';
import { jest, describe, it, expect } from '@jest/globals';
describe('wrapWithFieldPicking', () => {
const fullData = {
id: 1,
name: 'Project A',
config: {
mode: 'advanced',
enabled: true,
},
extra: 'should be ignored',
};
const successResult: SafeResult<typeof fullData> = {
kind: 'ok',
data: fullData,
};
const mockFn = jest.fn(async () => successResult);
it('returns full data when fields is not specified', async () => {
const wrapped = wrapWithFieldPicking(mockFn);
const result = await wrapped({});
expect(result).toEqual(successResult);
});
it('filters top-level fields', async () => {
const wrapped = wrapWithFieldPicking(mockFn);
const result = await wrapped({
fields: `{ id name }`,
});
expect(result).toEqual({
kind: 'ok',
data: {
id: 1,
name: 'Project A',
},
});
});
it('filters nested fields', async () => {
const wrapped = wrapWithFieldPicking(mockFn);
const result = await wrapped({
fields: `{ config { mode } }`,
});
expect(result).toEqual({
kind: 'ok',
data: {
config: {
mode: 'advanced',
},
},
});
});
it('returns original error if result is an error', async () => {
const errorResult = { kind: 'error', message: 'boom' } as const;
const errorFn = jest.fn(async () => errorResult);
const wrapped = wrapWithFieldPicking(errorFn);
const result = await wrapped({ fields: `{ id }` });
expect(result).toBe(errorResult);
});
it('ignores fields not in data', async () => {
const wrapped = wrapWithFieldPicking(mockFn);
const result = await wrapped({ fields: `{ id unknown }` });
expect(result).toEqual({
kind: 'ok',
data: {
id: 1,
},
});
});
it('filters arrays of objects', async () => {
const arrFn = jest.fn(
async (_) =>
({
kind: 'ok',
data: [
{ id: 1, name: 'A', unused: true },
{ id: 2, name: 'B', unused: false },
],
}) as const
);
const wrapped = wrapWithFieldPicking(arrFn);
const result = await wrapped({ fields: `{ name }` });
expect(result).toEqual({
kind: 'ok',
data: [{ name: 'A' }, { name: 'B' }],
});
});
});
```
--------------------------------------------------------------------------------
/src/tools/updateVersionMilestone.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const updateVersionMilestoneSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_UPDATE_VERSION_MILESTONE_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_UPDATE_VERSION_MILESTONE_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
id: z.number().describe(t('TOOL_UPDATE_VERSION_MILESTONE_ID', 'Version ID')),
name: z
.string()
.describe(t('TOOL_UPDATE_VERSION_MILESTONE_NAME', 'Version name')),
description: z
.string()
.optional()
.describe(
t('TOOL_UPDATE_VERSION_MILESTONE_DESCRIPTION', 'Version description')
),
startDate: z
.string()
.optional()
.describe(t('TOOL_UPDATE_VERSION_MILESTONE_START_DATE', 'Start date')),
releaseDueDate: z
.string()
.optional()
.describe(
t('TOOL_UPDATE_VERSION_MILESTONE_RELEASE_DUE_DATE', 'Release due date')
),
archived: z
.boolean()
.optional()
.describe(
t(
'TOOL_UPDATE_VERSION_MILESTONE_ARCHIVED',
'Archive status of the version'
)
),
}));
export const updateVersionMilestoneTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof updateVersionMilestoneSchema>,
(typeof VersionSchema)['shape']
> => {
return {
name: 'update_version_milestone',
description: t(
'TOOL_UPDATE_VERSION_MILESTONE_DESCRIPTION',
'Updates an existing version milestone'
),
schema: z.object(updateVersionMilestoneSchema(t)),
outputSchema: VersionSchema,
importantFields: [
'id',
'name',
'description',
'startDate',
'releaseDueDate',
'archived',
],
handler: async ({ projectId, projectKey, id, ...params }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.patchVersions(result.value, id, params);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/updateProject.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
const updateProjectSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_UPDATE_PROJECT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_UPDATE_PROJECT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
name: z
.string()
.optional()
.describe(t('TOOL_UPDATE_PROJECT_NAME', 'Project name')),
key: z
.string()
.optional()
.describe(t('TOOL_UPDATE_PROJECT_KEY', 'Project key')),
chartEnabled: z
.boolean()
.optional()
.describe(
t('TOOL_UPDATE_PROJECT_CHART_ENABLED', 'Whether to enable chart')
),
subtaskingEnabled: z
.boolean()
.optional()
.describe(
t(
'TOOL_UPDATE_PROJECT_SUBTASKING_ENABLED',
'Whether to enable subtasking'
)
),
projectLeaderCanEditProjectLeader: z
.boolean()
.optional()
.describe(
t(
'TOOL_UPDATE_PROJECT_LEADER_CAN_EDIT',
'Whether project leaders can edit other project leaders'
)
),
textFormattingRule: z
.enum(['backlog', 'markdown'])
.optional()
.describe(t('TOOL_UPDATE_PROJECT_TEXT_FORMATTING', 'Text formatting rule')),
archived: z
.boolean()
.optional()
.describe(
t('TOOL_UPDATE_PROJECT_ARCHIVED', 'Whether to archive the project')
),
}));
export const updateProjectTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof updateProjectSchema>,
(typeof ProjectSchema)['shape']
> => {
return {
name: 'update_project',
description: t(
'TOOL_UPDATE_PROJECT_DESCRIPTION',
'Updates an existing project'
),
schema: z.object(updateProjectSchema(t)),
outputSchema: ProjectSchema,
handler: async ({ projectId, projectKey, ...param }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
return backlog.patchProject(result.value, param);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/updateProject.test.ts:
--------------------------------------------------------------------------------
```typescript
import { updateProjectTool } from './updateProject.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('updateProjectTool', () => {
const mockBacklog: Partial<Backlog> = {
patchProject: jest.fn<() => Promise<any>>().mockResolvedValue({
id: 1,
projectKey: 'UPDATED',
name: 'Updated Project',
chartEnabled: true,
subtaskingEnabled: true,
projectLeaderCanEditProjectLeader: false,
textFormattingRule: 'markdown',
archived: true,
displayOrder: 0,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = updateProjectTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns updated project', async () => {
const result = await tool.handler({
projectKey: 'TEST',
name: 'Updated Project',
key: 'UPDATED',
archived: true,
});
expect(result).toHaveProperty('name', 'Updated Project');
expect(result).toHaveProperty('projectKey', 'UPDATED');
expect(result).toHaveProperty('archived', true);
});
it('calls backlog.patchProject with correct params when using project key', async () => {
await tool.handler({
projectKey: 'TEST',
name: 'Updated Project',
key: 'UPDATED',
textFormattingRule: 'markdown',
archived: true,
});
expect(mockBacklog.patchProject).toHaveBeenCalledWith('TEST', {
name: 'Updated Project',
key: 'UPDATED',
chartEnabled: undefined,
subtaskingEnabled: undefined,
projectLeaderCanEditProjectLeader: undefined,
textFormattingRule: 'markdown',
archived: true,
});
});
it('calls backlog.patchProject with correct params when using project ID', async () => {
await tool.handler({
projectId: 1,
chartEnabled: true,
subtaskingEnabled: true,
});
expect(mockBacklog.patchProject).toHaveBeenCalledWith(1, {
name: undefined,
key: undefined,
chartEnabled: true,
subtaskingEnabled: true,
projectLeaderCanEditProjectLeader: undefined,
textFormattingRule: undefined,
archived: undefined,
});
});
it('throws an error if neither projectId nor projectKey is provided', async () => {
const params = {
// projectId and projectKey are missing
name: 'Test Project Name',
};
await expect(tool.handler(params as any)).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getDocuments.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getDocumentsTool } from './getDocuments.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getDocumentsTool', () => {
const mockBacklog: Partial<Backlog> = {
getDocuments: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
projectId: 100,
title: 'Test Document 1',
content: 'This is a test document.',
createdUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
created: '2023-01-01T00:00:00Z',
updatedUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
updated: '2023-01-01T00:00:00Z',
},
{
id: 2,
projectId: 100,
title: 'Test Document 2',
content: 'This is another test document.',
createdUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
created: '2023-01-01T00:00:00Z',
updatedUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
updated: '2023-01-01T00:00:00Z',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getDocumentsTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns a list of documents as formatted JSON text', async () => {
const result = await tool.handler({ projectIds: [11], offset: 0 });
if (!Array.isArray(result)) {
throw new Error('Unexpected non-array result');
}
expect(result).toHaveLength(2);
expect(result[0].title).toContain('Test Document 1');
});
it('calls backlog.getDocuments with correct params', async () => {
await tool.handler({ projectIds: [11], offset: 0 });
expect(mockBacklog.getDocuments).toHaveBeenCalledWith({
projectId: [11],
offset: 0,
});
});
});
```
--------------------------------------------------------------------------------
/src/tools/countIssues.test.ts:
--------------------------------------------------------------------------------
```typescript
import { countIssuesTool } from './countIssues.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('countIssuesTool', () => {
const mockBacklog: Partial<Backlog> = {
getIssuesCount: jest.fn<() => Promise<any>>().mockResolvedValue({
count: 42,
}),
};
const mockTranslationHelper = createTranslationHelper();
const tool = countIssuesTool(mockBacklog as Backlog, mockTranslationHelper);
it('returns issue count', async () => {
const result = await tool.handler({
projectId: [100],
});
expect(result).toHaveProperty('count', 42);
});
it('calls backlog.getIssuesCount with correct params', async () => {
const params = {
projectId: [100],
statusId: [1],
keyword: 'bug',
};
await tool.handler(params);
expect(mockBacklog.getIssuesCount).toHaveBeenCalledWith(params);
});
it('calls backlog.getIssuesCount with date filters', async () => {
await tool.handler({
createdSince: '2023-01-01',
createdUntil: '2023-01-31',
});
expect(mockBacklog.getIssuesCount).toHaveBeenCalledWith({
createdSince: '2023-01-01',
createdUntil: '2023-01-31',
});
});
it('calls backlog.getIssuesCount with custom fields', async () => {
await tool.handler({
projectId: [100],
customFields: [
{ id: 12345, value: 'test-value' },
{ id: 67890, value: 123 },
],
});
expect(mockBacklog.getIssuesCount).toHaveBeenCalledWith({
projectId: [100],
customField_12345: 'test-value',
customField_67890: 123,
});
});
it('calls backlog.getIssuesCount with custom fields array values', async () => {
await tool.handler({
customFields: [{ id: 11111, value: ['option1', 'option2'] }],
});
expect(mockBacklog.getIssuesCount).toHaveBeenCalledWith({
customField_11111: ['option1', 'option2'],
});
});
it('calls backlog.getIssuesCount with empty custom fields', async () => {
await tool.handler({
projectId: [100],
customFields: [],
});
expect(mockBacklog.getIssuesCount).toHaveBeenCalledWith({
projectId: [100],
});
});
it('calls backlog.getIssuesCount without custom fields', async () => {
await tool.handler({
projectId: [100],
statusId: [1],
});
expect(mockBacklog.getIssuesCount).toHaveBeenCalledWith({
projectId: [100],
statusId: [1],
});
});
});
```
--------------------------------------------------------------------------------
/src/tools/addPullRequestComment.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { PullRequestCommentSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey, resolveIdOrName } from '../utils/resolveIdOrKey.js';
const addPullRequestCommentSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_ADD_PULL_REQUEST_COMMENT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_ADD_PULL_REQUEST_COMMENT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
repoId: z
.number()
.optional()
.describe(t('TOOL_ADD_PULL_REQUEST_REPO_ID', 'Repository ID')),
repoName: z
.string()
.optional()
.describe(t('TOOL_ADD_PULL_REQUEST_REPO_NAME', 'Repository name')),
number: z
.number()
.describe(t('TOOL_ADD_PULL_REQUEST_COMMENT_NUMBER', 'Pull request number')),
content: z
.string()
.describe(t('TOOL_ADD_PULL_REQUEST_COMMENT_CONTENT', 'Comment content')),
notifiedUserId: z
.array(z.number())
.optional()
.describe(
t('TOOL_ADD_PULL_REQUEST_COMMENT_NOTIFIED_USER_ID', 'User IDs to notify')
),
}));
export const addPullRequestCommentTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof addPullRequestCommentSchema>,
(typeof PullRequestCommentSchema)['shape']
> => {
return {
name: 'add_pull_request_comment',
description: t(
'TOOL_ADD_PULL_REQUEST_COMMENT_DESCRIPTION',
'Adds a comment to a pull request'
),
schema: z.object(addPullRequestCommentSchema(t)),
outputSchema: PullRequestCommentSchema,
importantFields: ['id', 'content', 'createdUser'],
handler: async ({
projectId,
projectKey,
repoId,
repoName,
number,
...params
}) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
const repoRes = resolveIdOrName(
'repository',
{ id: repoId, name: repoName },
t
);
if (!repoRes.ok) {
throw repoRes.error;
}
return backlog.postPullRequestComments(
result.value,
String(repoRes.value),
number,
params
);
},
};
};
```
--------------------------------------------------------------------------------
/src/utils/wrapServerWithToolRegistry.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, expect, it, jest, beforeEach } from '@jest/globals';
import { z } from 'zod';
import { wrapServerWithToolRegistry } from './wrapServerWithToolRegistry';
describe('wrapServerWithToolRegistry', () => {
let mockServer: any;
let toolCalls: Array<{ name: string; description: string }> = [];
beforeEach(() => {
toolCalls = [];
mockServer = {
tool: jest.fn((name: string, description: string) => {
toolCalls.push({ name, description });
}),
};
});
it('registers a tool when not already registered', () => {
const server = wrapServerWithToolRegistry(mockServer);
const schema = z.object({}).shape;
server.registerOnce('hello', 'test tool', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
expect(toolCalls).toHaveLength(1);
expect(toolCalls[0].name).toBe('hello');
});
it('skips duplicate registration', () => {
const server = wrapServerWithToolRegistry(mockServer);
const schema = z.object({}).shape;
server.registerOnce('dup', 'first', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
server.registerOnce('dup', 'second', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
expect(toolCalls).toHaveLength(1);
expect(toolCalls[0].name).toBe('dup');
expect(toolCalls[0].description).toBe('first');
});
it('does not throw if registerOnce is called twice with same name', () => {
const server = wrapServerWithToolRegistry(mockServer);
const schema = z.object({}).shape;
expect(() => {
server.registerOnce('toolX', 'desc1', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
server.registerOnce('toolX', 'desc2', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
}).not.toThrow();
expect(toolCalls).toHaveLength(1);
});
it('adds __registeredToolNames to server', () => {
const server = wrapServerWithToolRegistry(mockServer);
expect(server.__registeredToolNames).toBeInstanceOf(Set);
});
it('registers multiple distinct tools', () => {
const server = wrapServerWithToolRegistry(mockServer);
const schema = z.object({}).shape;
server.registerOnce('tool1', 'desc1', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
server.registerOnce('tool2', 'desc2', schema, () => ({
content: [{ type: 'text', text: 'ok' }],
}));
expect(toolCalls).toHaveLength(2);
expect(toolCalls[0].name).toBe('tool1');
expect(toolCalls[1].name).toBe('tool2');
});
});
```
--------------------------------------------------------------------------------
/src/tools/getIssueComments.test.ts:
--------------------------------------------------------------------------------
```typescript
import { getIssueCommentsTool } from './getIssueComments.js';
import { jest, describe, it, expect } from '@jest/globals';
import type { Backlog } from 'backlog-js';
import { createTranslationHelper } from '../createTranslationHelper.js';
describe('getIssueCommentsTool', () => {
const mockBacklog: Partial<Backlog> = {
getIssueComments: jest.fn<() => Promise<any>>().mockResolvedValue([
{
id: 1,
content: 'This is the first comment',
changeLog: [],
createdUser: {
id: 1,
userId: 'admin',
name: 'Admin User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
created: '2023-01-01T00:00:00Z',
updated: '2023-01-01T00:00:00Z',
},
{
id: 2,
content: 'This is the second comment',
changeLog: [],
createdUser: {
id: 5,
userId: 'user',
name: 'Test User',
roleType: 1,
lang: 'en',
mailAddress: '[email protected]',
lastLoginTime: '2023-01-01T00:00:00Z',
},
created: '2023-01-02T00:00:00Z',
updated: '2023-01-02T00:00:00Z',
},
]),
};
const mockTranslationHelper = createTranslationHelper();
const tool = getIssueCommentsTool(
mockBacklog as Backlog,
mockTranslationHelper
);
it('returns issue comments', async () => {
const result = await tool.handler({
issueKey: 'TEST-1',
});
if (!Array.isArray(result)) {
throw new Error('Unexpected non array result');
}
expect(result).toHaveLength(2);
expect(result[0]).toHaveProperty('content', 'This is the first comment');
expect(result[1]).toHaveProperty('content', 'This is the second comment');
});
it('calls backlog.getIssueComments with correct params when using issue key', async () => {
await tool.handler({
issueKey: 'TEST-1',
count: 10,
order: 'desc',
});
expect(mockBacklog.getIssueComments).toHaveBeenCalledWith('TEST-1', {
count: 10,
order: 'desc',
});
});
it('calls backlog.getIssueComments with correct params when using issue ID and min/max IDs', async () => {
await tool.handler({
issueId: 1,
minId: 100,
maxId: 200,
});
expect(mockBacklog.getIssueComments).toHaveBeenCalledWith(1, {
// Expect number
minId: 100,
maxId: 200,
});
});
it('throws an error if neither issueId nor issueKey is provided', async () => {
await expect(tool.handler({})).rejects.toThrow(Error);
});
});
```
--------------------------------------------------------------------------------
/src/tools/getPullRequestsCount.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { PullRequestCountSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey, resolveIdOrName } from '../utils/resolveIdOrKey.js';
const getPullRequestsCountSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_GET_PULL_REQUESTS_COUNT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_GET_PULL_REQUESTS_COUNT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
repoId: z
.number()
.optional()
.describe(t('TOOL_GET_PULL_REQUESTS_COUNT_REPO_ID', 'Repository ID')),
repoName: z
.string()
.optional()
.describe(t('TOOL_GET_PULL_REQUESTS_COUNT_REPO_NAME', 'Repository name')),
statusId: z
.array(z.number())
.optional()
.describe(t('TOOL_GET_PULL_REQUESTS_COUNT_STATUS_ID', 'Status IDs')),
assigneeId: z
.array(z.number())
.optional()
.describe(
t('TOOL_GET_PULL_REQUESTS_COUNT_ASSIGNEE_ID', 'Assignee user IDs')
),
issueId: z
.array(z.number())
.optional()
.describe(t('TOOL_GET_PULL_REQUESTS_COUNT_ISSUE_ID', 'Issue IDs')),
createdUserId: z
.array(z.number())
.optional()
.describe(
t('TOOL_GET_PULL_REQUESTS_COUNT_CREATED_USER_ID', 'Created user IDs')
),
}));
export const getPullRequestsCountTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof getPullRequestsCountSchema>,
(typeof PullRequestCountSchema)['shape']
> => {
return {
name: 'get_pull_requests_count',
description: t(
'TOOL_GET_PULL_REQUESTS_COUNT_DESCRIPTION',
'Returns count of pull requests for a repository'
),
schema: z.object(getPullRequestsCountSchema(t)),
outputSchema: PullRequestCountSchema,
handler: async ({ projectId, projectKey, repoId, repoName, ...params }) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
const repoResult = resolveIdOrName(
'repository',
{ id: repoId, name: repoName },
t
);
if (!repoResult.ok) {
throw repoResult.error;
}
return backlog.getPullRequestsCount(
result.value,
String(repoResult.value),
params
);
},
};
};
```
--------------------------------------------------------------------------------
/src/tools/updatePullRequestComment.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from 'zod';
import { Backlog } from 'backlog-js';
import { buildToolSchema, ToolDefinition } from '../types/tool.js';
import { TranslationHelper } from '../createTranslationHelper.js';
import { PullRequestCommentSchema } from '../types/zod/backlogOutputDefinition.js';
import { resolveIdOrKey, resolveIdOrName } from '../utils/resolveIdOrKey.js';
const updatePullRequestCommentSchema = buildToolSchema((t) => ({
projectId: z
.number()
.optional()
.describe(
t(
'TOOL_UPDATE_PULL_REQUEST_COMMENT_PROJECT_ID',
'The numeric ID of the project (e.g., 12345)'
)
),
projectKey: z
.string()
.optional()
.describe(
t(
'TOOL_UPDATE_PULL_REQUEST_COMMENT_PROJECT_KEY',
"The key of the project (e.g., 'PROJECT')"
)
),
repoId: z
.number()
.optional()
.describe(t('TOOL_UPDATE_PULL_REQUEST_COMMENT_REPO_ID', 'Repository ID')),
repoName: z
.string()
.optional()
.describe(
t('TOOL_UPDATE_PULL_REQUEST_COMMENT_REPO_NAME', 'Repository name')
),
number: z
.number()
.describe(
t('TOOL_UPDATE_PULL_REQUEST_COMMENT_NUMBER', 'Pull request number')
),
commentId: z
.number()
.describe(t('TOOL_UPDATE_PULL_REQUEST_COMMENT_COMMENT_ID', 'Comment ID')),
content: z
.string()
.describe(t('TOOL_UPDATE_PULL_REQUEST_COMMENT_CONTENT', 'Comment content')),
}));
export const updatePullRequestCommentTool = (
backlog: Backlog,
{ t }: TranslationHelper
): ToolDefinition<
ReturnType<typeof updatePullRequestCommentSchema>,
(typeof PullRequestCommentSchema)['shape']
> => {
return {
name: 'update_pull_request_comment',
description: t(
'TOOL_UPDATE_PULL_REQUEST_COMMENT_DESCRIPTION',
'Updates a comment on a pull request'
),
schema: z.object(updatePullRequestCommentSchema(t)),
outputSchema: PullRequestCommentSchema,
importantFields: ['id', 'content', 'createdUser', 'updated'],
handler: async ({
projectId,
projectKey,
repoId,
repoName,
number,
commentId,
content,
}) => {
const result = resolveIdOrKey(
'project',
{ id: projectId, key: projectKey },
t
);
if (!result.ok) {
throw result.error;
}
const repoResult = resolveIdOrName(
'repository',
{ id: repoId, name: repoName },
t
);
if (!repoResult.ok) {
throw repoResult.error;
}
return backlog.patchPullRequestComments(
result.value,
String(repoResult.value),
number,
commentId,
{ content }
);
},
};
};
```