habby-youtrack-mcp

v1.0.10

Published

a year ago

YouTrack MCP 服务器，提供 YouTrack API 的转发服务

Downloads

0High
0Medium
0Low

y736674690

youtrack mcp api

Habby YouTrack MCP 服务器

这是一个基于 Model Context Protocol (MCP) 的 YouTrack API 服务器实现，提供了 YouTrack API 的转发服务。

功能

该服务器实现了以下 YouTrack API 转发服务：

基础功能

获取敏捷看板列表：GET ${baseUrl}/api/agiles
获取问题列表：GET ${baseUrl}/api/issues
创建问题：POST ${baseUrl}/api/issues
获取项目列表：GET ${baseUrl}/api/admin/projects
获取用户列表：GET ${baseUrl}/api/users

高级功能 (v1.0.3+)

获取问题历史记录：GET ${baseUrl}/api/issues/{issueId}/activities
批量更新问题：POST ${baseUrl}/api/commands
导出问题数据为CSV格式：基于问题查询结果生成CSV
获取工作项统计信息：GET ${baseUrl}/api/issues/{issueId}/timeTracking/workItems
添加问题关联关系：POST ${baseUrl}/api/issues/{sourceIssueId}/links
更新问题：POST ${baseUrl}/api/issues/{issueId}
添加问题评论：POST ${baseUrl}/api/issues/{issueId}/comments
添加工作项（记录工时）：POST ${baseUrl}/api/issues/{issueId}/timeTracking/workItems
添加问题到敏捷看板：POST ${baseUrl}/api/commands

版本历史

v1.0.10 (2025-03-11)

优化依赖：移除了不必要的 axios 依赖包
减小包体积，提高安装速度

v1.0.9 (2025-03-10)

改进功能：优化添加问题关联关系的实现
修正命令格式，使用 YouTrack 命令系统添加问题关联
添加对关联说明的支持，可选参数 comment
完善错误处理和日志输出

v1.0.8 (2025-03-10)

新增功能：创建问题时支持绑定到敏捷看板
修正命令格式，使用正确的 YouTrack 命令格式来添加问题到敏捷看板和 Sprint
修复类型错误，确保正确处理 Promise
添加获取创建后的问题详情的逻辑
更新文档，添加新功能的使用示例

安装

# 克隆仓库
git clone <仓库地址>
cd habby-youtrack-mcp

# 安装依赖
npm install

# 构建项目
npm run build

配置

在使用前，需要设置以下环境变量：

# YouTrack 服务器地址
export YOUTRACK_BASE_URL=https://youtrack.example.com

# YouTrack API 令牌
export YOUTRACK_TOKEN=your_youtrack_token

使用方法

作为命令行工具

npm start

作为依赖库

import { Server } from "habby-youtrack-mcp";

// 初始化服务器
const server = new Server();

高级功能使用示例

获取问题历史记录

{
  "name": "get_issue_history",
  "arguments": {
    "issueId": "PROJECT-123"
  }
}

批量更新问题

{
  "name": "batch_update_issues",
  "arguments": {
    "issueIds": ["PROJECT-123", "PROJECT-124"],
    "command": "Priority Normal"
  }
}

导出问题数据为CSV格式

{
  "name": "export_issues_to_csv",
  "arguments": {
    "query": "sort by: updated desc limit: 100"
  }
}

获取工作项统计信息

{
  "name": "get_work_items_stats",
  "arguments": {
    "issueId": "PROJECT-123"
  }
}

添加问题关联关系

{
  "name": "add_issue_link",
  "arguments": {
    "sourceIssueId": "PROJECT-123",
    "targetIssueId": "PROJECT-124",
    "linkType": "relates to",
    "comment": "通过 API 添加关联"
  }
}

可用的关联类型包括：relates to, depends on, is required for, duplicates, is duplicated by, parent for, subtask of

参数说明：

sourceIssueId：源问题ID（必填）
targetIssueId：目标问题ID（必填）
linkType：关联类型（必填）
comment：关联说明（可选）

更新问题

{
  "name": "update_issue",
  "arguments": {
    "issueId": "PROJECT-123",
    "summary": "更新后的问题标题",
    "description": "更新后的问题描述",
    "customFields": [
      {
        "name": "Priority",
        "$type": "EnumField",
        "value": "Critical"
      }
    ],
    "muteUpdateNotifications": true
  }
}

添加问题评论

{
  "name": "add_issue_comment",
  "arguments": {
    "issueId": "PROJECT-123",
    "text": "这是一条评论内容",
    "muteNotifications": false
  }
}

添加工作项（记录工时）

{
  "name": "add_work_item",
  "arguments": {
    "issueId": "PROJECT-123",
    "duration": {
      "minutes": 120
    },
    "date": "2025-03-10",
    "type": "Development",
    "text": "实现新功能"
  }
}

添加问题到敏捷看板

{
  "name": "add_issues_to_agile",
  "arguments": {
    "agileId": "1-0",
    "issueIds": ["PROJECT-123", "PROJECT-124"],
    "sprintId": "1-1",
    "columnId": "1-2"
  }
}

或者通过敏捷看板名称添加：

{
  "name": "add_issues_to_agile",
  "arguments": {
    "agileName": "我的敏捷看板",
    "issueIds": ["PROJECT-123", "PROJECT-124"],
    "sprintName": "Sprint 1"
  }
}

获取项目列表

{
  "name": "get_projects",
  "arguments": {
    "fields": ["id", "name", "shortName", "description"],
    "skip": 0,
    "top": 10
  }
}

获取用户列表

{
  "name": "get_users",
  "arguments": {
    "query": "name: John",
    "fields": ["id", "login", "name", "email"],
    "skip": 0,
    "top": 10
  }
}

API 工具

获取敏捷看板列表

{
  "name": "get_agiles",
  "arguments": {
    "baseUrl": "https://youtrack.example.com",
    "fields": ["id", "name", "owner", "projects", "sprints"],
    "skip": 0,
    "top": 10
  }
}

获取问题列表

{
  "name": "get_issues",
  "arguments": {
    "baseUrl": "https://youtrack.example.com",
    "query": "project: MyProject",
    "sort": "updated desc",
    "fields": ["id", "summary", "description", "created", "updated"],
    "skip": 0,
    "top": 20
  }
}

创建问题

{
  "name": "create_issue",
  "arguments": {
    "baseUrl": "https://youtrack.example.com",
    "project": "MyProject",
    "summary": "问题标题",
    "description": "问题描述",
    "assignee": "user123",
    "tags": ["bug", "critical"],
    "state": "Open",
    "estimation": "2h",
    "priority": "Normal",
    "agileBoard": "我的敏捷看板",
    "customFields": [
      {
        "name": "CustomField",
        "value": "CustomValue"
      }
    ]
  }
}

agileBoard 参数是可选的，如果提供，创建的问题将自动绑定到指定的敏捷看板。

优先级可用值

创建问题时，可以使用以下优先级值：

Unknown - 未知优先级
Show-stopper - 阻止发布
Critical - 关键
Major - 重要
Normal - 普通
Minor - 次要

错误处理

服务器实现了完善的错误处理机制，包括：

参数验证错误
资源未找到错误
认证失败错误
权限不足错误
API 速率限制错误
资源冲突错误

开发

# 启动开发模式
npm run dev