内容
# gittr-mcp
<!-- mcp-name: io.github.arbadacarbaYK/gittr-mcp -->
**让您的 AI 代理（或应用程序）像开发者一样使用 [gittr.space](https://gittr.space) —— 创建仓库、推送代码、开启和合并拉取请求、管理问题以及处理闪电赏金 —— 使用您的 **Nostr 身份**，而非 GitHub 登录。**
适用于 **Cursor**、**Claude Desktop**、**VS Code / Copilot MCP**、**Windsurf**、**OpenClaw** 或任何支持 [Model Context Protocol](https://modelcontextprotocol.io/) 的主机。
---
## 为什么使用这个？
| 没有 gittr-mcp | 使用 gittr-mcp |
|-------------------|----------------|
| 您需要在聊天和 gittr 网站之间复制粘贴 | 代理调用工具：推送文件、发布仓库元数据、开启问题/拉取请求 |
| 自定义 NIP-98 网桥身份验证和 NIP-34 签名脚本 | 内置签名、挑战处理和中继检查 |
| 不清楚推送是否真正到达 Nostr | 工具返回成功/失败以及 `verification` / `nextSteps` 用于自动化 |
**最终结果：** 一个 MCP 服务器连接您的代理到 **Nostr 上的去中心化 git** —— 与 gittr.space 上的同一个账户（`nsec` / 密钥文件），无需为代理创建单独的供应商账户。
---
## 您可以使用（工作流程）
这些是人们实际运行的 **流程**；每个流程都映射到代理可以调用的 MCP 工具。
### 发布新项目
1. **`createRepo`** — 将初始文件推送到网桥 **和** 发布 Nostr 类型 **30617** + **30618**（适用于代理的最佳默认设置）。
传 `**publicRead: false**` 以创建 **私有** 仓库（代码/克隆/API/SSH 仅对您和列出的维护者可读）。公告名称/描述仍然出现在中继上 —— 只有文件访问权限受到限制。
2. 或分步： **`pushToBridge`** → **`publishRepoAnnouncement`** → **`publishRepoState`**.
### 私有仓库
- 设置 **`publicRead: false`** 在 **`createRepo`**、 **`publishRepoAnnouncement`**、 **`forkRepo`** 或 **`mirrorRepo`** 上。
- 私有仓库对陌生人 **隐藏于 Explore/home/profile 列表**。
- **直接 URL** 仍然显示仓库名称，带有 **私有** 徽章；未经授权的查看者会看到锁定屏幕（无代码）。
- **SSH / CLI / API 读取** 使用与 Web UI 相同的 ACL：您的 **npub** 必须是所有者或维护者（`addCollaborator` 或 设置 → 贡献者 在 gittr.space 上）。
- **SSH 密钥注册** 不变 —— 密钥标识 *您*；私有仓库仅检查 *您的公钥* 是否具有读取权限。
### 日常开发
- **`pushToBridge`** — 在分支上更新文件（NIP-98 身份验证到 gittr 网桥）。
- **`getFile`**、 **`bridgeListFiles`**、 **`bridgeGetFileContent`**、 **`getBranches`**、 **`getCommitHistory`** — 读取仓库状态，无需克隆。
- **`resolveRepoByNostrId`** — 从 npub + 仓库名称查找克隆 URL 和中继。
### 问题（错误报告、任务）
- **`listIssues`**、 **`createIssue`**、 **`getIssueById`**
- **`closeIssue`**、 **`reopenIssue`** — 发布 NIP-34 状态事件（1632 / 1630）。
### 拉取请求（代码审查流程）
| 步骤 | 工具 | 备注 |
|------|------|--------|
| 列出/开启 PR | **`listPRs`**、 **`createPR`** | 签名 Nostr 事件（类型 **1618**）。 |
| 完整的 PR，带有 git 分支 | **`createPRViaGittrCLI`** | 推荐在代理具有 `git` 命令时使用。 |
| 更新 PR 提示 | **`updatePullRequest`** | 新提交 + PR 事件上的克隆 URL。 |
| 合并到 `main` | **`mergePullRequest`** | **真正的 git 合并**：克隆/获取、合并、推送网桥、发布 **30618** + 合并状态 **1631**。仓库所有者或列出的维护者；需要 **`git`**。 |
| 标记已合并（仅 Nostr） | **`markPullRequestMerged`** | 仅状态 —— 无 git 合并。 |
**PR 的诚实限制：** 通过 MCP 创建和列出 PR 支持。**合并** 需要 **`git`** 安装和仓库权限。一些中继对 **克隆 URL + 中继** 匹配在仓库公告中很严格 —— 如果 PR 发布失败，请修复元数据（参见 [限制](#限制-prs--clone-urls)）或使用 **`createPRViaGittrCLI`**。详情： [docs/DEVELOPER.md#limitations](docs/DEVELOPER.md#limitations)。
### 分叉、镜像、导入
- **`forkRepo`** — 在您的密钥下分叉现有的 gittr 仓库。
- **`mirrorRepo`** — 从 GitHub/GitLab URL 复制到 gittr。
- **`importRemoteToBridge`** — 服务器端导入/重新获取到网桥存储。
### 发现与社交
- **`listRepos`**、 **`searchRepos`**、 **`myRepos`**、 **`exploreRepos`**、 **`getTrendingRepos`**（趋势 = 最近的仓库，非参与度排名）
- **`starRepo`**、 **`unstarRepo`**、 **`listStars`** — NIP-25 在仓库的 **30617** 事件上（与 gittr 星标按钮相同）。
- **`watchRepo`**、 **`unwatchRepo`**、 **`listWatchedRepos`** — NIP-51 类型 **10018** 已关注仓库列表（与 gittr 关注相同）。
- **`getRepoContributors`**
**一致性详情：** [docs/MCP-GITTR-PARITY.md](docs/MCP-GITTR-PARITY.md) —— 与 gittr.space 匹配的功能以及注意事项。
### 版本与标签
- **`listReleases`** — 来自网桥的 git **标签** (`refs/tags/*`)，而非 Web UI 的“版本”备注。
- **`createRelease`** — 仅返回指导（gittr 在 UI 中存储版本备注，直到下一个 **30617** 推送）。
### 闪电赏金与付费推送
- 赏金： **`listBounties`**、 **`createBountyInvoice`**、 **`publishBountyToNostr`**、 **`submitBounty`**、 **`listBountiesForIssue`**，发布/撤销工具。
- 付费墙： **`getPushPaywallStatus`**、 **`createPushPaywallIntent`**、 **`syncRepoPushPolicy`**。
- 可选 LNbits：设置 **`GITTR_LNBITS_URL`** 和 **`GITTR_LNBITS_ADMIN_KEY`** 在 MCP 环境变量中（参见 `.env.example`）。
### 会话 / 密钥
- **`describeAgentAuth`** — 运行一次：确认密钥加载（从不返回 `nsec`）；如果未配置，它会告诉代理询问您关于测试密钥对的问题。
- **`setupTestKeypair`** — 在您明确同意后，将一次性测试身份写入 `.nostr-keys.json`（用您的真实 `nsec` 替换任何时候）。
- **`loadCredentials`**、 **`getPublicKey`** — 调试助手。
**完整工具列表：** `server.js` 中的 50 多个工具（搜索 `name:`）。库 API： [docs/DEVELOPER.md](docs/DEVELOPER.md)。
---
## 安装（5 分钟）
### 要求
- **Node.js 18+**
- **Nostr 私钥** (`nsec` 或十六进制) —— 您在 gittr.space 上使用的同一身份
### 1. 获取服务器
**克隆（开发者 / Cursor）：**
```bash
git clone https://github.com/arbadacarbaYK/gittr-mcp.git
cd gittr-mcp
npm install
```
**Claude Desktop 一键式（`.mcpb`）：** 从 [GitHub Releases](https://github.com/arbadacarbaYK/gittr-mcp/releases) 下载最新的软件包（`gittr-mcp-x.y.z.mcpb`）。新版本在我们推送 `v*` 标签时自动构建 —— 参见 [docs/RELEASE.md](docs/RELEASE.md)。
### 2. 添加您的密钥（仅本地，从不提交）
```bash
cp .nostr-keys.json.example .nostr-keys.json
```
编辑 `.nostr-keys.json` 并设置您的 **`nsec`**（或十六进制 `secretKey`）。该文件被 gitignore。
查找顺序：`./.nostr-keys.json` → `~/.nostr-identity.json` → `~/.config/gittr/keys.json`.
**还没有密钥？测试密钥对流程。** 如果没有凭证找到，`describeAgentAuth` 和所有缺少密钥的错误都会告诉代理询问您是否应该创建一次性 **测试密钥对**。如果您同意，代理会调用 **`setupTestKeypair({ confirm: true })`** —— 它将一个全新的身份写入 `.nostr-keys.json`（标记为 `"generated": true`，文件模式 600，从不提交）并从那时起自动加载它。任何时候都可以用您的真实密钥替换该文件中的 `nsec`; `describeAgentAuth` 会不断提醒代理测试密钥是活动的。它从不运行而没有 `confirm: true`，并且在没有您明确要求 `force: true` 的情况下，从不覆盖现有的凭证 —— 在密钥对下发布的任何内容都将永久保留在该身份下，因此这是您而不是代理的决定。
### 3. 连接您的 MCP 主机
**重要：** **添加** 一个新的服务器条目 —— **不要** 替换您的整个 MCP 配置。
#### Cursor
编辑 `~/.cursor/mcp.json`（或项目 MCP 设置）。使用 **绝对** 路径：
```json
{
"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](docs/MCP-HOSTS.md).
#### 作为库嵌入（无 MCP）
```javascript
const gittr = require('gittr-mcp');
await gittr.pushToBridge({ /* ... */ });
```
入口点： `index.js`. MCP 进程： `server.js`（npm 二进制 **`gittr-mcp`**）。
### 4. 验证
在聊天中，要求代理调用 **`describeAgentAuth`**，或从仓库：
```bash
npm test
```
---
## 询问您的代理
上述工作流程的示例：
- “创建仓库 `my-demo` 并附上 README，在 gittr 上发布。”
- “将这些文件更改推送到 `my-demo` 的 `main` 分支。”
- “开启一个问题：登录按钮已损坏。”
- “列出 npub…/my-demo 上的开放 PR 并合并 PR `<id>` 如果我是所有者。”
- “将 `https://github.com/user/repo` 镜像到 gittr 作为 `repo-name`。”
代理应该将工具结果读取为 JSON；许多响应包括 **`agentSummary`** 和 **`nextSteps`**。
---
## 限制（PRs & clone URLs）
简短版本 —— 完整详情在 [docs/DEVELOPER.md](docs/DEVELOPER.md)：
1. **网桥推送** 和 **Nostr 发布** 是单独的步骤，除非您使用 **`createRepo`**。仅推送不使仓库在所有地方可见。
2. **`git clone`** 仅在您的发布的 **`clone`** URL 提供 git HTTP 时才“有效”。此 MCP 默认趋向 **`https://git.gittr.space/<hex-pubkey>/<repo>.git`**。克隆失败意味着修复 **30617** 中的 URL，而不是“忽略并继续”。
3. **`mergePullRequest`** 需要运行 MCP 的机器上的 **`git`** 和维护者/所有者权限。
4. 中继可以限制速率或延迟；验证失败是 **失败** 发布，而不是“可能 OK”。
---
## 开发者
```bash
npm ci
npm test
# 现场测试（真实中继；可选 LNbits）—— 参见 .env.example
GITTR_TEST_NSEC=nsec1... npm run test:live:matrix
```
| 文档 | 内容 |
|-----|----------|
| [docs/MCP-HOSTS.md](docs/MCP-HOSTS.md) | 每种主机的 MCP 配置 |
| [docs/AGENT-WORKFLOW.md](docs/AGENT-WORKFLOW.md) | 逐步推送 + 发布 |
| [docs/AGENT-QUICKSTART.md](docs/AGENT-QUICKSTART.md) | 复制粘贴代理提示 |
| [docs/DEVELOPER.md](docs/DEVELOPER.md) | API、验证合约、GRASP |
| [docs/SIGNING-GUIDE.md](docs/SIGNING-GUIDE.md) | 密钥和 NIP-98 |
| [docs/NIP34-SCHEMAS.md](docs/NIP34-SCHEMAS.md) | 事件类型 |
| [docs/MCP-GITTR-PARITY.md](docs/MCP-GITTR-PARITY.md) | MCP 与 gittr.space 功能映射 |
---
## 安全
- **不要** 提交 `.nostr-keys.json`、`.env` 或真实的 `nsec` 值。
- 网桥身份验证使用 **NIP-98**；将代理记录视为敏感信息。
- 只有 **`.nostr-keys.json.example`** 属于 git。
---
## 链接
- **此仓库：** https://github.com/arbadacarbaYK/gittr-mcp
- **gittr.space：** https://gittr.space
- **NIP-34（git on Nostr）：** https://github.com/nostr-protocol/nips/blob/master/34.md
MIT License.
