Backlog MCP Server

Instructions

Implementation Reference

• registerEndpoints.ts:60-151 (handler)

  Generic handler that executes the tool logic for 'getIssue': validates params with schema, processes path 'issues/{issueId}' by replacing {issueId}, calls fetchFromBacklog, returns JSON response.
  const handler = async (params: Record<string, unknown>): Promise<McpResponse> => { try { // パラメータのバリデーション const validatedParams = await endpoint.schema.parseAsync(params); // URL中のプレースホルダーを置換 let path = endpoint.path; // URIスキーム（例：space://info）の場合はBacklog APIのパスに変換 if (path.includes('://')) { // URIスキームを取り除いてAPIパスに変換 const uriParts = path.split('://'); const resourceType = uriParts[0]; const resourcePath = uriParts[1]; // リソースタイプに応じてAPIパスを構築 switch (resourceType) { case 'space': path = 'space'; break; case 'projects': if (resourcePath === 'list') { path = 'projects'; } else { path = `projects/${resourcePath}`; } break; case 'issues': if (resourcePath.includes('/list')) { const projectPart = resourcePath.split('/')[0]; path = 'issues'; validatedParams.projectIdOrKey = projectPart; } else if (resourcePath.includes('/details')) { const issuePart = resourcePath.split('/')[0]; path = `issues/${issuePart}`; } break; case 'wikis': if (resourcePath.includes('/list')) { const projectPart = resourcePath.split('/')[0]; path = 'wikis'; validatedParams.projectIdOrKey = projectPart; } break; case 'users': path = 'users'; break; default: path = resourcePath; } } // 通常のパスパラメータの置換処理 for (const [key, value] of Object.entries(validatedParams)) { if (typeof value === "string" || typeof value === "number") { const placeholder = `{${key}}`; if (path.includes(placeholder)) { path = path.replace(placeholder, String(value)); // プレースホルダーとして使用したパラメータは削除 delete validatedParams[key]; } } } // メソッドの追加 if (endpoint.method !== "GET") { validatedParams.method = endpoint.method; } // APIリクエストの実行 const data = await fetchFromBacklog(path, validatedParams); return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }], }; } catch (error: any) { // エラーメッセージの整形 const errorMessage = error.errors ? `バリデーションエラー: ${JSON.stringify(error.errors)}` : `エラー: ${error.message}`; return { content: [{ type: "text" as const, text: errorMessage }], isError: true, }; } };
• endpoints.ts:110-117 (schema)

  Schema and configuration for getIssue tool: defines input schema requiring 'issueId', path template, description.
  { name: "getIssue", description: "特定の課題情報の取得", path: "issues/{issueId}", method: "GET", schema: z.object({ issueId: issueIdSchema }), type: "tool", },
• registerEndpoints.ts:154-161 (registration)

  MCP server.tool registration code that registers 'getIssue' (and other tools) by name, description, and the shared handler.
  if (endpoint.type === "tool") { // ツールの登録 server.tool( endpoint.name, endpoint.description, async (args: Record<string, unknown>) => handler(args) ); } else if (endpoint.type === "resource") {
• src/backlogApi.ts:32-167 (helper)

  Helper function that performs the actual HTTP fetch to Backlog API, handles authentication, param sanitization, path processing, error handling; called by the tool handler.
  export async function fetchFromBacklog(endpoint: string, params: Record<string, any> = {}): Promise<any> { // 環境変数のバリデーション const domain = process.env.BACKLOG_DOMAIN; const apiKey = process.env.BACKLOG_API_KEY; if (!domain) { throw new Error('環境変数 BACKLOG_DOMAIN が設定されていません'); } if (!apiKey) { throw new Error('環境変数 BACKLOG_API_KEY が設定されていません'); } try { // パラメータのサニタイズ const sanitizedParams: Record<string, any> = {}; // projectIdOrKeyパラメータをprojectIdに変換（互換性のため） if (params.projectIdOrKey !== undefined) { sanitizedParams.projectId = params.projectIdOrKey; delete params.projectIdOrKey; } // その他のパラメータをコピー Object.keys(params).forEach(key => { if (params[key] !== undefined && params[key] !== null) { sanitizedParams[key] = params[key]; } }); // エンドポイントのパスパラメータを置換 let processedEndpoint = endpoint; const pathParams = processedEndpoint.match(/:([a-zA-Z0-9_]+)/g) || []; for (const param of pathParams) { const paramName = param.substring(1); // :を除去 if (sanitizedParams[paramName] === undefined) { throw new Error(`パスパラメータ ${paramName} が指定されていません`); } processedEndpoint = processedEndpoint.replace(param, sanitizedParams[paramName]); delete sanitizedParams[paramName]; } // リクエストURLの構築 const baseUrl = `https://${domain}/api/v2/${processedEndpoint}`; const isPost = processedEndpoint.includes('POST'); let url = baseUrl; let requestOptions: RequestInit = { headers: { 'Content-Type': 'application/json', }, }; // GETリクエストの場合はクエリパラメータを追加 if (!isPost) { const queryParams = new URLSearchParams(); queryParams.append('apiKey', apiKey); Object.keys(sanitizedParams).forEach(key => { if (Array.isArray(sanitizedParams[key])) { sanitizedParams[key].forEach((value: any) => { queryParams.append(`${key}[]`, value.toString()); }); } else { queryParams.append(key, sanitizedParams[key].toString()); } }); url = `${baseUrl}?${queryParams.toString()}`; } else { // POSTリクエストの場合はボディにパラメータを設定 requestOptions.method = 'POST'; requestOptions.body = JSON.stringify(sanitizedParams); url = `${baseUrl}?apiKey=${apiKey}`; } // デバッグ用ログ（開発時のみ） if (process.env.NODE_ENV === 'development') { console.debug(`Backlog API リクエスト: ${url}`); console.debug('パラメータ:', sanitizedParams); } // APIリクエストの実行 const response = await fetch(url, requestOptions); // レスポンスのステータスコードチェック if (!response.ok) { const errorText = await response.text(); let errorMessage = `Backlog API エラー: HTTP ${response.status}`; try { const errorJson = JSON.parse(errorText); if (isBacklogError(errorJson)) { const error = errorJson.errors[0]; errorMessage = `Backlog API呼び出しエラー: Backlogエラー [${error.code}]: ${error.message}${error.moreInfo ? ` - ${error.moreInfo}` : ''}`; } } catch (e) { errorMessage += ` - ${errorText}`; } throw new Error(errorMessage); } // レスポンスのJSONパース try { const data = await response.json(); // Backlogエラーのチェックとエラーメッセージのフォーマット if (isBacklogError(data)) { const error = data.errors[0]; throw new Error(`Backlog API呼び出しエラー: Backlogエラー [${error.code}]: ${error.message}${error.moreInfo ? ` - ${error.moreInfo}` : ''}`); } return data; } catch (error) { if (error instanceof SyntaxError) { throw new Error(`Backlog API呼び出しエラー: JSONパースエラー - ${error.message}`); } throw error; } } catch (error) { // ネットワークエラーなどの例外処理 if (error instanceof TypeError && error.message.includes('fetch')) { throw new Error(`Backlog API接続エラー: ${error.message}`); } // タイムアウトエラー if (error instanceof Error && error.name === 'AbortError') { throw new Error('Backlog APIタイムアウトエラー: リクエストがタイムアウトしました'); } // その他のエラーはそのまま再スロー throw error; }
• server.ts:29-29 (registration)

  Invocation of endpoint registration on the MCP server instance.
  registerEndpoints(server);