Gemini CLI GitHub MCP

Gemini CLI+MCP文档生成器

此存储库包含一个多功能的GitHub Actions工作流，该工作流使用Google的Gemini CLI和模型上下文协议（MCP）集成自动生成文档。

特性

• 与跨平台支持：Windows和Linux工作流
• 可配置路径：自定义输入和输出目录
• 灵活的触发器：手动调度或自动推送
• 错误处理：全面的验证和错误报告
• MCP集成：GitHub MCP服务器，用于增强上下文
• 自动化工作流程：无缝的文档更新

快速开始

1.复制工作流

将相应的工作流文件复制到您的存储库：

• 视窗: .github/workflows/update_docs_windows.yml
• Linux: .github/workflows/update_docs_linux.yml

2.设置秘密

将这些机密添加到您的存储库（设置→ 秘密和变量→ 行动）：

• PERSONAL_ACCESS_TOKEN：具有repo权限的GitHub个人访问令牌
• GITHUB_TOKEN：由GitHub Actions自动提供

3.配置您的存储库

工作流旨在使用以下默认值开箱即用：

• 输入目录: src/
• 输出目录: docs/
• 分支: main

运作原理

MCP服务器配置

工作流会自动配置GitHub MCP服务器，该服务器提供：

• 存储库上下文和文件信息
• 发出并提取请求数据
• 增强的文档生成功能

文档生成过程

1. 设置：安装Node.js和Gemini CLI
2. MCP配置：创建 .gemini/settings.json 使用GitHub MCP服务器
3. 文档：从源文件生成文档
4. 承诺与推动：自动提交和推送更改

自定义选项

存储库变量（可选）

您可以在存储库设置中设置这些变量（设置→ 秘密和变量→ 行动→ 变量）：

• INPUT_DIR：文档生成的源目录（默认： src/)
• OUTPUT_DIR：生成文档的输出目录（默认： docs/)
• COMMIT_MESSAGE：自定义提交消息（默认：“使用Gemini CLI+MCP自动更新文档”）
• ENABLE_AUTO_PUSH：启用/禁用自动推送（默认值： true)
• CLEAN_CACHE：运行前清理npm缓存（默认： true)

手动触发选项

手动触发工作流时，您可以覆盖：

• 输入目录：指定自定义源目录
• 输出目录：指定自定义输出目录
• 分支名称：提交的目标分支
• 提交消息：自定义提交消息
• 自动推送：启用/禁用自动推送
• 清理缓存：启用/禁用npm缓存清理

使用示例

基本用法

# Copy the workflow file to your repository
# Set up the required secrets
# The workflow will run automatically on pushes to main

自定义目录结构

如果您的项目具有不同的结构：

# Set repository variables:
INPUT_DIR: "source/"
OUTPUT_DIR: "documentation/"

不同分行

# Set repository variables:
DEFAULT_BRANCH: "develop"

具有自定义设置的手动触发器

1. 转到操作→ 工作流→ “使用Gemini CLI+MCP自动更新文档”
2. 点击“运行工作流”
3. 填写自定义参数：

- 输入目录： lib/ - 输出目录： api-docs/ - 提交消息：“更新API文档”

工作流功能

错误处理

• 验证输入目录是否存在
• 验证MCP配置创建
• 检查文档生成是否成功
• 提供详细的错误消息

性能优化

• NPM缓存可加快安装速度
• 有条件缓存清理
• 高效的文件操作

安全

• 使用GitHub令牌进行身份验证
• 安全MCP服务器配置
• 没有硬编码凭据

高级功能

MCP服务器集成

该工作流包括一个GitHub MCP服务器，该服务器提供：

• 存储库元数据访问
• 文件内容和结构信息
• 问题和公关管理能力
• 增强文档生成的上下文

自定义文档脚本

存储库包括一个示例 scripts/generate_docs.js 这表明：

• 文件系统操作
• 文档模板生成
• 与外部工具集成

故障排除

常见问题

1. “输入目录不存在”

- 确保源目录存在 - 检查 INPUT_DIR 变量或工作流输入

1. “MCP配置失败”

- 验证 PERSONAL_ACCESS_TOKEN 秘密已经设定 - 检查令牌权限

1. “没有要提交的更改”

- 如果文档没有更改，这是正常的 - 检查源文件是否被修改

1. “文档生成失败”

- 验证Gemini CLI安装 - 检查源文件是否有效

调试步骤

1. 在“操作”选项卡中检查工作流日志
2. 验证机密是否配置正确
3. 先用手动触发器进行测试
4. 检查文件权限和路径

高级配置

多个文档集

为不同的文档类型创建多个工作流文件：

# api-docs.yml
INPUT_DIR: "api/"
OUTPUT_DIR: "api-docs/"

# user-guide.yml  
INPUT_DIR: "docs/"
OUTPUT_DIR: "user-guide/"

条件执行

修改工作流，使其仅在特定条件下运行：

on:
  push:
    branches: [main, develop]
    paths: ['src/**', 'docs/**']

自定义MCP服务器

扩展MCP配置以用于其他服务器：

mcpServers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
  custom:
    command: "npx"
    args: ["-y", "your-custom-mcp-server"]

发展

局部测试

要在本地测试工作流，请执行以下操作：

1. 克隆存储库
2. 设置您的GitHub令牌
3. 手动运行工作流
4. 检查生成的文档

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 使用不同的存储库结构进行测试
5. 提交拉取请求

相关文件

• .github/workflows/update_docs_windows.yml：Windows工作流
• .github/workflows/update_docs_linux.yml：Linux工作流
• scripts/generate_docs.js：示例文档脚本
• Gemini.md：项目配置和惯例

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。