File Context MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with the ability to read local folder files and use them for context to query and ask questions about file data.

Features

This MCP server provides four powerful tools for file system interaction:

🔧 Available Tools

1. read_file - Read the contents of any file from the local filesystem

   • Input: path (string) - The path to the file to read

   • Returns: File content as text

2. list_directory - List all files and directories in a given directory

   • Input: path (string) - The path to the directory to list

   • Returns: Formatted list with file/directory indicators and sizes

3. search_files - Search for files by name pattern in a directory tree

   • Input: rootPath (string), pattern (string) - Root directory and search pattern

   • Returns: List of matching file paths

4. analyze_folder - Get comprehensive analysis of folder structure

   • Input: path (string) - The path to the folder to analyze

   • Returns: Detailed analysis including file types, sizes, and directory structure

Quick Start

1. Install Dependencies

2. Configure Claude API Key

Set your Anthropic/Claude API key as an environment variable. Create a .env.local file in the project root:

Note: This project works exclusively with Anthropic's Claude API. You'll need an API key from Anthropic. OpenAI keys are not supported.

Alternatively, you can set the environment variable directly:

⚠️ Security Note: The .env.local file is automatically ignored by git to keep your API key secure. If no API key is found, the application will automatically run in mock mode for development.

3. Build the Project

4. Run Tests

5. Test the Server

Interactive Web UI (Recommended)

Then open http://localhost:3000 in your browser for a full interactive interface!

Command Line Interface

Interface Options

This project includes multiple ways to interact with your files:

🎨 Interactive Web UI (New!)

Open http://localhost:3000 in your browser for a modern, interactive interface featuring:

• 🗂️ File Operations Panel: Direct access to read, list, search, and analyze tools

• 💬 AI Chat Assistant: Natural language file queries with intelligent command detection

• 📊 Real-time Results: Live display of file operations and responses

• 📱 Responsive Design: Works on desktop, tablet, and mobile devices

• ⌨️ Keyboard Shortcuts: Ctrl/Cmd+K to focus chat, Enter to send messages

💬 Chat Interface Options

🌐 Terminal Chat Interface (requires network & API key)

🎭 Mock Mode (no network required)

Perfect for corporate environments or testing:

Mock mode features:

• ✅ Full file system access (read, list, search)

• ✅ Realistic AI-like responses

• ✅ No network calls or API keys needed

• ✅ Perfect for demos and corporate networks

• ✅ Automatic fallback when API fails

🦙 Local AI (Ollama integration)

Testing

This project includes comprehensive test coverage using Jest and TypeScript:

🧪 Test Categories

• Unit Tests: Core file operations (read, list, search, analyze)

• Integration Tests: MCP server functionality and tool interactions

• Mock Tests: Chat interface with simulated Claude responses

• Error Handling: Edge cases, permissions, and network failures

• Performance Tests: Large directories and concurrent operations

📊 Test Coverage

Current coverage: >90% of core functionality

🚀 Running Tests

✅ Test Features

• Isolated test environments with temporary directories

• Mocked external dependencies (API calls, file system)

• Cross-platform compatibility testing

• Security validation (path traversal, permissions)

• Performance benchmarks

Usage with MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

VS Code Configuration

The project includes a .vscode/mcp.json file for VS Code MCP integration:

Example Use Cases

🎨 Web UI Examples

The interactive web interface supports both direct tool usage and natural language:

Direct Operations:

• Use the file operation panels to read, list, search, and analyze files

• Real-time results display with syntax highlighting

• Chat assistant for natural language queries

Natural Language Chat:

• "What files are in the current directory?"

• "Read the package.json file"

• "Search for all .ts files in the src folder"

• "Analyze this project structure"

• "Show me the contents of README.md"

📖 Reading Project Files

"Can you read the package.json file and tell me about the project dependencies?"

🔍 Analyzing Codebases

"Analyze the src directory and give me an overview of the project structure"

🔎 Finding Specific Files

"Search for all TypeScript files that contain 'interface' in the filename"

📊 Project Analysis

"Analyze this entire project folder and tell me what kind of application this is"

Security Features

• Path Resolution: All file paths are resolved to prevent directory traversal attacks

• Access Checks: Files and directories are checked for read permissions before access

• Limited Recursion: Directory analysis limits depth to prevent infinite loops

• Hidden File Filtering: Skips hidden directories and node_modules in recursive operations

Development

Project Structure

Available Scripts

• npm run build - Compile TypeScript to JavaScript

• npm run dev - Watch mode compilation

• npm start - Run the compiled server

Testing the Server

You can test the server using the MCP Inspector:

Technical Details

• Protocol: Model Context Protocol (MCP)

• Transport: STDIO (Standard Input/Output)

• Language: TypeScript/Node.js

• SDK: @modelcontextprotocol/sdk

Requirements

• Node.js 16+

• TypeScript 5+

• Model Context Protocol compatible client (Claude Desktop, VS Code, etc.)

License

MIT

Need Help? Check out the Model Context Protocol documentation for more information about MCP and how to integrate it with different clients.