Git Steer

git操舵

自托管GitHub自治引擎。 为您的卧铺提供防滑转向。

git steer允许您通过模型上下文协议（MCP）服务器自主控制您的GitHub帐户。通过自然语言管理仓库、分支、安全、操作——一切。从一开始就有速率限制：ETag缓存、GraphQL批处理、并发上限和分块执行使其在任何车队规模下都能很好地保持在GitHub的API护栏内。

通过 TAEM 04期闸门审查 在涵盖安全性、架构和测试覆盖率的两个补救周期之后。

理念：零足迹

你的机器会转向。GitHub做其他事情。

没有任何东西在本地存在——没有克隆的存储库，没有配置文件，没有构建工件。git steer将您的PC或Mac视为一个瘦控制平面，将GitHub视为整个运行时。

• 零本地代码：没有克隆存储库，没有 node_modules，没有锁定文件
• 仅钥匙扣：macOS Keychain中的GitHub应用程序凭据——磁盘上没有其他凭据
• Git作为数据库：所有配置、状态和审计日志都位于私有GitHub仓库中
• 计算操作：依赖修复、linting和PR发生在临时云运行器中
• 速率限制硬化：节流/重试插件、ETag缓存、GraphQL批处理、并发上限——在任何舰队规模下都是安全的

+-----------------------------------------------------------------+
|                        YOUR PC or MAC                           |
|                                                                 |
|   Keychain:                                                     |
|     - GitHub App private key                                    |
|     - App ID / Installation ID                                  |
|                                                                 |
|   $ npx git-steer                  (stdio -> Claude Desktop)    |
|   $ npx git-steer --http           (portal -> localhost:3333)   |
|         |                                                       |
|         +-> Pulls itself from ry-ops/git-steer                  |
|         +-> Pulls state from ry-ops/git-steer-state             |
|         +-> Runs MCP server in-memory (rate-limit-aware)        |
|         +-> Commits state changes back on shutdown              |
|                                                                 |
+-----------------------------------------------------------------+
                               |
                    Throttled, ETag-cached,
                    GraphQL-batched API calls
                               |
                               v
+-----------------------------------------------------------------+
|                         GITHUB                                  |
|                                                                 |
|   ry-ops/git-steer              (source of truth for code)      |
|   |                                                             |
|   ry-ops/git-steer-state        (private repo)                  |
|   +-- config/                                                   |
|   |   +-- policies.yaml         (branch protection templates)   |
|   |   +-- schedules.yaml        (job definitions)               |
|   |   +-- managed-repos.yaml    (what git-steer controls)       |
|   +-- state/                                                    |
|   |   +-- jobs.jsonl            (job history, append-only)      |
|   |   +-- audit.jsonl           (action log + rate telemetry)   |
|   |   +-- rfcs.jsonl            (RFC lifecycle tracking)        |
|   |   +-- quality.jsonl         (linter/SAST results)           |
|   |   +-- cache.json            (ETag map + sweep cursor)       |
|   +-- .github/workflows/                                        |
|       +-- heartbeat.yml         (scheduled triggers)            |
|                                                                 |
+-----------------------------------------------------------------+

建筑

工具模块系统

MCP服务器被拆分为以下每个域的工具模块 src/mcp/tools/.每个模块导出 getTools() （工具定义）和 handleCall() （工具执行）。服务器在启动时从所有模块收集工具，并通过名称到处理程序映射进行分派。

src/mcp/
+-- server.ts            # MCP protocol, transport init, tool dispatch (~600 lines)
+-- permissions.ts       # Destructive tool registry, dry-run defaults
+-- tools/
    +-- index.ts         # Re-exports all domain modules
    +-- types.ts         # Shared ToolDeps interface
    +-- repos.ts         # Repository management (8 tools)
    +-- branches.ts      # Branch operations (3 tools)
    +-- prs.ts           # Pull request workflows (3 tools -- was 5 with dedup)
    +-- security.ts      # Security scanning and sweeps (7 tools)
    +-- actions.ts       # GitHub Actions (3 tools)
    +-- ops.ts           # Observability, config, reports (8 tools)
    +-- k8s.ts           # Kubernetes ops (4 tools, conditional)
    +-- misc.ts          # Slack, code review, quality (5 tools)

结构工具（CVE管道和git操作）在 server.ts 并委托给 @git-fabric/cve 和那个 FabricGitHubAdapter 在运行时。

所有模块都会收到 ToolDeps 包含GitHub客户端、状态管理器、网关句柄、速率限制助手和并发限制器的包——没有直接导入共享状态。

MCP工具

42个核心工具+20个结构工具，按领域组织。

转发（Repos.ts）

分支（Branches.ts）

拉取请求（prs.ts）

安全（Security.ts）

动作（Actions.ts）

操作和可观察性（Ops.ts）

Kubernetes（k8s.ts）——有条件

仅在以下情况下注册 kubectl 在PATH上。在中不可见 ListTools 否则。

杂项（Misc.ts）-部分有条件

code_review 仅在以下情况下注册 cr （CodeRabbit）二进制文件位于PATH上。

结构CVE（通过@git Fabric/CVE）

结构Git（通过FabricGitHubAdapter）

14个用于GitHub直接操作的工具(fabric_git_list_repos, fabric_git_get_file, fabric_git_commit_files, fabric_git_list_commits, fabric_git_get_commit, fabric_git_compare_commits, fabric_git_list_branches, fabric_git_create_branch, fabric_git_delete_branch, fabric_git_list_files, fabric_git_list_pull_requests, fabric_git_get_pull_request, fabric_git_create_pull_request, fabric_git_merge_pull_request).

安全模型

破坏性工具确认

被归类为破坏性的工具需要明确 confirm 参数设置为 CONFIRM_ （例如。， CONFIRM_REPO_DELETE).如果没有它，该工具将返回警告并不采取任何行动。破坏性工具： repo_delete, repo_archive, repo_scrub_history, branch_reap, cert_renew, security_dismiss.

干运行默认值

扫描和修复工具默认为 dry_run: true 当调用者没有显式设置它时。这意味着LLM不能无意中触发写入。受影响的工具： security_sweep, security_fix_pr, branch_reap, oomkill_remediate.

令牌隔离

这 FabricGitHubAdapter 接口暴露了一个 headers() 返回预构建的Authorization标头的方法。原始令牌对调用者来说永远不可见——它在适配器实现中保持私有。网关不再向写入令牌 process.env.

Slack webhook满负荷列表

Slack webhook URL根据分配列表进行验证(hooks.slack.com, hooks.slack-gov.com).任意URL被拒绝。

有条件的工具注册

K8s工具(oomkill_detect, oomkill_remediate, cert_check, cert_renew)仅在以下情况下注册 kubectl 在PATH中找到。 code_review 仅在以下情况下注册 cr 二进制文件可用。无法执行的工具不会被公告。

快速开始

# First time setup
npx git-steer init

# This will:
# 1. Create a GitHub App with required permissions
# 2. Install it to your account
# 3. Create a private git-steer-state repo
# 4. Store credentials in macOS Keychain

# Start the MCP server
npx git-steer

Claude桌面集成

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "git-steer": {
      "command": "npx",
      "args": ["git-steer"]
    }
  }
}

或者使用本地结账：

{
  "mcpServers": {
    "git-steer": {
      "command": "node",
      "args": ["/path/to/git-steer/bin/cli.js", "start", "--stdio"]
    }
  }
}

本地门户

git steer包含一个HTTP/SSE传输模式，该模式将MCP服务器暴露为本地门户网站：

git-steer start --http               # Default port 3333
git-steer start --http --port 8080   # Custom port

终点： /dashboard （实时安全仪表板）， /mcp （流式HTTP，协议2025-11）， /sse + /messages （传统SSE，协议2024-11）， /health （JSON状态）。

门户使用与stdio模式相同的钥匙链凭据、相同的状态回购和相同的速率限制排序的API堆栈。

速率限制硬化

七层API安全堆栈：

1. 油门/重试 --主（429）自动重试高达4次，次（403）始终回退，瞬时5xx指数回退
2. 并发上限 --写入最多2个，读取最多8个，搜索序列（通过p-limit）
3. ETag缓存 --内容API发送If-Non-Match，304避免了费率成本，在重新启动时保持不变
4. GraphQL批处理 --所有者解析、分支机构列表、Dependabot警报分批为单个呼叫
5. 费率预算可见性 -- steer_status 显示剩余百分比的所有桶，警告低于15%
6. 审计遥测 --每个操作都记录了rate_remaining、retry_count、backff_ms
7. 块状清扫 -- security_sweep(chunkSize: 10) 批处理，游标持久化 resume: true

测试

42个测试通过7个测试文件。Vitest与v8覆盖提供商合作，60%在行/函数/语句上，50%在分支上。

npm test              # Run all tests
npm run test:coverage # Run with coverage report

需要GitHub应用程序权限

• 仓库：读写（内容、元数据）
• 拉取请求：读写
• 问题：读写（用于RFC跟踪）
• 行动：读写（用于工作流调度）
• Dependabot 警报：读写
• 代码扫描警报：阅读
• 秘密：读写（用于动作秘密）
• 行政：读写（用于仓库设置）
• 页面：读写（用于仪表板部署）

命令

git-steer init                       # First-time setup
git-steer                            # Start MCP server via stdio (Claude Desktop)
git-steer start --http               # Start local portal on port 3333
git-steer start --http --port 8080   # Start portal on custom port
git-steer scan                       # Run security scan across all repos
git-steer scan --repo owner/name     # Scan a specific repo
git-steer scan --severity critical   # Filter by severity
git-steer status                     # Show status + rate limit budget
git-steer sync                       # Force sync state to GitHub
git-steer reset                      # Remove local credentials

许可证

麻省理工学院

______________________________________________________________________

建造于 ry ops