AI导哈

Atlassian集成服务器

一个提供与Atlassian Jira和Confluence集成的MCP服务器，允许LLM通过结构化API与Jira工单和Confluence页面交互。

  • by george-stoica
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 george-stoica/atlassian-mcp-server

使用说明

Atlassian MCP服务器

一种模型上下文协议（MCP）服务器，提供与Atlassian Jira和Confluence的集成。此服务器允许LLM通过结构化API与Jira票证和Confluence页面进行交互。

概述

此MCP服务器集成了Atlassian Jira和Confluence，提供：

  • 按受让人、创建者或日期范围检索JIRA票证
  • 汇流页面搜索
  • 与Jira云平台REST API v3集成
  • 与Confluence REST API v2集成

MCP工具

服务器提供以下工具：

Jira工具

  • search_jira_tickets：使用灵活的过滤器搜索票证（受让人、创建者、项目、状态、创建/更新日期范围）
  • get_jira_tickets_by_assignee：通过可选的日期过滤按受让人获取门票
  • get_jira_tickets_by_creator：通过可选的日期过滤按创建者获取门票
  • get_jira_tickets_in_timeframe：获取在特定时间范围内创建的门票
  • get_ticket_by_key：按密钥检索特定票证

汇流工具

  • search_confluence_pages：按CQL搜索Confluence页面

建筑

项目结构

src/
├── services/           # Core service classes
│   ├── jira.ts        # Jira API client (strict types, Zod validation, error handling)
│   └── confluence.ts  # Confluence API client
├── types/             # TypeScript type definitions
│   └── atlassian.ts   # Atlassian API types
├── schemas/           # Zod validation schemas
│   └── atlassian.ts   # Input validation
├── __tests__/         # Unit tests (Jest)
│   ├── jira.test.ts
│   ├── confluence.test.ts
│   └── schemas.test.ts
└── index.ts           # MCP server entry point

关键组件

  • JiraService (src/services/jira.ts)：处理Jira API交互，包括按受让人、创建者和日期范围进行的票证搜索，并进行严格的类型检查和Zod验证。
  • 汇流服务 (src/services/conference.ts)：管理Confluence API调用。
  • 架构验证：使用Zod进行输入验证和类型安全(src/schemas/atlassian.ts).
  • 错误处理：全面的错误处理和有意义的消息。
  • 测试：所有主要功能的完整单元测试覆盖(src/测试/).

发展

添加新功能

  1. 添加新类型 在……里面 src/types/atlassian.ts
  2. 创建验证模式 在……里面 src/schemas/atlassian.ts
  3. 实施服务方法 在各自的服务类别中
  4. 添加MCP工具定义 在……里面 src/index.ts
  5. 编写全面的测试 在……里面 src/__tests__/

代码质量

  • TypeScript：已启用严格类型检查
  • 测试：玩弄全面的单元测试
  • 验证：所有输入的Zod模式
  • 错误处理：正确的错误消息和HTTP状态代码

故障排除

常见问题

  1. 身份验证错误

    • 验证API令牌是否正确
    • 检查电子邮件地址是否与Atlassian帐户匹配
    • 确保令牌具有足够的权限

  2. 连接问题

    • 验证基本URL是否正确
    • 检查网络连接
    • 确认Atlassian实例可访问

  3. 查询错误

    • 验证Jira查询的JQL语法
    • 检查Confluence搜索的CQL语法
    • 确保项目密钥和空间密钥存在

调试模式

在开发模式下运行以查看详细的错误消息：

npm run dev

安全考虑

  • 安全存储API令牌（使用环境变量）
  • 从不将令牌提交到版本控制
  • 使用最少特权API令牌
  • 定期轮换API代币
  • 监控API使用情况和费率限制

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 确保所有测试通过
  5. 提交拉取请求

许可证

ISC许可证-有关详细信息，请参阅许可证文件。

更新日志

v1.0.0

  • Jira门票搜索和检索
  • 汇流页搜索功能
  • 全面的测试覆盖率
  • 完整的MCP服务器实施
  • 文件和示例

Jira集成

  • 按受让人搜索门票 -检索分配给特定用户的票证
  • 按创建者搜索门票 -查找特定用户创建的工单
  • 基于日期的过滤 -按创建日期范围筛选票证
  • 时间范围查询 -获取在特定时间段内创建的所有门票
  • 高级搜索 -同时使用多个筛选器（受让人、创建者、项目、状态、日期）

汇流集成

  • 页面搜索 -按文本内容查找页面
  • 空间滤波 -将搜索限制在特定的Confluence空间
  • 页面链接 -检索匹配页面的直接链接
  • 内容类型过滤 -搜索页面或博客文章

先决条件

  • Node.js（v16或更高版本）
  • TypeScript
  • 具有API访问权限的Atlassian云实例
  • Jira和Confluence的API令牌

安装

  1. 克隆和安装依赖关系：
git clone <repository-url>
cd gst-atlassian-mcp
npm install
  1. 配置环境变量：
cp .env.example .env

编辑 .env 使用您的Atlassian凭据：

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token

CONFLUENCE_BASE_URL=https://your-domain.atlassian.net
CONFLUENCE_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-api-token
  1. 构建项目：
npm run build

API令牌设置

对于Jira和Confluence Cloud：

  1. 首选 大西洋API代币
  2. 点击“创建API令牌”
  3. 给它一个描述性的标签
  4. 复制生成的令牌
  5. 使用您的电子邮件地址和API令牌进行身份验证

用法

发展模式

npm run dev

生产模式

npm start

运行测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

MCP工具

服务器提供以下工具：

Jira工具

search_jira_tickets

使用各种过滤器搜索Jira门票。

参数：

  • assignee （可选）：受让人的电子邮件
  • creator （可选）：创建者的电子邮件
  • createdAfter （可选）：此日期之后创建的票证的ISO日期字符串
  • createdBefore （可选）：在此日期之前创建的票证的ISO日期字符串
  • project （可选）：项目密钥
  • status （可选）：票证状态
  • maxResults （可选）：最大结果数（1-100，默认值：50）
  • startAt （可选）：分页的起始索引（默认值：0）

get_jira_tickets_by_assignee

获取分配给特定用户的门票。

参数：

  • assigneeEmail （必填）：受让人的电子邮件
  • createdAfter （可选）：ISO日期字符串
  • createdBefore （可选）：ISO日期字符串
  • maxResults （可选）：最大结果（默认值：50）

get_jira_tickets_by_creator

获取由特定用户创建的工单。

参数：

  • creatorEmail （必填）：创建者的电子邮件
  • createdAfter （可选）：ISO日期字符串
  • createdBefore （可选）：ISO日期字符串
  • maxResults （可选）：最大结果（默认值：50）

get_jira_tickets_in_timeframe

获取在特定时间范围内创建的门票。

参数：

  • startDate （必填）：ISO日期字符串表示时间范围的开始
  • endDate （必填）：ISO日期字符串表示时间范围结束
  • maxResults （可选）：最大结果（默认值：50）

汇流工具

search_confluence_pages

基于文本查询搜索Confluence页面。

参数：

  • query （必填）：要在页面中搜索的文本
  • spaceKey （可选）：空格键限制搜索
  • type （可选）：'page'或'blogpost'（默认值：'page]）
  • limit （可选）：最大结果（1-100，默认值：25）
  • start （可选）：分页的起始索引（默认值：0）

get_confluence_page_links

获取与搜索查询匹配的Confluence页面的直接链接。

参数：

  • query （必填）：要搜索的文本
  • spaceKey （可选）：空格键限制搜索
  • limit （可选）：最大结果（默认值：25）

查询示例

Jira示例

// Get all tickets assigned to john.doe@example.com
{
  "name": "get_jira_tickets_by_assignee",
  "arguments": {
    "assigneeEmail": "john.doe@example.com"
  }
}

// Get tickets created in January 2024
{
  "name": "get_jira_tickets_in_timeframe",
  "arguments": {
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-01-31T23:59:59.999Z"
  }
}

// Search for high priority bugs in the TEST project
{
  "name": "search_jira_tickets",
  "arguments": {
    "project": "TEST",
    "status": "Open",
    "maxResults": 25
  }
}

汇流示例

// Search for pages about "API documentation"
{
  "name": "search_confluence_pages",
  "arguments": {
    "query": "API documentation"
  }
}

// Get links to pages about "user guide" in the DOCS space
{
  "name": "get_confluence_page_links",
  "arguments": {
    "query": "user guide",
    "spaceKey": "DOCS",
    "limit": 10
  }
}

建筑

项目结构

src/
├── services/           # Core service classes
│   ├── jira.ts        # Jira API client
│   └── confluence.ts  # Confluence API client
├── types/             # TypeScript type definitions
│   └── atlassian.ts   # Atlassian API types
├── schemas/           # Zod validation schemas
│   └── atlassian.ts   # Input validation
├── __tests__/         # Unit tests
│   ├── jira.test.ts
│   ├── confluence.test.ts
│   └── schemas.test.ts
└── index.ts           # MCP server entry point

关键组件

  • JiraService：使用REST API v3处理所有Jira API交互
  • 汇流服务：使用REST API v2管理Confluence API调用
  • 架构验证：使用Zod进行输入验证和类型安全
  • 错误处理：通过有意义的消息进行全面的错误处理
  • 测试：所有主要功能的完整单元测试覆盖

发展

添加新功能

  1. 添加新类型 在……里面 src/types/atlassian.ts
  2. 创建验证模式 在……里面 src/schemas/atlassian.ts
  3. 实施服务方法 在各自的服务类别中
  4. 添加MCP工具定义 在……里面 src/index.ts
  5. 编写全面的测试 在……里面 src/__tests__/

代码质量

  • TypeScript：已启用严格类型检查
  • 测试：玩弄全面的单元测试
  • 验证：所有输入的Zod模式
  • 错误处理：正确的错误消息和HTTP状态代码

故障排除

常见问题

  1. 身份验证错误

    • 验证API令牌是否正确
    • 检查电子邮件地址是否与Atlassian帐户匹配
    • 确保令牌具有足够的权限

  2. 连接问题

    • 验证基本URL是否正确
    • 检查网络连接
    • 确认Atlassian实例可访问

  3. 查询错误

    • 验证Jira查询的JQL语法
    • 检查Confluence搜索的CQL语法
    • 确保项目密钥和空间密钥存在

调试模式

在开发模式下运行以查看详细的错误消息：

npm run dev

安全考虑

  • 安全存储API令牌（使用环境变量）
  • 从不将令牌提交到版本控制
  • 使用最少特权API令牌
  • 定期轮换API代币
  • 监控API使用情况和费率限制

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 确保所有测试通过
  5. 提交拉取请求

许可证

ISC许可证-有关详细信息，请参阅许可证文件。

更新日志

v1.0.0（初始版本）

  • Jira门票搜索和检索
  • 汇流页搜索功能
  • 全面的测试覆盖率
  • 完整的MCP服务器实施
  • 文件和示例

相关 MCP