Skip to content

Commit 3a3d092

Browse files
jliocsarjliocsar
committed
add docs
1 parent 6e447f4 commit 3a3d092

File tree

2 files changed

+281
-5
lines changed

2 files changed

+281
-5
lines changed

‎docs.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# Bitbucket MCP Tools Documentation
2+
3+
This document describes all available tools for interacting with Bitbucket repositories through the MCP (Model Context Protocol) server.
4+
5+
## get-pull-request-comment
6+
7+
Retrieves a specific comment from a pull request in a Bitbucket repository.
8+
9+
### Description
10+
11+
This tool fetches detailed information about a single comment on a pull request, including the comment content, author information, creation and update timestamps, and any associated metadata. It's useful for examining specific feedback, discussions, or reviews within a pull request.
12+
13+
### Arguments
14+
15+
| Parameter | Type | Required | Description |
16+
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
17+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
18+
| `repository` | string | Yes | The repository name or UUID containing the pull request |
19+
| `pullRequestId` | number | Yes | The unique identifier of the pull request containing the comment |
20+
| `commentId` | number | Yes | The unique identifier of the specific comment to retrieve |
21+
| `fields` | string | No | Comma-separated list of fields to include in the response |
22+
23+
## get-pull-request-diff
24+
25+
Retrieves the diff/changes for a specific pull request in a Bitbucket repository.
26+
27+
### Description
28+
29+
This tool fetches the complete diff showing all file changes, additions, and deletions for a pull request. It provides detailed line-by-line changes that can be used to understand what modifications the pull request introduces to the codebase.
30+
31+
### Arguments
32+
33+
| Parameter | Type | Required | Description |
34+
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
35+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
36+
| `repository` | string | Yes | The repository name or UUID containing the pull request |
37+
| `pullRequestId` | number | Yes | The unique identifier of the pull request to get the diff for |
38+
| `fields` | string | No | Comma-separated list of fields to include in the response |
39+
40+
## get-pull-request-task
41+
42+
Retrieves a specific task from a pull request in a Bitbucket repository.
43+
44+
### Description
45+
46+
This tool fetches information about a specific task within a pull request. Tasks are actionable items that can be created during code review to track things that need to be addressed before merging.
47+
48+
### Arguments
49+
50+
| Parameter | Type | Required | Description |
51+
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
52+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
53+
| `repository` | string | Yes | The repository name or UUID containing the pull request |
54+
| `pullRequestId` | number | Yes | The unique identifier of the pull request containing the task |
55+
| `taskId` | number | Yes | The unique identifier of the specific task to retrieve |
56+
| `fields` | string | No | Comma-separated list of fields to include in the response |
57+
58+
## get-pull-request
59+
60+
Retrieves detailed information about a specific pull request in a Bitbucket repository.
61+
62+
### Description
63+
64+
This tool fetches comprehensive information about a pull request, including its title, description, author, reviewers, status, source and destination branches, and other metadata. It's the primary tool for examining pull request details.
65+
66+
### Arguments
67+
68+
| Parameter | Type | Required | Description |
69+
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
70+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
71+
| `repository` | string | Yes | The repository name or UUID containing the pull request |
72+
| `pullRequestId` | number | Yes | The unique identifier of the pull request to retrieve |
73+
| `fields` | string | No | Comma-separated list of fields to include in the response |
74+
75+
## get-repositories
76+
77+
Retrieves a list of repositories within a Bitbucket workspace.
78+
79+
### Description
80+
81+
This tool fetches information about repositories accessible within a specified workspace. It returns repository metadata including names, descriptions, clone URLs, and access permissions.
82+
83+
### Arguments
84+
85+
| Parameter | Type | Required | Description |
86+
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
87+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID to list repositories from |
88+
| `fields` | string | No | Comma-separated list of fields to include in the response |
89+
| `page` | string | No | Page token for pagination |
90+
| `pagelen` | number | No | Number of items to return per page (default: 10, max: 100) |
91+
| `q` | string | No | Query string to filter repositories |
92+
| `sort` | string | No | Field to sort results by (e.g., "name", "created_on", "updated_on") |
93+
94+
## get-repository-commit
95+
96+
Retrieves detailed information about a specific commit in a Bitbucket repository.
97+
98+
### Description
99+
100+
This tool fetches comprehensive information about a single commit, including the commit message, author information, timestamp, changed files, and parent commits. It's useful for examining the details of specific changes in the repository history.
101+
102+
### Arguments
103+
104+
| Parameter | Type | Required | Description |
105+
| ------------ | ------ | -------- | -------------------------------------------------------------------- |
106+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
107+
| `repository` | string | Yes | The repository name or UUID containing the commit |
108+
| `commit` | string | Yes | The SHA hash of the commit to retrieve |
109+
110+
## get-repository-diff
111+
112+
Retrieves the diff/changes between two commits or references in a Bitbucket repository.
113+
114+
### Description
115+
116+
This tool fetches the diff showing changes between two points in the repository history. It can compare commits, branches, or tags to show what files were modified and the specific line-by-line changes.
117+
118+
### Arguments
119+
120+
| Parameter | Type | Required | Description |
121+
| ------------------ | ------- | -------- | --------------------------------------------------------------------- |
122+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
123+
| `repository` | string | Yes | The repository name or UUID to get the diff from |
124+
| `spec` | string | Yes | The diff specification (e.g., "commit1..commit2", "branch1..branch2") |
125+
| `pullRequestId` | number | Yes | The unique identifier of the pull request for the diff |
126+
| `binary` | boolean | No | Whether to include binary file changes |
127+
| `context` | number | No | Number of context lines around changes |
128+
| `fields` | string | No | Comma-separated list of fields to include in the response |
129+
| `ignoreWhitespace` | boolean | No | Whether to ignore whitespace changes |
130+
| `merge` | boolean | No | Whether to include merge commits |
131+
| `path` | string | No | Specific file path to get diff for |
132+
| `renames` | boolean | No | Whether to detect renames |
133+
| `topic` | boolean | No | Whether to include topic information |
134+
135+
## get-repository
136+
137+
Retrieves detailed information about a specific Bitbucket repository.
138+
139+
### Description
140+
141+
This tool fetches comprehensive information about a repository, including its name, description, language, size, clone URLs, default branch, and various settings. It's useful for understanding repository configuration and metadata.
142+
143+
### Arguments
144+
145+
| Parameter | Type | Required | Description |
146+
| ------------ | ------ | -------- | -------------------------------------------------------------------- |
147+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
148+
| `repository` | string | Yes | The repository name or UUID to retrieve information about |
149+
| `fields` | string | No | Comma-separated list of fields to include in the response |
150+
151+
## get-snippet-raw-files
152+
153+
Retrieves the raw content of files from a Bitbucket snippet.
154+
155+
### Description
156+
157+
This tool fetches the raw file contents from a Bitbucket snippet. Snippets are lightweight repositories used for sharing code fragments, configuration files, or small pieces of text.
158+
159+
### Arguments
160+
161+
| Parameter | Type | Required | Description |
162+
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
163+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the snippet is located |
164+
| `encodedId` | string | Yes | The encoded identifier of the snippet |
165+
| `path` | string | Yes | The specific file path within the snippet to retrieve |
166+
| `fields` | string | No | Comma-separated list of fields to include in the response |
167+
168+
## get-workspaces
169+
170+
Retrieves a list of Bitbucket workspaces accessible to the authenticated user.
171+
172+
### Description
173+
174+
This tool fetches information about all workspaces that the current user has access to. Workspaces are containers for repositories and teams in Bitbucket, and this tool helps discover available workspaces for further operations.
175+
176+
### Arguments
177+
178+
| Parameter | Type | Required | Description |
179+
| --------- | ------ | -------- | ------------------------------------------------------------------- |
180+
| `fields` | string | No | Comma-separated list of fields to include in the response |
181+
| `page` | string | No | Page token for pagination |
182+
| `pagelen` | number | No | Number of items to return per page (default: 10, max: 100) |
183+
| `q` | string | No | Query string to filter workspaces |
184+
| `sort` | string | No | Field to sort results by (e.g., "name", "created_on", "updated_on") |
185+
186+
## list-commits
187+
188+
Retrieves a list of commits from a Bitbucket repository.
189+
190+
### Description
191+
192+
This tool fetches a paginated list of commits from a repository, optionally filtered by branch, author, or date range. It's useful for examining the commit history and finding specific changes in the repository.
193+
194+
### Arguments
195+
196+
| Parameter | Type | Required | Description |
197+
| ------------ | ------ | -------- | ----------------------------------------------------------------------------- |
198+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
199+
| `repository` | string | Yes | The repository name or UUID to list commits from |
200+
| `branch` | string | No | Specific branch to list commits from |
201+
| `page` | string | No | Page token for pagination |
202+
| `pagelen` | number | No | Number of items to return per page (default: 30, max: 100) |
203+
| `q` | string | No | Query string to filter commits |
204+
| `sort` | string | No | Field to sort results by (e.g., "date", "-date") |
205+
| `exclude` | string | No | Branch, tag, or commit to exclude from the results |
206+
| `fields` | string | No | Comma-separated list of fields to include in the response |
207+
| `include` | string | No | Branch, tag, or commit to include in the results (defaults to default branch) |
208+
209+
## list-pull-request-comments
210+
211+
Retrieves a list of comments from a specific pull request in a Bitbucket repository.
212+
213+
### Description
214+
215+
This tool fetches all comments associated with a pull request, including both general comments and inline code comments. It's useful for reviewing all feedback and discussions related to a pull request.
216+
217+
### Arguments
218+
219+
| Parameter | Type | Required | Description |
220+
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
221+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
222+
| `repository` | string | Yes | The repository name or UUID containing the pull request |
223+
| `pullRequestId` | number | Yes | The unique identifier of the pull request to list comments from |
224+
| `page` | string | No | Page token for pagination |
225+
| `pagelen` | number | No | Number of items to return per page (default: 10, max: 100) |
226+
| `q` | string | No | Query string to filter comments |
227+
| `sort` | string | No | Field to sort results by (e.g., "created_on", "-created_on") |
228+
| `fields` | string | No | Comma-separated list of fields to include in the response |
229+
230+
## list-pull-requests
231+
232+
Retrieves a list of pull requests from a Bitbucket repository.
233+
234+
### Description
235+
236+
This tool fetches a list of pull requests from a repository, optionally filtered by state (open, merged, declined), author, or other criteria. It's useful for discovering and managing pull requests in a repository.
237+
238+
### Arguments
239+
240+
| Parameter | Type | Required | Description |
241+
| ------------ | ------ | -------- | -------------------------------------------------------------------------- |
242+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
243+
| `repository` | string | Yes | The repository name or UUID to list pull requests from |
244+
| `fields` | string | No | Comma-separated list of fields to include in the response |
245+
| `page` | string | No | Page token for pagination |
246+
| `pagelen` | number | No | Number of items to return per page (default: 10, max: 100) |
247+
| `q` | string | No | Query string to filter pull requests |
248+
| `sort` | string | No | Field to sort results by (e.g., "created_on", "-created_on", "updated_on") |
249+
| `state` | string | No | Filter by pull request state: "OPEN", "MERGED", "DECLINED" |
250+
251+
## list-refs
252+
253+
Retrieves a list of references (branches and tags) from a Bitbucket repository.
254+
255+
### Description
256+
257+
This tool fetches all branches and tags from a repository. References are important for understanding the repository structure and available code versions that can be used for comparisons, checkouts, or pull request targets.
258+
259+
### Arguments
260+
261+
| Parameter | Type | Required | Description |
262+
| ------------ | ------ | -------- | -------------------------------------------------------------------- |
263+
| `workspace` | string | Yes | The Bitbucket workspace name or UUID where the repository is located |
264+
| `repository` | string | Yes | The repository name or UUID to list references from |
265+
| `page` | string | No | Page token for pagination |
266+
| `pagelen` | number | No | Number of items to return per page (default: 10, max: 100) |
267+
| `q` | string | No | Query string to filter references |
268+
| `sort` | string | No | Field to sort results by (e.g., "name", "-name") |
269+
| `fields` | string | No | Comma-separated list of fields to include in the response |

‎readme.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
# 🌬️ bitbucket-mcp-server
22

3-
Simple MCP implementation for Bitbucket pull requests.
3+
Simple MCP implementation for (mostly) pull requests on Bitbucket.
44

55
Provide context from your PRs to your favorite LLM and let it review them for you!
66

7-
Written in Bun and Civet.
7+
Written in Bun and Civet using Cursor.
88

9-
> 🚧 This repository is above all a MCP learning exercise and it is still work in progress. The API lacks many features as of now, working mostly for basic PR reviews based on the code diff. More features might be added in the near future. 🚧
9+
Read the documentation [here](docs.md).
10+
11+
> 🚧 This repository is a MCP learning exercise and it is still work in progress.
12+
>
13+
> The API here lacks many features as of now. More features might be added in the near future.
14+
>
15+
> Also, the documentation was written by Cursor itself. Don't expect it to be perfect. 🚧
1016
1117
## Install
1218

@@ -85,11 +91,12 @@ Then follow the same steps from the [Release](#release) option to add the MCP se
8591

8692
## Development
8793

88-
Make sure you have `bun` installed.
94+
Make sure you have both Bun's runtime and Civet's VSCode/Cursor extension installed.
8995

90-
Then after cloning the repository and `cd`ing into it:
96+
Then after cloning the repository, install its dependencies:
9197

9298
```sh
99+
cd /path/to/repository
93100
bun i
94101
```
95102

0 commit comments

Comments
 (0)