DeepGraph Next.js Server

Analyze Next.js project architecture, component relationships, and dependency graphs with deep code visualization powered by the DeepGraph MCP server.

When to Use This MCP Server

Connect this server when you need to:

• Understand complex Next.js application architecture by visualizing component hierarchies, page routing trees, and module dependency graphs
• Identify circular dependencies, unused components, and optimization opportunities in large Next.js codebases during refactoring work
• Map data flow patterns including server components, client components, and their prop-passing relationships across your Next.js application

Consider alternatives when:

• Your project uses Vue.js, React without Next.js, or another framework that has its own dedicated DeepGraph MCP server variant
• You need runtime performance profiling or bundle analysis rather than static code structure analysis, where browser DevTools or webpack-bundle-analyzer are more appropriate

Quick Start

Configuration

Copy
name: deepgraph-nextjs-server
type: mcp
category: deepgraph

Example Connection

Copy
claude mcp:connect deepgraph-nextjs-server

Available Tools

analyze-components:    Map all React components with their props, state, and import relationships
dependency-graph:      Generate a full dependency graph showing module interconnections
find-circular-deps:    Detect circular dependency chains that may cause build or runtime issues
route-tree:            Visualize the Next.js file-based routing structure with layouts and pages
component-usage:       Show where and how each component is used across the entire project

Core Concepts

DeepGraph Analysis Overview

Aspect	Details
Transport	stdio-based process via npx running mcp-code-graph against a Next.js project
Analysis Engine	Static AST parsing of JavaScript, TypeScript, JSX, and TSX source files
Scope	Covers pages, components, hooks, utilities, API routes, and middleware
Output Format	Structured graph data with nodes (modules) and edges (dependencies)
Framework Support	Next.js App Router, Pages Router, and hybrid configurations

DeepGraph Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [mcp-code-graph]
                              |
                              v
                     [AST Parser Engine]
                      /       |        \
               Pages/     Components/  Hooks/
               Routes      Modules     Utils
                      \       |        /
                    [Dependency Graph Builder]
                              |
                              v
                   [Graph Query Interface]
                   (Traversal & Analysis)

Configuration

Parameter	Type	Default	Description
project_path	string	cwd	Root directory of the Next.js project to analyze
include_node_modules	boolean	false	Include node_modules in dependency analysis for full external dep mapping
max_depth	integer	10	Maximum dependency chain depth to traverse before stopping
file_patterns	string[]	[.ts,.tsx,.js,.jsx]	File glob patterns to include in the analysis scope
ignore_patterns	string[]	[.test.,.spec.]	File glob patterns to exclude from analysis results

Best Practices

1. Run Analysis Before Major Refactors - Generate a full dependency graph before restructuring components or moving files. Understanding existing import relationships prevents breaking changes and reveals the true impact radius of your refactoring work.

2. Check for Circular Dependencies Regularly - Use find-circular-deps as part of your development routine. Circular dependencies in Next.js can cause subtle issues with server-side rendering, hot module replacement, and tree shaking that are difficult to debug later.

3. Map Server vs Client Component Boundaries - Use component-usage to identify where "use client" boundaries exist in your App Router project. Understanding these boundaries helps optimize your bundle by keeping as much logic as possible in server components.

4. Analyze Route Trees After Adding Pages - After adding new pages or route groups, run route-tree to verify the routing structure matches your expectations. Nested layouts, parallel routes, and intercepting routes can produce unexpected hierarchies.

Common Issues

1. Analysis Timeout on Large Projects - Projects with thousands of files may cause the analyzer to time out. Narrow the scope by configuring file_patterns to target specific directories, or increase the timeout in your MCP client configuration.

2. Missing Components in Graph - Files using non-standard extensions or dynamic imports may not appear in the static analysis. Ensure file_patterns includes all relevant extensions, and check that dynamic import paths are resolvable at parse time.

3. Incorrect Route Tree for App Router - If your project mixes App Router and Pages Router, the route-tree tool may show overlapping routes. Specify which router directory to analyze by adjusting the project_path to point at the app or pages directory specifically.