stden/graphify repository overview

⁠stden/graphify

Build Graphify knowledge graphs of code and docs, then query them from the CLI or MCP.

⁠Overview

This image provides Graphify⁠, the graphifyy package on PyPI. Graphify reads a project folder and writes a knowledge graph of its code, documents, and papers. AI coding assistants query this graph instead of reading every file.

The image includes:

• The graphify command and the graphify-mcp server.
• mcpo⁠, which publishes the MCP tools as an OpenAPI HTTP server for Open WebUI and other HTTP clients.
• Support for MCP, watch mode, Leiden clustering, PDF, Office, SQL, and SVG export.
• The Anthropic and OpenAI client libraries for document extraction with a language model.

Code extraction uses tree-sitter in the container. It does not need an API key or a network connection. Documents, papers, and images need a language model. The base image is python:latest. The working directory is /workspace. The default command starts Bash.

⁠Tags

View all tags on Docker Hub⁠. The latest tag changes when a new build passes its tests.

⁠Pull the image

docker pull stden/graphify:latest

⁠Tutorial

Do these steps in your project directory. The commands mount the directory at /workspace and run as your user, so the output files belong to you. Set a short name for the command first:

alias graphify='docker run --rm -i --user "$(id -u):$(id -g)" -v "$PWD":/workspace stden/graphify:latest graphify'

⁠Step 1: Exclude files

Graphify skips the files in .gitignore. Add a .graphifyignore file for other files that you do not want in the graph, such as generated code:

printf 'generated/\nvendor/\n*.min.js\n' > .graphifyignore

⁠Step 2: Build the graph

graphify extract . --code-only
graphify cluster-only . --no-label

The commands write the graphify-out/ directory:

• graph.json contains the full graph.
• GRAPH_REPORT.md lists the most connected nodes, the communities, and unexpected connections. Read this file first.
• graph.html shows the graph in a browser.

⁠Step 3: Query the graph

graphify query "How does login work?"
graphify explain UserService
graphify path Router Database

query starts at the matching nodes and follows their connections. explain shows one node and its connections. path shows the shortest path between two nodes. For scripts: exit code 0 means an answer, 3 means an ambiguous name, and 4 means no match.

⁠Step 4: Update the graph after a change

graphify update .
graphify cluster-only . --no-label

update extracts the changed code files again and does not need a language model. cluster-only refreshes the communities and the report.

⁠Step 5: Export the graph

graphify export svg
graphify export graphml

Add graph.svg to a document or a wiki page. Open the GraphML file in a graph tool such as Gephi or yEd.

⁠Step 6: Connect an AI assistant over MCP

Add this server to the MCP configuration of your assistant. Replace /path/to/project with the absolute path of your project.

{
  "mcpServers": {
    "graphify": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "-v", "/path/to/project:/workspace",
        "stden/graphify:latest", "graphify-mcp", "graphify-out/graph.json"
      ]
    }
  }
}

The server gives tools such as query_graph, get_node, get_neighbors, and shortest_path.

⁠Step 7: Serve the tools over HTTP with mcpo

mcpo starts graphify-mcp and publishes each tool as a POST /<tool> endpoint. The API description is at /openapi.json, and the interactive documentation is at /docs. With --strict-auth, every request must send the key as Authorization: Bearer <key>.

openssl rand -hex 32 > mcpo-api.key
docker run -d --name graphify-tools -p 127.0.0.1:8000:8000 --user "$(id -u):$(id -g)" \
  -v "$PWD":/workspace stden/graphify:latest \
  mcpo --port 8000 --api-key "$(cat mcpo-api.key)" --strict-auth -- \
  graphify-mcp graphify-out/graph.json

curl -H "Authorization: Bearer $(cat mcpo-api.key)" -H 'Content-Type: application/json' \
  -d '{"question": "How does login work?"}' http://127.0.0.1:8000/query_graph

To connect Open WebUI⁠, put both containers on one Docker network. Then the Open WebUI server can find the tool server by its name:

docker network create ai-tools
docker network connect ai-tools open-webui
docker network connect ai-tools graphify-tools

In Open WebUI, open Admin Panel → Settings → Integrations. In the Tools section, under External Tool Servers, select Add Connection and the OpenAPI type. Enter the URL http://graphify-tools:8000, the path openapi.json, and the Bearer key from mcpo-api.key. The Open WebUI server calls an admin connection. A connection in the personal Settings → Integrations is called from your browser, so it needs the URL http://127.0.0.1:8000 instead.

⁠Optional: Add documents with a language model

Remove --code-only to also read documents, papers, and images. Give the container the API key of the model provider. Graphify uses the backend of the key that you set.

docker run --rm -e ANTHROPIC_API_KEY --user "$(id -u):$(id -g)" \
  -v "$PWD":/workspace stden/graphify:latest graphify extract .

Use OPENAI_API_KEY for OpenAI. The --backend option also selects gemini, deepseek, kimi, or ollama.

⁠Best practices

• Start with code only. --code-only is free, fast, and offline. Add documents later, when you know which ones the assistant needs.
• Keep your code private when you must. A language model backend sends file contents to its provider. Use --code-only for code that must stay on your computer.
• Keep secrets out of the graph. Put secret files, data dumps, and build output in .graphifyignore. Do not give the container more of the disk than the project.
• Pass API keys from the environment. Use -e ANTHROPIC_API_KEY without a value. Do not write a key on the command line, in a Dockerfile, or in the project.
• Keep the graph current. Run graphify update . after git pull and after large changes. An old graph gives the assistant wrong answers.
• Install git hooks on the host, not from this container. graphify hook install writes the path of the container's Python into .git. The hooks then fail on your computer. In a container workflow, run graphify update . yourself or in CI.
• Read GRAPH_REPORT.md before you query. The most connected nodes show the main parts of the system. The unexpected connections often show coupling problems.
• Use exact names in scripts. graphify explain and graphify path refuse an ambiguous name with exit code 3 and list the candidates.
• Protect the HTTP server. Start mcpo with --api-key and --strict-auth, publish the port on 127.0.0.1 only, and keep the key file out of git. Anyone with the key can read the graph, which contains names and paths from your code.
• Skip the HTML view for large graphs. Add --no-viz to cluster-only when the graph has more than about 5000 nodes, or in CI.
• Use a fixed image in CI. The latest tag changes. Pin a digest, such as stden/graphify@sha256:..., when a CI job must give the same result every time.

⁠Source and checks

The smoke test runs the tutorial steps on Python, JavaScript, and SQL files without a language model. It checks the ignore file, the report, the query, explain, and path commands, update, SVG export, the installed extras, the MCP server, and mcpo with its API key.

• Dockerfile⁠
• Smoke test⁠
• Overview source⁠
• Repository and Docker tutorial⁠