Gitea MCP Tool

Instructions

Implementation Reference

• src/tools/workflow.ts:851-930 (handler)

  The core handler function implementing the 'gitea_workflow_sync_status' tool. Loads workflow config, initializes BoardSyncManager, fetches projects and issues, calculates sync actions based on direction (label-to-board, board-to-label, or both), and returns sync report.

  export async function workflowSyncStatus(
    ctx: WorkflowToolsContext,
    args: {
      owner?: string;
      repo?: string;
      config?: WorkflowConfig;
      direction: 'label-to-board' | 'board-to-label' | 'both';
    }
  ): Promise<{
    success: boolean;
    synced_count: number;
    actions: SyncAction[];
    error?: string;
  }> {
    logger.debug({ args: { ...args, config: args.config ? '[provided]' : undefined } }, 'Syncing status');
  
    const { owner, repo } = ctx.contextManager.resolveOwnerRepo(args.owner, args.repo);
  
    // 获取配置
    let config = args.config;
    if (!config) {
      const loadResult = await workflowLoadConfig(ctx, { owner, repo });
      if (!loadResult.success || !loadResult.config) {
        return {
          success: false,
          synced_count: 0,
          actions: [],
          error: loadResult.error || '无法加载配置',
        };
      }
      config = loadResult.config;
    }
  
    const boardSyncManager = new BoardSyncManager(config);
    const actions: SyncAction[] = [];
  
    try {
      // 获取项目和列
      const projects = await ctx.client.get<Array<{ id: number; title: string }>>(
        `/repos/${owner}/${repo}/projects`
      );
  
      const workflowProject = projects.find((p) => p.title === config.board.name);
      if (!workflowProject) {
        return {
          success: false,
          synced_count: 0,
          actions: [],
          error: `未找到项目看板: ${config.board.name}`,
        };
      }
  
      // 获取开放的 Issue
      const issues = await ctx.client.get<Issue[]>(`/repos/${owner}/${repo}/issues?state=open&limit=100`);
  
      // 计算同步操作（这里只返回建议的操作，实际同步需要更复杂的实现）
      for (const issue of issues) {
        const syncActions = boardSyncManager.calculateSyncActions(issue, null, args.direction);
        actions.push(...syncActions);
      }
  
      logger.info({ owner, repo, actions: actions.length }, 'Status sync calculated');
  
      return {
        success: true,
        synced_count: actions.length,
        actions,
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      logger.error({ owner, repo, error: errorMessage }, 'Failed to sync status');
  
      return {
        success: false,
        synced_count: 0,
        actions: [],
        error: errorMessage,
      };
    }
  }

• src/tools-registry/workflow-registry.ts:287-319 (registration)

  Registers the 'gitea_workflow_sync_status' tool with the MCP server, defining its title, description, input schema, and wiring the handler from WorkflowTools.

  mcpServer.registerTool(
    'gitea_workflow_sync_status',
    {
      title: '状态双向同步',
      description:
        'Synchronize issue status labels with project board column positions. Supports label-to-board, board-to-label, or bidirectional sync.',
      inputSchema: z.object({
        owner: z.string().optional().describe('Repository owner. Uses context if not provided'),
        repo: z.string().optional().describe('Repository name. Uses context if not provided'),
        direction: z
          .enum(['label-to-board', 'board-to-label', 'both'])
          .describe('Sync direction'),
      }),
    },
    async (args) => {
      try {
        const result = await WorkflowTools.workflowSyncStatus(
          { client: ctx.client, contextManager: ctx.contextManager },
          args
        );
        return {
          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
          isError: !result.success,
        };
      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [{ type: 'text' as const, text: `Error: ${errorMessage}` }],
          isError: true,
        };
      }
    }
  );

• src/tools-registry/workflow-registry.ts:293-299 (schema)

  Zod input schema validation for the tool, defining parameters: owner (optional string), repo (optional string), direction (enum: 'label-to-board', 'board-to-label', 'both').

  inputSchema: z.object({
    owner: z.string().optional().describe('Repository owner. Uses context if not provided'),
    repo: z.string().optional().describe('Repository name. Uses context if not provided'),
    direction: z
      .enum(['label-to-board', 'board-to-label', 'both'])
      .describe('Sync direction'),
  }),

• src/utils/board-sync.ts:78-140 (helper)

  Key helper method in BoardSyncManager used by the handler to compute synchronization actions between issue labels and board columns based on the specified direction.

  calculateSyncActions(
    issue: Issue,
    currentColumn: ProjectColumn | null,
    direction: SyncDirection
  ): SyncAction[] {
    const actions: SyncAction[] = [];
    const statusLabel = this.getStatusLabel(issue);
    const expectedColumn = statusLabel ? this.findColumnByLabel(statusLabel) : null;
  
    if (direction === 'label-to-board' || direction === 'both') {
      // 标签 → 看板：根据状态标签移动卡片
      if (statusLabel && expectedColumn) {
        if (!currentColumn) {
          // Issue 不在看板上，需要创建卡片
          actions.push({
            type: 'create_card',
            issue_number: issue.number,
            details: {
              to_column: expectedColumn.name,
            },
            reason: `根据标签 ${statusLabel} 添加到看板列 ${expectedColumn.name}`,
          });
        } else if (currentColumn.name !== expectedColumn.name) {
          // 卡片在错误的列，需要移动
          actions.push({
            type: 'move_card',
            issue_number: issue.number,
            details: {
              from_column: currentColumn.name,
              to_column: expectedColumn.name,
            },
            reason: `根据标签 ${statusLabel} 移动卡片`,
          });
        }
      }
    }
  
    if (direction === 'board-to-label' || direction === 'both') {
      // 看板 → 标签：根据卡片位置更新标签
      if (currentColumn) {
        const expectedLabel = this.findLabelByColumn(currentColumn.name);
        if (expectedLabel && expectedLabel !== statusLabel) {
          // 需要更新状态标签
          if (statusLabel) {
            actions.push({
              type: 'remove_label',
              issue_number: issue.number,
              details: { label: statusLabel },
              reason: `移除旧状态标签 ${statusLabel}`,
            });
          }
          actions.push({
            type: 'add_label',
            issue_number: issue.number,
            details: { label: expectedLabel },
            reason: `根据看板位置 ${currentColumn.name} 添加标签`,
          });
        }
      }
    }
  
    return actions;
  }