file rank mcp

A TypeScript-based tool for ranking files in your codebase by importance and providing summaries with dependency tracking.

Overview

This tool helps you keep track of which files in your project are most important, giving them a rating between 0 (least important) to 10 (most important). It also tracks file dependencies and provides summaries, helping you understand the codebase structure.

Features

• Rank files on a scale from 0-10 (10 being most important)
• Track and visualize file dependencies (which files import which)
• Real-time file system monitoring for automatic updates
• Get summaries of files (with placeholder for LLM integration)
• Query rankings for individual files, directories, or the entire codebase
• Self-documenting API with discovery endpoints
• Simple stdio JSON interface

Setup

1. Clone this repository
2. Make the build script executable:

   chmod +x build.sh

3. Run the build script:

   ./build.sh

   This will:
4. Check for Node.js installation
5. Install project dependencies
6. Compile TypeScript code
7. Generate MCP configuration

8. Create a detailed log file in /tmp/file-rank-mcp_*.log

9. Move the generated mcp.json to your project's .cursor/ directory to use with Cursor AI

Usage

The tool communicates via JSON over stdio using the Model Context Protocol (MCP). It automatically monitors your project directory for changes and updates the file tree accordingly.

Running the Server

node dist/mcp-server.js

Supported Languages

The server automatically detects dependencies in the following languages: - Python: import and from ... import statements - C/C++: #include directives - Rust: use and mod statements - Lua: require statements - JavaScript/TypeScript: import statements

How It Works

The tool maintains a real-time tree structure of your codebase, stored in file-tree.json. This file is automatically updated whenever changes are detected in your project directory.

Data Structure

The file tree is stored in a JSON structure:

{
  "path": "/path/to/directory",
  "name": "directory_name",
  "isDirectory": true,
  "children": [
    {
      "path": "/path/to/file.ts",
      "name": "file.ts",
      "isDirectory": false,
      "dependencies": ["/path/to/dependency.ts"],
      "importance": 8
    }
  ]
}

Dependency Detection

The tool analyzes source code to detect dependencies: - Scans file contents for language-specific import patterns - Resolves relative imports to absolute paths - Verifies that imported files exist - Calculates importance based on dependency count

File Importance Calculation

Files are assigned importance scores (0-10) based on: - Number of dependencies (files that import this file) - Position in the dependency tree - File type and location

Technical Stack

• TypeScript/Node.js
• Model Context Protocol SDK (v1.7.0)
• Chokidar for file system monitoring
• ES2020 target with CommonJS modules

Development

To modify or extend the project:

1. Make changes to the TypeScript files in the src directory

2. Run the build script to compile and update configuration:

   ./build.sh

3. Run the server:

   node dist/mcp-server.js

The build script will: - Install any new dependencies - Compile TypeScript code - Generate updated MCP configuration - Create a detailed log file for troubleshooting

Integration with LLMs

The current implementation includes a placeholder for LLM integration. In a production environment, the server could be extended to: - Generate file summaries using LLMs - Analyze code complexity and maintainability - Provide intelligent suggestions for file organization - Generate documentation based on code structure

License

This project is licensed under the GNU General Public License v3 (GPL-3.0). See the LICENSE file for the full license text.