File Context Server

A Model Context Protocol (MCP) server that provides file system context to Large Language Models (LLMs). This server enables LLMs to read, search, and analyze code files with advanced caching and real-time file watching capabilities.

Features

File Operations
- Read file and directory contents
- List files with detailed metadata
- Real-time file watching and cache invalidation
- Support for multiple file encodings
- Recursive directory traversal
- File type filtering
Code Analysis
- Cyclomatic complexity calculation
- Dependency extraction
- Comment analysis
- Quality metrics:
  - Duplicate lines detection
  - Long lines detection (>100 characters)
  - Complex function identification
  - Line counts (total, non-empty, comments)
Smart Caching
- LRU (Least Recently Used) caching strategy
- Automatic cache invalidation on file changes
- Size-aware caching with configurable limits
- Cache statistics and performance metrics
- Last read result caching for efficient searches
Advanced Search
- Regex pattern matching
- Context-aware results with configurable surrounding lines
- File type filtering
- Multi-pattern search support
- Cached result searching
- Exclusion patterns

Installation

Installing via Smithery

To install File Context Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @bsmi021/mcp-file-context-server --client claude

Manual Installation

npm install @modelcontextprotocol/file-context-server

Usage

Starting the Server

npx file-context-server

Available Tools

list_context_files

Lists files in a directory with detailed metadata

{
  "path": "./src",
  "recursive": true,
  "includeHidden": false
}

read_context

Reads file or directory contents with metadata

{
  "path": "./src/index.ts",
  "encoding": "utf8",
  "maxSize": 1000000,
  "recursive": true,
  "fileTypes": ["ts", "js"]
}

search_context

Searches for patterns in files with context

{
  "pattern": "function.*",
  "path": "./src",
  "options": {
    "recursive": true,
    "contextLines": 2,
    "fileTypes": ["ts"]
  }
}

analyze_code

Analyzes code files for quality metrics

{
  "path": "./src",
  "recursive": true,
  "metrics": ["complexity", "dependencies", "quality"]
}

cache_stats
- Gets cache statistics and performance metrics
```
{
  "detailed": true
}
```

Error Handling

The server provides detailed error messages with specific error codes:

FILE_NOT_FOUND: File or directory does not exist
PERMISSION_DENIED: Access permission issues
INVALID_PATH: Invalid file path format
FILE_TOO_LARGE: File exceeds size limit
ENCODING_ERROR: File encoding issues
UNKNOWN_ERROR: Unexpected errors

Configuration

Environment variables for customization:

MAX_CACHE_SIZE: Maximum number of cached entries (default: 1000)
CACHE_TTL: Cache time-to-live in milliseconds (default: 1 hour)
MAX_FILE_SIZE: Maximum file size in bytes for reading

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Start in development mode
npm run dev

License

MIT

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

File Context Server