Large File MCP Server

大文件MCP服务器

一种模型上下文协议（MCP）服务器，用于智能处理具有智能分块、导航和流媒体功能的大文件。

](https://www.npmjs.com/package/@willianpinho/large-file-mcp) ](https://www.npmjs.com/package/@willianpinho/large-file-mcp)     ](https://nodejs.org/)   ](https://github.com/willianpinho/large-file-mcp/stargazers) ](https://github.com/willianpinho/large-file-mcp/issues)

特性

• 智能分块 -根据文件类型自动确定最佳块大小
• 智能导航 -跳转到具有周围上下文的特定行
• 强大的搜索功能 -正则表达式支持匹配前后的上下文行
• 文件分析 -全面的元数据和统计分析
• 内存效率高 -无需加载到内存中即可流式传输任何大小的文件
• 性能优化 -内置LRU缓存，用于频繁访问的块
• 类型安全 -用TypeScript编写，具有严格的类型
• 交叉平台的 -适用于Windows、macOS和Linux

安装

npm install -g @willianpinho/large-file-mcp

或者直接与npx一起使用：

npx @willianpinho/large-file-mcp

快速开始

克劳德代码CLI

使用CLI添加MCP服务器：

# Add for current project only (local scope)
claude mcp add --transport stdio --scope local large-file-mcp -- npx -y @willianpinho/large-file-mcp

# Add globally for all projects (user scope)
claude mcp add --transport stdio --scope user large-file-mcp -- npx -y @willianpinho/large-file-mcp

验证安装：

claude mcp list
claude mcp get large-file-mcp

如果需要，请删除：

# Remove from local scope
claude mcp remove large-file-mcp -s local

# Remove from user scope
claude mcp remove large-file-mcp -s user

MCP范围：

• local -仅在当前项目目录中可用
• user -适用于全球所有项目
• project -定义于 .mcp.json 用于团队共享

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "large-file": {
      "command": "npx",
      "args": ["-y", "@willianpinho/large-file-mcp"]
    }
  }
}

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

编辑后重新启动Claude Desktop。

其他AI平台

双子座：

{
  "tools": [
    {
      "name": "large-file-mcp",
      "command": "npx @willianpinho/large-file-mcp",
      "protocol": "mcp"
    }
  ]
}

用法

配置后，您可以使用自然语言与大文件交互：

Read the first chunk of /var/log/system.log

Find all ERROR messages in /var/log/app.log

Show me line 1234 of /code/app.ts with context

Get the structure of /data/sales.csv

可用工具

read_large_file_chunk

使用智能分块读取大文件的特定块。

参数：

• filePath （必填）：文件的绝对路径
• chunkIndex （可选）：从零开始的块索引（默认值：0）
• linesPerChunk （可选）：每个块的行数（如果未提供，则自动检测）
• includeLineNumbers （可选）：包含行号（默认值：false）

例子：

{
  "filePath": "/var/log/system.log",
  "chunkIndex": 0,
  "includeLineNumbers": true
}

search_in_large_file

在具有上下文的大文件中搜索模式。

参数：

• filePath （必填）：文件的绝对路径
• pattern （必填）：搜索模式
• caseSensitive （可选）：区分大小写的搜索（默认值：false）
• regex （可选）：使用正则表达式模式（默认值：false）
• maxResults （可选）：最大结果（默认值：100）
• contextBefore （可选）：匹配前的上下文行（默认值：2）
• contextAfter （可选）：匹配后的上下文行（默认值：2）

例子：

{
  "filePath": "/var/log/error.log",
  "pattern": "ERROR.*database",
  "regex": true,
  "maxResults": 50
}

get_file_结构

分析文件结构并获取全面的元数据。

参数：

• filePath （必填）：文件的绝对路径

退货： 文件元数据、行统计信息、推荐的块大小和示例行。

navigate_to_line

跳到具有周围上下文的特定行。

参数：

• filePath （必填）：文件的绝对路径
• lineNumber （必填）：要导航到的行号（1-索引）
• contextLines （可选）：前后上下文行（默认值：5）

get_file_摘要

获取文件的全面统计摘要。

参数：

• filePath （必填）：文件的绝对路径

退货： 文件元数据、行统计、字符统计和字数统计。

stream_large_file

将文件分块流式传输，以处理非常大的文件。

参数：

• filePath （必填）：文件的绝对路径
• chunkSize （可选）：块大小（以字节为单位）（默认值：64KB）
• startOffset （可选）：起始字节偏移量（默认值：0）
• maxChunks （可选）：要返回的最大块数（默认值：10）

支持的文件类型

服务器智能地检测并优化以下内容：

• 文本文件（.txt）-500行/块
• 日志文件（.Log）-500行/块
• 代码文件（.ts、.js、.py、.java、.cpp、.go、.rs等）-300行/块
• CSV文件（.CSV）-1000行/块
• JSON文件（.JSON）-100行/块
• XML文件（.XML）-200行/块
• Markdown文件（.md）-500行/块
• 配置文件（.yml、.yaml、.sh、.bash）-300行/块

配置

使用环境变量自定义行为：

自定义设置示例（Claude Desktop）：

{
  "mcpServers": {
    "large-file": {
      "command": "npx",
      "args": ["-y", "@willianpinho/large-file-mcp"],
      "env": {
        "CHUNK_SIZE": "1000",
        "CACHE_ENABLED": "true"
      }
    }
  }
}

自定义设置示例（Claude Code CLI）：

claude mcp add --transport stdio --scope user large-file-mcp \
  --env CHUNK_SIZE=1000 \
  --env CACHE_ENABLED=true \
  -- npx -y @willianpinho/large-file-mcp

例子

分析日志文件

Analyze /var/log/nginx/access.log and find all 404 errors

人工智能将使用搜索工具查找模式，并提供每个匹配的上下文。

代码导航

Find all function definitions in /project/src/main.py

使用正则表达式搜索来定位具有周围代码上下文的函数定义。

CSV数据探索

Show me the structure of /data/sales.csv

返回元数据、行数、样本行和推荐的块大小。

大文件处理

Stream the first 100MB of /data/huge_dataset.json

使用流模式高效处理非常大的文件。

演出

缓存

• LRU缓存 具有可配置的大小（默认100MB）
• 基于TTL的过期 （默认5分钟）
• 命中率80-90% 用于重复访问
• 频繁访问的文件的性能显著提高

内存管理

• 流媒体架构 -文件是逐行读取的，从未完全加载
• 可配置的块大小 -根据您的用例进行调整
• 智能缓冲 -搜索操作的最小内存占用

文件大小处理

发展

从源头构建

git clone https://github.com/willianpinho/large-file-mcp.git
cd large-file-mcp
pnpm install
pnpm build

发展模式

pnpm dev    # Watch mode
pnpm lint   # Run linter
pnpm start  # Run server

项目结构

src/
├── index.ts        # Entry point
├── server.ts       # MCP server implementation
├── fileHandler.ts  # Core file handling logic
├── cacheManager.ts # Caching implementation
└── types.ts        # TypeScript type definitions

故障排除

文件不可访问

确保文件路径是绝对的，并且文件具有读取权限：

chmod +r /path/to/file

内存不足

1. 减少 CHUNK_SIZE 环境变量
2. 禁用缓存 CACHE_ENABLED=false
3. 使用 stream_large_file 对于非常大的文件

搜索性能缓慢

1. 减少 maxResults 参数
2. 使用 startLine 和 endLine 限制搜索范围
3. 确保已启用缓存

Claude Code CLI：找不到MCP服务器

检查服务器是否已安装：

claude mcp list

如果未列出，请重新安装：

claude mcp add --transport stdio --scope user large-file-mcp -- npx -y @willianpinho/large-file-mcp

检查服务器运行状况：

claude mcp get large-file-mcp

使用指标

此MCP服务器被积极维护和监控使用模式，以提高功能。使用指标帮助我们：

• 了解哪些工具最有价值
• 识别性能瓶颈
• 优先考虑功能开发
• 确保可靠性和稳定性

生产监控

服务器通过环境变量提供全面的日志记录和遥测：

• CACHE_ENABLED：启用/禁用缓存（默认值： true)
• CACHE_SIZE：缓存大小（以字节为单位）（默认值： 104857600 -100MB）
• CACHE_TTL：缓存TTL（以毫秒为单位）（默认值： 300000 -5分钟）
• CHUNK_SIZE：每个块的默认行数（默认值： 500)
• MAX_FILE_SIZE：最大文件大小（以字节为单位）（默认值： 10737418240 -10克）
• 重叠线：块之间的重叠（默认值： 10)

使用示例

最近的使用模式表明，服务器在以下方面特别有效：

• 日志分析：使用搜索和导航处理多GB日志文件
• 数据处理：以可管理的块读取大型CSV/JSON文件
• 代码审查：高效地浏览大型代码库
• 系统监控：分析系统日志和调试输出
• 文件分析：处理大型文本文档

有关详细的分析和使用趋势，请访问 Glama.ai仪表板.

贡献

欢迎投稿！请随时提交问题或拉取请求。

开发流程

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 确保代码构建和lint成功
5. 提交拉取请求

看 贡献.md 详细指南。

许可证

麻省理工学院

支持

• 问题：
• 文档： 此README和内联代码文档
• 示例： 检查 examples/ 目录

致谢

与 模型上下文协议SDK.

______________________________________________________________________

专为AI开发者社区打造。