内容
<div align="center">
<img src="assets/header.jpg" alt="Jason-MCP" width="340">
# Jason-MCP
**一款适用于讨厌处理 YouTrack 繁琐事务的人的功能齐全的 YouTrack MCP。**
*冲刺、团队报告、名称感知操作和官方 MCP 遗忘的通知收件箱。*
</div>
---
Jason-MCP 是一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，允许 Claude（和任何 MCP 客户端）驱动 **JetBrains YouTrack** — 读取和写入问题，移动冲刺，报告开发人员/团队的 story points，分配人员，检查等待您的事项。它使用纯字符串，不使用脆弱的 API 对象，因此常见操作直接生效。
> **新来这里 / 为队友设置？**
> → [docs/INTRODUCTION.md](docs/INTRODUCTION.md) — 一页宣传 ·
> [docs/INSTALL.md](docs/INSTALL.md) — 安装并连接，约 10 分钟 ·
> [skills/README.md](skills/README.md) — 单词技能包。
## ✨ 这里的精细调整
除了标准的 YouTrack 工具外，Jason-MCP 还添加了：
- **🗂️ 模式感知自定义字段** — 字段类型从问题本身读取，因此任何状态/枚举/用户字段更新正确（不再出现 `StateBundleElement` 类型错误），并且可以 **清除** 字段（一次性取消所有人）。
- **🏃 冲刺操作** — 在冲刺之间移动问题，滚动冲刺，获取冲刺内容。
- **📊 团队报告** — 每个开发人员和每个团队的 story points。
- **🙋 名称感知操作** — 按 **显示名称** 而非登录名分配、设置审查人和 @-提及人员。Jason-MCP 为您解析名称。
- **🔔 通知收件箱** — 显示官方 MCP 未公开的提及和评论活动。
有关完整列表，请参阅 **[FINE_TUNED_FEATURES.md](FINE_TUNED_FEATURES.md)**，并参阅 **[BLOCKED_OPERATIONS.md](BLOCKED_OPERATIONS.md)** 以了解自定义字段修复程序以及修复原因。
## 🚀 快速参考 — 常见操作
这些使用 **经过验证的简单字符串格式**。传递纯字符串，而不是嵌套对象。
### 状态、优先级、指派人、类型、估算
```python
update_issue_state("DEMO-123", "进行中")
update_issue_priority("DEMO-123", "关键")
update_issue_assignee("DEMO-123", "john.doe") # 或显示名称： "John Doe"
update_issue_type("DEMO-123", "错误")
update_issue_estimation("DEMO-123", "4h") # 30m · 4h · 2d · 1w · "3d 5h"
```
### 自定义字段（及其清除）
```python
# 一次设置多个
update_custom_fields("DEMO-123", {"优先级": "关键", "类型": "错误"})
# 清除字段 — None 清空它们（取消指派所有人，清空团队等）
update_custom_fields("DEMO-123", {
"指派人": None,
"审查人": None,
"团队": None,
})
update_issue_assignee("DEMO-123", "未指派") # 也清除指派人
```
### 查找、创建、链接、评论
```python
search_issues("登录中的错误")
get_project_issues("DEMO")
get_issue("DEMO-123")
create_issue(project_id="DEMO", summary="登录系统中的错误",
description="用户无法使用特殊字符登录")
add_dependency("DEMO-123", "DEMO-124")
add_relates_link("DEMO-123", "DEMO-125")
add_comment("DEMO-123", "已修复登录错误")
get_issue_comments("DEMO-123")
```
### 附件
```python
get_issue_raw("DEMO-123") # 原始数据，包括附件
get_attachment_content("DEMO-123", "1-456") # 下载为 base64
delete_attachment("DEMO-123", "1-456") # 需要权限
```
## 🛠️ 安装和运行（从源代码）
Jason-MCP 直接从此仓库运行在 stdio 上 — 无需 Docker 或 npm 包。
```bash
git clone https://github.com/jasonsteinman/youtrack-mcp.git
cd youtrack-mcp
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
设置您的凭证（或将它们放在 `.env` 文件中 — 自动加载）：
```bash
export YOUTRACK_URL="https://your-instance.youtrack.cloud"
export YOUTRACK_API_TOKEN="perm-XXXXXXXX..."
```
然后运行它：
```bash
python main.py # stdio（默认，用于 MCP 客户端）
python main.py --transport sse --port 8000 # 或 SSE over HTTP
python main.py --version
```
### 将其连接到 Claude
将 Jason-MCP 添加到您的 MCP 客户端配置（例如 Claude Desktop / Claude Code），指向此仓库的 `main.py`:
```json
{
"mcpServers": {
"youtrack": {
"command": "python",
"args": ["/absolute/path/to/youtrack-mcp/main.py"],
"env": {
"YOUTRACK_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_API_TOKEN": "perm-XXXXXXXX..."
}
}
}
}
```
## ⚙️ 配置
| 变量 | 目的 |
|---|---|
| `YOUTRACK_URL` | 您的 YouTrack 实例 URL |
| `YOUTRACK_API_TOKEN` | 您的 YouTrack 永久 API 令牌 |
| `YOUTRACK_VERIFY_SSL` | SSL 验证（默认：`true`） |
| `ENABLED_TOOLS` | 允许列表 — 仅启用这些工具（禁用所有其他工具） |
| `DISABLED_TOOLS` | 禁用列表 — 禁用特定工具 |
**工具过滤** 使上下文保持精简。工具名称不区分大小写，并将 `-`/`_` 视为相同；`ENABLED_TOOLS` 优先于 `DISABLED_TOOLS`。过滤在启动时发生。
```bash
export ENABLED_TOOLS="get_issue,search_issues,update_issue_state" # 允许列表
export DISABLED_TOOLS="delete_issue,delete_attachment" # 禁用列表
```
## 🧪 开发
```bash
pip install -r requirements.txt
python -m pytest tests/unit -q # 运行单元测试套件
```
自定义字段修复程序在 `tests/unit/test_custom_field_schema_aware.py` 中涵盖。
## 🐱 关于名称
Jason-MCP. 小猫只是为了提高士气。
## 💬 支持
有疑问、错误或想法？打开一个 [问题](https://github.com/jasonsteinman/youtrack-mcp/issues) 或联系我：**maintainer@example.com**。
---
<sub>从 [`tonyzorin/youtrack-mcp`](https://github.com/tonyzorin/youtrack-mcp) 分叉并精细调整。感谢原始作者为基础工作。</sub>
