Skip to content

Commit a2402c7

Browse files
nszcetanszceta
committed
Merge PR sooperset#663: PAT (bearer) auth for Atlassian Server/Data Center instances (resolving conflicts)
2 parents aa212fd + 12f8dd2 commit a2402c7

File tree

19 files changed

+2198
-26
lines changed

19 files changed

+2198
-26
lines changed

‎AUTH_FIX.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Authentication Fix for Atlassian Server/Data Center PATs
2+
3+
## Problem
4+
The original implementation incorrectly used Basic Authentication for Personal Access Tokens (PATs) on Atlassian Server/Data Center instances. Server/DC PATs require Bearer authentication, not Basic authentication.
5+
6+
## Solution
7+
This fix introduces proper Bearer authentication support for Server/DC PATs while maintaining compatibility with Cloud instances.
8+
9+
### Changes Made
10+
11+
1. **New authentication utility** (`src/mcp_atlassian/utils/auth.py`):
12+
- Added `configure_server_pat_auth()` function to configure Bearer authentication
13+
14+
2. **Updated Jira client** (`src/mcp_atlassian/jira/client.py`):
15+
- Detects Server/DC instances when using PAT authentication
16+
- Creates a session with Bearer authentication for Server/DC
17+
- Maintains existing behavior for Cloud instances
18+
19+
3. **Updated Confluence client** (`src/mcp_atlassian/confluence/client.py`):
20+
- Same improvements as Jira client
21+
22+
4. **Updated tests**:
23+
- Modified PAT authentication tests to verify Bearer headers
24+
- Added unit tests for the new authentication utility
25+
26+
## Authentication Matrix
27+
28+
| Instance Type | Auth Method | Implementation |
29+
|--------------|-------------|----------------|
30+
| Cloud | API Token | Basic Auth (username + token) |
31+
| Cloud | OAuth | Bearer Auth (via OAuth flow) |
32+
| Cloud | PAT | Token parameter (rare) |
33+
| Server/DC | Username/Password | Basic Auth |
34+
| Server/DC | PAT | **Bearer Auth** (fixed) |
35+
| Server/DC | OAuth | Not supported |
36+
37+
## Testing
38+
39+
To test the fix:
40+
41+
1. **Server/DC with PAT**:
42+
```bash
43+
export JIRA_URL="https://jira.yourcompany.com"
44+
export JIRA_PERSONAL_TOKEN="your-pat-token"
45+
```
46+
47+
2. **Cloud with API Token** (unchanged):
48+
```bash
49+
export JIRA_URL="https://yourinstance.atlassian.net"
50+
export JIRA_USERNAME="[email protected]"
51+
export JIRA_API_TOKEN="your-api-token"
52+
```
53+
54+
## Verification
55+
56+
You can verify the authentication is working correctly by checking the debug logs:
57+
58+
```bash
59+
export MCP_ATLASSIAN_LOG_LEVEL=DEBUG
60+
# Run your MCP server
61+
```
62+
63+
For Server/DC with PAT, you should see:
64+
```
65+
Jira Server/DC client initialized with Bearer auth. Session headers (Authorization masked): {'Authorization': 'Bearer ***'}
66+
```
67+
68+
## Compatibility
69+
70+
This fix is backward compatible:
71+
- Cloud instances continue to work as before
72+
- Server/DC instances with username/password still work
73+
- Server/DC instances with PAT now work correctly with Bearer authentication

‎DEVELOPMENT_INFO.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Jira Development Information Integration
2+
3+
This feature adds support for retrieving development information (pull requests, branches, commits, builds) linked to Jira issues through integrations like Bitbucket for Jira, GitHub for Jira, or GitLab for Jira.
4+
5+
## Features
6+
7+
### New MCP Tool
8+
- `get_development_information` - Retrieves all linked development data for a Jira issue
9+
10+
### Data Retrieved
11+
- **Pull Requests**: Title, status, author, source/destination branches, URLs
12+
- **Branches**: Name, repository, last commit, URLs
13+
- **Commits**: ID, message, author, timestamp, files changed
14+
- **Builds**: Name, status, duration, URLs
15+
- **Repositories**: Name, URL, description
16+
17+
## Implementation Details
18+
19+
### Files Added
20+
1. `src/mcp_atlassian/jira/development.py` - Core development information retrieval logic
21+
2. `src/mcp_atlassian/models/jira/development.py` - Data models for development information
22+
3. `test_dev_info.py` - Test script to verify functionality
23+
24+
### Files Modified
25+
1. `src/mcp_atlassian/jira/client.py` - Added DevelopmentMixin to JiraClient
26+
2. `src/mcp_atlassian/servers/jira.py` - Added MCP tool endpoint
27+
3. `src/mcp_atlassian/models/__init__.py` - Exported development models
28+
29+
## API Endpoints Used
30+
31+
### Server/Data Center
32+
- `/rest/dev-status/latest/issue/detail` - Legacy endpoint for development status
33+
34+
### Cloud
35+
- `/rest/api/3/issue/{issueIdOrKey}/development` - Cloud API endpoint
36+
- Falls back to legacy endpoint if needed
37+
38+
## Usage
39+
40+
### Via MCP Tool in Claude
41+
```python
42+
# Get all development information
43+
await get_development_information(
44+
issue_key="PROJ-123"
45+
)
46+
47+
# Filter by application type
48+
await get_development_information(
49+
issue_key="PROJ-123",
50+
application_type="bitbucket" # or "github", "gitlab", "stash"
51+
)
52+
```
53+
54+
### Direct Python Usage
55+
```python
56+
from mcp_atlassian.jira.client import JiraClient
57+
from mcp_atlassian.jira.config import JiraConfig
58+
59+
# Initialize client
60+
config = JiraConfig.from_env()
61+
client = JiraClient(config)
62+
63+
# Get development information
64+
dev_info = client.get_development_information("PROJ-123")
65+
66+
# Access specific data
67+
print(f"Open PRs: {len(dev_info.open_pull_requests)}")
68+
print(f"Total commits: {dev_info.total_commits}")
69+
print(f"Summary: {dev_info.summary}")
70+
71+
# Get just pull requests
72+
prs = client.get_linked_pull_requests("PROJ-123")
73+
```
74+
75+
## Testing
76+
77+
Test the feature using the provided script:
78+
79+
```bash
80+
# Test with a specific issue
81+
python test_dev_info.py PROJ-123
82+
```
83+
84+
This will:
85+
1. Fetch development information for the issue
86+
2. Display a summary in the console
87+
3. Export full details to a JSON file
88+
89+
## Data Models
90+
91+
### DevelopmentInformation
92+
Main container with:
93+
- `pull_requests`: List of PullRequest objects
94+
- `branches`: List of Branch objects
95+
- `commits`: List of Commit objects
96+
- `builds`: List of Build objects
97+
- `repositories`: List of Repository objects
98+
- `has_development_info`: Boolean indicator
99+
- `summary`: Text summary of all development data
100+
101+
### PullRequest
102+
- `id`, `title`, `url`
103+
- `status` (OPEN, MERGED, DECLINED)
104+
- `author`, `source_branch`, `destination_branch`
105+
- `last_update`, `commentCount`
106+
- Helper properties: `is_open`, `is_merged`
107+
108+
### Branch
109+
- `id`, `name`, `url`
110+
- `last_commit`, `repository`
111+
- Helper properties: `is_feature_branch`, `is_bugfix_branch`
112+
113+
### Commit
114+
- `id`, `message`, `url`
115+
- `author`, `author_timestamp`
116+
- `files_changed`, `lines_added`, `lines_removed`
117+
- Helper properties: `short_id`, `first_line_message`
118+
119+
### Build
120+
- `id`, `name`, `url`
121+
- `status` (SUCCESS, FAILED, IN_PROGRESS)
122+
- `started_time`, `finished_time`, `duration_seconds`
123+
- Helper properties: `is_successful`, `is_failed`
124+
125+
## Error Handling
126+
127+
The implementation handles:
128+
- Missing development panel/plugin
129+
- Permission issues accessing development data
130+
- Different response formats between Cloud and Server/DC
131+
- Empty or malformed responses
132+
133+
If development information cannot be retrieved, an empty DevelopmentInformation object is returned with error details.
134+
135+
## Compatibility
136+
137+
- ✅ Jira Server/Data Center (with Bitbucket Server integration)
138+
- ✅ Jira Cloud (with Bitbucket Cloud, GitHub, GitLab integrations)
139+
- ✅ Handles both PAT and Basic authentication
140+
- ✅ Works with the authentication fix for Server/DC Bearer tokens
141+
142+
## Limitations
143+
144+
1. Requires the appropriate integration plugin installed in Jira
145+
2. User must have permission to view development information
146+
3. Some fields may not be available depending on the integration type
147+
4. Build information requires additional CI/CD integration
148+
149+
## Contributing
150+
151+
When adding support for new development tool integrations:
152+
1. Add parsing logic in `_parse_<provider>_instance()` method
153+
2. Update the `application_type` parameter documentation
154+
3. Add test cases for the new provider format

‎JIRA_GET_COMMENTS.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# New Feature: jira_get_comments
2+
3+
## Overview
4+
Added a dedicated `jira_get_comments` tool to retrieve comments from Jira issues. This complements the existing `jira_add_comment` functionality and provides a focused way to fetch issue comments.
5+
6+
## Tool Details
7+
8+
### Name
9+
`jira_get_comments`
10+
11+
### Purpose
12+
Retrieve all comments from a specific Jira issue with configurable limits.
13+
14+
### Parameters
15+
- **issue_key** (required): Jira issue key (e.g., 'PROJ-123')
16+
- **limit** (optional): Maximum number of comments to retrieve (1-1000, default: 50)
17+
18+
### Returns
19+
JSON object containing:
20+
```json
21+
{
22+
"issue_key": "PROJ-123",
23+
"total_comments": 5,
24+
"comments": [
25+
{
26+
"id": "10001",
27+
"body": "Comment text content (cleaned and converted to markdown)",
28+
"created": "2025-08-20 10:30:00",
29+
"updated": "2025-08-20 10:35:00",
30+
"author": "John Doe"
31+
},
32+
// ... more comments
33+
]
34+
}
35+
```
36+
37+
## Features
38+
- **Markdown Conversion**: Comment body text is automatically cleaned and converted from Jira markup to Markdown
39+
- **User Mention Processing**: Jira user mentions are properly processed and formatted
40+
- **Date Formatting**: Creation and update dates are formatted consistently
41+
- **Configurable Limit**: Retrieve anywhere from 1 to 1000 comments per request
42+
- **Error Handling**: Graceful error handling with detailed logging
43+
44+
## Implementation Details
45+
46+
### Files Modified
47+
1. **`src/mcp_atlassian/servers/jira.py`**:
48+
- Added `get_comments` tool function
49+
- Integrated with existing `CommentsMixin.get_issue_comments` method
50+
- Properly tagged with `{"jira", "read"}` for tool filtering
51+
52+
### Files Already Present
53+
1. **`src/mcp_atlassian/jira/comments.py`**:
54+
- Contains the `CommentsMixin` class with `get_issue_comments` method
55+
- Handles comment retrieval from Jira API
56+
- Processes comment text through the preprocessor
57+
58+
## Usage Examples
59+
60+
### Via MCP Tool in Claude
61+
```
62+
Use the jira_get_comments tool to get comments from issue PROJ-123 with a limit of 20 comments.
63+
```
64+
65+
### Via Python Client
66+
```python
67+
from mcp_atlassian.jira.comments import CommentsMixin
68+
from mcp_atlassian.jira.config import JiraConfig
69+
70+
# Create client
71+
config = JiraConfig.from_env()
72+
client = CommentsMixin(config)
73+
74+
# Get comments
75+
comments = client.get_issue_comments(
76+
issue_key="PROJ-123",
77+
limit=20
78+
)
79+
80+
# Process results
81+
for comment in comments:
82+
print(f"Author: {comment['author']}")
83+
print(f"Date: {comment['created']}")
84+
print(f"Text: {comment['body']}")
85+
```
86+
87+
## Testing
88+
89+
A test script is provided at `test_jira_comments.py`:
90+
91+
```bash
92+
# Test with a specific issue
93+
python test_jira_comments.py PROJ-123
94+
```
95+
96+
The test script:
97+
1. Tests direct client method (`get_issue_comments`)
98+
2. Tests server endpoint (`jira_get_comments`)
99+
3. Optionally tests adding a comment (if not in read-only mode)
100+
4. Validates comment structure and content
101+
102+
## Compatibility
103+
- Works with both Cloud and Server/DC instances
104+
- Supports all authentication methods (OAuth, PAT, Basic Auth)
105+
- Respects read-only mode (tool is read-only, tagged with "read")
106+
107+
## Related Tools
108+
- **jira_get_issue**: Can also retrieve comments as part of issue details (with `comment_limit` parameter)
109+
- **jira_add_comment**: Add new comments to issues
110+
- **jira_search**: Search for issues (comments not included in search results)
111+
112+
## Notes
113+
- Comments are returned in chronological order (oldest first)
114+
- The comment body is automatically processed to convert Jira markup to Markdown
115+
- User mentions in comments are properly formatted
116+
- HTML content in comments is converted to readable text

0 commit comments

Comments
 (0)