How shashankss1205/codegraphcontext works
Project type and purpose
• This is a full-stack developer tool: an MCP (Meta-Computation Protocol) server and CLI application that indexes Python code into a graph database (Neo4j) and exposes it via a JSON-RPC API for AI assistants and IDEs.
• The README highlights code indexing, relationship analysis, live updates (file watching), an interactive setup wizard, and a JSON-RPC server for queries.
File structure
Top-level directories and key files:
• src/codegraphcontext/cli: CLI entry points (main.py, setup_wizard.py)
• src/codegraphcontext/core: Core engine (database.py, jobs.py, watcher.py)
• src/codegraphcontext/tools: Code analysis and graph construction (code_finder.py, graph_builder.py, import_extractor.py, system.py)
• src/codegraphcontext/server.py: MCP/JSON-RPC server implementation
• src/codegraphcontext/prompts.py, utils/debug_log.py: helper modules
• pyproject.toml: build configuration and dependencies
• .github/workflows/test.yml: CI pipeline
• tests/: integration and unit tests
README for additional insights
• Architecture hints: MCP client/server, Neo4j backend, Watchdog for file watching, Typer for CLI, Requests for HTTP clients.
• Features: interactive setup (wizard), live updates (file watcher + background jobs), JSON-RPC API.
a. Main components:
1. CLI Layer
• Commands: cgc setup, cgc start, cgc watch, cgc index, etc.
• Implements interactive setup wizard, writes mcp.json, IDE config.
2. Core Engine
• jobs.py: orchestrates tasks (indexing, watching)
• watcher.py: uses Watchdog to detect FS changes
• tools: code_finder, import_extractor, graph_builder build the AST and graph data
• database.py: Neo4j driver wrapper, sessions, Cypher queries
3. MCP Server (server.py)
• JSON-RPC over HTTP
• Exposes methods: list_imports, add_code_to_graph, check_job_status, etc.
4. External Services
• Neo4j instance (local via Docker or remote)
• IDE/AI clients (VS Code, Claude, Gemini) acting as MCP clients
5. Configuration & State
• mcp.json, ~/.codegraphcontext/.env
• pyproject.toml, Docker compose (in wizard)
b. Relationships and interactions:
• User invokes CLI → CLI calls core.jobs or server.start
• jobs module uses tools to parse code → pushes nodes/edges to database module → Neo4j
• watcher monitors FS events → signals jobs to re-index changed files
• server listens for client requests → dispatches to tools/database
• clients communicate with server over JSON-RPC (HTTP/WebSocket)
c. Architectural patterns & principles:
• Layered architecture: Presentation (CLI), Application (core), Data (DB)
• Plugin-like tools: code analysis is modularized
• Event-driven updates: file watcher triggers new indexing jobs
• Client-server: MCP JSON-RPC interface
d. Technologies & frameworks:
• Typer for CLI
• Watchdog for file watching
• Neo4j Python driver for database access
• Requests for HTTP calls
• Rich/InquirerPy for wizard UI
• stdlibs for project introspection
• python-dotenv for env config
Elements
• Clear labels: “CLI (cgc)”, “Core Engine (jobs, watcher, tools)”, “Neo4j Database”, “MCP Server (JSON-RPC)”, “IDE/AI Clients”
• User → CLI
• CLI ↔ Core Engine
• Core Engine → Neo4j
• Watcher → Core Engine
• IDE Client → MCP Server → Core Engine → Neo4j
• Rectangles for software modules
• Parallelograms or clouds for external clients/services
Detailed capture of essential architectural elements
[User & IDE clients]
↓
[CLI layer] ←→ [MCP Server layer]
↓ ↓
[Core Engine: jobs, watcher, tools]
↓
[Database Module]
↓
(Neo4j instance)
• “Setup Wizard” as a sub-flow under CLI that writes config files and provisions Neo4j (Docker or remote).
• Interactions (e.g., “build graph via graph_builder”, “execute Cypher query”, “respond JSON-RPC”).