bitbucket-mcp: Instructions file for Codex

Bitbucket MCP Server - Project Context

This document provides essential information for AI CLI to understand the Bitbucket MCP Server project and its development environment.

Project Overview

The Bitbucket MCP Server is a Model Context Protocol (MCP) server that provides a bridge between AI models and the Bitbucket API. It allows AI agents to interact with Bitbucket repositories, pull requests, issues, commits, and more.

Key Technologies

• Runtime: Node.js (v20+)
• Language: TypeScript
• MCP Framework: @modelcontextprotocol/sdk
• Validation: zod
• Testing: vitest
• Networking: node-fetch

Project Structure

• src/index.ts: The main entry point that starts the server.
• src/server.ts: Handles server instantiation, transport (Stdio), and lifecycle management.
• src/bitbucket-api.ts: Core Bitbucket API client implementation with retry logic and error handling.
• src/tools/index.ts: Orchestration-only entry that delegates to per-resource modules.
• src/tools/<resource>.ts: Per-resource tool implementations — repositories, pull-requests, pr-comments, commits, branches, issues, pipelines, search, system.
• src/tools/helpers.ts: Shared makeRegister factory used by the per-resource modules.
• src/config.ts: Configuration management and environment variable validation.
• src/monitoring/: Contains specialized monitors for process, protocol, and transport performance.
• src/metrics.ts: Collects and manages server performance metrics.
• src/rate-limiting.ts: Implements multi-tier rate limiting to prevent API abuse.

Development Workflows

Building

Compile the TypeScript source code into the build/ directory:

npm run build

Running

Start the server in production mode (requires a build):

npm start

For development with automatic recompilation:

npm run dev

Testing

Run the test suite using Vitest:

npm test

Generate coverage reports:

npm run test:coverage