backlog-readonly-mcp-blog 1.0.0

package/packages/backlog-readonly-mcp/src/tools/user-tools.ts

@@ -0,0 +1,111 @@
+/**
+ * ユーザー関連ツール
+ *
+ * Backlogのユーザー情報を取得するためのツールを提供します。
+ */
+
+import type { BacklogApiClient } from '../client/backlog-api-client.js';
+import type { BacklogUser } from '../types/index.js';
+import type { ToolRegistry } from './tool-registry.js';
+
+/**
+ * ユーザー関連ツールを登録します
+ */
+export function registerUserTools(
+  toolRegistry: ToolRegistry,
+  apiClient: BacklogApiClient,
+): void {
+  // ユーザー一覧取得ツール
+  toolRegistry.registerTool(
+    {
+      name: 'get_users',
+      description: 'ユーザー一覧を取得します（読み取り専用）',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+    },
+    async () => {
+      try {
+        const users = await apiClient.get<BacklogUser[]>('/users');
+
+        return {
+          success: true,
+          data: users,
+          count: users.length,
+          message: `${users.length}名のユーザーを取得しました`,
+        };
+      } catch (error) {
+        throw new Error(
+          `ユーザー一覧の取得に失敗しました: ${error instanceof Error ? error.message : '不明なエラー'}`,
+        );
+      }
+    },
+  );
+
+  // ユーザー詳細取得ツール
+  toolRegistry.registerTool(
+    {
+      name: 'get_user',
+      description: 'ユーザーの詳細情報を取得します（読み取り専用）',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          userId: {
+            type: 'string',
+            description: 'ユーザーID（数値IDまたはユーザーキー）',
+          },
+        },
+        required: ['userId'],
+      },
+    },
+    async (args) => {
+      const { userId } = args as { userId: string };
+
+      try {
+        const user = await apiClient.get<BacklogUser>(
+          `/users/${encodeURIComponent(userId)}`,
+        );
+
+        return {
+          success: true,
+          data: user,
+          message: `ユーザー "${user.name}" の詳細情報を取得しました`,
+        };
+      } catch (error) {
+        throw new Error(
+          `ユーザー詳細の取得に失敗しました: ${error instanceof Error ? error.message : '不明なエラー'}`,
+        );
+      }
+    },
+  );
+
+  // 自分のユーザー情報取得ツール
+  toolRegistry.registerTool(
+    {
+      name: 'get_myself',
+      description: '自分のユーザー情報を取得します（読み取り専用）',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+    },
+    async () => {
+      try {
+        const user = await apiClient.get<BacklogUser>('/users/myself');
+
+        return {
+          success: true,
+          data: user,
+          message: `自分のユーザー情報を取得しました: ${user.name}`,
+        };
+      } catch (error) {
+        throw new Error(
+          `自分のユーザー情報の取得に失敗しました: ${error instanceof Error ? error.message : '不明なエラー'}`,
+        );
+      }
+    },
+  );
+}

package/packages/backlog-readonly-mcp/src/tools/wiki-tools.ts

@@ -0,0 +1,149 @@
+/**
+ * Wiki関連ツール
+ *
+ * BacklogのWiki情報を取得するためのツールを提供します。
+ */
+
+import type { BacklogApiClient } from '../client/backlog-api-client.js';
+import { ConfigManager } from '../config/config-manager.js';
+import type { BacklogWiki } from '../types/index.js';
+import type { ToolRegistry } from './tool-registry.js';
+
+/**
+ * Wiki関連ツールを登録します
+ */
+export function registerWikiTools(
+  toolRegistry: ToolRegistry,
+  apiClient: BacklogApiClient,
+): void {
+  // Wiki一覧取得ツール
+  toolRegistry.registerTool(
+    {
+      name: 'get_wikis',
+      description:
+        'Wiki一覧を取得します（読み取り専用）。プロジェクトIDまたはキーを省略した場合、デフォルトプロジェクトを使用します。大量のWikiがあるプロジェクトではキーワード検索の使用を推奨します。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          projectIdOrKey: {
+            type: 'string',
+            description:
+              'プロジェクトIDまたはプロジェクトキー（例: "MYPROJ" または "123"）。省略時はデフォルトプロジェクトを使用。',
+          },
+          keyword: {
+            type: 'string',
+            description:
+              'キーワード検索（Wiki名と内容を対象）。大量のWikiがあるプロジェクトでは指定を推奨。',
+          },
+        },
+        required: [],
+      },
+    },
+    async (args) => {
+      const { projectIdOrKey, keyword } = args as {
+        projectIdOrKey?: string;
+        keyword?: string;
+      };
+      const configManager = ConfigManager.getInstance();
+
+      const params: Record<string, unknown> = {};
+      if (keyword) {
+        params.keyword = keyword;
+      }
+
+      try {
+        const resolvedProjectIdOrKey =
+          configManager.resolveProjectIdOrKey(projectIdOrKey);
+
+        const wikis = await apiClient.get<BacklogWiki[]>(
+          `/projects/${encodeURIComponent(resolvedProjectIdOrKey)}/wikis`,
+          params,
+        );
+
+        const isDefaultProject =
+          !projectIdOrKey && configManager.hasDefaultProject();
+
+        return {
+          success: true,
+          data: wikis,
+          count: wikis.length,
+          message: `${wikis.length}件のWikiページを取得しました${isDefaultProject ? '（デフォルトプロジェクト）' : ''}`,
+          isDefaultProject,
+          searchParams: params,
+        };
+      } catch (error) {
+        if (
+          error instanceof Error &&
+          error.message.includes('デフォルトプロジェクト')
+        ) {
+          throw error;
+        }
+
+        // 504エラー（Gateway Timeout）の場合は、データが多すぎることを示すメッセージを返す
+        // AxiosErrorの場合はHTTPステータスコードを直接チェック
+        const isAxiosError =
+          error && typeof error === 'object' && 'response' in error;
+        const is504Error =
+          isAxiosError &&
+          (error as { response?: { status?: number } }).response?.status ===
+            504;
+
+        if (is504Error) {
+          const isDefaultProject =
+            !projectIdOrKey && configManager.hasDefaultProject();
+
+          return {
+            success: false,
+            data: [],
+            count: 0,
+            message: `プロジェクトのWikiページが多すぎて取得に時間がかかりすぎました。キーワード検索を使用して絞り込んでください${isDefaultProject ? '（デフォルトプロジェクト）' : ''}`,
+            isDefaultProject,
+            searchParams: params,
+            error: 'TIMEOUT_TOO_MANY_WIKIS',
+          };
+        }
+
+        throw new Error(
+          `Wiki一覧の取得に失敗しました: ${error instanceof Error ? error.message : '不明なエラー'}`,
+        );
+      }
+    },
+  );
+
+  // 特定Wiki取得ツール
+  toolRegistry.registerTool(
+    {
+      name: 'get_wiki',
+      description: '特定のWikiページを取得します（読み取り専用）',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          wikiId: {
+            type: 'string',
+            description: 'WikiのID（数値）',
+          },
+        },
+        required: ['wikiId'],
+      },
+    },
+    async (args) => {
+      const { wikiId } = args as { wikiId: string };
+
+      try {
+        const wiki = await apiClient.get<BacklogWiki>(
+          `/wikis/${encodeURIComponent(wikiId)}`,
+        );
+
+        return {
+          success: true,
+          data: wiki,
+          message: `Wikiページ "${wiki.name}" を取得しました`,
+        };
+      } catch (error) {
+        throw new Error(
+          `Wikiページの取得に失敗しました: ${error instanceof Error ? error.message : '不明なエラー'}`,
+        );
+      }
+    },
+  );
+}

package/packages/backlog-readonly-mcp/src/types/index.ts

@@ -0,0 +1,297 @@
+/**
+ * Backlog読み取り専用MCPサーバーの型定義
+ */
+
+// 設定関連の型
+export interface BacklogConfig {
+  /** Backlogドメイン (例: your-company.backlog.com) */
+  domain: string;
+  /** APIキー */
+  apiKey: string;
+  /** デフォルトプロジェクトキー (オプション) */
+  defaultProject?: string;
+  /** リトライ回数 */
+  maxRetries: number;
+  /** タイムアウト（ミリ秒） */
+  timeout: number;
+}
+
+// Backlog API レスポンス型
+export interface BacklogProject {
+  id: number;
+  projectKey: string;
+  name: string;
+  chartEnabled: boolean;
+  subtaskingEnabled: boolean;
+  projectLeaderCanEditProjectLeader: boolean;
+  useWikiTreeView: boolean;
+  textFormattingRule: string;
+  archived: boolean;
+  displayOrder: number;
+  useDevAttributes: boolean;
+}
+
+export interface BacklogUser {
+  id: number;
+  userId: string;
+  name: string;
+  roleType: number;
+  lang: string;
+  mailAddress: string;
+  nulabAccount?: {
+    nulabId: string;
+    name: string;
+    uniqueId: string;
+  };
+}
+
+export interface BacklogIssue {
+  id: number;
+  projectId: number;
+  issueKey: string;
+  keyId: number;
+  issueType: IssueType;
+  summary: string;
+  description: string;
+  resolution: Resolution | null;
+  priority: Priority;
+  status: Status;
+  assignee: BacklogUser | null;
+  category: Category[];
+  versions: Version[];
+  milestone: Milestone[];
+  startDate: string | null;
+  dueDate: string | null;
+  estimatedHours: number | null;
+  actualHours: number | null;
+  parentIssueId: number | null;
+  createdUser: BacklogUser;
+  created: string;
+  updatedUser: BacklogUser;
+  updated: string;
+  customFields: CustomField[];
+  attachments: Attachment[];
+  sharedFiles: SharedFile[];
+  stars: Star[];
+}
+
+export interface IssueType {
+  id: number;
+  projectId: number;
+  name: string;
+  color: string;
+  displayOrder: number;
+}
+
+export interface Resolution {
+  id: number;
+  name: string;
+}
+
+export interface Priority {
+  id: number;
+  name: string;
+}
+
+export interface Status {
+  id: number;
+  projectId: number;
+  name: string;
+  color: string;
+  displayOrder: number;
+}
+
+export interface Category {
+  id: number;
+  name: string;
+  displayOrder: number;
+}
+
+export interface Version {
+  id: number;
+  projectId: number;
+  name: string;
+  description: string;
+  startDate: string | null;
+  releaseDueDate: string | null;
+  archived: boolean;
+  displayOrder: number;
+}
+
+export interface Milestone {
+  id: number;
+  projectId: number;
+  name: string;
+  description: string;
+  startDate: string | null;
+  releaseDueDate: string | null;
+  archived: boolean;
+  displayOrder: number;
+}
+
+export interface CustomField {
+  id: number;
+  typeId: number;
+  name: string;
+  description: string;
+  required: boolean;
+  applicableIssueTypes: number[];
+  allowAddItem: boolean;
+  items: CustomFieldItem[];
+  value?: string | number | string[] | number[] | null;
+}
+
+export interface CustomFieldItem {
+  id: number;
+  name: string;
+  displayOrder: number;
+}
+
+export interface Attachment {
+  id: number;
+  name: string;
+  size: number;
+  createdUser: BacklogUser;
+  created: string;
+}
+
+export interface SharedFile {
+  id: number;
+  type: string;
+  dir: string;
+  name: string;
+  size: number;
+  createdUser: BacklogUser;
+  created: string;
+  updatedUser: BacklogUser;
+  updated: string;
+}
+
+export interface Star {
+  id: number;
+  comment: string | null;
+  url: string;
+  title: string;
+  presenter: BacklogUser;
+  created: string;
+}
+
+export interface BacklogComment {
+  id: number;
+  content: string;
+  changeLog: ChangeLog[];
+  createdUser: BacklogUser;
+  created: string;
+  updated: string;
+  stars: Star[];
+  notifications: Notification[];
+}
+
+export interface ChangeLog {
+  field: string;
+  newValue: string;
+  originalValue: string;
+}
+
+export interface Notification {
+  id: number;
+  alreadyRead: boolean;
+  reason: number;
+  user: BacklogUser;
+  resourceAlreadyRead: boolean;
+}
+
+export interface BacklogWiki {
+  id: number;
+  projectId: number;
+  name: string;
+  content: string;
+  tags: WikiTag[];
+  attachments: Attachment[];
+  sharedFiles: SharedFile[];
+  stars: Star[];
+  createdUser: BacklogUser;
+  created: string;
+  updatedUser: BacklogUser;
+  updated: string;
+}
+
+export interface WikiTag {
+  id: number;
+  name: string;
+}
+
+// エラー関連の型
+export interface BacklogError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+export interface MCPError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+// カスタムエラークラス
+export class ReadOnlyViolationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ReadOnlyViolationError';
+  }
+}
+
+export class AuthenticationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class NetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+
+/**
+ * シンプルな JSON Schema 型定義
+ *
+ * - 学習用・検証用のため、よく使うプロパティのみに絞っています
+ * - 必要に応じてプロパティを拡張していく想定です
+ */
+export interface JSONSchema {
+  type:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'object'
+    | 'array'
+    | 'null';
+  description?: string;
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  enum?: Array<string | number | boolean | null>;
+  required?: string[];
+}
+
+// ツール関連の型
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, JSONSchema>;
+    required?: string[];
+  };
+}
+
+export interface ToolResult {
+  content: Array<{
+    type: 'text';
+    text: string;
+  }>;
+}

package/packages/backlog-readonly-mcp/src/utils/logger.ts

@@ -0,0 +1,123 @@
+/**
+ * ログユーティリティ
+ *
+ * MCPサーバーのログ出力を管理します。
+ * 要件7.3: 重要な操作とエラーをログに記録する
+ */
+
+export enum LogLevel {
+  ERROR = 0,
+  WARN = 1,
+  INFO = 2,
+  DEBUG = 3,
+}
+
+let logLevel: LogLevel = LogLevel.INFO;
+
+/**
+ * ログレベルを設定
+ */
+export function setLogLevel(level: LogLevel): void {
+  logLevel = level;
+}
+
+/**
+ * エラーログ
+ */
+export function error(message: string, ...args: unknown[]): void {
+  if (logLevel >= LogLevel.ERROR) {
+    const timestamp = new Date().toISOString();
+    console.error(`[ERROR] ${timestamp} ${message}`, ...args);
+  }
+}
+
+/**
+ * 警告ログ
+ */
+export function warn(message: string, ...args: unknown[]): void {
+  if (logLevel >= LogLevel.WARN) {
+    const timestamp = new Date().toISOString();
+    console.warn(`[WARN] ${timestamp} ${message}`, ...args);
+  }
+}
+
+/**
+ * 情報ログ
+ */
+export function info(message: string, ...args: unknown[]): void {
+  if (logLevel >= LogLevel.INFO) {
+    const timestamp = new Date().toISOString();
+    console.log(`[INFO] ${timestamp} ${message}`, ...args);
+  }
+}
+
+/**
+ * デバッグログ
+ */
+export function debug(message: string, ...args: unknown[]): void {
+  if (logLevel >= LogLevel.DEBUG) {
+    const timestamp = new Date().toISOString();
+    console.log(`[DEBUG] ${timestamp} ${message}`, ...args);
+  }
+}
+
+/**
+ * API操作のログ記録
+ */
+export function logApiOperation(
+  operation: string,
+  endpoint: string,
+  params?: Record<string, unknown>,
+  duration?: number,
+): void {
+  const message = `API操作: ${operation} ${endpoint}`;
+  const details = {
+    params: params ? Object.keys(params) : undefined,
+    duration: duration ? `${duration}ms` : undefined,
+  };
+  info(message, details);
+}
+
+/**
+ * エラー詳細のログ記録
+ */
+export function logError(
+  context: string,
+  err: unknown,
+  additionalInfo?: Record<string, unknown>,
+): void {
+  const errorMessage = err instanceof Error ? err.message : String(err);
+  const errorStack = err instanceof Error ? err.stack : undefined;
+
+  error(`${context}: ${errorMessage}`, {
+    stack: errorStack,
+    ...additionalInfo,
+  });
+}
+
+/**
+ * レート制限のログ記録
+ */
+export function logRateLimit(retryAfter: number, attempt: number): void {
+  warn(
+    `レート制限に達しました。${retryAfter}秒後にリトライします (試行回数: ${attempt})`,
+  );
+}
+
+/**
+ * 設定読み込みのログ記録
+ */
+export function logConfigLoad(
+  source: string,
+  success: boolean,
+  details?: string,
+): void {
+  if (success) {
+    info(`設定を読み込みました: ${source}`, details ? { details } : undefined);
+  } else {
+    warn(
+      `設定の読み込みに失敗しました: ${source}`,
+      details ? { details } : undefined,
+    );
+  }
+}