Skip to main content
Glama
MCP File Context Server

MCP File Context Server

by bsmi021

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

Related MCP server: TokenScope

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

  1. list_context_files

    • Lists files in a directory with detailed metadata

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

    • Reads file or directory contents with metadata

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

    • Searches for patterns in files with context

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

    • Analyzes code files for quality metrics

    {
      "path": "./src",
      "recursive": true,
      "metrics": ["complexity", "dependencies", "quality"]
    }
  5. 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.

Cross-Platform Path Compatibility

Note: As of April 2025, all file and directory path handling in File Context Server has been updated for improved cross-platform compatibility (Windows, macOS, Linux):

  • All glob patterns use POSIX-style paths (forward slashes) internally, ensuring consistent file matching regardless of OS.

  • All file system operations (reading, writing, stat, etc.) use normalized absolute paths for reliability.

  • If you are developing or extending the server, use path.posix.join for glob patterns and path.normalize for file system access.

  • This change prevents issues with path separators and file matching on different operating systems.

No changes are required for end users, but developers should follow these conventions when contributing to the project.

Available Tools

6 tools
generate_outlineC

Generate a code outline for a file, showing its structure (classes, functions, imports, etc). Supports TypeScript/JavaScript and Python files.

Inputs: path (required).

get_chunk_countA

Get the total number of chunks that will be returned for a read_context request. Use this tool FIRST before reading content to determine how many chunks you need to request. The parameters should match what you'll use in read_context.

Inputs: path (required), encoding, maxSize, recursive, +1 more.

getFilesC

Retrieve multiple files by their paths, returning content and metadata for each file

Inputs: filePathList (required).

get_profile_contextC

Get repository context based on current profile settings

Inputs: refresh.

read_contextA

Read and analyze code files with advanced filtering and chunking. The server automatically ignores common artifact directories and files:

  • Version Control: .git/

  • Python: .venv/, pycache/, *.pyc, etc.

  • JavaScript/Node.js: node_modules/, bower_components/, .next/, dist/, etc.

  • IDE/Editor: .idea/, .vscode/, .env, etc.

For large files or directories, use get_chunk_count first to determine total chunks, then request specific chunks using chunkNumber parameter.

Inputs: path (required), maxSize, encoding, recursive, +2 more.

set_profileC

Set the active profile for context generation

Inputs: profile_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have distinct purposes, but 'getFiles' and 'read_context' both involve retrieving file content, which could cause confusion. 'generate_outline' and 'get_profile_context' are clearly separate, and 'set_profile' and 'get_chunk_count' are specialized utilities.

    Naming Consistency2/5

    Naming is inconsistent with mixed conventions: 'generate_outline' and 'read_context' use snake_case, while 'getFiles' uses camelCase. Verb styles vary (e.g., 'generate' vs. 'get' vs. 'read'), and 'get_chunk_count' includes an underscore while 'getFiles' does not, creating a chaotic pattern.

    Tool Count5/5

    With 6 tools, the count is well-scoped for a file context server, covering core operations like file retrieval, analysis, and profile management without being overwhelming or too sparse.

    Completeness4/5

    The toolset covers key file context operations: retrieving files, analyzing code, generating outlines, and managing profiles. A minor gap exists in update or delete operations for profiles or contexts, but agents can likely work around this for the server's purpose.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables token-aware directory exploration and file analysis for LLMs, helping them understand codebases through intelligent scanning and reporting.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.
      90
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that enables AI applications to access and analyze local code repositories without manual uploads, providing file listing, content reading, code searching, and project structure analysis capabilities.
      7
      MIT