astrograph

ASTrograph is an MCP server that prevents duplicate code writes by analyzing your codebase's structure using AST graphs. It blocks attempts to write new code that has the same abstract structure as existing code, regardless of variable names, formatting, or comments. This helps maintain unique implementations across a project and can be integrated into your IDE or CI workflow via MCP configuration. The server supports Python, JavaScript/TypeScript, Go, and attaches language servers for other languages, enabling real-time code structure comparisons during edits and merges. To use it, configure the astrograph MCP entry in your project (via Docker as shown) and connect your editor or tooling to the MCP server. The server loads and indexes your workspace on startup and re-indexes on file changes, so you’ll receive immediate feedback if a conflicting snippet is attempted.

Prerequisites:

• Docker installed and running on your machine
• Access to the project you want to index
• Basic knowledge of MCP configuration in your workspace

Install and run with Docker (recommended):

1. Add the MCP configuration to your project root (e.g., .mcp.json) with the following content:

{
  "mcpServers": {
    "astrograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--pull", "missing",
        "--add-host", "host.docker.internal:host-gateway",
        "-v", ".:/workspace",
        "-v", "./.metadata_astrograph:/workspace/.metadata_astrograph",
        "thaylo/astrograph:latest"
      ]
    }
  }
}

2. Ensure your project is available at the mounted workspace path so Astrograph can index files.
3. Start the container using your MCP tooling or run the docker command directly if you prefer to test locally.

If you prefer running Astrograph without Docker, you can install via Python (as shown in the README) and run the module directly:

pip install .
python -m astrograph.server

But the README primarily provides the Docker-based setup as the recommended path.

Tips and considerations:

• The Docker configuration mounts your project at /workspace inside the container and stores metadata in .metadata_astrograph. Ensure these paths are correct for your environment.
• The server reports its current version in serverInfo.version on connect, so you can track releases easily.
• Astrograph supports Python, JavaScript, TypeScript, and Go out of the box; other languages can attach language servers over TCP as described in the README.
• If you see performance issues on very large codebases, consider indexing in incremental passes or adjusting the workspace mount strategy to reduce I/O overhead.
• For Claude or Codex integration, follow the provided examples to configure the astrograph MCP server in their respective config files.