bamboo-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# Bamboo MCP Server - CI/CD Operations for Any Prompt
+
+[![NPM Version](https://img.shields.io/npm/v/bamboo-mcp-server?color=red)](https://www.npmjs.com/package/bamboo-mcp-server)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-1.0-green)](https://modelcontextprotocol.io/)
+
+A Model Context Protocol (MCP) server that brings Atlassian Bamboo CI/CD operations directly into AI assistants like Claude Code and Cursor.
+
+## ❌ Without Bamboo MCP
+
+Working with Bamboo CI/CD requires constant context switching:
+
+- ❌ Switching to browser to check build status
+- ❌ Manually navigating through Bamboo UI to find logs
+- ❌ Copy-pasting build keys and deployment IDs
+- ❌ No AI assistance for CI/CD troubleshooting
+
+## ✅ With Bamboo MCP
+
+Bamboo MCP brings your CI/CD operations directly into your AI workflow:
+
+```txt
+What's the status of the latest build for project MY-PROJECT?
+```
+
+```txt
+Show me the deployment logs for deployment result 2661941325
+```
+
+```txt
+Trigger a build for plan PROJ-PLAN with variable ENV=staging
+```
+
+No tab-switching, no manual navigation — just ask and get instant CI/CD insights.
+
+## Features
+
+- **24 tools** covering all major Bamboo operations
+- **Build logs** with actual content (not just URLs)
+- **Deployment logs** with full output
+- **Proxy support** for corporate environments
+- **TypeScript** with full type safety
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- Bamboo personal access token ([how to create](#creating-a-bamboo-token))
+
+### From Source
+
+```bash
+git clone https://github.com/norus/atlassian-bamboo-mcp.git
+cd atlassian-bamboo-mcp
+npm install
+npm run build
+```
+
+### From npm
+
+```bash
+npm install -g bamboo-mcp-server
+```
+
+## Configuration
+
+The server requires these environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BAMBOO_URL` | Yes | Base URL of your Bamboo server |
+| `BAMBOO_TOKEN` | Yes | Personal access token |
+| `BAMBOO_PROXY` | No | Proxy URL (e.g., `http://proxy:8080`) |
+
+### Creating a Bamboo Token
+
+1. Log into Bamboo
+2. Go to **Profile** → **Personal access tokens**
+3. Click **Create token**
+4. Give it a name and appropriate permissions
+5. Copy the token (you won't see it again)
+
+## Setup
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+Run this command:
+
+```bash
+claude mcp add bamboo -- node /path/to/bamboo-mcp-server/dist/index.js
+```
+
+Or add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "bamboo": {
+      "command": "node",
+      "args": ["/path/to/bamboo-mcp-server/dist/index.js"],
+      "env": {
+        "BAMBOO_URL": "https://bamboo.example.com",
+        "BAMBOO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to your config file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "bamboo": {
+      "command": "node",
+      "args": ["/path/to/bamboo-mcp-server/dist/index.js"],
+      "env": {
+        "BAMBOO_URL": "https://bamboo.example.com",
+        "BAMBOO_TOKEN": "your-token",
+        "BAMBOO_PROXY": "http://proxy:8080"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "bamboo": {
+      "command": "node",
+      "args": ["/path/to/bamboo-mcp-server/dist/index.js"],
+      "env": {
+        "BAMBOO_URL": "https://bamboo.example.com",
+        "BAMBOO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>npx</b></summary>
+
+```bash
+BAMBOO_URL="https://bamboo.example.com" \
+BAMBOO_TOKEN="your-token" \
+npx bamboo-mcp-server
+```
+
+</details>
+
+<details>
+<summary><b>Docker</b></summary>
+
+#### Build the image
+
+```bash
+docker build -t bamboo-mcp-server .
+```
+
+#### Run with Docker
+
+```bash
+docker run -i --rm \
+  -e BAMBOO_URL="https://bamboo.example.com" \
+  -e BAMBOO_TOKEN="your-token" \
+  bamboo-mcp-server
+```
+
+#### Use with Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "bamboo": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "BAMBOO_URL=https://bamboo.example.com",
+        "-e", "BAMBOO_TOKEN=your-token",
+        "bamboo-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+#### Docker Compose
+
+```yaml
+services:
+  bamboo-mcp:
+    build: .
+    environment:
+      - BAMBOO_URL=https://bamboo.example.com
+      - BAMBOO_TOKEN=${BAMBOO_TOKEN}
+    stdin_open: true
+```
+
+</details>
+
+## Available Tools
+
+### Server (2)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_server_info` | Get Bamboo server version and state |
+| `bamboo_health_check` | Check server health status |
+
+### Projects (2)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_list_projects` | List all projects |
+| `bamboo_get_project` | Get project details by key |
+
+### Plans (5)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_list_plans` | List all build plans |
+| `bamboo_get_plan` | Get plan details by key |
+| `bamboo_search_plans` | Search plans by name |
+| `bamboo_enable_plan` | Enable a build plan |
+| `bamboo_disable_plan` | Disable a build plan |
+
+### Branches (2)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_list_plan_branches` | List branches for a plan |
+| `bamboo_get_plan_branch` | Get branch details |
+
+### Builds (7)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_trigger_build` | Trigger a build (supports variables) |
+| `bamboo_stop_build` | Stop a running build |
+| `bamboo_get_build_result` | Get specific build result |
+| `bamboo_get_latest_result` | Get latest build result |
+| `bamboo_list_build_results` | List build results with filters |
+| `bamboo_get_build_logs` | Get build log file URLs |
+| `bamboo_get_build_result_logs` | Get build logs with actual content |
+
+### Queue (2)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_get_build_queue` | Get current build queue |
+| `bamboo_get_deployment_queue` | Get deployment queue status |
+
+### Deployments (5)
+
+| Tool | Description |
+|------|-------------|
+| `bamboo_list_deployment_projects` | List deployment projects |
+| `bamboo_get_deployment_project` | Get deployment project details |
+| `bamboo_get_deployment_results` | Get deployment results for environment |
+| `bamboo_get_deployment_result` | Get deployment result with logs |
+| `bamboo_trigger_deployment` | Trigger a deployment |
+
+## Example Prompts
+
+```txt
+Show me all failed builds in the last 24 hours
+```
+
+```txt
+What's blocking the deployment queue?
+```
+
+```txt
+Get the logs for build PROJ-PLAN-123 and tell me why it failed
+```
+
+```txt
+Trigger a build for MY-PROJECT with variable DEPLOY_ENV=staging
+```
+
+```txt
+List all branches for plan MY-PLAN and their build status
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+BAMBOO_URL="https://bamboo.example.com" \
+BAMBOO_TOKEN="your-token" \
+node dist/index.js
+```
+
+## Troubleshooting
+
+<details>
+<summary><b>Connection refused / timeout</b></summary>
+
+- Verify `BAMBOO_URL` is correct and accessible
+- If behind a proxy, set `BAMBOO_PROXY`
+- Check if your token has expired
+
+</details>
+
+<details>
+<summary><b>401 Unauthorized</b></summary>
+
+- Verify your `BAMBOO_TOKEN` is correct
+- Ensure the token hasn't expired
+- Check token permissions in Bamboo
+
+</details>
+
+<details>
+<summary><b>Tool not found in Claude</b></summary>
+
+- Restart Claude Code/Desktop after config changes
+- Verify the path to `dist/index.js` is absolute
+- Check Claude's MCP logs for errors
+
+</details>
+
+## Security
+
+- **No hardcoded secrets** — all credentials via environment variables
+- **Input validation** — Zod schemas on all tool inputs
+- **Proxy support** — works in corporate environments
+- **Read-heavy** — most operations are read-only
+
+For security issues, please report via GitHub Security tab.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines before submitting PRs.

package/dist/bamboo-client.d.ts

@@ -0,0 +1,71 @@
+import type { BambooClientConfig } from './types.js';
+export declare class BambooClient {
+    private baseUrl;
+    private token;
+    private proxyAgent?;
+    constructor(config: BambooClientConfig);
+    private request;
+    getServerInfo(): Promise<unknown>;
+    healthCheck(): Promise<unknown>;
+    listProjects(params?: {
+        expand?: string;
+        startIndex?: number;
+        maxResults?: number;
+    }): Promise<unknown>;
+    getProject(projectKey: string, expand?: string): Promise<unknown>;
+    listPlans(params?: {
+        expand?: string;
+        startIndex?: number;
+        maxResults?: number;
+    }): Promise<unknown>;
+    getPlan(planKey: string, expand?: string): Promise<unknown>;
+    searchPlans(name: string, params?: {
+        fuzzy?: boolean;
+        startIndex?: number;
+        maxResults?: number;
+    }): Promise<unknown>;
+    enablePlan(planKey: string): Promise<unknown>;
+    disablePlan(planKey: string): Promise<unknown>;
+    listPlanBranches(planKey: string, params?: {
+        enabledOnly?: boolean;
+        startIndex?: number;
+        maxResults?: number;
+    }): Promise<unknown>;
+    getPlanBranch(planKey: string, branchName: string): Promise<unknown>;
+    triggerBuild(planKey: string, params?: {
+        stage?: string;
+        executeAllStages?: boolean;
+        customRevision?: string;
+        variables?: Record<string, string>;
+    }): Promise<unknown>;
+    stopBuild(planKey: string): Promise<unknown>;
+    getBuildResult(buildKey: string, expand?: string): Promise<unknown>;
+    getLatestBuildResult(planKey: string, expand?: string): Promise<unknown>;
+    listBuildResults(params?: {
+        projectKey?: string;
+        planKey?: string;
+        buildState?: string;
+        startIndex?: number;
+        maxResults?: number;
+        expand?: string;
+        includeAllStates?: boolean;
+    }): Promise<unknown>;
+    getBuildLogs(buildKey: string, jobKey?: string): Promise<unknown>;
+    getBuildResultWithLogs(buildKey: string, params?: {
+        maxLogLines?: number;
+    }): Promise<unknown>;
+    getBuildQueue(expand?: string): Promise<unknown>;
+    getDeploymentQueue(): Promise<unknown>;
+    listDeploymentProjects(): Promise<unknown>;
+    getDeploymentProject(projectId: string | number): Promise<unknown>;
+    triggerDeployment(versionId: string | number, environmentId: string | number): Promise<unknown>;
+    getDeploymentResults(environmentId: string | number, params?: {
+        startIndex?: number;
+        maxResults?: number;
+    }): Promise<unknown>;
+    getDeploymentResult(deploymentResultId: string | number, params?: {
+        includeLogs?: boolean;
+        maxLogLines?: number;
+    }): Promise<unknown>;
+}
+export declare function createBambooClientFromEnv(): BambooClient;