npm package: @habby/server-youtrack
Description: YouTrack MCP Service for Model Context Protocol
Author: Habby
Latest version: 1.0.17

# 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

## 安装

### 作为项目依赖安装

```bash
npm install @habby/server-youtrack
```

### 通过 npx 直接运行

```bash
npx @habby/server-youtrack
```

## 配置

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

```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 服务

```bash
# 设置环境变量
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` 文件：

```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` - 健康检查端点

示例请求：

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

支持的 `action` 类型：

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

## 使用示例

```typescript
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 类

#### 构造函数

```typescript
constructor(baseUrl: string, token: string)
```

#### 问题管理

```typescript
// 获取问题列表
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>
```

#### 评论管理

```typescript
// 添加评论
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>
```

#### 看板管理

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

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

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

## 运行测试

```bash
npm test
```

## 注意事项

1. API 调用限制
   - 建议在测试中添加适当的延迟，避免触发 API 限流
   - 使用 `fields` 参数指定需要的字段，减少响应数据大小

2. 错误处理
   - 所有 API 调用都应该包含适当的错误处理
   - 特别注意处理权限相关的错误（HTTP 403）

3. 权限要求
   - 不同的操作可能需要不同的权限级别
   - 建议使用最小权限原则配置 token

## 许可证

MIT

## 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request