CodeNav MCP

CodeNav MCP is a remote Model Context Protocol server for exploring a codebase. It runs on Cloudflare Workers through agents/mcp and exposes tools that let an MCP client list files, read source, search text, inspect imports and exports, find functions and classes, detect likely unused code, and summarize project structure.

The server endpoint is:

/mcp

What This Project Does

This project turns a repository into a set of MCP tools. A connected client can ask questions like:

• What files are in this project?
• Read src/index.ts.
• Search for every TODO.
• Find exported functions.
• Show imports for one file.
• Count file types.
• Find files that are not reachable from known entrypoints.

The tools return JSON as MCP text content, so clients can display it directly or parse it for follow-up calls.

Project Layout

src/
  index.ts      MCP server entrypoint and tool registration
  schema.ts     Zod input schemas shared by registered tools
  tools.ts      Public tool implementations
  utils.ts      Filesystem walking, parsing, search, and helper logic
  types.ts      Shared TypeScript result and option types
  constants.ts  Supported extensions, ignored folders, and default entrypoints

Bit by bit:

1. src/index.ts creates the CodeNav MCP server and registers every tool with this.server.registerTool(...).
2. src/schema.ts defines reusable Zod schemas for common options like rootDir, includeExtensions, and excludeDirs.
3. src/tools.ts contains the functions that do the actual work. Each exported function maps to one MCP tool.
4. src/utils.ts contains lower-level helpers for path safety, directory walking, AST parsing, import resolution, search, and result formatting.
5. src/types.ts keeps result shapes explicit, such as FileReadResult, ImportInfo, FunctionInfo, and TodoInfo.
6. src/constants.ts defines what file extensions are understood and which directories are ignored by default.

Requirements

• Node.js
• npm
• A Cloudflare account if you want to deploy
• An MCP client such as Claude Desktop, Cursor, Windsurf, or Cloudflare AI Playground

Install dependencies:

npm install

Development Commands

npm run dev

Starts the local Wrangler dev server.

npm run type-check

Runs TypeScript without emitting files.

npm run format

Formats the project with oxfmt.

npm run lint:fix

Runs oxlint and applies automatic fixes.

npm run deploy

Deploys the Worker with Wrangler.

Running Locally For Filesystem Tools

Use the local Node.js stdio server when you want CodeNav to inspect the files in this repository:

npm run mcp:local

MCP clients usually start this command for you from their config. The local entrypoint is src/local.ts, and it has normal Node.js access to the workspace filesystem.

Running The Worker

Start the server:

npm run dev

Wrangler usually serves the Worker at:

http://localhost:8787/mcp

If Wrangler chooses a different port, use the URL printed in the terminal.

Important: Cloudflare Workers do not provide a readable local filesystem. If you call a CodeNav tool that needs fs through the Worker endpoint, the server returns a clear MCP error instead of the lower-level [unenv] fs.readdir is not implemented yet! runtime error.

Connecting Claude Desktop

For local code navigation, point Claude Desktop at the Node.js stdio entrypoint.

Example Claude Desktop config:

{
	"mcpServers": {
		"codenav": {
			"command": "npm",
			"args": ["run", "mcp:local"],
			"cwd": "/Users/chukwudi/Documents/codenav-mcp"
		}
	}
}

After saving the config, restart Claude Desktop. The CodeNav tools should appear under the codenav server.

Connecting VS Code

VS Code can use a workspace-level MCP config. This repo includes:

.vscode/mcp.json

The config points VS Code at the local Node.js stdio server:

{
	"servers": {
		"codenav-mcp": {
			"command": "npm",
			"args": ["run", "mcp:local"]
		}
	}
}

To use it:

1. Open this repository in VS Code.
2. Make sure dependencies are installed with npm install.
3. Use VS Code's MCP server controls to start or refresh the codenav-mcp server.

If you specifically want VS Code to connect to the Worker endpoint instead, use mcp-remote:

{
	"servers": {
		"codenav-mcp": {
			"command": "npx",
			"args": ["mcp-remote", "http://localhost:8787/mcp"]
		}
	}
}

The Worker connection is useful for testing the remote MCP transport, but it cannot read local project files.

Deploying

Deploy to Cloudflare Workers:

npm run deploy

After deployment, your MCP endpoint will look like:

https://<worker-name>.<account-subdomain>.workers.dev/mcp

Use that deployed /mcp URL in any remote MCP client.

Common Tool Options

Most tools accept one or more shared options.

Option	Type	Meaning
rootDir	string	Project root to inspect. Defaults to process.cwd().
includeExtensions	string[]	Restrict scanning to specific extensions, such as [".ts", ".tsx"].
excludeDirs	string[]	Extra directory names to skip.
recursive	boolean	Whether to walk nested directories. Defaults to recursive behavior in most scan tools.
includeHidden	boolean	Include dotfiles and dot-directories. Defaults to hidden paths being skipped in directory walks.
maxResults	number	Limit search-style result counts. Defaults to 100 where supported.
maxBytes	number	Limit file read size. Defaults to 256000 bytes for file reads.

Paths are resolved inside rootDir. If a requested path tries to escape the root, the server returns an MCP error result.

Default Ignored Directories

Directory walks skip these folders by default:

.git
.next
.turbo
build
coverage
dist
node_modules

Add more ignored directory names with excludeDirs.

Supported Extensions

General code reading and searching support:

.cjs, .css, .cts, .go, .html, .js, .jsx, .json, .mjs,
.mts, .py, .svelte, .ts, .tsx, .vue

Import graph analysis focuses on importable source files:

.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs, .go, .json, .py

TypeScript-family files are parsed with the TypeScript compiler API. Go and Python have lightweight parser support for imports and function declarations.

Registered Tools

list_files

Lists files under a directory.

Input:

{
	"directoryPath": ".",
	"recursive": true,
	"includeExtensions": [".ts"]
}

Returns file path, absolute path, size, and extension.

list_directories

Lists directories under a directory.

Input:

{
	"directoryPath": "src",
	"recursive": true
}

Returns project-relative and absolute directory paths.

get_project_tree

Returns a nested tree for a directory.

Input:

{
	"directoryPath": ".",
	"maxDepth": 3
}

Returns nodes with name, path, type, and optional children.

find_file

Finds files by basename or project-relative path.

Input:

{
	"query": "utils",
	"maxResults": 10
}

Set exact: true to require an exact basename or path match.

read_file

Reads a file as text.

Input:

{
	"filePath": "src/index.ts",
	"maxBytes": 12000
}

Returns path, absolute path, size, truncation status, and content.

read_file_range

Reads a 1-based line range from a file.

Input:

{
	"filePath": "src/index.ts",
	"startLine": 1,
	"endLine": 80
}

Use this when a full file read would be too large.

read_multiple_files

Reads multiple files in one call.

Input:

{
	"filePaths": ["src/index.ts", "src/tools.ts"],
	"maxBytes": 20000
}

Returns an array of file read results.

read_code

Reads a supported code file and adds language metadata.

Input:

{
	"filePath": "src/tools.ts"
}

Returns the normal file content plus language and lineCount.

search_text

Searches code files for plain text.

Input:

{
	"query": "registerJsonTool",
	"caseSensitive": false,
	"maxResults": 20
}

Returns file, line, column, line text, and matched text.

search_regex

Searches code files using a regular expression.

Input:

{
	"pattern": "export async function \\w+",
	"flags": "i",
	"maxResults": 20
}

The implementation adds the global flag when it is missing.

find_imports

Finds imports in one file or across the project.

Input:

{
	"filePath": "src/index.ts"
}

If filePath is omitted, the tool scans supported project source files. Results include import specifier, kind, imported names, resolved project path when local, line, and column.

find_exports

Finds exports in one file or across the project.

Input:

{
	"filePath": "src/tools.ts"
}

Detects common TypeScript/JavaScript export forms and Python __all__ entries.

find_functions

Finds functions and methods.

Input:

{
	"filePath": "src/tools.ts",
	"includeClasses": false
}

Returns name, file, line, column, export status, and declaration kind.

find_classes

Finds class declarations.

Input:

{
	"filePath": "src/index.ts"
}

Returns the class subset of function declaration results.

find_unused_functions

Finds functions that appear unused inside the scanned project.

Input:

{
	"includeExported": false
}

By default, exported declarations are ignored because they may be used outside the local project. This is a static heuristic, so review results before deleting code.

find_unused_files

Finds source files that are not reachable from entrypoints.

Input:

{
	"entrypoints": ["src/index.ts"]
}

If entrypoints is omitted, the tool tries common defaults such as src/index.ts, src/main.ts, main.py, and __main__.py, plus package.json main and bin entries.

find_todos

Finds TODO-style comments.

Input:

{
	"tags": ["TODO", "FIXME"],
	"maxResults": 50
}

Supported tags are TODO, FIXME, HACK, and NOTE.

get_file_metadata

Gets filesystem metadata for a file or directory.

Input:

{
	"filePath": "src/index.ts"
}

Returns size, extension, created time, modified time, and file/directory booleans.

find_entry_points

Finds likely project entrypoints.

Input:

{}

Uses default entrypoint names and package.json fields where available.

count_file_types

Counts files by extension.

Input:

{
	"recursive": true
}

Returns extensions sorted by count, then by extension name.

Result Shape

Every tool returns an MCP result like this:

{
	"content": [
		{
			"type": "text",
			"text": "{ ...pretty printed JSON... }"
		}
	]
}

When a tool fails, the server returns:

{
	"isError": true,
	"content": [
		{
			"type": "text",
			"text": "Error message"
		}
	]
}

Safety Notes

• Tool paths are resolved relative to rootDir.
• Paths that escape rootDir are rejected.
• Directory walks skip common generated and dependency folders by default.
• File reads are truncated by maxBytes.
• Unused code detection is heuristic and should be treated as a review aid, not an automatic deletion signal.

Extending The Server

To add a new tool:

1. Add the implementation to src/tools.ts.
2. Add or reuse input schemas from src/schema.ts.
3. Register it in src/register-tools.ts with registerJsonTool.
4. Add any new result types to src/types.ts.
5. Run npm run type-check.

Example registration:

this.registerJsonTool(
	"tool_name",
	"Short description.",
	{
		filePath: z.string(),
		...projectOptions,
	},
	({ filePath, ...options }) => tools.someTool(filePath as string, options),
);

Current Package Scripts

The package currently exposes:

{
	"deploy": "wrangler deploy",
	"dev": "wrangler dev",
	"format": "oxfmt --write .",
	"lint:fix": "oxlint --fix",
	"start": "wrangler dev",
	"cf-typegen": "wrangler types",
	"type-check": "tsc --noEmit"
}

Quick Usage Flow

1. Start the Worker with npm run dev.
2. Connect an MCP client to http://localhost:8787/mcp.
3. Call get_project_tree to understand the repository shape.
4. Use find_file or search_text to locate code.
5. Use read_file_range or read_code to inspect specific files.
6. Use find_imports, find_exports, find_functions, and find_classes for code intelligence.
7. Use find_unused_functions, find_unused_files, and find_todos for review work.