timeverse-code-reader 0.1.1

TimeVerse File Reader MCP Tool - 读取文件内容、列出目录、获取文件元数据

TimeVerse Code Reader

TimeVerse Code Reader 是一个基于 MCP (Model Context Protocol) 的文件读取工具，专为 AI 编码助手和 LLM 应用设计。通过标准化的 MCP 协议，为 AI 模型提供精准、高效、安全的文件系统读取能力。

---

核心优势

🚀 智能缓存机制

内置 FileCache 采用 mtime 校验 + LRU 淘汰 策略：

• mtime 自动失效：文件修改后缓存自动失效，下次读取重新加载，保证始终返回最新内容
• LRU 淘汰：最多缓存 100 个文件，最近最少使用的自动淘汰，内存占用可控
• 大文件保护：超过 10MB 的文件跳过缓存，防止挤占内存
• 会话级复用：MCP 子进程长驻运行，缓存跨多次 Tool Call 复用，典型会话命中 10-30 次，大幅减少磁盘 I/O

🔍 专注于代码阅读，不限于代码

专为阅读源码场景优化，同时能处理任何文本文件：

• 按行范围读取：支持 start_line / end_line 参数，只读取感兴趣的行段，减少 Token 消耗
• 40+ 编程语言识别：自动检测 Python、TypeScript、Go、Rust、Java 等主流语言，返回标准化语言名称
• 智能编码处理：统一 UTF-8 读取，errors="replace" 容错策略确保非完美编码文件也不崩溃
• 二进制文件识别：通过前 1024 字节快速检测，避免将二进制文件以文本形式暴露给 LLM

📂 完整文件系统元数据

通过 get_file_info 一次获取文件全貌，赋能 AI 理解项目结构：

• 文件类型、大小（原始 + 格式化显示）
• 最后修改时间（ISO 8601，UTC）
• 语言检测结果、MIME 类型
• 行数统计、二进制文件标识

⚡ 高性能设计

优化	实现
文件内容缓存	mtime 校验 + LRU，避免重复磁盘 I/O
缓存上限 100	内存开销控制在 ~30MB
行范围不缓存	避免缓存被截取的"脏"内容
跳过不可访问条目	单个权限错误不影响整体操作
延迟二进制检测	仅检查前 1024 字节

---

对比 Filesystem MCP Server

@modelcontextprotocol/server-filesystem 是 MCP 官方提供的文件系统操作参考实现。TimeVerse Code Reader 与它的定位不同，各有侧重：

定位差异

维度	TimeVerse Code Reader	Filesystem MCP Server
定位	专注于安全读取的只读工具	通用的文件系统读写管理工具
适用场景	AI 编码助手阅读源码、分析项目结构	文件全生命周期管理（增删改查）
运行时	Python（pip install）	Node.js（npx）
工具数量	3 个精炼只读工具	15 个全功能工具
写操作	❌ 不提供	✅ write / edit / move / delete

TimeVerse Code Reader 的独特优势

特性	TimeVerse Code Reader	Filesystem MCP Server
智能缓存	✅ mtime 校验 + LRU 淘汰，会话级复用	❌ 无内置缓存，每次读取都走磁盘 I/O
按行范围读取	✅ start_line / end_line 任意范围截取	⚠️ 仅支持 head（前 N 行）或 tail（后 N 行），不可同时使用，无法指定中间范围
编程语言识别	✅ 40+ 语言自动检测，返回标准化名称	❌ 无语言识别能力
文件元数据丰富度	✅ 语言、行数、MIME、格式化大小、二进制标识	⚠️ 基础元数据（大小、时间、类型、权限）
二进制文件检测	✅ 前 1024 字节快速识别	❌ 不提供二进制检测
安全性	✅ 只读设计，天然无破坏风险	⚠️ 需显式配置允许目录，写操作需谨慎
安装体积	✅ 纯 Python，轻量无外部依赖	⚠️ 需 Node.js 运行时

选型建议

• AI 编码/代码阅读场景：选 TimeVerse Code Reader —— 只读更安全，缓存减少重复 I/O，语言识别和行范围读取更适合代码分析
• 文件全量管理场景：选 Filesystem MCP Server —— 需要增删改、文件搜索、批量编辑等功能时更合适
• 两者可同时启用：互不冲突，可在一个 MCP 客户端中同时配置两个服务器，各取所长

Tools

工具	描述
read_file	读取文件内容，支持按行范围读取
list_directory	列出目录下的文件和子目录（一级，不递归）
get_file_info	获取文件或目录的完整元数据

安装

pip install timeverse-code-reader

或从源码安装：

git clone https://github.com/elimyliu/timeverse-code-reader.git
cd timeverse-code-reader
pip install -e ".[dev]"

使用

作为 CLI 工具

timeverse-code-reader

传输方式

支持两种传输模式，通过 --transport 参数选择：

stdio 模式（默认）

通过标准输入输出与客户端通信，适合本地/嵌入使用：

# 直接运行
timeverse-code-reader
# 或显式指定
timeverse-code-reader --transport stdio

HTTP 模式

通过 Streamable HTTP 远程调用，适合跨网络或独立部署：

# 需要先安装 HTTP 依赖
pip install "timeverse-code-reader[http]"
# 启动 HTTP 服务
timeverse-code-reader --transport http --host 0.0.0.0 --port 8000
# 开发模式（启用热重载，代码变更自动重启）
timeverse-code-reader --transport http --host 0.0.0.0 --port 8000 --dev

启动后客户端通过 SSE 端点连接：

• SSE 端点：http://<host>:<port>/sse
• 消息端点：http://<host>:<port>/messages/

与 TimeVerse Studio 集成

在 TimeVerse Studio 的 MCP Server 配置中添加：

{
  "mcpServers": {
    "timeverse-code-reader": {
      "command": "timeverse-code-reader",
      "args": [],
      "env": {
        "PROJECT_ROOT": "/path/to/workspace"
      }
    }
  }
}

如果使用 uvx（无需安装，直接运行）：

{
  "mcpServers": {
    "timeverse-code-reader": {
      "command": "uvx",
      "args": ["timeverse-code-reader"]
    }
  }
}

其他 MCP 客户端集成

所有支持 MCP 协议的客户端（Claude Desktop、Cursor、Windsurf、Trae 等）配置方式一致，只需在客户端的 MCP Server 配置中添加：

{
  "mcpServers": {
    "timeverse-code-reader": {
      "command": "timeverse-code-reader",
      "args": []
    }
  }
}

如果使用 uvx（无需安装，直接运行）：

{
  "mcpServers": {
    "timeverse-code-reader": {
      "command": "uvx",
      "args": ["timeverse-code-reader"]
    }
  }
}

不同客户端的配置文件位置请参考其官方文档。需要 HTTP 模式时添加 --transport http 参数。

环境变量

• PROJECT_ROOT（可选）：工作区根目录路径，默认为当前工作目录。所有相对路径将基于此目录解析。

开发

pip install -e ".[dev]"
ruff check src/ tests/
ruff format src/ tests/
mypy src/
pytest -v

License

MIT