@atercates/bitbucket-mcp 1.0.0

package/docs/guides/PROJECT_STRUCTURE.md

@@ -0,0 +1,317 @@
+# Project Structure & Configuration Files
+
+This guide explains the purpose of important configuration files and directories in the Bitbucket MCP project.
+
+## Core Directories
+
+### `src/`
+The source code for the MCP server.
+
+- **`index.ts`** - Entry point. Loads configuration and starts the MCP server
+- **`server.ts`** - Main MCP server setup, tool registration, and request routing
+- **`client.ts`** - Bitbucket API client wrapper using Axios with pagination support
+- **`config.ts`** - Environment variable parsing and URL normalization
+- **`logger.ts`** - Winston-based file logging setup
+- **`types.ts`** - TypeScript interfaces for Bitbucket API entities
+- **`schemas.ts`** - Shared JSON schemas for pagination
+- **`utils.ts`** - Helper functions (response formatting, etc.)
+- **`pagination.ts`** - Custom pagination handler for Bitbucket API
+- **`handlers/`** - Feature modules (repositories, pull-requests, pipelines, etc.)
+
+### `dist/`
+Compiled JavaScript output from TypeScript. Generated by `pnpm build`. Executed via `pnpm start`.
+
+### `__tests__/`
+Test files (Vitest format). Mirrors the `src/` structure for easy navigation.
+
+### `docs/`
+User-facing documentation:
+- `README.md` - Documentation index
+- `TOOLS.md` - Complete 59-tool reference with examples
+- `guides/` - Setup, deployment, environment variables, this file
+- `architecture/` - Technical design and extension guide
+
+---
+
+## Configuration Files
+
+### `server.json`
+**Purpose:** MCP server metadata and configuration schema.
+
+**Contents:**
+- `$schema` - Points to official MCP schema for validation
+- `name` - Unique identifier (e.g., `io.github.bitbucket-mcp/bitbucket-mcp`)
+- `title` - Display name ("Bitbucket MCP")
+- `description` - Server description
+- `version` - Package version (synced from `package.json`)
+- `packages` - NPM package info for registry discovery
+
+**When used:**
+- MCP clients (Cursor, Claude) read this to understand how to invoke the server
+- Used by the official MCP registry for discoverability
+- Validated by `scripts/validate-server-json.mjs`
+
+**Do NOT edit manually.** The version is synced automatically from `package.json` during builds.
+
+---
+
+## Registry Directory
+
+### `registry/`
+Contains manifest for MCP registry integration.
+
+#### `bitbucket-mcp.manifest.json`
+**Purpose:** Metadata for the official MCP registry (GitHub's model-context-protocol/registry).
+
+**Contents:**
+- `name`, `slug`, `version` - Basic metadata
+- `description`, `homepage`, `repository` - Project links
+- `license`, `author`, `keywords` - Licensing and discovery
+- `icon` - Bitbucket favicon
+- `transport` - Communication protocol (`stdio`)
+- `startCommand` - How to launch the server (`node dist/index.js`)
+- `configSchema` - JSON Schema defining all environment variable options
+
+**When used:**
+- When the MCP registry processes your server submission
+- Consumed by MCP clients to show available configuration options
+- Helps users understand what environment variables they need
+
+**Generated by:** `scripts/generate-registry-manifest.cjs` (runs automatically)
+
+**Example client usage:**
+```json
+{
+  "mcpServers": {
+    "bitbucket": {
+      "command": "npx",
+      "args": ["-y", "bitbucket-mcp@latest"],
+      "env": {
+        "BITBUCKET_TOKEN": "app_password_here",
+        "BITBUCKET_WORKSPACE": "my-workspace"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Scripts Directory
+
+### `scripts/`
+Build and validation utilities.
+
+#### `generate-registry-manifest.cjs`
+**Purpose:** Automatically generate `registry/bitbucket-mcp.manifest.json` from `package.json`.
+
+**What it does:**
+1. Reads `package.json` (version, description, repository, etc.)
+2. Merges with hardcoded registry metadata (icon, transport, startCommand)
+3. Writes to `registry/bitbucket-mcp.manifest.json`
+
+**When it runs:**
+- Manually: `node scripts/generate-registry-manifest.cjs`
+- Automatically as part of the build process (via `package.json` scripts)
+
+**Why it exists:**
+- Single source of truth: package.json is the authority
+- Prevents version mismatches between NPM and registry
+- Ensures metadata is always up-to-date
+
+**Do NOT edit** `registry/bitbucket-mcp.manifest.json` directly. Edit `package.json` instead, then regenerate.
+
+#### `validate-server-json.mjs`
+**Purpose:** Validate `server.json` against the official MCP server schema.
+
+**What it does:**
+1. Reads `server.json`
+2. Fetches the official MCP server schema from `static.modelcontextprotocol.io`
+3. Validates JSON structure and field types
+4. Reports validation errors
+
+**When it runs:**
+- Manually: `node scripts/validate-server-json.mjs`
+- Automatically as part of CI/CD (GitHub Actions)
+
+**Why it exists:**
+- Ensures your `server.json` is compatible with MCP clients
+- Catches configuration errors before deployment
+- Guarantees registry acceptance
+
+**Example output:**
+```
+✓ server.json is valid against the schema.
+```
+
+---
+
+## Package Management Files
+
+### `package.json`
+Main Node.js configuration.
+
+**Key sections:**
+- `version` - Current semantic version (5.0.6)
+- `name` - NPM package name (`bitbucket-mcp`)
+- `description` - Short project description
+- `main` - Entry point for imports (`dist/index.js`)
+- `bin` - CLI command mapping (`bitbucket-mcp` → `dist/index.js`)
+- `type` - Module system (`module` = ESM)
+- `scripts` - Development and build commands
+- `dependencies` - Production dependencies
+- `devDependencies` - Development tools (TypeScript, Vitest, ESLint, etc.)
+- `files` - Files included in NPM package
+
+**Important scripts:**
+- `build` - Compile TypeScript to `dist/`
+- `dev` - Run in development mode with watch
+- `start` - Run compiled server
+- `test` - Run Vitest suite
+- `lint` - Check code with ESLint
+- `format` - Format code with Prettier
+- `inspector` - Launch MCP inspector for debugging
+
+### `pnpm-lock.yaml`
+Lockfile for reproducible builds with pnpm (like `package-lock.json` for npm).
+
+### `pnpm-workspace.yaml`
+Workspace configuration (if using monorepo structure). Currently minimal.
+
+---
+
+## Build & Compilation Files
+
+### `tsconfig.json`
+TypeScript compiler configuration.
+
+**Key settings:**
+- `module` - Output module format (`esnext` = modern JS)
+- `target` - JavaScript version (`es2020`)
+- `strict` - Strict type checking enabled
+- `skipLibCheck` - Skip type checking of dependencies
+- `include` - Files to compile (`src/**/*`)
+- `exclude` - Files to ignore (`node_modules`, `dist`, `__tests__`)
+
+### `vitest.config.ts`
+Vitest test runner configuration.
+
+**Key settings:**
+- `environment: "node"` - Run tests in Node.js (not browser)
+- `globals: true` - No need to import test functions
+
+### `eslint.config.js`
+ESLint code quality configuration (flat config format).
+
+**What it checks:**
+- TypeScript syntax errors
+- Unused variables
+- Proper function signatures
+- Naming conventions
+
+### `.prettierrc`
+Code formatting configuration.
+
+**Settings:**
+- Semicolons at end of lines
+- Double quotes for strings
+- 2-space indentation
+- Trailing commas where valid
+
+---
+
+## Deployment & CI/CD
+
+### `.github/workflows/publish-mcp.yml`
+GitHub Actions workflow for automated NPM publishing.
+
+**What it does:**
+1. Runs on version tags (e.g., `v5.0.6`)
+2. Installs dependencies with pnpm
+3. Builds and tests the project
+4. Publishes to NPM registry
+5. Updates the official MCP registry
+
+### `Dockerfile`
+Containerized deployment configuration.
+
+**Usage:**
+```bash
+docker build -t bitbucket-mcp .
+docker run -e BITBUCKET_TOKEN=... bitbucket-mcp
+```
+
+### `DEPLOYMENT.txt`
+Quick reference for deployment steps and environment setup.
+
+---
+
+## Application Metadata
+
+### `server.json` vs `registry/bitbucket-mcp.manifest.json`
+
+| File | Purpose | Audience | Auto-generated |
+|------|---------|----------|---|
+| `server.json` | MCP client configuration | MCP clients (Cursor, Claude) | Yes (version synced) |
+| `registry/bitbucket-mcp.manifest.json` | MCP registry metadata | MCP registry, discoverability | Yes (from package.json) |
+
+**Workflow:**
+1. You update `package.json` version
+2. CI/CD regenerates both files
+3. MCP clients read `server.json`
+4. Registry reads manifest file
+5. Users discover via registry
+
+---
+
+## What You Can Delete (If Unnecessary)
+
+❌ **DO NOT DELETE:**
+- `server.json` - Required for MCP protocol
+- `registry/bitbucket-mcp.manifest.json` - Required for registry
+- `scripts/*.mjs` - Used in build/validation pipeline
+- `package.json` - Project metadata
+- `tsconfig.json` - TypeScript compilation
+
+✅ **SAFE TO DELETE (if not using):**
+- `Dockerfile` - Only if not deploying to containers
+- `.github/workflows/` - Only if not using GitHub Actions
+- `DEPLOYMENT.txt` - Only if you have separate deployment docs
+
+---
+
+## Environment Variables Required for Deployment
+
+When deploying to NPM, you need these environment variables:
+
+### GitHub Actions (for automated publishing)
+```bash
+NPM_TOKEN=npm_...         # NPM authentication token
+GITHUB_TOKEN=ghp_...      # GitHub API token (usually auto-provided)
+```
+
+### Local Development
+```bash
+BITBUCKET_TOKEN=...           # Your app password
+BITBUCKET_WORKSPACE=...       # Your Bitbucket workspace
+```
+
+See [ENVIRONMENT_VARIABLES.md](ENVIRONMENT_VARIABLES.md) for complete reference.
+
+---
+
+## Summary
+
+| Directory/File | Purpose | Who Edits It | Auto-Generated |
+|---|---|---|---|
+| `src/` | Source code | You | ❌ |
+| `dist/` | Compiled JS | Build system | ✅ |
+| `__tests__/` | Tests | You | ❌ |
+| `docs/` | Documentation | You | ❌ |
+| `server.json` | MCP config | Version auto-synced | ⚠️ |
+| `registry/*.json` | Registry metadata | Generated from package.json | ✅ |
+| `scripts/` | Build utilities | You (rarely) | ❌ |
+| `package.json` | Dependencies & metadata | You | ❌ |
+| `tsconfig.json` | TypeScript config | You (rarely) | ❌ |
+| `.github/workflows/` | CI/CD automation | You (rarely) | ❌ |
+

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@atercates/bitbucket-mcp",
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) server for Bitbucket Cloud and Server API integration",
+  "mcpName": "io.github.bitbucket-mcp/bitbucket-mcp",
+  "type": "module",
+  "private": false,
+  "main": "dist/index.js",
+  "bin": {
+    "bitbucket-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "keywords": [
+    "bitbucket",
+    "bitbucket-cloud",
+    "bitbucket-server",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm"
+  ],
+  "author": "Bitbucket MCP Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atercates/bitbucket-mcp"
+  },
+  "homepage": "https://github.com/atercates/bitbucket-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/atercates/bitbucket-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "axios": "^1.13.6",
+    "winston": "^3.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^4.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "version": "git add -A src",
+    "postversion": "git push && git push --tags",
+    "publish:patch": "pnpm version patch && pnpm publish",
+    "publish:minor": "pnpm version minor && pnpm publish",
+    "publish:major": "pnpm version major && pnpm publish",
+    "release": "pnpm publish:patch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "inspector": "pnpm dlx @modelcontextprotocol/inspector dist/index.js",
+    "registry:manifest": "node scripts/generate-registry-manifest.cjs",
+    "registry:validate": "node scripts/validate-server-json.mjs"
+  }
+}