MCP server for interacting with Bitbucket, providing tools to authenticate, manage repositories, view codebase structures, retrieve file contents, and manage pull requests
This server has significant gaps in definition quality. While all 13 tools are explicitly registered with Pydantic models providing schemas and descriptions, the descriptions are generic and lack actionable guidance for LLM selection. No tool descriptions explain WHEN to use each tool vs. similar alternatives (e.g., get_codebase vs get_codebase_paginated is unclear). Parameter descriptions are present but minimal. No output schemas are documented, forcing LLMs to guess what fields will be returned. Error handling is absent, tools will fail without guidance on recovery. Naming is verb-first (good) but some names create redundancy (get_codebase and get_codebase_paginated should be one tool with automatic pagination). Critical security issue: the authenticate_user tool accepts an email parameter but BITBUCKET_TOKEN is loaded from an environment variable, if the token is ever exposed in logs or responses, it cannot be revoked per-call. No tool declares required permissions or destructive capabilities.
No output schemas documented for any tool. LLMs cannot plan downstream operations or extract required fields because they don't know what will be returned.
get_codebase and get_codebase_paginated are near-duplicates. The distinction should be implicit (automatic pagination) within a single tool, not two separate tools. This violates composition principles and forces LLMs to choose between similar tools.
Descriptions are generic and lack guidance on tool selection. Many pairs of tools (get_repositories vs search_repositories, get_pull_requests vs search_pull_requests, get_file_content vs get_codebase) have overlapping purposes, but descriptions don't explain WHEN to use each one.
Recommendations
For every tool, add an output schema documenting the structure of returned data. Example: 'Returns object with fields: repositories (array of {name, slug, description, updated_at}), total_count (int), next_cursor (string or null)'.
Merge get_codebase and get_codebase_paginated into a single tool. Implement pagination internally using max_items as the page size. Return results with total_count and next_cursor if more items exist.
Enhance descriptions to clarify tool selection. For get_repositories vs search_repositories: 'get_repositories: Lists all repos (optionally in one workspace). Use this to browse. search_repositories: Searches by name across all workspaces. Use this to find a specific repo by partial name.' Similar clarification for get_pull_requests vs search_pull_requests.
Add error handling that guides LLM recovery. When authentication fails, suggest: 'Authenticate first with authenticate_user(email). If you have the email, pass it. Otherwise, check BITBUCKET_EMAIL environment variable.' When a repository is not found, return: 'Repo not found. Available repos: [list]. Did you mean one of these?'.
For parameters that accept one of a limited set of values (e.g., state: OPEN|MERGED|DECLINED|SUPERSEDED), document the allowed values in the description. Example: 'state: PR lifecycle state (OPEN=not yet merged, MERGED=accepted, DECLINED=rejected, SUPERSEDED=replaced by newer PR)'.
Clarify pagination in tool descriptions. Example for get_repositories: 'Returns up to page_size repositories. If total_count > returned items, use next_cursor in subsequent calls to fetch more.' Add page and cursor parameters if not already present.
Score history
Overall score trend
↑ 33 points across a rubric change (v1 → v2)
49/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
49
2026-07-28+
v2
2026-03-09
F
16
-
v1
get_pull_requests
read onlyauthsource verified68/100
Get pull requests from a repository with specified state
No error handling or recovery guidance. Tools will fail on invalid input (e.g., missing workspace, invalid branch name, nonexistent file) with no explanation of what went wrong or what to do next.
No pagination guidance. Tools accept page_size but descriptions don't explain whether there's a total_count, next_cursor, or whether results are truncated if more items exist.
Parameter descriptions lack actionable detail. For example, 'state' in get_pull_requests lists valid values but descriptions don't explain differences (OPEN vs MERGED vs DECLINED). 'path' in get_codebase doesn't indicate format (empty string for root? '/'? './'?).
No tool declares what permissions it requires (read:repo, write:pr, etc.) or which tools are read-only vs destructive. All tools appear safe (all listed as READ_ONLY risk), but this should be explicit via tool annotations.
authenticate_user requires email as input but the server loads BITBUCKET_TOKEN from environment. The pattern should be either: (1) both email and token in environment (no input params), or (2) accept both as inputs with secure handling. Current mixed approach is confusing.
authenticate_user
Add tool annotations (readOnlyHint, idempotentHint) to every tool to signal safety. All tools are read-only; mark them explicitly so agents know they're safe to retry.
Move BITBUCKET_TOKEN to a server-side-only secret (never exposed in parameters). If email is also sensitive, load it from environment too. If email is user-provided, accept it as input but never log or return it.
Add a diagnostic tool like 'test_connection' that verifies authentication and returns user info, helping debug auth failures without making agents guess.
For file content tools (get_file_content, list_files, get_codebase), add max_size or max_depth parameters with defaults. Explain in descriptions: 'Large files (>1MB) are truncated for token efficiency. Pass max_file_size=0 to request full content (may be expensive).'
Document what fields each tool returns as part of the description. Example for get_repositories: 'Each repository includes: name (string), slug (string), description (string), updated_at (ISO 8601 date), is_private (boolean). Pass repository.slug to other tools requiring repo_slug.'
Add required parameters explicitly in descriptions. Example: 'workspace (required): Workspace slug, e.g. 'my-team'. repo_slug (required): Repository slug, e.g. 'my-project'. branch (default: 'main'): Branch name.'
For search tools, document search semantics. Example: 'search_repositories matches repo_name as a substring, case-insensitive, across all workspaces. Returns partial matches ranked by relevance.'