Graphkeeper

What graphkeeper MCP server does

The graphkeeper MCP server turns a repository’s Git history into a queryable knowledge graph. Its primary signal is file co-change frequency: for each commit, it records which files were modified together and counts those pairings across the repository’s history. An agent can use that information to identify files that are likely to need coordinated changes when one file is edited.

The project is local-only. It reads the checked-out repository and writes a .graphkeeper/graph.json store, with no account, hosted service, embeddings API, or remote data requirement described in the project materials. The npm and Python distributions implement the same schema, so either CLI can read a store created by the other.

How it works

Running build analyzes the repository’s complete non-merge history with git log --no-merges --name-only. It counts file pairs that occur in the same commit and saves the resulting graph. The default limit skips commits that touch more than 100 files, reducing noise from mass formatting, vendoring, or similarly broad changes. This threshold can be changed with --max-files-per-commit.

The graphkeeper MCP server can optionally enrich the same store with symbol and call relationships from the local graphify executable. If graphify is on PATH, the build invokes its code-only extraction mode and merges the resulting nodes and edges. If it is absent, co-change analysis remains available and call-graph queries report that the enrichment is unavailable rather than returning an empty result.

Setup and configuration

Install the JavaScript implementation globally with npm install -g graphkeeper-cli, run it without installation through npx graphkeeper-cli build, or install the Python implementation with pip install graphkeeper-cli. Node.js 18 or newer is required for the npm package; Python 3.9 or newer is required for the Python package. Both implementations require git on PATH.

From a repository, run graphkeeper build and then query a file with graphkeeper query co-change path/to/file. The build accepts an optional repository path and writes the store beneath that repository. Use --no-graphify to disable optional enrichment even when graphify is installed. The README does not specify environment variables or a hosted configuration service.

Tools and capabilities

• Build a co-change graph from the repository’s Git history.
• Query files that historically changed alongside a specified file.
• Query symbol callers and callees when graphify enrichment has been included.
• Return command results as JSON with --json, making output suitable for scripts and agents.
• Limit oversized commits to preserve the usefulness of co-change counts.
• Share the .graphkeeper/graph.json format between the npm and Python implementations.

The repository’s examples show query co-change returning ranked files with their co-change counts, and query calls returning callers and callees for a symbol in an enriched store.

Limitations and notes

Results describe observed editing history, not a static dependency guarantee. A file pair appears because both files changed in the same commits; the graph does not establish that one file imports or requires the other. Large commits are excluded by the default file-count cap, which can affect results for repositories with many broad changes.

Call-graph queries require the separate graphify executable and its local extraction path. Without that optional dependency, the graphkeeper MCP server operates in co-change-only mode. The provided material describes local CLI packages and MCP use, but does not document authentication, remote repository access, environment variables, or a hosted deployment mode.