# willianpinho/large-file-mcp architecture

> Architecture diagram of the GitHub repository willianpinho/large-file-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/willianpinho/large-file-mcp
- Repository: https://github.com/willianpinho/large-file-mcp

## Overview

Large File MCP Server exposes large-file operations as MCP tools over stdio. An AI client requests chunk reads, line navigation, search, structure or summary analysis, or byte streaming; the server dispatches requests through the FileHandler API to specialized file-processing modules. Metadata checks and file-type-based chunk sizing support those operations, while the server caches chunks and structure results. The README documents all six capabilities; source excerpts show dispatch and most implementations, but not every server handler or external-client integration in full.

Main entry points: [`src/file-handler/metadata.ts`](https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/metadata.ts) (File metadata), [`src/fileHandler.ts`](https://github.com/willianpinho/large-file-mcp/blob/master/src/fileHandler.ts) (FileHandler API), [`src/types.ts`](https://github.com/willianpinho/large-file-mcp/blob/master/src/types.ts) (Shared types), [`src/server.ts`](https://github.com/willianpinho/large-file-mcp/blob/master/src/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_entry["CLI entry<br/>[index.ts]"]
  node_server["MCP server<br/>[server.ts]"]
  node_mcp_sdk["MCP SDK"]
end

subgraph group_fileops["File operations"]
  node_api["FileHandler API<br/>[fileHandler.ts]"]
  node_reader["Chunk navigation<br/>[reader.ts]"]
  node_search["Context search<br/>[search.ts]"]
  node_analysis["Structure analysis<br/>[analysis.ts]"]
  node_stream["Byte streaming<br/>[stream.ts]"]
end

subgraph group_optimization["Caching"]
  node_cache["LRU cache<br/>[cacheManager.ts]"]
end

subgraph group_foundation["Shared foundations"]
  node_metadata["File metadata<br/>[metadata.ts]"]
  node_types["Shared types<br/>[types.ts]"]
end

node_client(("AI client"))
node_local_files[("Local files")]

node_client -->|"invokes tools"| node_server
node_entry -->|"starts"| node_server
node_server -->|"connects over stdio"| node_mcp_sdk
node_server -->|"dispatches file calls"| node_api
node_server -->|"reads and writes"| node_cache
node_api -->|"delegates metadata"| node_metadata
node_api -->|"delegates reads"| node_reader
node_api -->|"delegates searches"| node_search
node_api -->|"delegates analysis"| node_analysis
node_api -->|"delegates streaming"| node_stream
node_reader -->|"gets file metadata"| node_metadata
node_search -->|"verifies file"| node_metadata
node_analysis -->|"gets metadata and sizing"| node_metadata
node_stream -->|"verifies file"| node_metadata
node_metadata -->|"checks and reads"| node_local_files
node_reader -->|"reads lines"| node_local_files
node_search -->|"scans lines"| node_local_files
node_analysis -->|"scans content"| node_local_files
node_stream -->|"streams bytes"| node_local_files
node_cache -->|"uses cache types"| node_types
node_metadata -->|"uses file types"| node_types
node_reader -->|"uses chunk types"| node_types
node_search -->|"uses search types"| node_types
node_analysis -->|"uses analysis types"| node_types
node_stream -->|"uses stream types"| node_types

click node_entry "https://github.com/willianpinho/large-file-mcp/blob/master/src/index.ts"
click node_server "https://github.com/willianpinho/large-file-mcp/blob/master/src/server.ts"
click node_api "https://github.com/willianpinho/large-file-mcp/blob/master/src/fileHandler.ts"
click node_metadata "https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/metadata.ts"
click node_reader "https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/reader.ts"
click node_search "https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/search.ts"
click node_analysis "https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/analysis.ts"
click node_stream "https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/stream.ts"
click node_cache "https://github.com/willianpinho/large-file-mcp/blob/master/src/cacheManager.ts"
click node_types "https://github.com/willianpinho/large-file-mcp/blob/master/src/types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_mcp_sdk,node_client toneBlue
class node_api,node_reader,node_search,node_analysis,node_stream,node_local_files toneAmber
class node_cache toneMint
class node_metadata,node_types toneRose
```

## Components

### MCP interface

- [CLI entry](https://github.com/willianpinho/large-file-mcp/blob/master/src/index.ts): `src/index.ts`
- [MCP server](https://github.com/willianpinho/large-file-mcp/blob/master/src/server.ts): `src/server.ts`
- **MCP SDK**

### File operations

- [FileHandler API](https://github.com/willianpinho/large-file-mcp/blob/master/src/fileHandler.ts): `src/fileHandler.ts`
- [Chunk navigation](https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/reader.ts): `src/file-handler/reader.ts`
- [Context search](https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/search.ts): `src/file-handler/search.ts`
- [Structure analysis](https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/analysis.ts): `src/file-handler/analysis.ts`
- [Byte streaming](https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/stream.ts): `src/file-handler/stream.ts`

### Caching

- [LRU cache](https://github.com/willianpinho/large-file-mcp/blob/master/src/cacheManager.ts): `src/cacheManager.ts`

### Shared foundations

- [File metadata](https://github.com/willianpinho/large-file-mcp/blob/master/src/file-handler/metadata.ts): `src/file-handler/metadata.ts`
- [Shared types](https://github.com/willianpinho/large-file-mcp/blob/master/src/types.ts): `src/types.ts`

### Other components

- **AI client**
- **Local files**

## Connections

- AI client → MCP server: invokes tools (evidence: `src/server.ts`)
- CLI entry → MCP server: starts (evidence: `src/index.ts`)
- MCP server → MCP SDK: connects over stdio (evidence: `src/server.ts`)
- MCP server → FileHandler API: dispatches file calls (evidence: `src/server.ts`)
- MCP server → LRU cache: reads and writes (evidence: `src/server.ts`)
- FileHandler API → File metadata: delegates metadata (evidence: `src/fileHandler.ts`)
- FileHandler API → Chunk navigation: delegates reads (evidence: `src/fileHandler.ts`)
- FileHandler API → Context search: delegates searches (evidence: `src/fileHandler.ts`)
- FileHandler API → Structure analysis: delegates analysis (evidence: `src/fileHandler.ts`)
- FileHandler API → Byte streaming: delegates streaming (evidence: `src/fileHandler.ts`)
- Chunk navigation → File metadata: gets file metadata (evidence: `src/file-handler/reader.ts`)
- Context search → File metadata: verifies file (evidence: `src/file-handler/search.ts`)
- Structure analysis → File metadata: gets metadata and sizing (evidence: `src/file-handler/analysis.ts`)
- Byte streaming → File metadata: verifies file (evidence: `src/file-handler/stream.ts`)
- File metadata → Local files: checks and reads (evidence: `src/file-handler/metadata.ts`)
- Chunk navigation → Local files: reads lines (evidence: `src/file-handler/reader.ts`)
- Context search → Local files: scans lines (evidence: `src/file-handler/search.ts`)
- Structure analysis → Local files: scans content (evidence: `src/file-handler/analysis.ts`)
- Byte streaming → Local files: streams bytes (evidence: `src/file-handler/stream.ts`)
- LRU cache → Shared types: uses cache types (evidence: `src/cacheManager.ts`)
- File metadata → Shared types: uses file types (evidence: `src/file-handler/metadata.ts`)
- Chunk navigation → Shared types: uses chunk types (evidence: `src/file-handler/reader.ts`)
- Context search → Shared types: uses search types (evidence: `src/file-handler/search.ts`)
- Structure analysis → Shared types: uses analysis types (evidence: `src/file-handler/analysis.ts`)
- Byte streaming → Shared types: uses stream types (evidence: `src/file-handler/stream.ts`)
