Segmint (Jon Zavialov)

Segmint

AI代理的语义Git运行时。

Segmint是一个原始的MCP服务器 git diff 输出到结构化、代理可读的对象中。它将差异解析为类型化的更改，通过模型上下文协议公开结构化的提交历史、责任、状态和引用对引用差异，以便任何兼容MCP的代理都可以检查存储库状态。

核心图元

Segmint将存储库建模为一组代理直接操作的结构化对象：

变化和驼背是基础层。所有其他结构（LogCommit、CommitDetails、RepoStatus、BlameResult）都是存储库状态的只读视图。

运作原理

git ──► structured objects ──► agent

Segmint作为基于stdio的MCP服务器运行。AI代理使用JSON-RPC通过stdin/stdout连接，并调用工具读取结构化差异、提交历史记录、责备数据、存储库状态和引用到引用差异。

一切都是机械的（没有法学硕士）： 差异解析、更改构造、提交历史检索、归因、状态收集、确定性ID分配。

MCP工具

所有工具都需要 set_repo_root 首先被调用（除非 set_repo_root 和 get_repo_root 他们自己）。工具返回a SEGMINT_NO_REPO 如果未选择存储库，则出错。返回的数组 repo_status 和 list_changes 参赛人数上限为200人 truncated 和 omitted_count 超出字段时。

set_repo_root

选择Segmint操作的存储库。

• 输入： { path: string } --git存储库中目录的绝对或相对路径
• 解析绝对目录的路径，然后运行 git rev-parse --show-toplevel 查找并存储存储库根
• 必须在任何其他git触摸工具之前调用
• 如果路径不在git工作树中，则返回 { isError: true } 并保留前一个根（如果有的话）
• 再次调用会切换到其他存储库

get_repo_root

返回当前配置的存储库根目录，如果没有设置，则返回null。

• 输入： {}
• 退货 { repo_root: string | null }

报告状态

以单个形式返回结构化存储库状态 RepoStatus 对象。

• HEAD信息：分支机构名称或分离的SHA
• 带有状态标签的分阶段文件（修改、添加、删除、重命名等）
• 带有状态标签的未过期文件
• 未标记的文件路径
• 相对于上游的超前/滞后计数（如果存在跟踪分支）
• 上游跟踪分行名称
• 合并/重基处理中的标志（通过检测 .git/MERGE_HEAD, .git/rebase-apply, .git/rebase-merge)
• 退货 { isError: true } 如果不在git存储库中

list_更改

按结构化方式返回所有未提交的更改（已阶段+未阶段） Change[] 带有打字大块的物体。

• 输入： { path?, summary_only? } --可选路径过滤器和摘要模式
• 两者都运行 git diff 和 git diff --cached，按文件合并（先分段大块）
• 按文件路径排序，分配确定性ID(change-1, change-2, ...)
• path 筛选器将输出限制为与给定文件或目录匹配的更改
• summary_only 返回没有完整大块内容的轻量级统计数据（大块计数、插入、删除）——适用于大型变更集
• 处理新文件、已删除文件、跳过二进制文件
• 退货 { isError: true } 如果不在git存储库中

日志

按结构化方式返回提交历史记录 LogCommit[] 物体。

• 输入： { limit?, ref?, path?, since?, until?, include_merges? }
• 默认值：HEAD提交20次，不合并
• 限位夹紧至1..200
• 支持通过以下方式进行日期过滤 since / until （ISO 8601或git日期字符串）
• 路径过滤限制了接触给定路径的提交
• 使用NUL分隔格式安全解析提交字段
• 退货 { isError: true } 对于错误的引用、路径或非git目录

显示_提交

以结构化方式返回单个提交的完整详细信息 CommitDetail 对象。

• 输入： { sha: string } --提交SHA、简短SHA或任何参考
• 返回元数据：主题、正文、作者/提交者姓名、电子邮件、日期（ISO 8601）、父母
• 返回带有状态标签（修改、添加、删除、重命名等）的受影响文件
• 返回解析为的完整diff Change[] 使用类型化大块（重用现有的diff解析器）
• 通过以下方式处理根提交（无父提交） git show 后备方案
• 退货 { isError: true } 用于未知的SHA或非git目录

diff_between_refs

返回任意两个git ref之间的结构化diff，如下所示 Change[] 物体。

• 输入： { base, head, path?, unified? }
• 支持分支、标签、SHA和表达式，如 HEAD~3
• 可选的路径过滤将diff限制为单个文件或目录
• 上下文行可通过以下方式配置 unified （默认3，夹紧0..20）
• 重复使用现有 parseDiff 变更/大块施工管道
• ID仅限于此输出(change-1, change-2, ...），按文件路径排序
• 退货 { isError: true } 对于无效的引用或非git目录

责备

返回文件的行级属性，显示最后修改每一行的提交。

• 输入： { path, ref?, start_line?, end_line?, ignore_whitespace?, detect_moves? }
• 默认参考：HEAD
• 可选的线路范围过滤 start_line / end_line （1-索引，包括在内）
• ignore_whitespace (-w)忽略属性中仅包含空格的更改
• detect_moves (-M -C)检测跨文件移动/复制的行
• 每行输出包括：行号、内容和提交元数据（SHA、作者、时间戳、摘要）
• 时间戳为ISO 8601
• 退货 { isError: true } 用于无效路径、错误引用或非git目录

舞台变化

通过提交的阶段文件路径 git add.

• 输入： { paths: string[], dry_run?: boolean }
• paths：到stage的repo相对文件路径（无通配符，仅显式路径）
• dry_run：如果为true，则验证路径而不执行 git add （默认为false）
• 退货 { staged_paths: string[], dry_run: boolean }
• 可逆通过 unstage_changes
• 退货 { isError: true } 如果路径为空，则路径无效，或者不在git存储库中

不稳定_变化

通过以下方式取消文件路径的固定 git reset HEAD.

• 输入： { paths: string[], dry_run?: boolean }
• paths：取消分级的repo相对文件路径（无通配符，仅显式路径）
• dry_run：如果为true，则验证路径而不执行 git reset （默认为false）
• 退货 { unstaged_paths: string[], dry_run: boolean }
• 可逆通过 stage_changes
• 退货 { isError: true } 如果路径为空，则路径无效，或者不在git存储库中

stage_hunks

按文件路径和大块索引显示特定阶段的大块。仅用选定的大块重建最小补丁，并通过以下方式应用 git apply --cached.

• 输入： { file_path: string, hunk_indices: number[], dry_run?: boolean }
• file_path：repo相对文件路径
• hunk_indices：从文件的未分段差异中分段的基于0的大块索引
• dry_run：当为true时，在不进行暂存的情况下进行验证（默认为false）
• 退货 { file_path: string, hunks_staged: number, dry_run: boolean }
• 退货 { isError: true } 如果文件路径无效，则大块索引超出范围，或者不在git存储库中

创建提交

通过消息提交分阶段更改。

• 输入： { message: string, dry_run?: boolean }
• message：提交消息
• dry_run：当为true时，检查在没有提交的情况下会提交什么（默认为false）
• 退货 { sha: string, short_sha: string, subject: string, dry_run: boolean }
• 退货 { isError: true } 如果没有暂存任何内容，则消息为空，或者不在git存储库中

create_branch

在引用处创建新分支。

• 输入： { name: string, ref?: string, dry_run?: boolean }
• name：要创建的分支名称
• ref：起始参考（默认HEAD）
• dry_run：当为true时，在不创建的情况下进行验证（默认为false）
• 退货 { branch_name: string, sha: string, dry_run: boolean }
• 退货 { isError: true } 如果分支名称已存在，则ref无效，或者不在git存储库中

checkout_branch

切换到现有分支。如果未提交的更改将被覆盖，Git自然会拒绝。

• 输入： { name: string, dry_run?: boolean }
• name：要切换到的分支名称
• dry_run：当为true时，在不切换的情况下进行验证（默认为false）
• 退货 { branch_name: string, previous_branch: string | null, dry_run: boolean }
• 退货 { isError: true } 如果分支不存在、未提交的更改冲突或不在git存储库中

stash_save

保留当前更改。

• 输入： { message?: string, dry_run?: boolean }
• message：可选隐藏消息
• dry_run：如果为true，则检查是否在不隐藏的情况下对隐藏进行了更改（默认为false）
• 退货 { message: string, dry_run: boolean }
• 退货 { isError: true } 如果git存储库中的stash没有更改或没有更改

统计列表

将所有藏匿处列为结构化条目。

• 输入： {}
• 退货 { stashes: StashEntry[] } 其中每个条目都有 { index: number, message: string, sha: string }
• 如果不存在隐藏，则返回空数组
• 退货 { isError: true } 如果不在git存储库中

stash-pop

弹出一个隐藏条目，将其应用于工作树。

• 输入： { index?: number, dry_run?: boolean }
• index：隐藏索引以弹出（默认值0）
• dry_run：当为true时，验证隐藏是否存在而不弹出（默认为false）
• 退货 { index: number, dry_run: boolean }
• 退货 { isError: true } 如果存储索引无效，冲突将阻止应用，或者不在git存储库中应用

reset_soft

向后移动HEAD，同时保持所有更改处于阶段性状态。

• 输入： { ref: string, dry_run?: boolean }
• ref：重置为目标ref（例如。， HEAD~1，a SHA）
• dry_run：当为true时，预览重置目标而不重置（默认为false）
• 退货 { ref: string, previous_sha: string, new_sha: string, dry_run: boolean }
• 退货 { isError: true } 如果ref无效或不在git存储库中

推

按遥控器。安全门： dry_run 默认为 true --代理必须显式设置 dry_run: false 执行。

• 输入： { remote?: string, branch?: string, force?: boolean, dry_run?: boolean }
• remote：远程名称（默认 origin)
• branch：要推送的分支（默认：当前分支）
• force：使用 --force-with-lease 而不是裸露 --force （默认为false）
• dry_run：模拟推送而不执行-- 默认为true 为了安全
• 退货 { remote: string, branch: string, dry_run: boolean, forced: boolean }
• 退货 { isError: true } 如果remote无效，则分支不存在，或者不在git存储库中

建筑

MCP服务器型号

Segmint在stdio传输上使用模型上下文协议。服务器公开了客户端通过JSON-RPC调用的工具：

1. 客户端发送 initialize 具有协议版本和功能。
2. 客户端发送 notifications/initialized.
3. 客户电话 tools/list 以发现可用的工具。
4. 客户电话 tools/call 带有工具名称和参数。

所有工具响应都包括 content （显示文本JSON）和 structuredContent （用于编程的键入对象）。

数据模型

所有模型均在中定义 src/models.ts.

改变 --单个文件的差异，解析自 git diff 输出。

{ id: string, file_path: string, hunks: Hunk[] }

型男 --文件中更改行的连续区域。

{ old_start, old_lines, new_start, new_lines, header: string, lines: string[] }

LogCommit --历史记录中的单个提交（第1层）。

{ sha: string, short_sha: string, subject: string, author_name: string,
  author_email: string, author_date: string, parents: string[] }

委员会详细信息 --完整的提交细节（第1层）。

{ sha, short_sha, subject, body, author_name, author_email, author_date,
  committer_name, committer_email, committer_date, parents: string[],
  files: FileStatus[], diff: { changes: Change[] } }

报告状态 --结构化存储库状态快照（第1层）。

{ is_git_repo, root_path, head: HeadInfo, staged: FileStatus[],
  unstaged: FileStatus[], untracked: string[], ahead_by?, behind_by?,
  upstream?, merge_in_progress, rebase_in_progress }

责备结果 --线路级故障输出（一级）。

{ path: string, ref: string, lines: BlameLine[] }

BlameLine --一条责备的线。

{ line_number: number, content: string, commit: BlameCommit }

责备提交 --责备提交元数据。

{ sha, short_sha, author_name, author_email, author_time, summary }

变更摘要 --轻量级更改统计数据（与 summary_only 模式）。

{ id: string, file_path: string, hunk_count: number, insertions: number, deletions: number }

阶段结果 --分级操作结果（第2级）。

{ staged_paths: string[], dry_run: boolean }

无日结果 --拆垛操作结果（第2级）。

{ unstaged_paths: string[], dry_run: boolean }

StageHunks结果 --大块级分期结果（第2级）。

{ file_path: string, hunks_staged: number, dry_run: boolean }

委员会结果 --提交操作结果（第2层）。

{ sha: string, short_sha: string, subject: string, dry_run: boolean }

CreateBranchResult --分支创建结果（第2层）。

{ branch_name: string, sha: string, dry_run: boolean }

检查结果 --分行结账结果（第2层）。

{ branch_name: string, previous_branch: string | null, dry_run: boolean }

StashEntry --单一藏匿条目（一级）。

{ index: number, message: string, sha: string }

StashSave结果 --存储保存结果（第2级）。

{ message: string, dry_run: boolean }

StashPopResult --隐藏弹出结果（第2级）。

{ index: number, dry_run: boolean }

重置结果 --软重置结果（第2层）。

{ ref: string, previous_sha: string, new_sha: string, dry_run: boolean }

PushResult --推送操作结果（第3层）。

{ remote: string, branch: string, dry_run: boolean, forced: boolean }

流水线状态

目录结构

src/
  index.ts        MCP server entrypoint (slim — imports createServer, connects stdio).
  server.ts       createServer() factory with all 19 tool registrations + repo_root state.
  exec-git.ts     Centralized git command execution + error handling.
  models.ts       TypeScript interfaces for all data models (Change, RepoStatus, etc.).
  git.ts          Executes git diff commands, parses unified diff format into Change objects.
  history.ts      Commit history retrieval — Tier 1 read-only, NUL-delimited parsing.
  show.ts         Single commit detail retrieval — Tier 1 read-only, reuses parseDiff.
  diff.ts         Ref-to-ref structured diff — Tier 1 read-only, reuses parseDiff.
  blame.ts        Line-level blame attribution — Tier 1 read-only, porcelain parsing.
  staging.ts      Tier 2 workspace mutation: staging/unstaging file paths and hunks.
  status.ts       Repository status gathering — Tier 1 read-only repo intelligence.
  commit.ts       Tier 2 workspace mutation: commit creation with dry-run.
  branch.ts       Tier 2 workspace mutation: branch creation and checkout.
  stash.ts        Tier 2 workspace mutation + Tier 1 read-only: stash save, list, pop.
  reset.ts        Tier 2 workspace mutation: soft reset with dry-run.
  push.ts         Tier 3 irreversible: push to remote with safety gating.

tests/
  unit/           Unit tests for parsers, helpers, and isolated logic.
  integration/    Integration tests against real temporary git repos.
  e2e/            In-process E2E tests via createServer() + InMemoryTransport.
  fixtures/       Test fixture files (diffs, etc.).

scripts/
  clean.mjs       Cross-platform clean script (removes build/ and coverage/).

typescript-sdk/   Local copy of the MCP TypeScript SDK (read-only reference).
llms-full.txt     MCP protocol documentation (read-only reference).
build/            Compiled JavaScript output (gitignored).
.github/workflows/ CI configuration (GitHub Actions).

配置

不需要环境变量。Segmint完全离线运行，仅使用本地 git CLI。不存在LLM依赖项或外部API调用。

本地运行

安装和构建

npm install
npm run build

这 build 脚本运行 npm run clean && tsc，从中删除过时的工件 build/ 在编译之前。这可以防止删除源模块中的剩余文件。

与Claude Desktop一起使用

将Segmint添加到您的Claude Desktop配置中(%APPDATA%\Claude\claude_desktop_config.json 在Windows上， ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "segmint": {
      "command": "node",
      "args": ["C:/path/to/segmint/build/index.js"]
    }
  }
}

不 cwd 字段是必需的--代理通过调用在运行时选择目标存储库 set_repo_root.

代理工作流

1. 代理连接并呼叫 set_repo_root 使用目标存储库路径。
2. 代理调用任何工具组合(repo_status, list_changes, log等等）。
3. 要切换存储库，请调用 set_repo_root 再次走上不同的道路。

通过stdio使用JSON-RPC进行测试

服务器使用JSON-RPC通过stdin/stdout进行通信。每行发送一条消息：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"set_repo_root","arguments":{"path":"/path/to/your/repo"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"repo_status","arguments":{}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"list_changes","arguments":{}}}
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"log","arguments":{"limit":5}}}
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"show_commit","arguments":{"sha":"HEAD"}}}
{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"diff_between_refs","arguments":{"base":"HEAD~1","head":"HEAD"}}}
{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"blame","arguments":{"path":"src/index.ts"}}}

启动服务器并管道输入：

npm start

设计原则

基材，而非应用。 Segmint为代理提供了结构化的Git原语。提交计划、PR生成、变更分组和工作流自动化是消费代理的责任——他们使用底层，但不定义它。

决定论。 在分配ID之前，更改按文件路径排序。给定相同的差异，输出是相同的。

MCP标准输出卫生。 stdout专门为JSON-RPC协议消息保留。所有诊断输出通过以下方式进入stderr console.errorstdout上没有横幅，也没有启动消息。

真实数据，无模拟。 所有19个MCP工具都在真实的git数据上运行。生产代码中没有模拟数据。

没有推测性的抽象。 代码是为当前需求编写的。只有当多个调用者共享时，才会引入助手。三条相似的线比过早的抽象要好。

结构性错误，永不崩溃。 输入返回无效 { isError: true } 带有描述性信息。MCP服务器从不因错误的用户输入而崩溃。

能力路线图（层级）

Segmint的长期方向是将全面的Git功能作为结构化、代理可操作的原语公开。工具按安全配置文件和依赖顺序组织成层次。

第1层：只读回购情报（安全、基础）

让代理在不改变任何东西的情况下理解存储库状态的工具。这些是安全的、可组合的，是所有下游操作的基础。

已实施：

• repo_status --分段/未分段/未跟踪计数，当前分支，远程前方/后方
• log --使用筛选器提交历史记录（日期范围、路径、引用、合并筛选、限制）
• show_commit --给定SHA的完整提交详细信息（消息、作者、差异）
• diff_between_refs --任意两个引用（分支、提交、标签）之间的结构化差异，带有可选的路径过滤
• blame --文件或行范围的行级归因
• stash_list --将所有仓库列为结构化条目

计划：

• list_branches / list_tags / current_branch --ref枚举
• list_remotes / remote_info --远程配置

第2层：工作空间突变（可控、可逆）

更改工作树或索引状态的工具。所有二级工具都包括明确的安全护栏（干运行模式和撤消路径）。

已实施：

• stage_changes / unstage_changes --带模拟运行验证的文件级暂存/取消暂存
• stage_hunks --大块级舞台 git apply --cached 进行干运行验证
• create_commit --通过模拟运行验证提交分阶段更改
• create_branch --在任何参考点创建分支，并进行模拟运行验证
• checkout_branch --带模拟运行验证的分支切换（git拒绝冲突）
• stash_save / stash_pop --通过模拟运行验证进行存储、保存和恢复
• reset_soft --向后移动HEAD，同时保持更改分阶段进行，并进行模拟运行验证

计划：

• apply_patch / revert_patch --应用或反转结构化补丁
• reset_mixed --带有防止数据丢失的护栏（否 --hard)

第3级：不可逆/破坏性操作（门控）

无法在本地撤消的操作。每个Tier 3工具都有明确的安全机制（默认情况下为模拟运行，需要确认，破坏性标志选择加入）。

已实施：

• push --使用推送到远程 dry_run 默认 true，力推使用 --force-with-lease

计划：

• rebase, reset --hard, force push --带有安全门的历史改写和破坏性操作

阶段路线图

v0.3.0后路线图

非目标（目前）

这些明显超出了范围，不得驱动基板设计：

• 提交计划、PR生成和变更分组。 这些是消费代理的责任，而不是Segmint。Segmint提供结构化数据；代理决定如何使用自己的推理对更改进行分组、计划提交和生成PR。
• 观点化的Git工作流程。 Segmint不强制执行分支策略、提交约定或合并策略。它公开了Git的功能；代理商决定如何使用它们。
• 交互式UI或仪表板。 Segmint是一个无头MCP服务器。任何UI都是构建在其上的单独关注点。
• Git托管集成。 GitHub/GitLab/Bitbucket API包装器不是基底的一部分。与远程托管平台交互是一项下游操作。

发展规则

这些规则通过CLAUDE.md执行，适用于所有贡献者（人类或人工智能）。

• list_changes 通过运行这两个程序来捕获阶段性+非阶段性更改 git diff 和 git diff --cached.切勿使用 git diff HEAD.
• 更改按以下方式排序 file_path 在分配ID之前(change-1, change-2, ...).
• 当合并同一文件的暂存块和未暂存块时，暂存块排在第一位。
• stdout仅包含JSON-RPC。所有日志记录都会进入stderr。
• 所有工具返回结构化MCP错误({ isError: true })失败。没有抛出的异常到达客户端。
• execFileSync 使用10MB缓冲区来处理较大的差异而不会崩溃。
• 没有明确的理由，就没有新的npm依赖关系。

测试

Segmint有一个全面的Vitest测试套件，在所有指标上都有95%以上的覆盖率。

npm test              # Run all tests
npm run test:unit     # Unit tests only
npm run test:integration  # Integration tests (requires git CLI)
npm run test:e2e      # E2E tests (in-process via InMemoryTransport)
npm run test:coverage # All tests with V8 coverage report
npm run test:watch    # Watch mode for development

所有测试都完全脱机运行，没有外部依赖关系。

CI在Ubuntu和Windows上通过GitHub Actions对每个推送和拉取请求运行。

堆栈

• TypeScript（严格模式，ESM）
• @modelcontextprotocol/sdk@1.26.0
• zod@3.x
• vitest + @vitest/coverage-v8 （dev）
• Node.js 20+
• stdio传输