project-graph-mcp: graf pro AI-navigaci

project-graph-mcp: graf závislostí pro navigaci AI agentů v kódu

Multiagentní systémy pro vývoj vyžadují přesnou navigaci v kódové bázi. Server project-graph-mcp poskytuje MCP rozhraní pro vytváření grafu závislostí, komprimovaného do minimalizovaného JSON. Díky tomu mohou agenty pochopit architekturu projektu bez zbytečného spotřebování tokenů na parsování zdrojových souborů.

Server analyzuje soubory, extrahuje třídy, metody, importy a vrátí strukturu s kompresí 10–50×. Podpora JavaScriptu, TypeScriptu, Pythonu a Go umožňuje práci s vícejazyčnými projekty.

Skeleton projektu ve zkomprimovaném formátu

Hlavní funkcí je generování "skeletu" projektu. Parser skenuje zdrojový kód a vytváří JSON s legendou, statistikou a grafem uzlů.

Příklad výstupu:

{
  "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 zkratek jmen
• s — statistika (soubory, třídy, funkce)
• n — uzly s metodami (m) a vlastnostmi ($)
• e, o, d, F — hrany, objekty, adresáře, soubory

Pro podrobnější informace jsou k dispozici metody expand a deps, které graf na vyžádání rozšiřují.

Vícejazyčné parsování bez AST

Původně byl použit Acorn pro JavaScript. Ve verzi 1.1 byly přidány parsery pro TypeScript, Python a Go na základě regulárních výrazů. Toto řešení vyhýbá se externím závislostem a bere v úvahu jazykové specifika.

Univerzální utilita stripStringsAndComments čistí kód od řetězců a komentářů:

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

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

// TypeScript (výchozí)
stripStringsAndComments(code)

Všechny parsery jsou unifikovány pod ParseResult: třídy, funkce, importy, volání. Regulární výrazy lze přizpůsobit stylu projektu.

Analýza kódu a Health Score

Server obsahuje metriky kvality:

• get_dead_code — hledání nevyužitého kódu
• get_complexity — cyklomatická složitost
• get_large_files — soubory vhodné pro refaktoring
• get_call_chain — řetězce volání (authMiddleware → validateToken → renderDashboard)

Příkazy:

# Zastaralé závislosti
npx project-graph-mcp outdated .

# Složitost
npx project-graph-mcp complexity src/

Výsledky jsou agregovány do Health Score (0–100). Response Hints navrhuje další kroky, např. kontrolu složitosti funkce.

Testovací check-listy prostřednictvím JSDoc

Podpora anotací @test a @expect pro dokumentaci testů:

/**
 * Vytvoří nového uživatele přes API
 * 
 * @test request: POST /api/users s platnými daty
 * @expect status: 201 Created
 */
async createUser(data) { ... }

• get_pending_tests — seznam neprovedených testů
• mark_test_passed — označení úspěšného průchodu

Podporovány API, CLI, integracní a prohlížečové testy.

Přizpůsobení pro frameworky

V zabudovaných 11 sadách pravidel (86 pravidel) pro React 18/19, Vue 3, Express 5, TypeScript 5, Symbiote.js. Automatické rozpoznání projektu prostřednictvím get_framework_reference.

Pro vlastní konvence:

• Přidání do složky rules/
• Použití set_custom_rule od agenta

Integrace s agentovým poolem

V fraktální orchestraci IDE-agent získá skelet a deleguje úkoly pracovníkům (Gemini atd.). Každý pracovník spustí lokální MCP pro navigaci pomocí expand/deps.

Balíček 132 kB, bez externích závislostí. Konfigurace pro VS Code, Cursor, Zed:

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

Bezpečnost a ochrana proti traversalu cest

Ověření cest prostřednictvím resolve + startsWith omezuje přístup pouze pracovním adresářem. Metody expand, deps, get_skeleton dědí ochranu – požadavek ../../etc/passwd vrátí chybu.

Důležité:

• Komprimovaný graf závislostí urychlí navigaci AI agentů
• Regex parsery pro JS/TS/Python/Go bez externích knihoven
• Health Score a řetězce volání pro refaktoring
• JSDoc check-listy automatizují testování
• 86 pravidel pro oblíbené frameworky z krabice

— Editorial Team