jira-helper

י

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

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

הערה חשובה: ל-JIRA קיים שרת MCP רשמי מ-Atlassian עם 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 מחובר (gh auth login).

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 בשורש הפרויקט (מצורף כאן כדוגמה):

{
  "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