git-a2a MCP server

git-a2a

Connect a Git component together with the agent responsible for it.

git-a2a is a cross-platform component dependency manager. A component repository publishes code, one A2A Agent Card reference for its owner, and optionally a readable surface such as API documentation, examples, or source. A consumer connects the code through its own platform's adapter and records the exact commit, adapter, and package-manager variant.

git-a2a does not send messages, manage tasks, run agents, or host Agent Cards. Use the usable Agent Card reference shown by git a2a whose NAME with an external A2A client: an HTTPS URL or a local copy of a repository-relative card from the applied commit.

Quick start

Run the binary directly as git-a2a, or install it on PATH and use Git's equivalent git a2a form:

git a2a init
git a2a add https://github.com/acme/lib-utils.git --name lib-utils
git a2a list
git a2a whose lib-utils
git a2a pull lib-utils
git a2a remove lib-utils

Version 2.1.0 introduces whose NAME and removes the positional argument from list. Scripts using list NAME --json must use list --json and select the alias from the array.

There are exactly six domain commands:

Command	Result
init	Creates a minimal schema 2 a2amodule.yml without overwriting an existing manifest.
add SOURCE	Resolves one commit, chooses applicable adapters, connects the component, and records its owner and surface.
pull [NAME]	Updates one or every dependency through the adapters and variants chosen by add; with no dependencies it reports No dependencies. and succeeds without mutation.
remove NAME	Removes only the selected dependency's owned integration and local materialization.
list	Reports every direct dependency, commit, adapter, Agent Card, surface, and local problem; --json returns the existing array format.
whose NAME	Reports one dependency's responsible agent, usable Agent Card reference, optional local surface, and recoverable metadata problems; --json returns one object.

pull is adapter lifecycle, not a wrapper around git pull. All bindings of a polyglot component use the same resolved commit. Adapter and manager selection is durable: a later change to PATH or consumer marker files cannot silently switch it.

End-to-end demo

The ACME app walkthrough demonstrates the complete loop: connect a component, discover its responsible agent, send a request through A2A, let the owner change the library, run git-a2a pull, and observe the new result. The app repository and library repository must be cloned next to each other. Docker with Compose is the only runtime requirement:

git clone https://github.com/neprel/git-a2a-demo-acme-lib.git
git clone https://github.com/neprel/git-a2a-demo-acme-app.git
cd git-a2a-demo-acme-app
./demo/run.sh

# Short npm-only profile
DEMO_PROFILE=npm ./demo/run.sh

The demo uses deterministic agents without LLM API keys, real A2A transport, the published git-a2a 2.0.0, and temporary local Git remotes. The separate demo client performs A2A communication; git-a2a manages dependency code and metadata. The agents exist only for the local run and are not permanently available public services. See the verified transcript for the recorded full-profile result.

Component contract

a2amodule.yml uses schema 2:

schema: 2
component:
  id: lib-utils
  description: Shared parsing and validation utilities.
  repository: https://github.com/acme/lib-utils.git
  exports:
    - adapter: npm
      name: "@acme/lib-utils"
    - adapter: pypi
      name: acme-lib-utils
  surface: docs/public
agent:
  name: lib-utils-owner
  card: https://agents.acme.example/lib-utils/.well-known/agent-card.json

The Agent Card remains the authority for the agent's interfaces, skills, and authentication. The manifest deliberately does not duplicate them. init may create an incomplete local manifest without agent; a repository consumed by add or pull must declare agent.card.

The optional component.surface is published data from the same applied commit and is materialized under .git-a2a/surfaces/NAME. If no surface is declared, no repository content is implicitly published. Surface is not an installation mechanism and is not a submodule.

See the manifest reference, authoring guide, consumer guide, and schema 1 migration guide.

Adapter matrix

Every existing platform integration is retained. Native adapters apply dependencies through the platform's own manager, updating declarations, native locks, and installed or resolved state; build-system adapters compose with one submodule checkout rather than copying source into a second tree.

Mode	Adapters
Native Git dependency	npm (npm, Yarn, pnpm, Bun), Python (uv, Poetry, PDM, PEP 621/pip), Go, Cargo, SwiftPM, Pub, Bundler, Composer, Mix, Cabal/Stack, Zig, Clojure, Nix
Submodule + build integration	CMake, Gradle, MSBuild, Maven, Meson
Submodule only	Fallback when no integration applies or the native manager cannot represent the source

Git submodule is an ordinary adapter with the same add/pull/remove/inspect lifecycle. Native lockfiles remain owned by their package managers. See Works with for the detailed matrix and boundaries.

Installation

These existing installation channels are preserved. Commands track the latest stable release; pin a version in CI.

Channel	Command
Go	go install github.com/neprel/git-a2a/v2/cmd/git-a2a@latest
Go zero-install	go run github.com/neprel/git-a2a/v2/cmd/git-a2a@latest --version
macOS/Linux installer	curl -fsSL https://git-a2a.com/install.sh | bash
Windows installer	irm https://git-a2a.com/install.ps1 | iex
Homebrew	brew install neprel/tap/git-a2a
Scoop	scoop bucket add git-a2a https://github.com/neprel/scoop-bucket; scoop install git-a2a
npm	npx git-a2a@latest --version
PyPI with uv	uvx git-a2a --version
PyPI with pipx	pipx run git-a2a --version
Container	docker run --pull=always --rm ghcr.io/neprel/git-a2a:latest --version
Nix flake	nix run github:neprel/git-a2a -- --version

Linux .deb, .rpm, and .apk packages are attached to GitHub Releases. Release archives cover Darwin, Linux, and Windows on amd64/arm64 and include checksums and SBOMs. The standalone installers verify checksums and support version pinning, destination selection, and dry-run. Package-manager installs are updated with that package manager; the binary has no self-updater.

Maintainer and provenance details are in the release guide.

Documentation

• CLI reference
• Manifest reference
• Authoring a component
• Consuming components
• Agents and external A2A clients
• Supported adapters
• Migrating from schema 1
• FAQ
• Release and installation maintenance

The portable Agent Skill teaches a coding agent this six-command workflow. It does not configure an MCP server or agent harness.

Specification as source

Repository decisions and invariants live in .hint files beside the artifacts they govern. hint <path> returns the knowledge governing a path, and hint check <path...> validates the linked research records. The repository and CI use HINT 2.0.1. See HINT for the tool and format.

License: MIT.