י

שרת [MCP](https://modelcontextprotocol.io) בפייתון שנותן ל-Claude (או לכל כלי AI שתומך ב-MCP)
כלים לקרוא ולכתוב ל-JIRA Cloud, וגשר קטן שמחבר טיקטים לקומיטים ב-GitHub.

הפרויקט נבנה כתרגיל למידה: להבין מה זה MCP מבפנים, ולא רק להשתמש בשרת מוכן.

> **הערה חשובה:** ל-JIRA קיים [שרת MCP רשמי מ-Atlassian](https://github.com/atlassian/atlassian-mcp-server)
> עם 72+ כלים. לעבודה יומיומית הוא עדיף. השרת הזה נבנה כדי **ללמוד**, לא כדי להחליף אותו.

## מה זה עושה

הזרימה שהפרויקט מדגים מקצה לקצה:

```
מסמך אפיון (Word)  →  Claude קורא ומפרק  →  create_issue  →  אפיקים ומשימות ב-JIRA
```

חלוקת העבודה שחשוב להבין:

| מי | עושה מה |
|-----|---------|
| **Claude** | קורא את מסמך האפיון, מבין את המבנה, מפרק לאפיקים ומשימות |
| **השרת הזה** | מבצע את הכתיבה בפועל ל-JIRA דרך ה-API |

השרת לא יודע כלום על מסמכי אפיון — הוא רק חושף כלים מדויקים. זו כל המהות של MCP.

## הכלים

| כלי | סוג | מה הוא עושה |
|-----|-----|-------------|
| `check_jira_connection` | 📖 קריאה | בודק שהאימייל והטוקן נכונים |
| `list_projects` | 📖 קריאה | רשימת הפרויקטים שיש לך גישה אליהם |
| `list_issues` | 📖 קריאה | כל הטיקטים בפרויקט, מסודרים לפי היררכיה |
| `get_issue` | 📖 קריאה | פרטי טיקט בודד |
| `create_issue` | ✍️ כתיבה | יוצר אפיק או משימה. `parent_key` מקשר משימה לאפיק |
| `delete_issue` | ⚠️ מחיקה | מוחק טיקט. בלתי הפיך — יש לאשר לפני שימוש |
| `trace_issue_to_code` | 📖 קריאה | הגשר: פרטי הטיקט מ-JIRA + הקומיטים ב-GitHub שמזכירים אותו |

## התקנה

דורש Python 3.10+, ולכלי הגשר גם [GitHub CLI](https://cli.github.com/) מחובר (`gh auth login`).

```bash
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## הגדרה

1. צור API token ב-<https://id.atlassian.com/manage-profile/security/api-tokens>
2. העתק `.env.example` ל-`.env` ומלא את הערכים:

```
JIRA_URL=https://your-site.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-token-here
```

**`.env` לא נשמר בגיט** — הטוקן הוא סוד. הקוד קורא אותו ממשתני סביבה, לא מתוך הקוד עצמו.

## חיבור לכלי AI

השרת הוא אותו קובץ אחד בכל הכלים — רק קובץ ההגדרות שונה. **החלף את הנתיבים לנתיבים שלך.**

**Claude Code** — קובץ `.mcp.json` בשורש הפרויקט (מצורף כאן כדוגמה):

```json
{
  "mcpServers": {
    "jira-helper": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\jira_server.py"]
    }
  }
}
```

**VS Code** — אותו תוכן בקובץ `.vscode/mcp.json`, אבל המפתח נקרא `servers` במקום `mcpServers`.

**Cursor** — אותו תוכן בקובץ `.cursor/mcp.json` (מפתח `mcpServers`).

> אחרי **כל** שינוי בקוד השרת צריך להפעיל אותו מחדש — התהליך שרץ מחזיק את הקוד הישן בזיכרון,
> והכלי שמר את רשימת הכלים מזמן החיבור.

## מבנה הפרויקט

| קובץ | תפקיד |
|------|--------|
| `jira_server.py` | שרת ה-MCP — כל הכלים |
| `server.py` | שרת נפרד ל-GitHub (נבנה ראשון כתרגיל, לפני JIRA) |
| `.mcp.json` | רישום השרת ב-Claude Code |
| `.env.example` | תבנית להגדרות (העתק ל-`.env`) |
| `requirements.txt` | התלויות |
| `spec_github_security.docx` | מסמך אפיון לדוגמה, ששימש להדגמת הזרימה |

## מה נלמד כאן

- **`@mcp.tool()`** הופך פונקציית פייתון לכלי ש-AI יכול להפעיל
- ה-**docstring אינו הערה** — Claude קורא אותו כדי להבין מתי ואיך להשתמש בכלי
- **סודות מחוץ לקוד**, במשתני סביבה
- הפרדה בין כלי **קריאה** (בטוחים) לכלי **כתיבה/מחיקה** (דורשים אישור)
- **היררכיה ב-JIRA**: שדה `parent` הוא מה שמקשר משימה לאפיק
- ה-JIRA API דורש תיאורים בפורמט **ADF** ולא טקסט פשוט

## רישיון

MIT