gittr-mcp

gittr-mcp

AI エージェント（またはアプリ）に、開発者と同じように gittr — Nostr の Git ホスティング — を使わせましょう — リポジトリの作成、コードのプッシュ、プルリクエストの作成とマージ、イシューの管理、Lightning バウンティの活用を、GitHub ログインではなくNostr アイデンティティを使って行えます。

Cursor、Claude Desktop、VS Code / Copilot MCP、Windsurf、OpenClaw、または stdio 経由で 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 のウェブサイト間でコピー＆ペーストする	エージェントがツールを呼び出して、ファイルのプッシュ、リポジトリのメタデータの公開、イシュー／PR の作成を行う
NIP-98 ブリッジ認証と NIP-34 署名のためにカスタムスクリプトを用意する	署名、チャレンジ処理、リレーのチェックが組み込まれている
プッシュが Nostr に「本当に」反映されたかどうかが分かりにくい	ツールが合否に加えて、verification / nextSteps を返すため自動化に利用できる

結果： 1 つの MCP サーバーで、エージェントをNostr 上の分散型 Gitに接続できます — gittr.space と同じアカウント（nsec / キーファイル）を使い、エージェント用の別のベンダーアカウントは不要です。

ホスティングに関する注意： ウェブサイトの作成／インポートフローでは、announce/Push するまでブラウザー内にデータが保持されます。MCP の createRepo / mirrorRepo / pushToBridge は、ウェブサイトと同じ方法で Git に書き込みます。クローンアドレスは Settings → Relays に保存されているサーバー（最初は自分のサーバー）、その後に公開コピーです。ソフト削除では tombstone がブリッジに POST され、ディスク上のデータが消去されます。

配置内の位置（プラットフォームマップ）

gittr-mcp は、人々がブラウザーで使うものと同じプラットフォームにアクセスするためのエージェント用の入口です。ここにいるのは = 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 はフォージの操作（リポジトリ、issue、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 では不要です。エージェントは通常、ブリッジの HTTPS とイベントを使用します

エージェント向けのアドレス指定： resolveRepoByNostrId(npub|hex, repo) → cloneUrl + リレー。告知された npub パスの HTTPS（git.gittr.space）を優先してください（NIP-34）。シンボリックリンクがない場合、hex パスはディスク上のフォールバックです。公開時は wss://relay.gittr.space を含めてください。

---

できること（ワークフロー）

以下は実際に人々が実行するプロセスで、それぞれエージェントが呼び出せる MCP ツールに対応しています。エージェントは docs/AGENT-WORKFLOW.md（使用するツールと、その後に呼び出してはいけないツール）に従ってください。

新しいプロジェクトを公開する

1. createRepo — 初期ファイルをブリッジにプッシュし、Nostr の kind 30617 と 30618 を一度に公開します（エージェント向けの最適なデフォルトです）。
   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 — ブランチ上のファイルを更新します（gittr ブリッジへの NIP-98 認証）。ファイルまたはフォルダーの削除には、任意で deletedPaths ／ allowTreeShrink を指定できます（Code タブのゴミ箱と同等です）。
• getFile、bridgeListFiles、bridgeGetFileContent、getBranches、getCommitHistory — クローンせずに読み取ります。getFile は ブリッジの後に短い GRASP リストを確認 します。Code タブではありません。ウェブサイトでは、最新のライブ 30617 が使用されます。forge の source がある場合は、そのツリーが使われます（古いブリッジの一覧は置き換えられます）。ない場合は、最初の空でない 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 の Issue のみが対象です。
• 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）は拒否されます。これらは元のサービスでクローズしてください。

プルリクエスト（コードレビューの流れ）

手順	ツール	備考
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	エージェントの PATH に git がある場合に推奨されます。
PR の先端を更新する	updatePullRequest	PR イベントに新しいコミットとクローン URL を追加します。
main にマージする	mergePullRequest	Nostr PR（kind 1618 のイベント ID）を実際に git でマージします。クローン／フェッチ、マージ、ブリッジへのプッシュを行い、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 リポジトリをウェブサイトで Push した場合と同じ結果になります。gittr 上にフォージのコミットを取り込み（履歴は保持され、後続の呼び出しで更新されます）、同じ git サーバー一覧に登録し、HEAD がフォージのデフォルトブランチを指す状態イベントを発行します。後続の呼び出しでは、すでに通知済みの名前、説明、ウェブリンクが維持されます。
• importRemoteToBridge — git サーバーにのみコピーします。オーナーキーを使うと、後続の呼び出しでフォージのコミットが更新されます。Nostr カードは公開しません。ウェブサイトと同じ結果にするには、mirrorRepo を使用してください。
• フォージの 403 エラー／アカウントの一時停止： リポジトリがすでにコピーされている場合は、引き続き https://git.gittr.space/<npub>/<repo>.git を使用してください。ソースを変更するために、mirrorRepo の参照先を新しいフォージに変更しないでください。新しい 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 — ブリッジの git タグ（refs/tags/*）であり、ウェブ UI の Releases タブや Zapstore ではありません。
• listForgeReleases — フォージの Releases タブの一覧（すべてのアセット。NIP-82 の MIME ゲートなし）。
• createRelease — ガイダンスのみを返します（次の 30617 の Push まで、リリースノートは UI に表示されます）。
• fetchForgeReleases — フォージのリリース 1 件と、告知可能なバイナリを取得します。最新のものを取得する場合は tag を省略し、sha256 を取得する場合は hash:true を指定してください（告知前に必須です）。
• announceSoftwareFromForgeRelease — タグ付きフォージリリースから Zapstore／NIP-82（kind 32267／30063／3063）を作成します。APK を優先します。AppImage／DMG／linux tar.gz／MSI／EXE／IPA にも対応します。同じタグの追加バイナリは関連アセットとして扱われます。フォージの 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 — ブリッジ上でロックファイルを解析し、gittr の /api/security/audit 経由で OSV に問い合わせます。

Lightning の懸賞金と Push 課金

• 懸賞金：listBounties、createBountyInvoice、publishBountyToNostr、submitBounty、listBountiesForIssue、リリース／出金ツール。
• ペイウォール：getPushPaywallStatus、createPushPaywallIntent、syncRepoPushPolicy。
• LNbits は任意です。MCP 環境変数に GITTR_LNBITS_URL と GITTR_LNBITS_ADMIN_KEY を設定してください（.env.example を参照）。

セッション／キー

• describeAgentAuth — 1 回実行します。キーが読み込まれることを確認します（nsec は返しません）。未設定の場合は、テスト用キーペアについてユーザーに尋ねるようエージェントに指示します。
• setupTestKeypair — 明示的な承認を得た後、使い捨てのテスト ID を .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 または hex）— gittr.space で使用しているものと同じ ID

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（または hex 形式の 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 とキー不足に関するすべてのエラーで、使い捨てのテスト用キーペアを作成するか、エージェントがあなたに確認するよう指示されます。同意すると、エージェントは setupTestKeypair({ confirm: true }) を呼び出します。新しい ID が .nostr-keys.json に書き込まれ（"generated": true のフラグが付き、ファイルモードは 600 で、決してコミットされません）、以後はすべて自動的に読み込まれます。準備ができたら、このファイルの nsec を実際のキーに置き換えてください。テスト用キーが有効な間は、describeAgentAuth がエージェントにそのことを繰り返し通知します。confirm: true がなければ実行されず、あなたが明示的に force: true を要求しない限り、既存の認証情報を上書きすることもありません。キーペアを使って公開したものは、永久にその ID に紐づきます。そのため、これは常にあなたが判断することであり、エージェントが決めることではありません。

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 を編集します（パスは OS によって異なります。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 bin gittr-mcp）。

4. 確認する

チャットで、エージェントに 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 を参照）。

---

エージェントに依頼できること

上記のワークフローに対応する例：

• 「README を含む my-demo リポジトリを作成して、gittr に公開してください。」
• 「これらのファイル変更を main の my-demo にプッシュしてください。」
• 「ログインボタンが壊れています、という Issue を作成してください。」
• 「npub…/my-demo のオープン PR を一覧表示して、私がオーナーなら PR <id> をマージしてください。」
• 「https://github.com/user/repo を repo-name として gittr にミラーしてください。」

エージェントはツールの結果を JSON として読み取る必要があります。多くの応答には agentSummary と nextSteps が含まれています。

---

制限事項（PR とクローン URL）

要約 — 詳細はdocs/DEVELOPER.mdをご覧ください。

1. Bridge へのプッシュとNostr への公開は、**createRepo**を使わない限り別々の手順です。プッシュしただけでは、リポジトリがあらゆる場所で表示されるようにはなりません。
2. git cloneが他のユーザーに対して「機能する」のは、公開したclone URL が Git HTTP を提供している場合だけです。この MCP は、既定で**https://git.gittr.space/<hex-pubkey>/<repo>.git**を優先します。クローンに失敗した場合は、「無視して続行」するのではなく、30617の URL を修正してください。https://git.gittr.spaceのようなホストのみの値は、公開時に拒否されるか、完全な形式に展開されます。
3. **mergePullRequestには、MCP の実行マシン上のgit**と、メンテナーまたはオーナーの権限が必要です。
4. リレーではレート制限や遅延が発生する場合があります。検証に失敗した場合は公開も失敗であり、「たぶん大丈夫」ではありません。
5. ウェブサイトでの「Push」と同じ結果になります。mirrorRepoはフォージのコミットをコピーし（リポジトリがすでに存在する場合は更新します）、gittr、ngit、gitnostr、shakespeare、danconway 用のcloneを書き込み、フォージの URL をsourceに保持し、フォージの既定ブランチ上のHEADとともにブランチ先端を公開します。2 回目の呼び出しでは、既存の名前、説明、ウェブリンクが保持されます。利用できないホスト（git-01.uid.ovh、ngit-relay.nostrver.se）は追加されません。
6. pushToBridgeはブランチを 1 つの新しいスナップショットで置き換え（作成者はgittr push）、インポートした GitHub の履歴を削除します。これはウェブサイト上でファイルを編集する場合と同じであり、GitHub との同期ではありません。mirrorRepoの実行後に使用しないでください。

MCP ユーザーは gittr のフィルター／CORS サーバーの修正を受けられますか？

**ほとんどの場合、MCP を更新しなくても受けられます。ブラウザー／filter／uploadpack／CORS の修正はgit.gittr.space**に適用されます。（MCP 経由のエージェントを含め）そのホストからクローンするユーザーは、サーバーの修正後すぐにその恩恵を受けます。

**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	コピーして使えるエージェント向けプロンプト
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値はコミットしないでください。
• Bridge の認証にはNIP-98を使用します。エージェントのトランスクリプトは機密情報として扱ってください。
• Git に含めるのは**.nostr-keys.json.example**だけです。
• gittr のDependenciesタブには、MCP SDK 内部の一致項目が表示される場合があります。gittr-mcp は stdio のみで通信します（サーバーであり、OAuth クライアントではありません）。CVE-2026-104850 がロックファイルに含まれないよう、@modelcontextprotocol/sdkは**^1.32.1以降を維持してください。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).