# TimeVerse Code Reader

[![PyPI](https://img.shields.io/pypi/v/timeverse-code-reader)](https://pypi.org/project/timeverse-code-reader/)
[![Python](https://img.shields.io/pypi/pyversions/timeverse-code-reader)](https://pypi.org/project/timeverse-code-reader/)
[![CI](https://github.com/elimyliu/timeverse-code-reader/actions/workflows/ci.yml/badge.svg)](https://github.com/elimyliu/timeverse-code-reader/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

TimeVerse Code Reader 是一个基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 的文件读取工具，专为 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`](https://github.com/modelcontextprotocol/servers/tree/main/src/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` | 获取文件或目录的完整元数据 |

## 安装

```bash
pip install timeverse-code-reader
```

或从源码安装：

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

## 使用

### 作为 CLI 工具

```bash
timeverse-code-reader
```

### 传输方式

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

#### stdio 模式（默认）

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

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

#### HTTP 模式

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

```bash
# 需要先安装 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 配置中添加：

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

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

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

### 其他 MCP 客户端集成

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

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

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

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

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

### 环境变量

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

## 开发

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

## License

MIT