mcp-server-bitbucket 0.11.0 → 0.19.0

package/src/index.ts

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 /**
  * Bitbucket MCP Server - TypeScript Implementation
- * 
+ *
  * Provides tools for interacting with Bitbucket repositories,
  * pull requests, pipelines, branches, commits, deployments, and webhooks.
+ *
+ * Supports two transport modes:
+ * - stdio (default): For local MCP clients like Claude Desktop
+ * - http: For remote MCP clients via Streamable HTTP (set MCP_TRANSPORT=http)
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
@@ -16,13 +21,37 @@ import {
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { createServer as createHttpServer, type RequestListener } from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { HttpInputError, parseMcpBody, readHttpBody } from './http-input.js';
+import {
+  AS_METADATA_PATH,
+  getAuthConfig,
+  METADATA_PATHS,
+  protectedResourceMetadata,
+  verifyBearer,
+  wwwAuthenticate,
+} from './auth.js';
+import {
+  AUTHORIZE_PATH,
+  buildAuthorizeRedirect,
+  forwardTokenRequest,
+  getProxyConfig,
+  proxyAuthorizationServerMetadata,
+  redactUrlForLog,
+  REGISTER_PATH,
+  registerClient,
+  resolveUpstreamEndpoints,
+  TOKEN_PATH,
+} from './oauth-proxy.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';
+const VERSION = '0.19.0';
 
 function createServer(): Server {
   const server = new Server(
@@ -125,6 +154,235 @@ function createServer(): Server {
   return server;
 }
 
+async function startStdio(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`Bitbucket MCP Server v${VERSION} started (stdio)`);
+}
+
+export function createHttpHandler(): RequestListener {
+  const sessions = new Map<string, { server: Server; transport: StreamableHTTPServerTransport }>();
+
+  // OAuth protection for /mcp. Null when unconfigured, in which case the
+  // endpoint stays open exactly as before (see src/auth.ts).
+  const auth = getAuthConfig();
+  // We stand in as the authorization server, translating to the real one (see
+  // src/oauth-proxy.ts for why going direct cannot work with Entra).
+  const proxy = auth ? getProxyConfig(auth) : null;
+
+  return async (req, res) => {
+    // CORS headers for remote MCP clients
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, DELETE');
+    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, mcp-session-id');
+    res.setHeader('Access-Control-Expose-Headers', 'mcp-session-id');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // One line per request. With a single shared Bitbucket credential this is
+    // the only record of who used the server, and it is what makes an OAuth
+    // problem diagnosable from the outside.
+    const clientIp =
+      (req.headers['x-forwarded-for'] as string | undefined)?.split(',')[0]?.trim() ??
+      req.socket.remoteAddress ??
+      'unknown';
+    res.on('finish', () => {
+      console.error(
+        `${req.method} ${redactUrlForLog(req.url ?? '')} -> ${res.statusCode} from ${clientIp}${
+          callerLabel ? ` (${callerLabel})` : ''
+        }`
+      );
+    });
+    let callerLabel = '';
+
+    // Health check — deliberately left open so platform probes keep working
+    if (req.method === 'GET' && req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', version: VERSION }));
+      return;
+    }
+
+    // Tells clients which authorization server issues tokens for this resource
+    if (auth && req.method === 'GET' && METADATA_PATHS.includes(req.url || '')) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(protectedResourceMetadata(auth)));
+      return;
+    }
+
+    // We are the authorization server as far as clients are concerned.
+    if (auth && proxy && req.method === 'GET' && req.url === AS_METADATA_PATH) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(proxyAuthorizationServerMetadata(auth, proxy)));
+      return;
+    }
+
+    // Authorization request: hand the user to the real authorization server,
+    // rewriting only what it will not accept.
+    if (auth && proxy && req.method === 'GET' && req.url?.startsWith(AUTHORIZE_PATH)) {
+      try {
+        const { authorize } = await resolveUpstreamEndpoints(auth);
+        const requestUrl = new URL(req.url, proxy.origin);
+        const result = buildAuthorizeRedirect(requestUrl, proxy, authorize);
+
+        if (result.status === 302) {
+          res.writeHead(302, { Location: result.location });
+          res.end();
+        } else {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: result.error, error_description: result.description }));
+        }
+      } catch (error) {
+        console.error(`Authorization request could not be forwarded: ${error}`);
+        res.writeHead(502, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'authorization_server_unavailable' }));
+      }
+      return;
+    }
+
+    // Dynamic client registration: MCP clients refuse an authorization server
+    // without it, so we hand back the client that already exists upstream.
+    if (auth && proxy && req.method === 'POST' && req.url === REGISTER_PATH) {
+      let parsed: unknown = {};
+      try {
+        parsed = JSON.parse((await readHttpBody(req.iterator({ destroyOnReturn: false }))).toString('utf8') || '{}');
+      } catch (error) {
+        const status = error instanceof HttpInputError ? error.status : 400;
+        res.writeHead(status, { 'Content-Type': 'application/json', Connection: 'close' });
+        res.end(JSON.stringify({ error: 'invalid_request', error_description:
+          error instanceof HttpInputError ? error.message : 'Body must be JSON' }));
+        return;
+      }
+
+      const result = registerClient(parsed, proxy);
+      if (result.status === 201) {
+        res.writeHead(201, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result.body));
+      } else {
+        res.writeHead(result.status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error, error_description: result.description }));
+      }
+      return;
+    }
+
+    // Token exchange: forwarded verbatim, so the token stays the issuer's.
+    if (auth && proxy && req.method === 'POST' && req.url === TOKEN_PATH) {
+      try {
+        const body = await readHttpBody(req.iterator({ destroyOnReturn: false }));
+        const { token } = await resolveUpstreamEndpoints(auth);
+        const upstream = await forwardTokenRequest(
+          body.toString('utf8'),
+          req.headers.authorization,
+          token
+        );
+
+        res.writeHead(upstream.status, { 'Content-Type': upstream.contentType });
+        res.end(upstream.body);
+      } catch (error) {
+        if (error instanceof HttpInputError) {
+          res.writeHead(error.status, { 'Content-Type': 'application/json', Connection: 'close' });
+          res.end(JSON.stringify({ error: 'invalid_request', error_description: error.message }));
+          return;
+        }
+        console.error(`Token request could not be forwarded: ${error}`);
+        res.writeHead(502, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'authorization_server_unavailable' }));
+      }
+      return;
+    }
+
+    if (req.url !== '/mcp') {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    // Every /mcp request carries its own token: a session is not a credential,
+    // so an established session must not become a way around the check.
+    if (auth) {
+      const result = await verifyBearer(req.headers.authorization, auth);
+      if (result.ok) {
+        callerLabel = result.caller ?? result.subject ?? 'authenticated';
+      }
+      if (!result.ok) {
+        res.writeHead(result.status, {
+          'Content-Type': 'application/json',
+          'WWW-Authenticate': wwwAuthenticate(auth, result),
+        });
+        res.end(JSON.stringify({ error: result.error, error_description: result.description }));
+        return;
+      }
+    }
+
+    // Authenticate first, then bound and parse input before the SDK validates it.
+    let parsedBody: unknown;
+    if (req.method === 'POST') {
+      try {
+        parsedBody = parseMcpBody(await readHttpBody(req.iterator({ destroyOnReturn: false })));
+      } catch (error) {
+        const status = error instanceof HttpInputError ? error.status : 400;
+        res.writeHead(status, { 'Content-Type': 'application/json', Connection: 'close' });
+        res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: {
+          code: -32600, message: error instanceof HttpInputError ? error.message : 'Invalid JSON',
+        } }));
+        return;
+      }
+    }
+
+    // Check for existing session
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+    if (sessionId && sessions.has(sessionId)) {
+      // Existing session — route to its transport
+      const session = sessions.get(sessionId)!;
+      await session.transport.handleRequest(req, res, parsedBody);
+      return;
+    }
+
+    // New session (POST without session ID = initialize)
+    if (req.method === 'POST' && !sessionId) {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+      });
+      const server = createServer();
+
+      transport.onclose = () => {
+        const sid = (transport as unknown as { _sessionId?: string })._sessionId;
+        if (sid) sessions.delete(sid);
+        server.close();
+      };
+
+      await server.connect(transport);
+      await transport.handleRequest(req, res, parsedBody);
+
+      // Capture the session ID that was generated
+      const newSessionId = res.getHeader('mcp-session-id') as string | undefined;
+      if (newSessionId) {
+        sessions.set(newSessionId, { server, transport });
+      }
+      return;
+    }
+
+    // Session not found
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Invalid or missing session' }));
+  };
+}
+
+async function startHttp(): Promise<void> {
+  const port = parseInt(process.env.PORT || '3000', 10);
+  const auth = getAuthConfig();
+  const httpServer = createHttpServer(createHttpHandler());
+  httpServer.listen(port, () => {
+    const mode = auth ? `OAuth required (issuer ${auth.issuer})` : 'unauthenticated';
+    console.error(`Bitbucket MCP Server v${VERSION} started (http) on port ${port} — ${mode}`);
+  });
+}
+
 async function main(): Promise<void> {
   // Validate settings on startup
   try {
@@ -134,16 +392,19 @@ async function main(): Promise<void> {
     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`);
+  const transport = process.env.MCP_TRANSPORT || (process.argv.includes('--http') ? 'http' : 'stdio');
+
+  if (transport === 'http') {
+    await startHttp();
+  } else {
+    await startStdio();
+  }
 }
 
-main().catch((error) => {
-  console.error('Fatal error:', error);
-  process.exit(1);
-});
+// Importing the handler for in-memory contracts must not start a listener.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}

package/src/oauth-proxy.ts

@@ -0,0 +1,298 @@
+/**
+ * Minimal OAuth proxy in front of the upstream authorization server.
+ *
+ * Why this exists: the MCP authorization spec and Microsoft Entra ID cannot be
+ * satisfied at the same time by pointing clients straight at Entra.
+ *
+ * - RFC 9728 requires the `resource` in our metadata to be the identifier the
+ *   metadata URL was built from, i.e. https://<host>/mcp. Clients send that as
+ *   the RFC 8707 `resource` parameter.
+ * - Entra rejects exactly that with AADSTS9010010 ("the resource parameter
+ *   provided in the request doesn't match with the requested scopes"): for Entra
+ *   the resource is the API's Application ID URI, and it only accepts https
+ *   identifiers on domains verified in the tenant.
+ * - Entra also serves no RFC 8414 metadata and no dynamic client registration.
+ *
+ * So this server becomes the authorization server clients talk to, and
+ * translates on the way through. It is deliberately thin:
+ *
+ * - it issues nothing and stores nothing — no tokens, no codes, no sessions;
+ * - /oauth/authorize redirects to Entra, swapping the scope for the one Entra
+ *   expects and dropping `resource`, while PKCE and state pass through untouched;
+ * - /oauth/token forwards the exchange to Entra verbatim (minus `resource`) and
+ *   returns its response, so the access token is still Entra's and is still
+ *   verified against Entra's keys by src/auth.ts.
+ *
+ * Redirect URIs are checked against an allowlist: this is the one place where a
+ * proxy like this can be turned into an open redirect, so it is not optional.
+ *
+ * Dynamic client registration (RFC 7591) is part of that translation: MCP
+ * clients refuse an authorization server without it ("Incompatible auth server:
+ * does not support dynamic client registration"), while Entra has no such
+ * endpoint. Registration here does not create anything — it hands back the
+ * client that already exists in Entra, and only for redirect URIs we accept.
+ * The client is registered in Entra as a public client, so there is no secret
+ * to hand out: PKCE is what protects the exchange.
+ *
+ * Environment variables:
+ * - MCP_OAUTH_UPSTREAM_SCOPE: scope requested from Entra, e.g.
+ *   "api://<app-id>/mcp.access offline_access"
+ * - MCP_OAUTH_REDIRECT_ALLOWLIST: comma-separated redirect URIs to accept
+ *   (defaults to Claude's callbacks)
+ */
+
+import type { AuthConfig } from './auth.js';
+import { authorizationServerMetadata, serverOrigin } from './auth.js';
+
+export const AUTHORIZE_PATH = '/oauth/authorize';
+export const TOKEN_PATH = '/oauth/token';
+export const REGISTER_PATH = '/oauth/register';
+
+/** Claude's callbacks. Loopback redirects are handled separately, below. */
+const DEFAULT_REDIRECT_ALLOWLIST = [
+  'https://claude.ai/api/mcp/auth_callback',
+  'https://claude.com/api/mcp/auth_callback',
+];
+
+/**
+ * Whether we are willing to send the user back to this redirect.
+ *
+ * Besides the configured list, loopback URIs are accepted: MCP clients that run
+ * on the user's own machine (Claude Code among them) listen on an ephemeral port
+ * and cannot register it in advance, which is exactly the case RFC 8252 §7.3
+ * describes. Only the host is trusted here — the port varies by design, and a
+ * loopback address is only reachable from the user's own machine.
+ */
+export function isAllowedRedirect(uri: string, allowlist: string[]): boolean {
+  if (allowlist.includes(uri)) {
+    return true;
+  }
+
+  try {
+    const parsed = new URL(uri);
+    return (
+      parsed.protocol === 'http:' &&
+      (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '[::1]')
+    );
+  } catch {
+    return false;
+  }
+}
+
+export interface ProxyConfig {
+  /** Public origin of this server; it is the issuer clients see. */
+  origin: string;
+  /** The client already registered upstream, handed out on registration. */
+  clientId: string;
+  /** Scope to request upstream, in place of whatever the client asked for. */
+  upstreamScope: string;
+  /** Redirect URIs we are willing to send users back to. */
+  redirectAllowlist: string[];
+}
+
+export function getProxyConfig(
+  auth: AuthConfig,
+  env: NodeJS.ProcessEnv = process.env
+): ProxyConfig {
+  const configured = (env.MCP_OAUTH_REDIRECT_ALLOWLIST || '')
+    .split(/[\s,]+/)
+    .filter(Boolean);
+
+  return {
+    origin: serverOrigin(auth),
+    clientId: (env.MCP_OAUTH_CLIENT_ID || '').trim(),
+    upstreamScope:
+      (env.MCP_OAUTH_UPSTREAM_SCOPE || '').trim() ||
+      [...(auth.advertisedScopes ?? []), 'offline_access'].join(' ').trim(),
+    redirectAllowlist: configured.length > 0 ? configured : DEFAULT_REDIRECT_ALLOWLIST,
+  };
+}
+
+/**
+ * Metadata for ourselves as the authorization server (RFC 8414). Clients build
+ * the whole flow from this, so the endpoints are ours, not Entra's.
+ */
+export function proxyAuthorizationServerMetadata(
+  auth: AuthConfig,
+  proxy: ProxyConfig
+): Record<string, unknown> {
+  return {
+    issuer: proxy.origin,
+    authorization_endpoint: `${proxy.origin}${AUTHORIZE_PATH}`,
+    token_endpoint: `${proxy.origin}${TOKEN_PATH}`,
+    response_types_supported: ['code'],
+    grant_types_supported: ['authorization_code', 'refresh_token'],
+    code_challenge_methods_supported: ['S256'],
+    token_endpoint_auth_methods_supported: ['none'],
+    ...(proxy.clientId ? { registration_endpoint: `${proxy.origin}${REGISTER_PATH}` } : {}),
+    ...(auth.advertisedScopes ? { scopes_supported: auth.advertisedScopes } : {}),
+  };
+}
+
+export type AuthorizeResult =
+  | { status: 302; location: string }
+  | { status: 400; error: string; description: string };
+
+/**
+ * Turn the client's authorization request into the upstream one.
+ *
+ * Everything the client chose about the flow — state, PKCE challenge, response
+ * type — is passed through unchanged. Only the parameters Entra disagrees with
+ * are rewritten: `scope` becomes the API scope, and `resource` is dropped.
+ */
+export function buildAuthorizeRedirect(
+  requestUrl: URL,
+  proxy: ProxyConfig,
+  upstreamAuthorizeEndpoint: string
+): AuthorizeResult {
+  const redirectUri = requestUrl.searchParams.get('redirect_uri');
+  if (!redirectUri) {
+    return { status: 400, error: 'invalid_request', description: 'redirect_uri is required' };
+  }
+  if (!isAllowedRedirect(redirectUri, proxy.redirectAllowlist)) {
+    // An unchecked redirect_uri here would make this an open redirect.
+    return {
+      status: 400,
+      error: 'invalid_request',
+      description: 'redirect_uri is not allowed for this server',
+    };
+  }
+
+  const upstream = new URL(upstreamAuthorizeEndpoint);
+  const passthrough = [
+    'client_id',
+    'response_type',
+    'redirect_uri',
+    'state',
+    'code_challenge',
+    'code_challenge_method',
+    'prompt',
+    'login_hint',
+  ];
+  for (const name of passthrough) {
+    const value = requestUrl.searchParams.get(name);
+    if (value !== null) {
+      upstream.searchParams.set(name, value);
+    }
+  }
+  upstream.searchParams.set('scope', proxy.upstreamScope);
+
+  return { status: 302, location: upstream.toString() };
+}
+
+/**
+ * Body to forward to the upstream token endpoint: the client's own body with
+ * `resource` removed, since that is what Entra objects to.
+ */
+export function buildTokenRequestBody(rawBody: string): URLSearchParams {
+  const params = new URLSearchParams(rawBody);
+  params.delete('resource');
+  return params;
+}
+
+export interface TokenResponse {
+  status: number;
+  body: string;
+  contentType: string;
+}
+
+/** Forward the token exchange upstream and hand back whatever it answers. */
+export async function forwardTokenRequest(
+  rawBody: string,
+  authorizationHeader: string | undefined,
+  upstreamTokenEndpoint: string,
+  fetchImpl: typeof fetch = fetch
+): Promise<TokenResponse> {
+  const response = await fetchImpl(upstreamTokenEndpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      ...(authorizationHeader ? { Authorization: authorizationHeader } : {}),
+    },
+    body: buildTokenRequestBody(rawBody).toString(),
+  });
+
+  return {
+    status: response.status,
+    body: await response.text(),
+    contentType: response.headers.get('content-type') ?? 'application/json',
+  };
+}
+
+/** Upstream endpoints, read from the issuer's own configuration. */
+export async function resolveUpstreamEndpoints(
+  auth: AuthConfig,
+  fetchImpl: typeof fetch = fetch
+): Promise<{ authorize: string; token: string }> {
+  const metadata = await authorizationServerMetadata(auth, fetchImpl);
+  const authorize = metadata.authorization_endpoint;
+  const token = metadata.token_endpoint;
+
+  if (typeof authorize !== 'string' || typeof token !== 'string') {
+    throw new Error('Issuer configuration is missing authorization_endpoint or token_endpoint');
+  }
+
+  return { authorize, token };
+}
+
+/**
+ * A URL safe to write to the log: authorization requests carry state and PKCE
+ * challenges, and token responses carry tokens. Neither belongs in a log line.
+ */
+export function redactUrlForLog(url: string): string {
+  const [path, query] = url.split('?');
+  return query ? `${path}?<redacted>` : path;
+}
+
+export type RegistrationResult =
+  | { status: 201; body: Record<string, unknown> }
+  | { status: 400; error: string; description: string };
+
+/**
+ * Answer a dynamic client registration request with the client that already
+ * exists upstream.
+ *
+ * Nothing is created and nothing is stored. The redirect URIs are checked
+ * against the allowlist first: handing our client out for an arbitrary redirect
+ * is how this would turn into someone else's authorization flow.
+ */
+export function registerClient(request: unknown, proxy: ProxyConfig): RegistrationResult {
+  if (!proxy.clientId) {
+    return {
+      status: 400,
+      error: 'invalid_request',
+      description: 'This server has no upstream client configured',
+    };
+  }
+
+  const body = (request ?? {}) as Record<string, unknown>;
+  const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris : [];
+
+  if (redirectUris.length === 0) {
+    return { status: 400, error: 'invalid_redirect_uri', description: 'redirect_uris is required' };
+  }
+
+  const rejected = redirectUris.filter(
+    (uri) => typeof uri !== 'string' || !isAllowedRedirect(uri, proxy.redirectAllowlist)
+  );
+  if (rejected.length > 0) {
+    return {
+      status: 400,
+      error: 'invalid_redirect_uri',
+      description: 'redirect_uris are not allowed for this server',
+    };
+  }
+
+  return {
+    status: 201,
+    body: {
+      client_id: proxy.clientId,
+      redirect_uris: redirectUris,
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      client_id_issued_at: Math.floor(Date.now() / 1000),
+      ...(typeof body.client_name === 'string' ? { client_name: body.client_name } : {}),
+    },
+  };
+}

package/src/prompts.ts

@@ -2,7 +2,7 @@
  * MCP Prompts for Bitbucket Server
  */
 
-import { Prompt, GetPromptResult, PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+import { Prompt, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
 
 /**
  * Prompt definitions for the MCP server