MCP Atlassian

MCP Atlassian

用于与 Atlassian 产品（Confluence 和 Jira）交互的模型上下文协议（MCP）服务，提供全面的工具。

概述

此 MCP 服务允许 AI Agent 通过标准化接口与 Atlassian 产品交互。它提供了丰富的工具，用于：

• Confluence：通过 v2 REST API 执行完整的 CRUD 操作、内容搜索、空间管理、页面管理、评论、标签等
• Jira：问题管理、项目操作、状态转换、评论以及全面的工作流支持

主要功能

• 现代 API 支持：使用 Confluence v2 REST API，并在搜索功能中回退至 v1
• 全面的工具集：包含 18+ 个 Confluence 工具和 8+ 个 Jira 工具，涵盖所有主要操作
• 安全与隐私：内置 PII 过滤和 SSL 验证控制
• 灵活配置：支持分别配置服务 URL、身份验证方式和工具筛选
• 分页支持：v2 API 使用基于游标的分页，v1 API 使用偏移量/限制分页
• 错误处理：提供全面的错误处理和详细错误信息
• 类型安全：使用 TypeScript 完整实现，并提供适当的类型定义

前提条件

• Node.js（v16 或更高版本）
• npm 或 yarn
• 拥有 API token 的 Atlassian 账户
• Docker（可选，用于容器化部署）

安装

标准安装

1. 克隆代码仓库：

   git clone https://github.com/yourusername/mcp-atlassian.git
   cd mcp-atlassian
   

2. 安装依赖项：

   npm install
   # or using make
   make install
   

3. 在根目录中创建 .env 文件，并填入你的 Atlassian 凭据：

   ATLASSIAN_HOST=https://your-domain.atlassian.net
   [email protected]
   ATLASSIAN_API_TOKEN=your-api-token
   

Docker 安装

1. 克隆代码仓库：

   git clone https://github.com/yourusername/mcp-atlassian.git
   cd mcp-atlassian
   

2. 按上述说明创建 .env 文件。

3. 构建并运行 Docker 容器：

   # Build the Docker image
   make docker-build
   
   # Run the Docker container
   make docker-run
   
   # Or use Docker Compose
   make docker-compose
   

用法

启动服务

# Using npm
npm start

# Using make
make start

# Using Docker
make docker-run

这将启动 MCP 服务，通过可流式 HTTP 进行监听和响应。

MCP 配置

    "mcp-searchapi": {
      "name": "mcp-searchapi",
      "type": "streamable-http",
      "streamable": true,
      "url": "http://localhost:3007/mcp"
    }

可用工具

Confluence 工具

搜索与发现：

• search_confluence：使用 v1 API 和 CQL 搜索 Confluence 中的内容

  • 参数：searchText（字符串）、spaceKey（字符串，可选）、limit（数字）、start（数字）

• search_confluence_pages_by_title：使用 v2 API 按标题搜索页面

  • 参数：title（字符串，可选）、spaceId（字符串，可选）、limit（数字）、cursor（字符串，可选）

空间管理：

• get_confluence_space_by_id_or_key：获取特定 Confluence 空间的信息

  • 参数：spaceIdOrKey（字符串）

• get_confluence_spaces：获取所有可用空间

  • 参数：limit（数字，可选）、cursor（字符串，可选）

页面管理：

• get_confluence_content：按 ID 获取特定页面的内容

  • 参数：pageId（字符串）、bodyFormat（枚举：storage/atlas_doc_format/wiki，可选）

• get_confluence_pages：获取某个空间中的所有页面

  • 参数：spaceId（字符串）、limit（数字，可选）、cursor（字符串，可选）

• get_confluence_child_pages：获取特定页面的子页面

  • 参数：pageId（字符串）、limit（数字，可选）、cursor（字符串，可选）

• confluence_create_page：创建新的 Confluence 页面

  • 参数：spaceId（字符串）、title（字符串）、content（字符串）、status（枚举，可选）、representation（枚举，可选）、parentId（字符串，可选）

• confluence_update_page：更新现有页面

  • 参数：pageId（字符串）、title（字符串）、content（字符串）、version（数字）、status（枚举，可选）、representation（枚举，可选）、versionMessage（字符串，可选）

• update_confluence_page_title：仅更新页面标题

  • 参数：pageId（字符串）、title（字符串）、status（枚举，可选）

• confluence_delete_page：删除 Confluence 页面

  • 参数：pageId（字符串）

标签管理：

• get_confluence_pages_by_label：查找带有特定标签的页面

  • 参数：label（字符串）、spaceId（字符串，可选）、limit（数字，可选）、cursor（字符串，可选）

• get_confluence_page_labels：获取特定页面的标签

  • 参数：pageId（字符串）、limit（数字，可选）、cursor（字符串，可选）

• add_confluence_page_labels：为页面添加标签

  • 参数：pageId（字符串）、labels（字符串数组）

评论：

• get_confluence_page_comments：获取页面上的常规评论

  • 参数：pageId（字符串）、limit（数字，可选）、cursor（字符串，可选）

• add_confluence_page_comment：为页面添加评论

  • 参数：pageId（字符串）、content（字符串）、representation（枚举，可选）

• get_confluence_page_inline_comments：获取页面上的行内评论

  • 参数：pageId（字符串）、limit（数字，可选）、cursor（字符串，可选）

• create_confluence_footer_comment：创建页脚评论

  • 参数：pageId（字符串，可选）、blogPostId（字符串，可选）、parentCommentId（字符串，可选）、attachmentId（字符串，可选）、customContentId（字符串，可选）、content（字符串）、representation（枚举，可选）

Jira 工具

• search_jira_issues：使用 JQL（Jira 查询语言）搜索问题

  • 参数：jql（字符串）、maxResults（数字，可选）

• get_jira_issue：获取特定问题的详细信息

  • 参数：issueKey（字符串）

• jira_get_all_projects：获取所有可访问的项目

  • 参数：无

• jira_create_issue：创建新的 Jira 问题

  • 参数：projectKey（字符串）、issueType（字符串）、summary（字符串）、description（字符串，可选）、其他字段

• jira_update_issue：更新现有问题

  • 参数：issueKey（字符串）、fields（包含更新数据的对象）

• jira_add_comment：为问题添加评论

  • 参数：issueKey（字符串）、comment（字符串）

• jira_get_transitions：获取问题可用的状态转换

  • 参数：issueKey（字符串）

• jira_transition_issue：将问题转换为其他状态

  • 参数：issueKey（字符串）、transitionId（字符串）、comment（字符串，可选）

架构说明

Confluence API 迁移

此服务主要使用 Confluence v2 REST API 执行大多数操作，并在必要时策略性地回退到 v1 API：

• v2 API：用于空间、页面、评论和标签，性能更佳，并支持现代的基于游标的分页
• v1 API：用于通过 CQL 搜索内容，提供更强大的搜索能力
• SSL 支持：可配置是否绕过 SSL 验证，以用于可自托管的实例
• 身份验证：支持基本身份验证、OAuth 2.0（计划支持）和 PAT 令牌

工具筛选与安全

• 只读模式：禁用所有写入操作，以便安全探索
• 工具白名单：通过 ENABLED_TOOLS 环境变量仅启用特定工具
• PII 筛选：自动检测并屏蔽响应中的敏感信息
• 错误上下文：提供详细的错误消息，同时不泄露敏感配置

开发

项目结构

src/
├── config/         # Configuration files
│   └── env.ts      # Environment configuration with validation
├── services/       # Service classes for Atlassian APIs
│   ├── confluencev2.ts    # Confluence v2 REST API service (primary)
│   ├── confluence.ts      # Legacy Confluence service (deprecated)
│   └── jira.ts           # Jira REST API service
├── tools/          # MCP tool implementations
│   ├── search-confluence.ts                    # Content search (v1 API)
│   ├── search-confluence-pages-by-title.ts     # Title search (v2 API)
│   ├── get-confluence-space.ts                 # Single space info
│   ├── get-confluence-spaces.ts                # All spaces list
│   ├── get-confluence-content.ts               # Page content by ID
│   ├── get-confluence-pages.ts                 # Pages in space
│   ├── get-confluence-child-pages.ts           # Child pages
│   ├── get-confluence-pages-by-label.ts        # Pages by label
│   ├── get-confluence-page-labels.ts           # Page labels
│   ├── add-confluence-page-labels.ts           # Add labels
│   ├── get-confluence-page-comments.ts         # Page comments
│   ├── add-confluence-page-comment.ts          # Add comment
│   ├── get-confluence-page-inline-comments.ts  # Inline comments
│   ├── confluence-create-page.ts               # Create page
│   ├── confluence-update-page.ts               # Update page
│   ├── update-confluence-page-title.ts         # Update title only
│   ├── confluence-delete-page.ts               # Delete page
│   ├── create-confluence-footer-comment.ts     # Footer comments
│   ├── search-jira-issues.ts                   # Jira search
│   ├── get-jira-issue.ts                       # Single issue
│   ├── jira-create-issue.ts                    # Create issue
│   ├── jira-update-issue.ts                    # Update issue
│   ├── jira-add-comment.ts                     # Add comment
│   ├── jira-get-transitions.ts                 # Get transitions
│   ├── jira-transition-issue.ts                # Transition issue
│   ├── jira-get-all-projects.ts                # All projects
│   ├── utils.ts                                 # Utility functions & PII filtering
│   └── index.ts                                # Tool exports
├── utils/          # Utility modules
│   └── tool-filter.ts      # Tool filtering and access control
└── index.ts        # Main entry point and server setup

构建

# Using npm
npm run build

# Using make
make build

测试

# Using npm
npm test

# Using make
make test

Makefile 命令

项目包含一个 Makefile，用于简化常见操作：

# Display available commands
make help

许可证

MIT

贡献

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request