thaylo/astrograph repository overview

⁠ASTrograph

    █ █ █
  █ █ █ █ █
  █       █
  █ █ █ █ █
    █ █ █
  █ █   █ █
  █       █

Stop writing code that already exists in your codebase.

ASTrograph is an MCP server that detects when you're about to create duplicate code - and blocks it before it happens.

⁠See It In Action

Your codebase already has this:

# src/math.py
def calculate_sum(a, b):
    return a + b

Your AI agent tries to write this:

# src/utils.py
def add_numbers(x, y):
    return x + y

ASTrograph intercepts and blocks:

BLOCKED: Cannot write - identical code exists at src/math.py:calculate_sum (lines 1-2).
Reuse the existing implementation instead.

Different variable names, same structure. ASTrograph compares code graphs, not text.

⁠Quick Start

Add .mcp.json to your project root:

{
  "mcpServers": {
    "astrograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--pull", "always",
        "-v", ".:/workspace",
        "thaylo/astrograph"
      ]
    }
  }
}

The codebase is auto-indexed when the Docker container starts. Then:

1. astrograph_analyze() - Find existing duplicates
2. Use astrograph_write / astrograph_edit - They'll block duplicates automatically

⁠The Problem

Large codebases accumulate duplicate code because:

• AI agents have limited context windows → they can't see all existing code → they rewrite what exists → duplicates inflate the codebase → smaller % of codebase fits in context → more duplicates (vicious cycle)
• Developers can't remember every function they wrote 6 months ago
• Similar patterns get reimplemented independently
• Copy-paste spreads bugs across multiple locations

⁠Key Tools

See all 8 tools →⁠

⁠Works With

• Claude Code - Tested. Project-level .mcp.json
• Any MCP client - Should work (standard stdio protocol), but untested

⁠Tool Reference

⁠Configuration Examples

{
  "mcpServers": {
    "astrograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--pull", "always",
        "-v", "/path/to/your/project:/workspace",
        "-v", "/path/to/your/project/.metadata_astrograph:/workspace/.metadata_astrograph",
        "thaylo/astrograph"
      ]
    }
  }
}

{
  "mcpServers": {
    "astrograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--pull", "always",
        "-v", "${workspaceFolder}:/workspace",
        "-v", "${workspaceFolder}/.metadata_astrograph:/workspace/.metadata_astrograph",
        "thaylo/astrograph"
      ]
    }
  }
}

{
  "mcpServers": {
    "astrograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--pull", "always",
        "-v", ".:/workspace",
        "-v", "./.metadata_astrograph:/workspace/.metadata_astrograph",
        "thaylo/astrograph"
      ]
    }
  }
}

pip install -e .

{
  "mcpServers": {
    "astrograph": {
      "command": "python",
      "args": ["-m", "astrograph.server"],
      "cwd": "/path/to/astrograph"
    }
  }
}

⁠How It Works

Python Source → AST Parser → Graph → WL Hash → Index Lookup → Match

⁠Development

pip install -e ".[dev]"
pytest tests/ -q
docker build -t astrograph .

⁠License

MIT