# jira-sisoog-mcp

MCP سرور برای Jira خودمیزبان (`jira.sisoog.com`) تا از داخل Cursor تسک‌ها را مدیریت و worklog ثبت کنید.

## پیش‌نیاز

- Node.js 18+
- دسترسی به Jira (یوزرنیم + پسورد یا Personal Access Token)

## نصب

```bash
cd E:/jira-mcp
npm install
npm run build
```

## تنظیمات

این متغیرهای محیطی لازم است:

| متغیر | توضیح |
|--------|--------|
| `JIRA_BASE_URL` | آدرس Jira (پیش‌فرض: `https://jira.sisoog.com`) |
| `JIRA_USERNAME` | نام کاربری Jira |
| `JIRA_API_TOKEN` | پسورد یا PAT |
| `JIRA_AUTH_TYPE` | `basic` (پیش‌فرض) یا `bearer` |

نمونه: فایل `.env.example` را ببینید. برای Cursor، مقادیر را در کانفیگ MCP بگذارید (نه در گیت).

اگر Jira Data Center از Personal Access Token پشتیبانی می‌کند، همان را در `JIRA_API_TOKEN` بگذارید. برای PATهای Bearer مقدار `JIRA_AUTH_TYPE=bearer` را ست کنید؛ در غیر این صورت `basic` کافی است.

## اتصال به Cursor

در `%USERPROFILE%\.cursor\mcp.json`:

```json
{
  "mcpServers": {
    "jira-sisoog": {
      "command": "node",
      "args": ["E:/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.sisoog.com",
        "JIRA_USERNAME": "YOUR_USER",
        "JIRA_API_TOKEN": "YOUR_PASSWORD_OR_PAT",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}
```

بعد Cursor را ری‌استارت کنید یا MCP را Reload کنید. نمونه کامل: `mcp.cursor.example.json`.

## استفاده

در چت Cursor می‌توانید بگویید:

- تسک‌های In Progress من را بیاور
- جزئیات APP-1851 را نشان بده
- ۲ ساعت لاگ کار برای دیروز روی APP-1851 بزن
- ورک‌لاگ ۲۱۸۰۷ را به ۱ دقیقه تغییر بده
- APP-1851 را Done کن
- روی APP-1851 کامنت بگذار: ...

نمونه پرامپت کوتاه:

```text
تسک‌های باز من رو لیست کن
روی APP-1851 برای سه روز پیش 2h لاگ بزن
همین لاگ رو ویرایش کن بکن 1m
APP-1851 رو Done کن
```

### ابزارهای MCP

| Tool | کار |
|------|-----|
| `jira_myself` | تست لاگین و پروفایل کاربر |
| `jira_my_open_issues` | تسک‌های بازِ assign‌شده به من |
| `jira_search` | جستجو با JQL |
| `jira_get_issue` | جزئیات یک ایشو |
| `jira_update_issue` | آپدیت summary / description / labels / assignee |
| `jira_add_comment` | افزودن کامنت |
| `jira_get_transitions` | لیست انتقال وضعیت |
| `jira_transition_issue` | تغییر وضعیت |
| `jira_add_worklog` | ثبت زمان |
| `jira_get_worklogs` | لیست ورک‌لاگ‌ها |
| `jira_update_worklog` | ویرایش ورک‌لاگ |
| `jira_delete_worklog` | حذف ورک‌لاگ |

### نمونه JQL

```text
assignee = currentUser() AND status = "In Progress"
assignee = currentUser() AND resolution = Unresolved ORDER BY updated DESC
project = APP AND updated >= -7d
```

### فرمت زمان worklog

مثل Jira: `1h`, `30m`, `2h 15m`, `1m`

تاریخ شروع (اختیاری): ISO مثل `2026-08-08T10:00:00`

## توسعه

```bash
npm run dev    # اجرای مستقیم با tsx
npm run build  # کامپایل به dist/
npm start      # اجرای dist
```

## نکته امنیتی

رمز یا توکن را در گیت commit نکنید. فقط در `mcp.json` محلی یا متغیر محیطی سیستم بگذارید.

## عیب‌یابی

| مشکل | کار پیشنهادی |
|------|----------------|
| MCP در Cursor دیده نمی‌شود | مسیر `dist/index.js` و ری‌استارت Cursor را چک کنید |
| `401 Unauthorized` | یوزرنیم/پسورد یا PAT و `JIRA_AUTH_TYPE` را بررسی کنید |
| `403 Forbidden` روی worklog | دسترسی Log Work در Jira را چک کنید |
| ابزار جدید نیست | بعد از `npm run build` سرور MCP را Reload کنید |