<div align="center">

# git-org-group-cred-vault

**MCP server for managing GitHub & GitLab credentials** — store tokens in an encrypted vault and let AI agents retrieve them automatically by org or group name.

[![Node](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol-000000)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform: GitHub + GitLab](https://img.shields.io/badge/Platform-GitHub%20%2B%20GitLab-blue)](#)

*A self-hosted, AI-agent-ready credential manager for MCP clients like Zed, Claude Desktop, VS Code, and Cursor.*

</div>

---

## What is this?

`git-org-group-cred-vault` is an **MCP (Model Context Protocol) server** that keeps your GitHub and GitLab **personal access tokens** in a local, encrypted vault and retrieves them **by keyword** — typically the org or group name. AI agents resolve the right credential automatically during git operations instead of hardcoding secrets into prompts or config.

- 🔐 **Secure storage** — tokens kept in a vault, never exposed in tool listings
- ⚡ **Automatic resolution** — say *"push to acme-org"*, the agent fetches the matching token
- 🧩 **Per-project scoping** — tokens can be global or scoped to a single repo
- 🌐 **Self-hosted** — full control; works on Windows, Linux, macOS, and Docker/Unraid
- 🏷️ **Platform tagging** — filter by `github` or `gitlab`
- 🔤 **Custom GitLab prefix support** — handles self-hosted instances with custom prefixes (e.g. `acmepat-`)

## Features

| Capability | Detail |
|------------|--------|
| **Keyword lookup** | Find tokens by org name, group name, token prefix, or any keyword. Scoring prioritizes exact matches → substring matches → token overlap. |
| **Dual scope** | Global (`~/.git-org_group-cred-vault/`) or project-scoped (`.git-org_group-cred-vault/`). Local tokens take precedence. |
| **Bulk import** | Load a whole credential file in one call. |
| **Platform tagged** | Each token tagged `github` or `gitlab`; filter as needed. |

## Tools

| Tool | Description |
|------|-------------|
| `add_token` | Store a GitHub or GitLab credential for an org/group. |
| `import_tokens` | Bulk-import multiple tokens from a plain-text file (`tokenName token` per line). |
| `get_git_credential_for_org` | **Main lookup tool.** Call BEFORE any git push/clone/fetch when the user mentions an org or group. Returns the matching token. |
| `list_tokens` | List all stored tokens (without exposing values). Shows name, platform, scope. |
| `remove_token` | Delete a stored token by name. |

## Quick Start

### 1. Install

```bash
npm install
# or run directly:
node src/index.mjs
```

Requires **Node.js ≥ 18** and an **MCP-compatible host** (Zed, Claude Desktop, VS Code, Cursor, etc.).

### 2. Add a token

From any MCP host, tell the agent:

> Store my GitHub token for org `acme` as `acme-github` with value `ghp_xxxxxxxxxxxxxxxxxxxx`

Or call `add_token` directly:

| Parameter | Required | Description |
|-----------|----------|-------------|
| `tokenName` | yes | Name/keyword for lookup (e.g. org or group name) |
| `token` | yes | The actual token value |
| `platform` | yes | `github` or `gitlab` |
| `org` | no | GitHub org name (extra keyword) |
| `group` | no | GitLab group name (extra keyword) |
| `prefix` | no | GitLab custom token prefix (extra keyword) |
| `scope` | no | `auto` (default), `project`, or `global` |

### 3. Retrieve a token

The tool fires automatically during git operations. Just say:

> push to acme-org

The agent calls `get_git_credential_for_org` to resolve the credential before pushing.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `keywords` | yes | Org name, group name, or any keyword to match |
| `platform` | no | `github` or `gitlab` to filter |

### 4. Bulk import

Import a whole credential file at once:

> import the tokens from `path/to/token-list.txt`

File format — one token per line, whitespace-separated:

```
acme-github ghp_xxxxxxxxxxxxxxxxxxxx
acme-gitlab glpat-xxxxxxxxxxxxxxxx
# lines starting with # are skipped
```

Platform is auto-detected: tokens starting with `glpat-`/`wfbpat-` are tagged `gitlab`, all others `github`.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `filePath` | yes | Absolute path to the text file |
| `scope` | no | `auto` (default), `project`, or `global` |
| `org` | no | Org name attached to ALL imported tokens (extra keyword) |

## Scope & Storage

| Scope | Location |
|-------|----------|
| **Global** | `~/.git-org_group-cred-vault/tokens.json` |
| **Project** | `.git-org_group-cred-vault/tokens.json` inside the repo |
| **Auto** (default) | project if a local vault exists, otherwise global |

## Running on Unraid / Docker

Because it's a plain stdio MCP server, you can host it in any MCP gateway or container. On Unraid, run it inside [mcpelevator](https://github.com/pacnpal/mcpelevator) (or any MCP gateway) and expose it to clients as an authenticated HTTP/SSE endpoint:

```bash
docker exec -it mcpelevator bash -c "cd /data/servers/git-org-group-cred-vault && npm install"
```

## License

[MIT](LICENSE)