mcp文件镜头
](https://pypi.org/project/mcp-file-lens/)  
MCP（模型上下文协议）服务器为您的目录结构和文件提供了一个灵活的“镜头”，使LLM客户端能够以最小的噪音高效地导航和理解代码库。
概述
mcp-file-lens 是一个基于Python的MCP服务器，旨在为LLM提供对文件系统的有针对性的访问。它不是不加选择地读取整个文件内容，而是提供手术工具来准确检查所需内容，保留上下文窗口并提高理解能力。
该服务器旨在与语言协议服务器（LPS）等其他MCP服务器协同工作，在LPS处理符号解析、类型检查和重构等语言特定操作的同时提供补充的文件导航功能。
特性
安全
- 目录限制：所有文件访问都限制在指定的目录树中，通过
--allowed-dir - 安全文件系统适配器：所有MCP工具都使用一个安全的文件系统适配器来验证每条路径
- Gitignore过滤：自动遵守.gitignore模式，以避免访问被忽略的文件
- 二进制文件检测：自动跳过二进制文件以防止编码错误
- 目标安全：安全检查仅适用于MCP工具操作，不适用于系统导入或库
- 无法逃脱：防止目录遍历攻击和访问系统文件
核心功能
- 目录列表 (
list_dir)：使用可选的递归模式高效导航目录结构 - 文件内容检索 (
read_file)：使用可选行号读取完整的文件内容 - 单个文件搜索 (
read_file_grep)：使用上下文查找包含特定字符串的行（如grep-A/-B/-C） - 多文件搜索 (
read_files_grep)：递归搜索目录树中的所有文件 - 范围选择 (
read_file_range)：从文件中提取特定的行范围 - 智能过滤：自动过滤二进制文件，尊重gitignore模式，并优雅地处理编码问题
益处
- 高效的上下文使用：只阅读必要的内容
- 降噪：过滤掉不相关的内容、二进制文件和gignored文件
- 灵活导航：智能地遍历代码库
- 最大程度的关注：关注相关代码部分
- 稳健的错误处理：优雅地处理编码问题和权限错误
- 安全第一：文件访问仅限于指定目录
- 纯文本输出：所有工具都返回纯文本（不是JSON）以进行最佳LLM解析
- 熟悉的格式：输出模拟标准Unix工具（ls、cat、grep）
- 无声操作：除非启用调试模式，否则没有日志噪音
安装
来自PyPI（推荐）
pip install mcp-file-lens备注：包名称使用连字符(mcp-file-lens)对于PyPI安装，但Python模块名称使用下划线(mcp_file_lens)对于进口。
来源
# Clone the repository
git clone https://github.com/solatis/mcp-file-lens.git
cd mcp-file-lens
# Install in development mode
pip install -e ".[dev]"用法
作为MCP服务器
# Start the server with a specific allowed directory
python -m mcp_file_lens --allowed-dir ./my_project
# Or with an absolute path
python -m mcp_file_lens --allowed-dir /absolute/path/to/project
# Enable debug logging
python -m mcp_file_lens --allowed-dir ./my_project --debug
# Disable gitignore filtering (not recommended)
python -m mcp_file_lens --allowed-dir ./my_project --disable-gitignore安全说明：The --allowed-dir 参数是必需的，它将文件访问限制在指定的目录树中。这可以防止LLM访问项目外部的文件。
配置
添加到MCP客户端配置中：
{
"servers": {
"mcp-file-lens": {
"command": "python",
"args": ["-m", "mcp_file_lens", "--allowed-dir", "./my_project"],
"env": {}
}
}
}调试配置
对于开发或故障排除，启用调试模式：
{
"servers": {
"mcp-file-lens": {
"command": "python",
"args": ["-m", "mcp_file_lens", "--allowed-dir", "./my_project", "--debug"],
"env": {}
}
}
}与其他MCP服务器协同工作
mcp-file-lens 旨在补充其他MCP服务器。例如，当与语言协议服务器一起使用时：
{
"servers": {
"mcp-file-lens": {
"command": "python",
"args": ["-m", "mcp_file_lens", "--allowed-dir", "./my_project"],
"env": {}
},
"typescript-lps": {
"command": "typescript-language-server",
"args": ["--stdio"],
"env": {}
}
}
}这允许LLM：
- 使用
mcp-file-lens用于高效的文件导航和内容检查 - 使用LPS实现特定语言的功能，如转到定义、查找参考等。
工具API
list_dir(path: str = ".", recursive: bool = False)
以ls-la格式列出目录的内容。自动过滤掉gignored文件和二进制文件。
参数：
path：列表的目录路径（默认：当前目录）recursive：如果为True，则递归列出所有文件（默认值：False）
退货： 包含文件大小和名称的纯文本目录列表（按gitignore筛选，不包括二进制文件）
过滤： 尊重.gitignore模式，并排除二进制文件以获得更清晰的输出。
输出示例：
2494 pyproject.toml
6420 README.md
src/read_file(path: str, lineno: bool = True)
读取n类格式文件的完整内容。自动跳过二进制文件并优雅地处理UTF-8编码问题。
参数：
path：要读取的文件路径lineno：在输出中包含行号（默认值：True）
退货： 带有可选行号的纯文本文件内容
输出示例：
1 #!/usr/bin/env python3
2 """Main module"""
3
4 import sysread_file_grep(path: str, search_string: str, before: int = 0, after: int = 0, context: int | None = None, lineno: bool = True)
搜索包含grep-n格式的可选上下文字符串的行。
参数：
path：要搜索的文件路径search_string：要搜索的字符串before：每场比赛前要包含的行（如grep-B）after：每场比赛后要包含的行（如grep-A）context：设置前后（如grep-C）lineno：在输出中包含行号（默认值：True）
退货： 带有匹配行和上下文的纯文本grep样式输出
输出示例：
15:def install_audit_hook() -> None:
16: """Install an audit hook to monitor file operations."""
17: def audit_hook(event: str, args: Tuple) -> None:
--
25: if _allowed_dir is not None:
26: sys.addaudithook(audit_hook)read_files_grep(path: str = ".", search_string: str = "", before: int = 0, after: int = 0, context: int | None = None, lineno: bool = True, filename: bool = True)
递归搜索目录树中所有文件的模式。自动过滤掉二进制文件和gitignored文件，以获得更清晰的结果。
参数：
path：递归搜索的目录（默认：当前目录）search_string：要搜索的字符串before：每场比赛前要包含的行（如grep-B）after：每场比赛后要包含的行（如grep-A）context：设置前后（如grep-C）lineno：在输出中包含行号（默认值：True）filename：在输出中包含文件名前缀（默认值：True）
退货： 纯文本grep-r样式输出，包含所有文件的匹配项
输出示例：
src/server.py:15:def install_audit_hook() -> None:
src/server.py:16: """Install an audit hook to monitor file operations."""
--
tests/test_server.py:42:def test_install_audit_hook():
tests/test_server.py:43: """Test audit hook installation."""read_file_range(path: str, start_line: int, end_line: int, lineno: bool = True)
从文件中读取特定的行范围。
参数：
path：要读取的文件路径start_line：起始行号（1-索引，包括在内）end_line：结束行号（1索引，包括在内）lineno：在输出中包含行号（默认值：True）
例子：
# Read lines 10-20
read_file_range("/path/to/file.py", 10, 20)退货： 纯文本，包含指定范围内的选定行
输出示例：
10:import logging
11:from pathlib import Path
12:from typing import Any
--
50:def validate_path(path: str) -> Tuple[bool, str]:
51: """Validate if path is allowed."""发展
设置开发环境
# Clone and install in development mode
git clone https://github.com/solatis/mcp-file-lens.git
cd mcp-file-lens
pip install -e ".[dev]"
# Run tests
pytest
# Code quality checks
ruff check . # Linting
black --check . # Format checking
mypy src/ # Type checking
# Auto-fix formatting
black . # Format code
ruff check --fix . # Fix linting issues项目结构
mcp-file-lens/
├── src/
│ └── mcp_file_lens/
│ ├── __init__.py
│ ├── __main__.py
│ └── server.py
├── tests/
│ └── test_server.py
├── pyproject.toml
└── README.md命令行参数
必需参数
--allowed-dir PATH: 必需 -限制对指定目录树的文件访问。可以是相对路径或绝对路径。
可选参数
--enable-gitignore：启用gitignore过滤（默认行为）。与.gitignore中的模式匹配的文件将被排除在列表和搜索之外。--disable-gitignore：禁用gitignore过滤。无论.gitignore模式如何，所有文件都可以访问。--debug：启用调试日志记录。显示有关文件操作、错误和安全检查的详细信息。
过滤行为
Gitignore支持：
- 自动检测并解析允许目录中的.gitignore文件
- 支持常见的gitignore模式，包括通配符（\*）、目录模式（/）和否定
- 对所有目录列表和递归文件操作应用筛选
- 默认情况下启用，可以使用禁用
--disable-gitignore
二进制文件检测：
- 在文本操作期间自动识别和跳过二进制文件
- 使用基于内容的检测（空字节、非文本字符比率）
- 防止UTF-8解码错误并减少搜索结果中的噪声
- 始终启用文件内容操作
错误处理：
- UTF-8解码错误通过回退到错误替换得到妥善处理
- 权限错误仅在调试模式下记录，以减少噪音
- 二进制文件会自动跳过，以避免编码问题
安全考虑
这 --allowed-dir argument通过文件系统适配器实现目标安全：
- 路径验证：每个MCP工具操作都会通过安全的文件系统适配器验证路径
- 无穿越：防止
../以及其他目录遍历尝试 - 目标范围：安全性仅适用于MCP文件操作，不适用于Python导入或库加载
- 绝对分辨率：在验证之前，所有路径都解析为绝对路径
这确保了LLM只能访问指定项目目录中的文件，保护您的系统文件和其他敏感数据，同时允许正常的Python操作不受阻碍地运行。
需求
- Python 3.12+
- 用于MCP协议实现的FastMCP
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
贡献
欢迎投稿！请随时提交拉取请求。