gittr-mcp

gittr-mcp

让你的 AI Agent（或应用）像开发者一样使用 gittr——Nostr git 托管服务——创建仓库、推送代码、创建和合并拉取请求、管理议题，以及处理 Lightning 悬赏——使用你的 Nostr 身份，而非 GitHub 登录账号。

兼容 Cursor、Claude Desktop、VS Code / Copilot MCP、Windsurf、OpenClaw，以及任何通过标准输入/输出支持 Model Context Protocol 的宿主。

需要 Node 22.23.4、24.22.1 或 26.12.1（或这些版本线上的更新版本）。Node 18 和 20 没有针对 2026 年 10 月证书和 Brotli 错误的修复，因此 gittr-mcp 在这些版本上会直接退出，不会启动。

文档中心： gittr-docu——产品概览，以及这个 MCP 如何与网站配合使用。

此仓库的页面： 根目录中的 index.html。执行 Push Manifest 后，将网站名称保存为 gittr-mcp。

---

为什么要使用它？

不使用 gittr-mcp	使用 gittr-mcp
你在聊天窗口和 gittr 网站之间复制粘贴	Agent 调用工具：推送文件、发布仓库元数据、创建议题/拉取请求
使用自定义脚本处理 NIP-98 桥接身份验证和 NIP-34 签名	内置签名、质询处理和中继检查
不清楚推送是否真的发布到了 Nostr	工具会返回成功/失败状态，以及供自动化使用的 verification / nextSteps

最终效果： 一个 MCP 服务即可将你的 Agent 连接到 Nostr 上的去中心化 Git——使用你在 gittr.space 上的同一账号（nsec / 密钥文件），Agent 无需单独注册其他服务商账号。

托管说明： 网站的创建/导入流程在点击 announce/Push 前都在 浏览器本地 进行。MCP 的 createRepo / mirrorRepo / pushToBridge 会像网站一样写入 Git。克隆地址来自 Settings → Relays 中保存的服务（优先使用你自己的服务），然后是公开副本。软删除会通过 POST 将墓碑记录发送到桥接服务，从而清除磁盘数据。

此处在平台中的位置（平台地图）

gittr-mcp 是通往人们在浏览器中使用的同一平台的 Agent 入口。你当前所在的位置 = gittr-mcp（本仓库，青绿色）。带青色边框的主机框 = 公共主机名（git. / pages. / relay.gittr.space）（青绿色 = 本仓库；青色边框 = 主机 URL）。

flowchart TB
  Agent["AI host<br/>Cursor / Claude / …"]
  MCP["★ YOU ARE HERE · gittr-mcp<br/>this repo · agent tools"]
  UI["gittr Client<br/>gittr.space"]
  Bridge["gitnostr Bridge<br/>git.gittr.space<br/>SSH / HTTPS git"]
  RelayGittr["gittr Pyramid relay<br/>relay.gittr.space<br/>wss · open forge + GRASP"]
  Relays["Other Nostr relays"]
  Pages["Pages / nsite<br/>pages.gittr.space"]
  Remote["git remote nostr<br/>optional"]

  Agent -->|MCP tools| MCP
  MCP -->|HTTPS + Nostr auth| Bridge
  MCP -->|sign NIP-34 events| RelayGittr
  MCP -->|sign NIP-34 events| Relays
  UI --> RelayGittr
  UI --> Relays
  UI --> Bridge
  Pages --> Relays
  Remote -.-> Relays

  classDef youAreHere fill:#0f766e,stroke:#5eead4,stroke-width:3px,color:#ecfdf5
  classDef hostUrl fill:#164e63,stroke:#22d3ee,stroke-width:2px,color:#ecfeff
  class MCP youAreHere
  class Bridge,Pages,RelayGittr hostUrl

部件	主机 / 链接	MCP 如何使用
gittr Client	gittr on gittr.space · gittr.space	同一产品；MCP 镜像代码托管操作（仓库、议题、PR、悬赏）
gitnostr Bridge	gitnostr on gittr.space · git.gittr.space	pushToBridge、文件列表、通过 HTTPS 合并克隆
Pages / nsite	nsite-gateway · pages.gittr.space	大多数 MCP git 工具不会用到
Blossom	gittr-blossom · blossom.gittr.space	Pages 上传文件存放于此的 Blob 存储
gittr Pyramid 中继	pyramid · relay.gittr.space	发布 NIP-34 时，优先将其加入中继列表
★ gittr-mcp（本 README）	gittr-mcp on gittr.space	你当前所在的位置
git remote nostr	ngit-cli	MCP 不需要；Agent 通常使用 Bridge HTTPS + 事件

Agent 寻址： resolveRepoByNostrId(npub|hex, repo) → cloneUrl + 中继。优先使用已公告的 npub 路径 HTTPS（位于 git.gittr.space，NIP-34）；如果符号链接缺失，hex 路径可作为磁盘回退方案。发布时请包含 wss://relay.gittr.space。

---

你可以做什么（工作流）

以下是人们实际运行的 流程；每个流程都对应 Agent 可调用的 MCP 工具。Agent：请遵循 docs/AGENT-WORKFLOW.md（使用哪个工具，以及调用后不要再调用什么）。

发布新项目

1. createRepo — 一步将初始文件推送到 Bridge，并且发布 Nostr kind 30617 + 30618（Agent 的最佳默认选择）。
   传入 publicRead: false 可创建 私有仓库（代码/克隆/API/SSH 仅对你和列出的维护者可读）。公告中的名称/描述仍会显示在中继上——只有文件访问受到限制。
2. 或按步骤操作：pushToBridge → publishRepoAnnouncement → publishRepoState。

私有仓库

• 在 createRepo、publishRepoAnnouncement、forkRepo 或 mirrorRepo 中设置 publicRead: false。
• 对陌生人隐藏私有仓库，不会显示在 Explore/首页/个人资料列表中。
• 直接 URL 仍会显示仓库名称和 Private 标记；未经授权的查看者会看到锁定屏幕（不显示代码）。
• SSH / CLI / API 读取使用与 Web UI 相同的 ACL：你的 npub 必须是所有者或维护者（通过 addCollaborator 或 gittr.space 上的 Settings → Contributors 添加）。
• SSH 密钥注册方式不变——密钥用于识别你；私有仓库只会检查你的公钥是否具有读取权限。

日常开发

• pushToBridge — 更新分支上的文件（使用 NIP-98 对 gittr bridge 进行身份验证）；删除文件或文件夹时，可选使用 deletedPaths / allowTreeShrink（与 Code 标签页中的移至回收站操作一致）。
• getFile、bridgeListFiles、bridgeGetFileContent、getBranches、getCommitHistory — 无需克隆即可读取。getFile 采用先查 bridge，再简短列出 GRASP 的方式——不是 Code 标签页。在网站上：最新的实时 30617；如果存在，forge source 是文件树（会替换过时的 bridge 列表）；否则使用第一个非空的 clone[] 列表。参见 MCP-GITTR-PARITY.md 和 gittr FILE_FETCHING_INSIGHTS.md。
• resolveRepoByNostrId — 根据 npub + 仓库名称查找克隆 URL 和中继。

Issue（错误报告、任务）

• listIssues、getIssueById — 返回与网站 Issues 标签页相同的行。包含 Nostr Issue，以及当仓库来源信息表明存在时的 GitHub 或 Codeberg/Gitea Issue。它们会作为独立行显示。使用 issue-N 或数字调用 getIssueById 时，需要提供 ownerPubkey 和 repoId。GitLab 来源仅支持 Nostr。
• createIssue
• listIssueComments、createIssueComment — 针对 64 字符 ID 的 Nostr 评论。当 ID 为 issue-N 或数字时，获取 Forge 评论（只读；网站不会将评论回写到 GitHub）。
• closeIssue、reopenIssue — 为 64 字符的 Nostr 事件 ID 发布 NIP-34 状态事件（1632 / 1630）。拒绝处理从 GitHub/Gitea 导入的 issue-12 / pr-12（以及单独的 12）——请在源平台关闭这些 Issue。

Pull Request（代码审查流程）

步骤	工具	说明
列出 / 打开 PR	listPRs、createPR	列表与网站一致：Nostr kind 1618，以及仓库来源包含 GitHub 或 Codeberg/Gitea 时的 pr-N。createPR 会发布 Nostr 事件。
评论 PR	listPRComments、createPRComment	针对 64 字符 ID 的 Nostr 评论。pr-N 会读取 Forge 对话（需要 ownerPubkey 和 repoId）。不会回写到 GitHub。
使用 git 分支创建完整 PR	createPRViaGittrCLI	当 Agent 的 PATH 中有 git 时推荐使用。
更新 PR 最新提交	updatePullRequest	在 PR 事件中添加新提交 + 克隆 URL。
合并到 main	mergePullRequest	对 Nostr PR（kind 1618 事件 ID）执行真实的 git 合并：克隆/获取、合并、推送到 bridge，发布 30618 + 已合并状态 1631。拒绝处理 Forge pr-N。调用者必须是仓库所有者或列出的维护者；需要 git。
标记为已合并（仅 Nostr）	markPullRequestMerged	仅更新状态——不执行 git 合并。

**关于 PR 的实际限制：**支持通过 MCP 创建和列出 PR。合并需要安装 git 并拥有仓库操作权限。某些中继会严格校验仓库公告中的 克隆 URL + 中继 是否匹配——如果 PR 发布失败，请修复元数据（参见 限制）或使用 createPRViaGittrCLI。详情见：docs/DEVELOPER.md#limitations。

派生、镜像与导入

• forkRepo — 在你的密钥名下派生现有 gittr 仓库。
• mirrorRepo — 与网站上的「推送 GitHub/GitLab 仓库」结果相同：在 gittr 上创建 Forge 提交（保留历史记录，后续调用会更新提交）、使用相同的 git-server 列表，并创建一个状态事件，其 HEAD 指向 Forge 默认分支。后续调用会保留已公布的名称、描述和网页链接。
• importRemoteToBridge — 仅复制到 git 服务。使用所有者密钥时，后续调用会更新 Forge 提交。此操作不会发布 Nostr 卡片。若要获得完整的网站操作结果，请使用 mirrorRepo。
• **Forge 403 / 账号已暂停：**如果仓库已经复制，请继续使用 https://git.gittr.space/<npub>/<repo>.git。不要将 mirrorRepo 指向新的 Forge 来更改源地址——这会把新 URL 复制到 gittr 并替换分支。指南：docs/AGENT-WORKFLOW.md。

发现与社交

• listRepos、searchRepos、myRepos、exploreRepos、getTrendingRepos（热门 = 最近的仓库，而非按互动量排名）
• starRepo、unstarRepo、listStars — 在仓库的 30617 事件上使用 NIP-25（与 gittr 的 Star 按钮相同）。
• watchRepo、unwatchRepo、listWatchedRepos — NIP-51 kind 10018 关注仓库列表（与 gittr 的 Watch 相同）。
• getRepoContributors

兼容性详情：docs/MCP-GITTR-PARITY.md — 与 gittr.space 一致的功能及注意事项。

发布与标签

• listReleases — 获取 bridge 上的 git 标签（refs/tags/*），不是网页界面的 Releases 选项卡，也不是 Zapstore。
• listForgeReleases — 列出 Forge 的 Releases 选项卡中的版本（包含所有资源；没有 NIP-82 MIME 限制）。
• createRelease — 仅返回操作指引（在下一次 30617 推送前，发布说明仅显示在界面上）。
• fetchForgeReleases — 获取一个 Forge Release 及可公告的二进制文件。省略 tag 即获取最新版本；使用 hash:true 获取 sha256（公告前必须执行）。
• announceSoftwareFromForgeRelease — 从带标签的 Forge Release 创建 Zapstore/NIP-82（kind 32267 / 30063 / 3063）公告。优先使用 APK；也支持 AppImage/DMG/linux tar.gz/MSI/EXE/IPA。同一标签下的其他二进制文件会作为关联资源处理。会从 Forge 的 zapstore.yaml 复制 images:。可选的 pinToBlossom（公开 Blossom；blossom.gittr.space 仅适用于官方的 space.gittr.app）。与 gittr 的 Nostr Apps（最新版本）或 Releases Announce on Nostr（tag=）相同。应用绝不会缺少标签。
• deleteSoftwareAnnounce — 为这些应用、发布版本或资源的事件 id 创建 NIP-09 kind 5 删除事件。

Pages 与安全

• publishNostrPages — 通过 gittr 使用 NIP-5A kind 35128 + Blossom 上传（必须包含 index.html）。
• auditRepoDependencies — 在 bridge 上解析锁文件，并通过 gittr /api/security/audit 查询 OSV。

Lightning 赏金与推送付费

• 赏金：listBounties、createBountyInvoice、publishBountyToNostr、submitBounty、listBountiesForIssue、发布/撤回工具。
• 付费墙：getPushPaywallStatus、createPushPaywallIntent、syncRepoPushPolicy。
• 可选 LNbits：在 MCP 环境中设置 GITTR_LNBITS_URL 和 GITTR_LNBITS_ADMIN_KEY（参见 .env.example）。

会话 / 密钥

• describeAgentAuth — 运行一次：确认密钥已加载（绝不返回 nsec）；如果尚未配置，会提示 Agent 询问你是否使用测试密钥对。
• setupTestKeypair — 在你明确同意后，将一次性测试身份写入 .nostr-keys.json（可随时替换为你的真实 nsec）。
• loadCredentials、getPublicKey — 调试辅助工具。MCP loadCredentials 会隐藏 nsec（仅显示前缀）、secretKey 和 private_key。

完整工具列表：server.js 中有 50 多个工具（搜索 name:）。库 API：docs/DEVELOPER.md。

---

安装（5 分钟）

要求

• Node.js 18+
• 一个 Nostr 私钥（nsec 或十六进制格式）——与你在 gittr.space 上使用的身份相同

1. 获取服务

克隆（开发者 / Cursor）：

git clone https://github.com/arbadacarbaYK/gittr-mcp.git
cd gittr-mcp
npm install

Claude Desktop 一键安装（.mcpb）： 此软件包不在 npm 上。从 GitHub Releases 下载最新的软件包（gittr-mcp-x.y.z.mcpb）并安装。每当我们推送 v* 标签时，都会自动构建新版本 — 参见 docs/RELEASE.md。

2. 添加你的密钥（仅本地使用，切勿提交）

cp .nostr-keys.json.example .nostr-keys.json

编辑 .nostr-keys.json 并设置你的 nsec（或十六进制 secretKey）。此文件已加入 gitignore。

查找顺序：./.nostr-keys.json（启动 MCP 进程时所在的文件夹）→ server.js 旁边的 .nostr-keys.json → ~/.nostr-identity.json → ~/.config/gittr/keys.json。在 Windows 上，即使未设置 HOME，也会使用主文件夹。读取文件前会移除 UTF-8 BOM（PowerShell 的默认设置）。

还没有密钥？测试密钥对流程。 如果找不到凭据，describeAgentAuth 和所有缺少密钥的错误都会提示 Agent 询问你是否要创建一个一次性测试密钥对。如果你同意，Agent 会调用 setupTestKeypair({ confirm: true }) — 此操作会在 .nostr-keys.json 中写入一个新的身份（标记为 "generated": true，文件模式为 600，绝不提交），此后会自动加载该身份。准备好后，随时可以将该文件中的 nsec 替换为你的真实密钥；describeAgentAuth 会继续提醒 Agent 当前使用的是测试密钥。除非带有 confirm: true，否则绝不会运行；也不会覆盖现有凭据，除非你明确要求使用 force: true — 使用密钥对发布的任何内容都会永久关联到该身份，因此始终由你决定，而不是 Agent。

3. 配置你的 MCP 主机

重要： 添加新的服务条目 — 不要替换整个 MCP 配置。

Cursor

编辑 ~/.cursor/mcp.json（或项目 MCP 设置）。使用绝对路径：

{
  "mcpServers": {
    "gittr": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gittr-mcp/server.js"],
      "env": {
        "BRIDGE_URL": "https://gittr.space"
      }
    }
  }
}

重新加载 MCP 或重启 Cursor。

Claude Desktop

退出 Claude，编辑 claude_desktop_config.json（路径因操作系统而异 — 参见 Anthropic 文档），添加与上文相同的 mcpServers 配置块，然后重启。

VS Code / Copilot、Windsurf、OpenClaw、自定义应用

使用相同的 stdio 协议：command：node，args：["/path/to/server.js"]，可选的 env。
OpenClaw / mcporter：参见 docs/MCP-HOSTS.md。

作为库嵌入（不使用 MCP）

const gittr = require('gittr-mcp');
await gittr.pushToBridge({ /* ... */ });

入口点：index.js。MCP 进程：server.js（npm 可执行文件 gittr-mcp）。

4. 验证

在聊天中，让 Agent 调用 describeAgentAuth，或在仓库中运行：

npm test                 # full package (includes clone-set + forge-match regressions)
npm run test:regressions # fast: grasp clone URLs + findReposBySource matchers
npm run test:mcp-stdio   # optional live stdio CallTool matrix

UI / 文件获取提示词保真度回归测试位于 gittr 单体仓库中：cd ../gittr/ui && npm run test:regressions（参见 gittr docs/FILE_FETCHING_INSIGHTS.md）。

---

可以向 Agent 提出什么要求

以下示例对应上面的工作流：

• “创建一个名为 my-demo 的仓库，添加 README 并发布到 gittr。”
• “将这些文件更改推送到 main 上的 my-demo。”
• “创建一个问题：登录按钮无法使用。”
• “列出 npub…/my-demo 上未关闭的 PR，并在我是所有者的情况下合并 PR <id>。”
• “将 https://github.com/user/repo 镜像到 gittr，并命名为 repo-name。”

Agent 应将工具结果作为 JSON 读取；许多响应包含 agentSummary 和 nextSteps。

---

限制（PR 和克隆 URL）

简而言之——完整详情请参阅 docs/DEVELOPER.md：

1. 桥接推送和 Nostr 发布是两个独立步骤，除非你使用 createRepo。仅推送不会让仓库在所有地方都可见。
2. 只有当你发布的 clone URL 提供 Git HTTP 服务时，其他人才能通过 git clone 成功克隆。本 MCP 默认使用 https://git.gittr.space/<hex-pubkey>/<repo>.git。克隆失败意味着要修复 30617 中的 URL，而不是“忽略并继续”。发布时会拒绝或扩展仅包含主机的值，例如 https://git.gittr.space。
3. mergePullRequest 需要在运行 MCP 的机器上安装 git，且需要维护者或所有者权限。
4. 中继可能会限流或延迟；验证失败就意味着发布失败，而不是“可能没问题”。
5. 效果与网站上的 Push 相同。 mirrorRepo 会复制 forge 的提交（如果仓库已存在，也会更新它），然后为 gittr、ngit、gitnostr、shakespeare 和 danconway 写入 clone，将 forge URL 保留在 source 中，并在 forge 的默认分支上以 HEAD 发布各分支的最新提交。再次调用时会保留现有的名称、描述和网页链接。不会添加已失效的主机（git-01.uid.ovh、ngit-relay.nostrver.se）。
6. pushToBridge 会用一个新的快照替换分支（作者为 gittr push），并丢弃导入的 GitHub 历史记录。这相当于在网站上编辑文件，而不是同步 GitHub。不要在 mirrorRepo 之后使用它。

MCP 用户能否享受到 gittr 的过滤器／CORS 服务端修复？

大多可以，无需更新 MCP。 浏览器／filter／uploadpack／CORS 修复部署在 git.gittr.space 上。任何克隆该主机的用户（包括通过 MCP 操作的 Agent）都能在服务端修复完成后立即受益。

MCP 更新是新版本，不是 npm 包。 本项目并非从 npm 注册表安装。Cursor 会在本地 server.js 上运行 node。Claude 可以从 GitHub Releases 安装 .mcpb 文件。

• Cursor： 在路径以 gittr-mcp/server.js 结尾的文件夹中运行 git pull，然后重新加载 MCP。npm install 仅用于首次下载该文件夹中的库，常规更新不需要运行它。
• 发布文件： 从 Releases 安装新的 gittr-mcp-x.y.z.mcpb。旧版 1.0.9 文件不包含后续修复。启动时显示的版本号可用于区分它们。

---

开发者

npm ci
npm test
# Live tests (real relays; optional LNbits) — see .env.example
GITTR_TEST_NSEC=nsec1... npm run test:live:matrix

文档	内容
docs/MCP-HOSTS.md	各主机的 MCP 配置
docs/AGENT-WORKFLOW.md	不同任务该使用哪个工具
docs/AGENT-QUICKSTART.md	可直接复制粘贴的 Agent 提示词
docs/DEVELOPER.md	API、验证约定、GRASP
docs/SIGNING-GUIDE.md	密钥和 NIP-98
docs/NIP34-SCHEMAS.md	事件类型
docs/MCP-GITTR-PARITY.md	MCP 与 gittr.space 功能对照表

---

安全

• 请勿提交 .nostr-keys.json、.env 或真实的 nsec 值。
• 桥接身份验证使用 NIP-98；请将 Agent 对话记录视为敏感信息。
• 只有 .nostr-keys.json.example 应当纳入 Git。
• gittr 的 Dependencies 选项卡可能会列出 MCP SDK 内部的匹配项。gittr-mcp 仅通过 stdio 通信（它是服务端，而非 OAuth 客户端）。@modelcontextprotocol/sdk 保持在 ^1.32.1 或更高版本，以确保 CVE-2026-104850 不会出现在锁文件中。overrides 会固定修补后的 fast-uri、hono、qs 和 zod 4.6.7（CVE-2023-54404——服务端不会使用 Zod 解析访客数组）。详情请参阅：docs/SECURITY-ADVISORIES.md。

---

Links

• This repo: https://github.com/arbadacarbaYK/gittr-mcp
• gittr.space: https://gittr.space
• Glama: https://glama.ai/mcp/servers/arbadacarbaYK/gittr-mcp
• Awesome MCP Servers: https://github.com/punkpeye/awesome-mcp-servers (Version Control)
• NIP-34 (git on Nostr): https://github.com/nostr-protocol/nips/blob/master/34.md

See LICENSE (MIT).