Git MCP Server
Clone, pull, commit, and push git repositories that live inside CharmIQ Folders.
|
|
charmiq://folder/<id> URI; everything inside that Folder lives in CharmIQ but stays in sync with the remote git repository.https://api.charmiq.ai/mcp/gitTools
clone | |
pull | |
check_remote | |
status | |
diff | |
commit | |
push | |
revert | |
log | |
reclone | |
delete | |
update_auth |
clone takes a root Folder URI — charmiq://folder/<id> — to identify which repository to act on.The Working Loop
status(folderUri)— find dirty files. Returnscharmiq://source/…URIs.diff(folderUri, fileUris)— see what changed against the last commit's blob.commit(folderUri, fileUris, message)— commit locally.push(folderUri)— push to the remote.
check_remote(folderUri)— has anything moved upstream? (fast, no network fetch.)pull(folderUri)— pull the latest if so.
status returns are interchangeable with the rest of the MCP surface — pass them to VFS server tools (read_file, replace_string, write_file) to actually make edits before committing.Initial Clone
clone(remoteUrl, parentFolderUri, name?) creates a new git-backed Folder under the parent and pulls the remote down. The result is a charmiq://folder/<id> URI that you'll pass to every subsequent git tool.What Lives Where
Source files in the repo show up as charmiq://source/<id>documents inside the cloned Folder.Folders in the repo show up as charmiq://folder/<id>sub-Folders.Binary files show up as charmiq://file/<id>assets.
list_dir, read_file, grep_search, semantic_search — work on cloned repos exactly the same way they work on Workspaces and Charms.Recovering From a Failed Operation
error with a lastError describing what happened. Error is not terminal: every operation (including pull, commit, push, revert, reclone, delete) can run from error. A successful operation clears the error automatically.OAuth integration removed or token revoked. Call update_auth(folderUri, integrationId)to bind a fresh integration, then retry the operation that failed.Push rejected as non-fast-forward. pull(folderUri)first to integrate the remote commits, thenpushagain.Merge conflict on pull. revert(folderUri)to drop the local changes that conflicted, thenpullagain. Orrecloneto start fresh from the remote.Unrelated histories on pull. The local and remote share no common ancestor (most often: the remote was re-initialized / force-pushed away). The only recovery is reclone(folderUri, confirmRepositoryName)— revert-then-pull cannot help because there's no shared base to merge from.Local state can't be reconciled. reclone(folderUri, confirmRepositoryName)rebuilds the local state from the remote in place. Discards all local work — dirty edits AND unpushed commits.
Type-to-Confirm: delete and reclone
delete and reclone are the two tools that discard committed history. Both require confirmRepositoryName matching the repository's displayed identity (the org/repo form derived from the remote URL, with any trailing .git stripped). The server validates the match before executing. This protects against accidental data loss when an agent acts on a stale plan.update_auth is metadata-only — it rebinds the OAuth integration without touching the archive or entity tree. It does not clear an error status; the next successful pull / push / commit proves the new credentials and clears the error.Patterns
statusbeforecommit. Always read what's actually dirty before staging anything. The user may have edits you didn't make.check_remotebeforepull. It's a fast metadata check — saves a network round-trip if there's nothing to do.Commit messages matter. They go straight into git history. The Charm that wrote the change should also write the message. deleteandrecloneare permanent. Both discard local work —deletealso removes the Folder. TheconfirmRepositoryNamerequirement is the safety; pass the repo's displayed identity exactly as it appears.