@habby/server-youtrack NPM

YouTrack MCP 服务

YouTrack API 集成服务，提供了一套完整的 TypeScript 接口用于与 YouTrack REST API 进行交互。现在支持作为 MCP (Model Context Protocol) 服务运行，可以通过 npx 直接运行。

功能特性

问题管理
- 获取问题列表
- 获取问题详情
- 创建新问题
- 更新问题状态
- 更新问题优先级
- 更新问题类型
评论管理
- 添加评论（支持纯文本、Markdown、HTML格式）
- 更新评论
- 删除评论
看板管理
- 获取看板列表
- 获取看板详情
- 将问题添加到看板
- Sprint 管理
时间跟踪
- 更新问题估算时间
- 更新问题已花费时间

环境要求

Node.js >= 14.0.0
TypeScript >= 4.0.0

安装

作为项目依赖安装

npm install @habby/server-youtrack

通过 npx 直接运行

npx @habby/server-youtrack

配置

在项目根目录创建 .env 文件，添加以下配置：

YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud/youtrack
YOUTRACK_TOKEN=your-permanent-token

注意： 1. YOUTRACK_BASE_URL 应该包含完整的 API 路径 2. YOUTRACK_TOKEN 需要具有足够的权限来执行相应的操作

MCP 服务使用

通过 npx 直接运行 MCP 服务

# 设置环境变量
export YOUTRACK_BASE_URL="https://habby.youtrack.cloud/youtrack/api"
export YOUTRACK_TOKEN="your-permanent-token"

# 运行 MCP 服务
npx @habby/youtrack-mcp

使用 mcp.config.json 配置文件

创建 mcp.config.json 文件：

{
  "services": {
    "youtrack": {
      "command": "npx",
      "args": [
        "-y",
        "@habby/server-youtrack"
      ],
      "env": {
        "YOUTRACK_BASE_URL": "https://habby.youtrack.cloud/youtrack",
        "YOUTRACK_TOKEN": "your-permanent-token"
      }
    }
  }
}

MCP 服务 API 端点

启动服务后，可以通过以下端点访问 MCP 服务：

POST /mcp/youtrack - MCP 服务主端点，接受 JSON 格式的请求体，包含 action 和 params 字段
GET /mcp/health - 健康检查端点

示例请求：

{
  "action": "getIssues",
  "params": {
    "query": "project: YourProject"
  }
}

支持的 action 类型：

getIssues - 获取问题列表
getIssueById - 获取问题详情
addIssueComment - 添加评论
updateIssueComment - 更新评论
deleteIssueComment - 删除评论
getBoards - 获取看板列表
getBoardById - 获取看板详情

使用示例

import { YouTrackService } from './services/YouTrackService';
import dotenv from 'dotenv';

// 加载环境变量
dotenv.config();

// 创建 YouTrack 服务实例
const youTrackService = new YouTrackService(
  process.env.YOUTRACK_BASE_URL!,
  process.env.YOUTRACK_TOKEN!
);

// 获取问题列表
async function getIssues() {
  try {
    const result = await youTrackService.getIssues({
      $top: 10,
      query: 'project: YourProject'
    });
    console.log('问题列表：', result.issues);
  } catch (error) {
    console.error('获取问题列表失败：', error);
  }
}

// 添加评论
async function addComment(issueId: string) {
  try {
    const comment = await youTrackService.addIssueComment(
      issueId,
      '这是一条测试评论',
      'plain'  // 可选：'plain'、'markdown'、'html'
    );
    console.log('评论已添加：', comment);
  } catch (error) {
    console.error('添加评论失败：', error);
  }
}

API 文档

YouTrackService 类

构造函数

constructor(baseUrl: string, token: string)

问题管理

// 获取问题列表
async getIssues(options?: {
  $skip?: number;
  $top?: number;
  query?: string;
  fields?: string;
}): Promise<{ total: number; issues: YouTrackIssue[] }>

// 获取问题详情
async getIssueById(issueId: string): Promise<YouTrackIssue>

// 创建新问题
async createIssue(issue: YouTrackIssue): Promise<YouTrackIssue>

评论管理

// 添加评论
async addIssueComment(
  issueId: string,
  text: string,
  textFormat: 'plain' | 'markdown' | 'html' = 'plain'
): Promise<YouTrackComment>

// 更新评论
async updateIssueComment(
  issueId: string,
  commentId: string,
  text: string,
  textFormat: 'plain' | 'markdown' | 'html' = 'plain'
): Promise<YouTrackComment>

// 删除评论
async deleteIssueComment(issueId: string, commentId: string): Promise<void>

看板管理

// 获取看板列表
async getBoards(): Promise<YouTrackBoard[]>

// 获取看板详情
async getBoardById(boardId: string): Promise<YouTrackBoard>

// 将问题添加到看板
async addIssueToBoard(issueId: string, boardId: string): Promise<void>