project-graph-mcp: graf dla nawigacji AI

project-graph-mcp: graf zależności do nawigacji agentów AI w kodzie

Systemy wieloagentowe w rozwoju oprogramowania wymagają precyzyjnej nawigacji po bazie kodu. Serwer project-graph-mcp oferuje interfejs MCP do budowy grafu zależności, skompresowanego do minimalnego formatu JSON. Pozwala to agentom zrozumieć architekturę projektu bez zużywania tokenów na analizę źródeł.

Serwer przetwarza pliki, wyodrębnia klasy, metody i importy, zwracając strukturę z kompresją 10–50 razy. Obsługa JavaScript, TypeScript, Python i Go umożliwia pracę z projektami wielojęzycznymi.

Szkielet projektu w skompresowanym formacie

Główną funkcją jest generowanie "szkieletu" projektu. Parser skanuje źródła i tworzy JSON z legendą, statystyką oraz grafem węzłów.

Przykład wyjścia:

{
  "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
  "s": { "files": 23, "classes": 10, "functions": 65 },
  "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
  "e": 35, "o": 7, "d": 5, "F": 63
}

• L — legenda skrótów nazw
• s — statystyka (pliki, klasy, funkcje)
• n — węzły z metodami (m) i właściwościami ($)
• e, o, d, F — krawędzie, obiekty, katalogi, pliki

Do szczegółowego rozszerzenia dostępne są metody expand i deps, które rozwijają graf na żądanie.

Wielojęzyczna analiza bez AST

Początkowo używano Acorn dla JavaScript. W wersji 1.1 dodano parsery dla TypeScript, Python i Go oparte na wyrażeniach regularnych. To rozwiązanie eliminuje zależności zewnętrzne i uwzględnia specyfikę języków.

Uniwersalna funkcja stripStringsAndComments czyści kod z napisów i komentarzy:

// Python
stripStringsAndComments(code, { tripleQuote: true, hashComment: true })

// Go
stripStringsAndComments(code, { backtick: true, templateInterpolation: false })

// TypeScript (domyślne)
stripStringsAndComments(code)

Wszystkie parserzy są zintegrowane pod wspólny typ ParseResult: klasy, funkcje, importy, wywołania. Wyrażenia regularne można dostosować do stylu projektu.

Analiza kodu i wskaźnik zdrowia

Serwer zawiera metryki jakości:

• get_dead_code — wyszukiwanie nieużywanego kodu
• get_complexity — złożoność cyklomatyczna
• get_large_files — pliki do refaktoryzacji
• get_call_chain — łańcuchy wywołań (authMiddleware → validateToken → renderDashboard)

Polecenia:

# Uprawnienia i zależności
npx project-graph-mcp outdated .

# Złożoność
npx project-graph-mcp complexity src/

Wyniki agregowane są w wskaźniku zdrowia (0–100). Podpowiedzi odpowiedzi sugerują kolejne kroki, np. sprawdzenie złożoności funkcji.

Testy w formie checklisty przez JSDoc

Obsługa adnotacji @test i @expect do dokumentowania testów:

/**
 * Tworzy nowego użytkownika przez API
 * 
 * @test request: POST /api/users z danymi ważnymi
 * @expect status: 201 Created
 */
async createUser(data) { ... }

• get_pending_tests — lista niezakończonych testów
• mark_test_passed — oznaczenie przejścia testu

Obsługa testów API, CLI, integracyjnych i przeglądarkowych.

Dostosowanie do frameworków

Wbudowanych 11 zestawów reguł (86 reguł) dla React 18/19, Vue 3, Express 5, TypeScript 5, Symbiote.js. Automatyczne rozpoznawanie projektu przez get_framework_reference.

Dla niestandardowych konwencji:

• Dodaj do katalogu rules/
• Użyj set_custom_rule od agenta

Integracja z pulą agentów

W orchestracji fraktalnej IDE-agent pobiera szkielet i deleguje zadania workerom (Gemini itp.). Każdy worker uruchamia lokalny MCP do nawigacji przez expand/deps.

Pakiet 132 KB, bez zależności zewnętrznych. Konfiguracja dla VS Code, Cursor, Zed:

{
  "mcpServers": {
    "project-graph": {
      "command": "npx",
      "args": ["-y", "project-graph-mcp"]
    }
  }
}

Bezpieczeństwo i ochrona przed przejściem ścieżek

Weryfikacja ścieżek przez resolve + startsWith ogranicza dostęp do katalogu roboczego. Metody expand, deps, get_skeleton dziedziczą ochronę — żądanie ../../etc/passwd zwróci błąd.

Co ważne:

• Skompresowany graf zależności przyspiesza nawigację agentów AI
• Parserzy regex dla JS/TS/Python/Go bez bibliotek zewnętrznych
• Wskaźnik zdrowia i łańcuchy wywołań do refaktoryzacji
• Checklisty JSDoc automatyzują testowanie
• 86 reguł dla popularnych frameworków gotowe do użycia

— Editorial Team