使用说明

🔧 MCP Atlassian（注：MCP可能指“Most Common Problem”或特定于Atlassian的某个项目/产品缩写，但在此上下文中未给出具体含义，因此直接保留原样）

为AI Agent打造的超轻量级高性能Atlassian MCP服务器

Model Context Protocol服务器，使Claude、ChatGPT等AI Agent能够直接控制Jira和Confluence。基于Rust 4.4MB 二进制文件罗 零拷贝优化哇 快速执行速度 提供。

韩语 | 英语

📖 目录

为什么是mcp-atlassian？
AI Agent应用实例
开始第三阶段
环境变量详细指南
Jira搜索字段优化
技术栈
项目结构
开发
安全
故障排除
参考资料
许可证
贡献

🤖 为什么是mcp-atlassian？

当AI Agent使用Atlassian时 优化后的体验提供：

🚀 基于Rust的高性能自托管

4.4MB 单一二进制文件无需单独运行时环境
立即执行以原生二进制快速启动
低资源Rust的内存效率

✨ 通过ADF完美支持实现丰富文本格式化

原生支持Atlassian文档格式

四工具ADF完美支持: jira_create_issue， jira_update_issue， jira_add_comment， jira_update_comment
自动转换普通文本 → 自动转换为ADF（100%向下兼容）
验证优化<1毫秒文档验证（仅顶层）
零拷贝处理使用ADF文档移动语义高效处理大容量文档

支持格式：

街区/区块标题（H1-H6）、代码块（语法高亮）、列表（有序/无序）
**直线（或“直排”，根据上下文，“인라인”在特定领域如滑冰或排版中可能有不同的翻译）**粗体，斜体，内联代码
重叠完美支持复杂文档结构

示例：

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": {"level": 2},
      "content": [{"type": "text", "text": "버그 수정"}]
    },
    {
      "type": "codeBlock",
      "attrs": {"language": "rust"},
      "content": [{"type": "text", "text": "fn main() { ... }"}]
    }
  ]
}

🎯 为AI Agent优化响应

智能过滤，最大化代币效率

Jira搜索优化

17个核心领域排除description，移除不必要的字段
自动过滤自动移除avatarUrls、iconUrl、self等元数据
环境变量控制按项目定制字段设置
优先级层次API → 环境变量 → 默认值 + 自定义 → 默认值

基本17个字段：

key, summary, status, priority, issuetype, assignee,
reporter, creator, created, updated, duedate, resolutiondate,
project, labels, components, parent, subtasks

响应大小比较：

기본 응답: ~50+ 필드, 대용량 description 포함
최적화 응답: 17개 필드, 핵심 정보만 (60-70% 감소)

条件编译优化

生产构建完全移除Stats追踪，移除Arc<Mutex<>>的开销
测试构建调试功能完美保留
结果零开销生产执行

🔧 14个MCP工具

Jira（8个） - 4个工具支持ADF：

jira_search - JQL搜索（优化的17个字段）
jira_get_issue - 查看问题详情
jira_create_issue ✨ - 创建问题（ADF支持）
jira_update_issue ✨ - 问题修复（ADF支持）
jira_add_comment ✨ - 添加评论（ADF支持）
jira_update_comment ✨ - 评论修改（ADF支持）
jira_transition_issue - 状态转换
jira_get_transitions - 可能的转换查询

汇合点（6个）：

confluence_search - CQL 检索
confluence_get_page - 页面查看
confluence_get_page_children - 子页面列表
confluence_get_comments - 查看评论
confluence_create_page - 创建页面
confluence_update_page - 修改页面

🔒 安全的访问控制

项目/空间过滤仅访问特定项目/空间
基于环境变量的认证API Token安全管理
专用HTTPS所有通信加密

💬 AI Agent应用示例

在Claude Desktop中

사용자: "이번 주 생성된 버그 목록 보여줘"
→ AI Agent가 jira_search 도구 자동 호출
→ 최적화된 17개 필드 응답 (토큰 절약)
→ Zero-copy로 빠른 응답

사용자: "PROJ-123에 코드 리뷰 완료 댓글 달아줘"
→ AI Agent가 jira_add_comment 도구 호출
→ 일반 텍스트가 자동으로 ADF로 변환
→ Move 시맨틱스로 효율적 처리

사용자: "포맷팅된 릴리즈 노트 이슈 만들어줘"
→ AI Agent가 jira_create_issue 호출
→ ADF 형식으로 제목, 코드 블록, 리스트 자동 생성
→ Zero-copy로 대용량 문서도 빠르게 처리

사용자: "댓글 10042를 '승인됨'으로 수정해줘"
→ AI Agent가 jira_update_comment 도구 호출
→ ADF 포맷팅 지원과 함께 댓글 수정
→ std::mem::replace로 복사 없는 업데이트

사용자: "프로젝트 README 페이지 만들어줘"
→ AI Agent가 confluence_create_page 도구 호출
→ 스페이스 자동 확인 및 페이지 생성

🚀 开始第三步

前提条件： 需要安装 Rust 1.90+（安装指南) 总耗时： ~10分钟（如果已安装Rust）⚡

1️⃣ 构建（⏱️ ~5分钟）

# Rust 설치 (1.90+)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 저장소 클론
git clone https://github.com/junyeong-ai/mcp-atlassian.git
cd mcp-atlassian

# Release 빌드 (LTO + 최적화)
cargo build --release

# 바이너리 위치: target/release/mcp-atlassian (4.4MB)

2️⃣ 设置环境变量 (⏱️ 约3分钟)

.env 文件创建：

# 필수 (3개)
ATLASSIAN_DOMAIN=yourcompany.atlassian.net
ATLASSIAN_EMAIL=you@example.com
ATLASSIAN_API_TOKEN=your_api_token_here

# 선택 - 필드 최적화 (기본: 17개 필드)
JIRA_SEARCH_DEFAULT_FIELDS=key,summary,status,assignee
JIRA_SEARCH_CUSTOM_FIELDS=customfield_10015,customfield_10016

# 선택 - 응답 최적화 (기본 25개 필드 자동 제거, 추가 필드만 지정)
# RESPONSE_EXCLUDE_FIELDS=customField1,customField2

# 선택 - 접근 제어
JIRA_PROJECTS_FILTER=PROJ1,PROJ2
CONFLUENCE_SPACES_FILTER=SPACE1,SPACE2

# 선택 - 성능
REQUEST_TIMEOUT_MS=30000
LOG_LEVEL=warn

生成API令牌： Atlassian API令牌

3️⃣ 连接 Claude Desktop（⏱️ 约2分钟）

claude_desktop_config.json 编辑：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "atlassian": {
      "command": "/Users/yourname/mcp-atlassian/target/release/mcp-atlassian",
      "env": {
        "ATLASSIAN_DOMAIN": "yourcompany.atlassian.net",
        "ATLASSIAN_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

重启 Claude Desktop → 🎉 准备就绪！

🎛️ 环境变量详细指南

字段优化

`JIRA_SEARCH_DEFAULT_FIELDS`

完全替代整个基本字段。

# 최소 필드만 요청 (최대 최적화)
JIRA_SEARCH_DEFAULT_FIELDS=key,summary,status,assignee

`JIRA_SEARCH_CUSTOM_FIELDS`

在基本的17个字段基础上扩展附加字段。

# 기본 17개 + 커스텀 필드 2개 = 총 19개
JIRA_SEARCH_CUSTOM_FIELDS=customfield_10015,customfield_10016

`RESPONSE_EXCLUDE_FIELDS`

从所有响应中移除特定字段（令牌优化）。

# 기본값 (25개 필드, 20-30% 토큰 절감):
# - UI 메타데이터: avatarUrls, iconUrl, profilePicture, icon, avatarId,
#                  colorName, iconCssClass
# - API 메타데이터: expand, _expandable, self
# - 고정값: accountType, projectTypeKey, simplified, entityType
# - 빈 객체/배열: childTypes, macroRenderedOutput, restrictions, breadcrumbs
# - 워크플로우 메타데이터: hasScreen, isAvailable, isConditional, isGlobal,
#                        isInitial, isLooped
# - 중복 데이터: friendlyLastModified

# 추가 필드만 지정 (기본 25개는 자동 적용)
RESPONSE_EXCLUDE_FIELDS=customField1,customField2

现场决定优先级：

┌─────────────────────────────────┐
│ 1. API fields 파라미터           │  ← 최우선 (명시적 요청)
└─────────────────────────────────┘
           ↓ (없으면)
┌─────────────────────────────────┐
│ 2. JIRA_SEARCH_DEFAULT_FIELDS   │  ← 기본값 완전 대체
└─────────────────────────────────┘
           ↓ (없으면)
┌─────────────────────────────────┐
│ 3. 기본 17개 필드                │  ← 내장 기본값
│    + JIRA_SEARCH_CUSTOM_FIELDS  │     (선택적 확장)
└─────────────────────────────────┘
           ↓ (모든 응답에 적용)
┌─────────────────────────────────┐
│ 4. RESPONSE_EXCLUDE_FIELDS      │  ← 불필요 메타데이터 제거
└─────────────────────────────────┘

访问控制

`JIRA_PROJECTS_FILTER`

仅允许访问特定Jira项目：

JIRA_PROJECTS_FILTER=TEAM1,TEAM2,PROJ3

如果AI Agent在JQL中未明确指定项目，则自动添加过滤器：

사용자 JQL: status = Open
실제 실행: project IN ("TEAM1","TEAM2","PROJ3") AND (status = Open)

`CONFLUENCE_SPACES_FILTER`

仅允许访问特定的Confluence空间：

CONFLUENCE_SPACES_FILTER=TEAM,DOCS,KB

性能调优

`REQUEST_TIMEOUT_MS`

API请求超时（默认：30000毫秒）：

REQUEST_TIMEOUT_MS=10000  # 빠른 실패 (네트워크 빠른 환경)
REQUEST_TIMEOUT_MS=60000  # 느린 네트워크 대응

`LOG_LEVEL`

日志详细程度（默认：警告）：

LOG_LEVEL=error  # 에러만
LOG_LEVEL=info   # 상세 로그
LOG_LEVEL=debug  # 디버깅용

🔍 Jira 搜索字段优化

基本17个字段（按类别划分）

类别	字段	说明
🔑（这表示一个钥匙形状的符号，直接翻译为中文可以是“钥匙”）识别	`key`	问题唯一密钥（例如：PROJ-123）
📝 核心元数据	`summary`	问题标题
	`status`	当前状态（开放、进行中等）
	`priority`	优先级（高、中、低）
	`issuetype`	问题类型（Bug、任务、故事等）
人群负责人	`assignee`	分配的负责人
	`reporter`	问题报告者
	`creator`	问题创建者
📅 日期	`created`	创建日期
	`updated`	最后修改日期
	`duedate`	截止日期
	`resolutiondate`	解决日期
标签：分类	`project`	项目信息
	`labels`	标签列表
	`components`	组件列表
🌳（一棵树）阶层	`parent`	上级问题
	`subtasks`	子问题列表

被排除的字段

**description**大容量文本字段（仅在详细查看时包含）
id： key和重复
**renderedFields**渲染后的HTML（expand=-渲染字段）

实战应用

# 방법 1: API 호출 시 명시 (최우선)
{
  "jql": "project = KEY",
  "fields": ["key", "summary", "status"]
}

# 방법 2: 환경변수로 기본값 변경
JIRA_SEARCH_DEFAULT_FIELDS=key,summary,status,assignee

# 방법 3: 기본값에 추가
JIRA_SEARCH_CUSTOM_FIELDS=customfield_10015

# 방법 4: 응답에서 불필요 필드 제거 (기본 25개 자동 적용, 추가만 지정)
# RESPONSE_EXCLUDE_FIELDS=customField1,customField2

📊 技术栈

组件	技术	特点
语言	Rust 1.90+（2024版）	内存安全，高性能
运行时	Tokyo 1.47	异步 I/O
HTTP（超文本传输协议）	Reqwest 0.12 (rustls)	支持 TLS 1.2+
序列化	Serde 1.0	JSON处理
记录（日志）	Tracing 0.1	结构化日志记录
构建优化	LTO + Strip	4.4MB 二进制文件

API版本

**Jira（注：Jira是一个项目管理和问题跟踪工具，直接音译为“吉拉”或保持原名不译也是常见的做法，具体根据语境和需求选择。）**REST API v3
**Confluence（此处可译为“汇合点”或根据上下文具体翻译，若指软件则保留原名）**REST API v2（仅搜索为v1）

MCP协议

通过标准输入输出（stdio）的JSON-RPC 2.0
支持版本： 2024-11-05， 2025-06-18

🏗️ 项目结构

src/
├── main.rs                   # 진입점
├── config/
│   └── mod.rs                # 환경변수 관리
├── mcp/
│   ├── server.rs             # MCP 프로토콜 서버
│   ├── handlers.rs           # 도구 등록
│   └── types.rs              # MCP 타입 정의
├── tools/
│   ├── handler.rs            # ToolHandler trait
│   ├── response_optimizer.rs # 응답 최적화
│   ├── jira/
│   │   ├── mod.rs            # 8개 Jira 도구
│   │   ├── adf_utils.rs      # ADF 검증 & 변환
│   │   └── field_filtering.rs # 필드 최적화
│   └── confluence/
│       ├── mod.rs            # 6개 Confluence 도구
│       └── field_filtering.rs # API 최적화
└── utils/
    ├── http_utils.rs         # HTTP 클라이언트
    └── logging.rs            # 구조화된 로깅

🛠️ 开发

构建/建造

# 개발 빌드
cargo build

# Release 빌드 (최적화, 28초)
cargo build --release

# 직접 실행
cargo run

# 타입 체크만
cargo check

测试

# 전체 테스트 (180개, 0.05초)
cargo test

# 출력 포함
cargo test -- --nocapture

# 특정 테스트
cargo test test_config_validation

# ADF 테스트만
cargo test adf_utils::tests

代码质量

# 포맷팅
cargo fmt

# Lint (zero warnings policy)
cargo clippy

# 전체 검사
cargo check && cargo clippy && cargo test

发布构建设置

[profile.release]
opt-level = 3       # 최대 최적화
lto = true          # Link-time optimization
codegen-units = 1   # 단일 코드 생성
strip = true        # 심볼 제거

结果4.4MB 优化后的二进制文件

🔐 安全

认证

方式HTTP 基本认证
格式: Authorization: Basic base64(email:api_token)
发送专用HTTPS

输入验证

必需参数验证
JQL/CQL通过Atlassian API传递
JSON模式验证
ADF结构验证

访问控制

项目/空间过滤（服务器端）
自定义过滤器优先
无法绕过

❓ 故障排除

在Claude Desktop上工具不显示

解决方案：

检查设置文件

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop 完全重启
- 在菜单中选择“Quit”（不是简单关闭窗口）
- 重新运行

二进制路径确认

# 바이너리가 존재하는지 확인
ls -la target/release/mcp-atlassian

# 실행 권한 확인
chmod +x target/release/mcp-atlassian

Atlassian API 连接失败

原因1：API令牌错误

Atlassian API令牌在其中新建
.env 文件或 claude_desktop_config.json确认是否已正确设置

原因2：域名设置错误

# 올바른 형식 (https:// 포함하지 않음)
ATLASSIAN_DOMAIN=yourcompany.atlassian.net

# 잘못된 형식
ATLASSIAN_DOMAIN=https://yourcompany.atlassian.net  ❌

原因3：网络超时

# 타임아웃 증가 (기본: 30000ms)
REQUEST_TIMEOUT_MS=60000

我只想访问特定的项目

JIRA_PROJECTS_FILTER 使用：

JIRA_PROJECTS_FILTER=PROJ1,PROJ2,PROJ3

详细内容请见访问控制请参阅相关部分。

我想添加自定义字段

JIRA_SEARCH_CUSTOM_FIELDS 使用：

JIRA_SEARCH_CUSTOM_FIELDS=customfield_10015,customfield_10016

详细内容请见字段优化请参阅相关部分。

查看日志的方法

# .env 파일에서 로그 레벨 변경
LOG_LEVEL=debug  # error, warn, info, debug, trace 중 선택

# macOS에서 서버 로그 확인 (Claude Desktop 로그)
tail -f ~/Library/Logs/Claude/mcp*.log

# 또는 직접 실행하여 로그 확인
./target/release/mcp-atlassian

📚 参考资料

Atlassian API

MCP

Rust（一种系统编程语言）

📝 许可证

MIT 许可证 - 许可证文件引用

🤝 贡献

欢迎提交Issue和Pull Request！

叉子
创建功能分支 (git checkout -b feature/amazing)
提交更改 (git commit -m 'Add amazing feature')
分支推送（git push origin feature/amazing)
创建拉取请求

用Rust打造的超轻量级高性能MCP服务器，专为AI Agent设计 🦀（螃蟹）

使用说明

🔧 MCP Atlassian（注：MCP可能指“Most Common Problem”或特定于Atlassian的某个项目/产品缩写，但在此上下文中未给出具体含义，因此直接保留原样）

📖 目录

🤖 为什么是mcp-atlassian？

🚀 基于Rust的高性能自托管

✨ 通过ADF完美支持实现丰富文本格式化

🎯 为AI Agent优化响应

Jira搜索优化

条件编译优化

🔧 14个MCP工具

🔒 安全的访问控制

💬 AI Agent应用示例

在Claude Desktop中

🚀 开始第三步

1️⃣ 构建（⏱️ ~5分钟）

2️⃣ 设置环境变量 (⏱️ 约3分钟)

3️⃣ 连接 Claude Desktop（⏱️ 约2分钟）

🎛️ 环境变量详细指南

字段优化

JIRA_SEARCH_DEFAULT_FIELDS

JIRA_SEARCH_CUSTOM_FIELDS

RESPONSE_EXCLUDE_FIELDS

访问控制

JIRA_PROJECTS_FILTER

CONFLUENCE_SPACES_FILTER

性能调优

REQUEST_TIMEOUT_MS

LOG_LEVEL

🔍 Jira 搜索字段优化

基本17个字段（按类别划分）

被排除的字段

实战应用

📊 技术栈

API版本

MCP协议

🏗️ 项目结构

🛠️ 开发

构建/建造

测试

代码质量

发布构建设置

🔐 安全

认证

输入验证

访问控制

❓ 故障排除

在Claude Desktop上工具不显示

Atlassian API 连接失败

我只想访问特定的项目

我想添加自定义字段

查看日志的方法

📚 参考资料

Atlassian API

MCP

Rust（一种系统编程语言）

📝 许可证

🤝 贡献

相关 MCP

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

Claude Code开发工具包

区块链交互服务器

语言服务器协议模型上下文协议

`JIRA_SEARCH_DEFAULT_FIELDS`

`JIRA_SEARCH_CUSTOM_FIELDS`

`RESPONSE_EXCLUDE_FIELDS`

`JIRA_PROJECTS_FILTER`

`CONFLUENCE_SPACES_FILTER`

`REQUEST_TIMEOUT_MS`

`LOG_LEVEL`