Next.js TypeScript Cartographer

An MCP tool for indexing your Next.js and TypeScript code to work with agents like Claude Code and Kiro.

Overview

Next.js TypeScript Cartographer solves a critical problem when AI agents work with complex TypeScript codebases: quickly locating code elements without expensive searches. When a user says "let's modify UserProfile", the AI agent can instantly find the exact location of the component definition instead of running multiple grep commands or bash scripts to hunt it down.

Goals

Primary Goals

• Instant Symbol Navigation: Jump to any class, function, interface, or component definition instantly.
• Deep Code Understanding: Provide rich metadata about symbols, including documentation (JSDoc) and source ranges.
• Zero Configuration: Work out of the box for standard Next.js and TypeScript projects.

Architecture

Next.js TypeScript Cartographer uses ts-morph for semantic code analysis:

• ts-morph integration: Uses the TypeScript Compiler API wrapper for full semantic understanding of TypeScript code.
• Project Loading: Loads tsconfig.json to understand project structure and dependencies.
• MCP Server: Built on the @modelcontextprotocol/sdk for Model Context Protocol support.
  • Async/await with Node.js
  • JSON Schema validation for tool parameters
  • Stdio transport for AI agent integration

Use Cases

1. AI-Assisted Development: Enable AI agents to navigate and modify code with surgical precision.
2. Code Navigation: Quick lookups for developers and tools.
3. Refactoring Support: Understand impact of changes across a codebase.
4. Documentation Generation: Extract and organize code documentation.

Current Implementation

The server provides two fully functional tools:

Tools

find_symbol

Find all occurrences of a TypeScript symbol (class, function, interface, variable, etc.) by name.

Features:

• Search modes: Exact, fuzzy (default), or prefix matching.
• Type filtering: Filter results to only type symbols (classes, interfaces, enums, type aliases).
• Rich metadata: Returns symbol name, kind, file path, line numbers, and documentation.

Example usage:

{
  "query": "UserProfile",
  "mode": "exact",
  "typesOnly": true
}

enumerate_file

List all symbols defined in a specific file.

Features:

• Returns all functions, methods, classes, interfaces, variables, and more.
• Provides symbol name, kind, line number ranges, and JSDoc documentation.
• Filters out irrelevant symbol kinds automatically.

Example usage:

{
  "filePath": "/absolute/path/to/components/UserProfile.tsx"
}

Implementation Details

• Semantic analysis: Uses ts-morph for accurate type information.
• Project loading: Automatically loads tsconfig.json.
• Symbol kinds: Supports Class, Method, Property, Function, Interface, Variable, TypeAlias, and Enum.

Running the Server

To install dependencies:

npm install

To run the server (communicates via stdio):

npm run mcp

Or:

npx tsx scripts/mcp-server.ts /path/to/project

Integration with AI Agents

To use Next.js TypeScript Cartographer with an MCP-compatible AI agent, add it to your MCP configuration.

For example, with Claude Code:

{
  "mcpServers": {
    "nextjs-cartographer": {
      "command": "npx",
      "args": ["-y", "tsx", "/path/to/next.js_typescript_cartographer/scripts/mcp-server.ts", "/path/to/target/project"]
    }
  }
}

Once configured, the AI agent will have access to the find_symbol and enumerate_file tools for navigating your codebase.