mcp-server-bitbucket 0.11.0

package/src/index.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Bitbucket MCP Server - TypeScript Implementation
+ * 
+ * Provides tools for interacting with Bitbucket repositories,
+ * pull requests, pipelines, branches, commits, deployments, and webhooks.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { getSettings } from './settings.js';
+import { toolDefinitions, handleToolCall } from './tools/index.js';
+import { resourceDefinitions, handleResourceRead } from './resources.js';
+import { promptDefinitions, handlePromptGet } from './prompts.js';
+
+const VERSION = '0.10.0';
+
+function createServer(): Server {
+  const server = new Server(
+    {
+      name: 'bitbucket',
+      version: VERSION,
+    },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+      },
+    }
+  );
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: toolDefinitions,
+    };
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    
+    try {
+      const result = await handleToolCall(name, args || {});
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: message }, null, 2),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // List available resources
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+      resources: resourceDefinitions,
+    };
+  });
+
+  // Handle resource reads
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    
+    try {
+      const content = await handleResourceRead(uri);
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'text/markdown',
+            text: content,
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      throw new Error(`Failed to read resource: ${message}`);
+    }
+  });
+
+  // List available prompts
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+      prompts: promptDefinitions,
+    };
+  });
+
+  // Handle prompt gets
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    
+    try {
+      const result = handlePromptGet(name, args || {});
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      throw new Error(`Failed to get prompt: ${message}`);
+    }
+  });
+
+  return server;
+}
+
+async function main(): Promise<void> {
+  // Validate settings on startup
+  try {
+    getSettings();
+  } catch (error) {
+    console.error('Configuration error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  
+  await server.connect(transport);
+  
+  // Log to stderr so it doesn't interfere with MCP communication on stdout
+  console.error(`Bitbucket MCP Server v${VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/prompts.ts

@@ -0,0 +1,208 @@
+/**
+ * MCP Prompts for Bitbucket Server
+ */
+
+import { Prompt, GetPromptResult, PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Prompt definitions for the MCP server
+ */
+export const promptDefinitions: Prompt[] = [
+  {
+    name: 'code_review',
+    description: 'Generate a code review prompt for a pull request',
+    arguments: [
+      {
+        name: 'repo_slug',
+        description: 'Repository slug',
+        required: true,
+      },
+      {
+        name: 'pr_id',
+        description: 'Pull request ID',
+        required: true,
+      },
+    ],
+  },
+  {
+    name: 'release_notes',
+    description: 'Generate release notes from commits between two refs',
+    arguments: [
+      {
+        name: 'repo_slug',
+        description: 'Repository slug',
+        required: true,
+      },
+      {
+        name: 'base_tag',
+        description: 'Base tag or commit (e.g., "v1.0.0")',
+        required: true,
+      },
+      {
+        name: 'head',
+        description: 'Head ref (default: "main")',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'pipeline_debug',
+    description: 'Debug a failed pipeline',
+    arguments: [
+      {
+        name: 'repo_slug',
+        description: 'Repository slug',
+        required: true,
+      },
+    ],
+  },
+  {
+    name: 'repo_summary',
+    description: 'Get a comprehensive summary of a repository',
+    arguments: [
+      {
+        name: 'repo_slug',
+        description: 'Repository slug',
+        required: true,
+      },
+    ],
+  },
+];
+
+/**
+ * Handle prompt get requests
+ */
+export function handlePromptGet(
+  name: string,
+  args: Record<string, string>
+): GetPromptResult {
+  switch (name) {
+    case 'code_review':
+      return promptCodeReview(args.repo_slug, args.pr_id);
+    case 'release_notes':
+      return promptReleaseNotes(args.repo_slug, args.base_tag, args.head || 'main');
+    case 'pipeline_debug':
+      return promptPipelineDebug(args.repo_slug);
+    case 'repo_summary':
+      return promptRepoSummary(args.repo_slug);
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+}
+
+function promptCodeReview(repoSlug: string, prId: string): GetPromptResult {
+  const content = `Please review pull request #${prId} in repository '${repoSlug}'.
+
+Use the following tools to gather information:
+1. get_pull_request(repo_slug="${repoSlug}", pr_id=${prId}) - Get PR details
+2. get_pr_diff(repo_slug="${repoSlug}", pr_id=${prId}) - Get the code changes
+3. list_pr_comments(repo_slug="${repoSlug}", pr_id=${prId}) - See existing comments
+
+Then provide a thorough code review covering:
+- Code quality and readability
+- Potential bugs or edge cases
+- Security concerns
+- Performance considerations
+- Suggestions for improvement
+
+If you find issues, use add_pr_comment() to leave feedback on specific lines.`;
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: content,
+        },
+      },
+    ],
+  };
+}
+
+function promptReleaseNotes(repoSlug: string, baseTag: string, head: string): GetPromptResult {
+  const content = `Generate release notes for repository '${repoSlug}' comparing ${baseTag} to ${head}.
+
+Use these tools:
+1. compare_commits(repo_slug="${repoSlug}", base="${baseTag}", head="${head}") - See changed files
+2. list_commits(repo_slug="${repoSlug}", branch="${head}", limit=50) - Get recent commits
+
+Organize the release notes into sections:
+- **New Features**: New functionality added
+- **Bug Fixes**: Issues that were resolved
+- **Improvements**: Enhancements to existing features
+- **Breaking Changes**: Changes that require user action
+
+Format as markdown suitable for a GitHub/Bitbucket release.`;
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: content,
+        },
+      },
+    ],
+  };
+}
+
+function promptPipelineDebug(repoSlug: string): GetPromptResult {
+  const content = `Help debug pipeline failures in repository '${repoSlug}'.
+
+Use these tools:
+1. list_pipelines(repo_slug="${repoSlug}", limit=5) - Get recent pipeline runs
+2. get_pipeline(repo_slug="${repoSlug}", pipeline_uuid="<uuid>") - Get pipeline details
+3. get_pipeline_logs(repo_slug="${repoSlug}", pipeline_uuid="<uuid>") - Get step list
+4. get_pipeline_logs(repo_slug="${repoSlug}", pipeline_uuid="<uuid>", step_uuid="<step>") - Get logs
+
+Analyze the failures and provide:
+- Root cause of the failure
+- Specific error messages
+- Recommended fixes
+- Commands to re-run the pipeline if appropriate`;
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: content,
+        },
+      },
+    ],
+  };
+}
+
+function promptRepoSummary(repoSlug: string): GetPromptResult {
+  const content = `Provide a comprehensive summary of repository '${repoSlug}'.
+
+Gather information using:
+1. get_repository(repo_slug="${repoSlug}") - Basic repo info
+2. list_branches(repo_slug="${repoSlug}", limit=10) - Active branches
+3. list_pull_requests(repo_slug="${repoSlug}", state="OPEN") - Open PRs
+4. list_pipelines(repo_slug="${repoSlug}", limit=5) - Recent CI/CD status
+5. list_commits(repo_slug="${repoSlug}", limit=10) - Recent activity
+
+Summarize:
+- Repository description and purpose
+- Current development activity
+- Open pull requests needing attention
+- CI/CD health
+- Recent contributors`;
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: content,
+        },
+      },
+    ],
+  };
+}
+

package/src/resources.ts

@@ -0,0 +1,160 @@
+/**
+ * MCP Resources for Bitbucket Server
+ */
+
+import { Resource } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from './client.js';
+
+/**
+ * Resource definitions for the MCP server
+ */
+export const resourceDefinitions: Resource[] = [
+  {
+    uri: 'bitbucket://repositories',
+    name: 'Repositories',
+    description: 'List all repositories in the workspace',
+    mimeType: 'text/markdown',
+  },
+  {
+    uri: 'bitbucket://repositories/{repo_slug}',
+    name: 'Repository Details',
+    description: 'Get detailed information about a specific repository',
+    mimeType: 'text/markdown',
+  },
+  {
+    uri: 'bitbucket://repositories/{repo_slug}/branches',
+    name: 'Repository Branches',
+    description: 'List branches in a repository',
+    mimeType: 'text/markdown',
+  },
+  {
+    uri: 'bitbucket://repositories/{repo_slug}/pull-requests',
+    name: 'Pull Requests',
+    description: 'List open pull requests in a repository',
+    mimeType: 'text/markdown',
+  },
+  {
+    uri: 'bitbucket://projects',
+    name: 'Projects',
+    description: 'List all projects in the workspace',
+    mimeType: 'text/markdown',
+  },
+];
+
+/**
+ * Handle resource read requests
+ */
+export async function handleResourceRead(uri: string): Promise<string> {
+  const client = getClient();
+
+  // Parse the URI to extract parameters
+  if (uri === 'bitbucket://repositories') {
+    return await resourceRepositories(client);
+  }
+  
+  if (uri === 'bitbucket://projects') {
+    return await resourceProjects(client);
+  }
+
+  // Match repository-specific URIs
+  const repoMatch = uri.match(/^bitbucket:\/\/repositories\/([^/]+)$/);
+  if (repoMatch) {
+    return await resourceRepository(client, repoMatch[1]);
+  }
+
+  const branchesMatch = uri.match(/^bitbucket:\/\/repositories\/([^/]+)\/branches$/);
+  if (branchesMatch) {
+    return await resourceBranches(client, branchesMatch[1]);
+  }
+
+  const prsMatch = uri.match(/^bitbucket:\/\/repositories\/([^/]+)\/pull-requests$/);
+  if (prsMatch) {
+    return await resourcePullRequests(client, prsMatch[1]);
+  }
+
+  throw new Error(`Unknown resource URI: ${uri}`);
+}
+
+async function resourceRepositories(client: ReturnType<typeof getClient>): Promise<string> {
+  const repos = await client.listRepositories({ limit: 50 });
+  const lines = [`# Repositories in ${client.workspace}`, ''];
+  
+  for (const r of repos) {
+    const name = r.name || 'unknown';
+    const desc = (r.description || '').substring(0, 50) || 'No description';
+    const icon = r.is_private ? '🔒' : '🌐';
+    lines.push(`- ${icon} **${name}**: ${desc}`);
+  }
+  
+  return lines.join('\n');
+}
+
+async function resourceRepository(client: ReturnType<typeof getClient>, repoSlug: string): Promise<string> {
+  const repo = await client.getRepository(repoSlug);
+  if (!repo) {
+    return `Repository '${repoSlug}' not found`;
+  }
+
+  const lines = [
+    `# ${repo.name || repoSlug}`,
+    '',
+    `**Description**: ${repo.description || 'No description'}`,
+    `**Private**: ${repo.is_private ? 'Yes' : 'No'}`,
+    `**Project**: ${repo.project?.name || 'None'}`,
+    `**Main branch**: ${repo.mainbranch?.name || 'main'}`,
+    '',
+    '## Clone URLs',
+  ];
+  
+  for (const clone of repo.links?.clone || []) {
+    lines.push(`- ${clone.name}: \`${clone.href}\``);
+  }
+
+  return lines.join('\n');
+}
+
+async function resourceBranches(client: ReturnType<typeof getClient>, repoSlug: string): Promise<string> {
+  const branches = await client.listBranches(repoSlug, { limit: 30 });
+  const lines = [`# Branches in ${repoSlug}`, ''];
+  
+  for (const b of branches) {
+    const name = b.name || 'unknown';
+    const commit = (b.target?.hash || '').substring(0, 7);
+    lines.push(`- **${name}** (${commit})`);
+  }
+  
+  return lines.join('\n');
+}
+
+async function resourcePullRequests(client: ReturnType<typeof getClient>, repoSlug: string): Promise<string> {
+  const prs = await client.listPullRequests(repoSlug, { state: 'OPEN', limit: 20 });
+  const lines = [`# Open Pull Requests in ${repoSlug}`, ''];
+  
+  if (prs.length === 0) {
+    lines.push('No open pull requests');
+  }
+  
+  for (const pr of prs) {
+    const prId = pr.id;
+    const title = pr.title || 'Untitled';
+    const author = pr.author?.display_name || 'Unknown';
+    lines.push(`- **#${prId}**: ${title} (by ${author})`);
+  }
+  
+  return lines.join('\n');
+}
+
+async function resourceProjects(client: ReturnType<typeof getClient>): Promise<string> {
+  const projects = await client.listProjects({ limit: 50 });
+  const lines = [`# Projects in ${client.workspace}`, ''];
+  
+  for (const p of projects) {
+    const key = p.key || '?';
+    const name = p.name || 'Unknown';
+    const desc = (p.description || '').substring(0, 40) || 'No description';
+    lines.push(`- **${key}** - ${name}: ${desc}`);
+  }
+  
+  return lines.join('\n');
+}
+

package/src/settings.ts

@@ -0,0 +1,63 @@
+/**
+ * Settings management for Bitbucket MCP Server
+ * 
+ * Configuration via environment variables:
+ * - BITBUCKET_WORKSPACE: Bitbucket workspace slug (required)
+ * - BITBUCKET_EMAIL: Account email for Basic Auth (required)
+ * - BITBUCKET_API_TOKEN: Repository access token (required)
+ * - API_TIMEOUT: Request timeout in seconds (default: 30, max: 300)
+ * - MAX_RETRIES: Max retry attempts for rate limiting (default: 3, max: 10)
+ * - OUTPUT_FORMAT: Output format - 'json' or 'toon' (default: json)
+ */
+
+import { z } from 'zod';
+
+const settingsSchema = z.object({
+  bitbucketWorkspace: z.string().min(1, 'BITBUCKET_WORKSPACE is required'),
+  bitbucketEmail: z.string().min(1, 'BITBUCKET_EMAIL is required'),
+  bitbucketApiToken: z.string().min(1, 'BITBUCKET_API_TOKEN is required'),
+  apiTimeout: z.number().min(1).max(300).default(30),
+  maxRetries: z.number().min(0).max(10).default(3),
+  outputFormat: z.enum(['json', 'toon']).default('json'),
+});
+
+export type Settings = z.infer<typeof settingsSchema>;
+
+let cachedSettings: Settings | null = null;
+
+/**
+ * Load and validate settings from environment variables.
+ * Results are cached for subsequent calls.
+ */
+export function getSettings(): Settings {
+  if (cachedSettings) {
+    return cachedSettings;
+  }
+
+  const rawSettings = {
+    bitbucketWorkspace: process.env.BITBUCKET_WORKSPACE || '',
+    bitbucketEmail: process.env.BITBUCKET_EMAIL || '',
+    bitbucketApiToken: process.env.BITBUCKET_API_TOKEN || '',
+    apiTimeout: parseInt(process.env.API_TIMEOUT || '30', 10),
+    maxRetries: parseInt(process.env.MAX_RETRIES || '3', 10),
+    outputFormat: (process.env.OUTPUT_FORMAT || 'json') as 'json' | 'toon',
+  };
+
+  const result = settingsSchema.safeParse(rawSettings);
+  
+  if (!result.success) {
+    const errors = result.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
+    throw new Error(`Configuration error: ${errors}`);
+  }
+
+  cachedSettings = result.data;
+  return cachedSettings;
+}
+
+/**
+ * Reset cached settings (useful for testing)
+ */
+export function resetSettings(): void {
+  cachedSettings = null;
+}
+

package/src/tools/branches.ts

@@ -0,0 +1,69 @@
+/**
+ * Branch tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit, notFoundResponse } from '../utils.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'list_branches',
+    description: 'List branches in a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'get_branch',
+    description: 'Get information about a specific branch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        branch_name: { type: 'string', description: 'Branch name' },
+      },
+      required: ['repo_slug', 'branch_name'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  list_branches: async (args) => {
+    const client = getClient();
+    const branches = await client.listBranches(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) || 50),
+    });
+    return {
+      branches: branches.map(b => ({
+        name: b.name,
+        commit: b.target?.hash?.substring(0, 7),
+        message: b.target?.message,
+        date: b.target?.date,
+      })),
+    };
+  },
+
+  get_branch: async (args) => {
+    const client = getClient();
+    const result = await client.getBranch(args.repo_slug as string, args.branch_name as string);
+    if (!result) {
+      return notFoundResponse('Branch', args.branch_name as string);
+    }
+    return {
+      name: result.name,
+      latest_commit: {
+        hash: result.target?.hash,
+        message: result.target?.message || '',
+        author: result.target?.author?.raw,
+        date: result.target?.date,
+      },
+    };
+  },
+};
+