gitingest-mcp

MCP server that converts Git repositories into compact, prompt-ready digests for Large-Language-Models (LLMs).

gitingest-mcp exposes the Model Context Protocol (MCP) over stdio so any LLM-aware editor or tool can request an up-to-date representation of a Git repository—local or remote. The server clones (or analyses a local checkout), applies flexible filters (e.g. .gitignore, size limits, glob patterns), and streams back a single text document containing:

1. A summary (branch, commit, size, token count…)
2. A human-readable directory tree
3. The concatenated contents of every included file

The result is optimised for conversational code understanding, code-review, and RAG style retrieval.

✨ Features

• Works with GitHub, GitLab, Bitbucket, generic git, or a local path
• Optional shallow clone, sparse checkout, or submodule support
• Honor .gitignore and custom .gitingestignore files
• Powerful include/exclude glob patterns
• Hard limits for file size, file count, total size, or token budget
• Built-in retry & timeout logic to survive flaky networks

🚀 Quick Start

# One-off execution via npx
npx -y gitingest-mcp-server

Every MCP-aware client needs a small configuration snippet. Example:

{
  "mcpServers": {
    "gitingest-mcp": {
      "command": "npx",
      "args": ["-y", "gitingest-mcp-server"],
    },
  },
}

(Swap npx for the absolute path to gitingest-mcp-server if you installed the package globally or are running from source.)

🛠️ Available Tools

ingest_repository

Transform a Git repository into an LLM-friendly digest.

| Parameter | Type | Default | Description | | ------------------------------------- | --------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------- | | repository | string | required | Git URL (https://…), SSH (git@…), shorthand (user/repo), or local path | | source | "github" \| "gitlab" \| "bitbucket" \| "local" \| "git" | auto | Force a specific provider | | branch / commit / tag | string | | Checkout a specific ref | | cloneDepth | number | 1 | Depth of shallow clone | | sparseCheckout | boolean | false | Enable sparse checkout when possible | | includeSubmodules | boolean | false | Recursively pull submodules | | includeGitignored | boolean | false | Include files matched by .gitignore | | useGitignore | boolean | true | Respect .gitignore when filtering | | useGitingestignore | boolean | true | Respect .gitingestignore when filtering | | excludePatterns / includePatterns | string[] | | Additional glob patterns | | maxFileSize | number | | Max single file size (bytes) | | maxFiles | number | 1000 | Hard file-count limit | | maxTotalSize | number | 52428800 (50 MiB) | Max combined size (bytes) | | maxTokens | number | | Trim output after N tokens | | token | string | | Auth token for private repos | | maxRetries | number | 3 | Retry attempts for network ops | | retryDelay | number | 1000 | Base delay between retries (ms) | | timeout | number | 30000 | Abort the entire operation after N ms |

Example call body:

{
  "name": "ingest_repository",
  "arguments": {
    "repository": "deadraid/gitingest-mcp",
    "branch": "main",
    "excludePatterns": ["**/tests/**"],
    "maxFileSize": 50000,
  },
}

🔭 Running from Source

# Clone & install
git clone https://github.com/deadraid/gitingest-mcp.git
cd gitingest-mcp
npm install

# Build TypeScript → dist
npm run build

# Start the MCP server (stdout/stdin)
node dist/server/index.js

During development you can use:

npm run dev   # ts-node with autoreload
npm run test  # vitest
npm run lint  # eslint

✅ Tests

Vitest suites live under tests/ and exercise cancellation, timeouts, schema validation, and advanced edge-cases.

Run all tests with coverage:

npm run test:coverage

📝 License

MIT © 2024 RaidHon