# 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:

```text
/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

```text
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:

```bash
npm install
```

## Development Commands

```bash
npm run dev
```

Starts the local Wrangler dev server.

```bash
npm run type-check
```

Runs TypeScript without emitting files.

```bash
npm run format
```

Formats the project with `oxfmt`.

```bash
npm run lint:fix
```

Runs `oxlint` and applies automatic fixes.

```bash
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:

```bash
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:

```bash
npm run dev
```

Wrangler usually serves the Worker at:

```text
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:

```json
{
	"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:

```text
.vscode/mcp.json
```

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

```json
{
	"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`:

```json
{
	"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:

```bash
npm run deploy
```

After deployment, your MCP endpoint will look like:

```text
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:

```text
.git
.next
.turbo
build
coverage
dist
node_modules
```

Add more ignored directory names with `excludeDirs`.

## Supported Extensions

General code reading and searching support:

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

Import graph analysis focuses on importable source files:

```text
.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:

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

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

### `list_directories`

Lists directories under a directory.

Input:

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

Returns project-relative and absolute directory paths.

### `get_project_tree`

Returns a nested tree for a directory.

Input:

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

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

### `find_file`

Finds files by basename or project-relative path.

Input:

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

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

### `read_file`

Reads a file as text.

Input:

```json
{
	"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:

```json
{
	"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:

```json
{
	"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:

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

Returns the normal file content plus `language` and `lineCount`.

### `search_text`

Searches code files for plain text.

Input:

```json
{
	"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:

```json
{
	"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:

```json
{
	"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:

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

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

### `find_functions`

Finds functions and methods.

Input:

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

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

### `find_classes`

Finds class declarations.

Input:

```json
{
	"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:

```json
{
	"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:

```json
{
	"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:

```json
{
	"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:

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

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

### `find_entry_points`

Finds likely project entrypoints.

Input:

```json
{}
```

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

### `count_file_types`

Counts files by extension.

Input:

```json
{
	"recursive": true
}
```

Returns extensions sorted by count, then by extension name.

## Result Shape

Every tool returns an MCP result like this:

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

When a tool fails, the server returns:

```json
{
	"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:

```ts
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:

```json
{
	"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.