timeverse-code-reader 0.1.1__py3-none-any.whl

timeverse_code_reader/__init__.py

@@ -0,0 +1 @@
+"""timeverse_code_reader - TimeVerse 文件读取 MCP 工具."""

timeverse_code_reader/cache.py

@@ -0,0 +1,105 @@
+"""
+FileCache - 文件内容缓存
+
+功能简述:
+    基于 mtime 校验 + LRU 淘汰策略的文件内容缓存。
+    跨多次 tool_call 复用，避免重复读取同一文件。
+    单文件超过 10MB 不缓存，单次对话典型命中 10-30 次。
+
+主要方法:
+    - get: 获取缓存内容，mtime 变更时自动失效
+    - set: 写入缓存，超过 MAX_FILE_SIZE 时跳过
+    - invalidate: 主动失效（预留）
+    - clear: 清空缓存
+"""
+
+from collections import OrderedDict
+from pathlib import Path
+
+
+class FileCache:
+    """
+    文件内容缓存 - mtime 校验 + LRU 淘汰
+
+    MAX_ENTRIES: 最多缓存 100 个文件（~30MB）
+    MAX_FILE_SIZE: 单文件超过 10MB 不缓存
+    """
+
+    MAX_ENTRIES = 100
+    MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+
+    def __init__(self):
+        self._cache: OrderedDict[str, tuple[float, str]] = OrderedDict()
+
+    def get(self, path: Path) -> str | None:
+        """
+        获取缓存内容
+
+        读取前检查文件的 mtime，如果文件已变更则自动失效。
+        缓存命中时将条目移到队尾（LRU 标记）。
+
+        Args:
+            path: 文件路径
+
+        Returns:
+            缓存的文件内容，未命中或已失效返回 None
+        """
+        key = str(path)
+        cached = self._cache.get(key)
+        if cached is None:
+            return None
+
+        try:
+            current_mtime = path.stat().st_mtime
+        except OSError:
+            self._cache.pop(key, None)
+            return None
+
+        if cached[0] != current_mtime:
+            # 文件已修改，缓存失效
+            del self._cache[key]
+            return None
+
+        # 命中：移到末尾（LRU 标记为最近使用）
+        self._cache.move_to_end(key)
+        return cached[1]
+
+    def set(self, path: Path, content: str):
+        """
+        写入缓存
+
+        大文件（超过 MAX_FILE_SIZE）不缓存，避免挤占内存。
+
+        Args:
+            path: 文件路径
+            content: 文件内容
+        """
+        try:
+            stat_result = path.stat()
+            if stat_result.st_size > self.MAX_FILE_SIZE:
+                return
+            mtime = stat_result.st_mtime
+        except OSError:
+            return
+
+        key = str(path)
+
+        # 超过上限：淘汰最久未访问的（队首）
+        if len(self._cache) >= self.MAX_ENTRIES:
+            self._cache.popitem(last=False)
+
+        self._cache[key] = (mtime, content)
+        self._cache.move_to_end(key)
+
+    def invalidate(self, path: Path):
+        """主动失效缓存条目（预留，外部通知文件变更时使用）"""
+        self._cache.pop(str(path), None)
+
+    def clear(self):
+        """清空所有缓存"""
+        self._cache.clear()
+
+    @property
+    def size(self) -> int:
+        """当前缓存条目数"""
+        return len(self._cache)

timeverse_code_reader/handler.py

@@ -0,0 +1,231 @@
+"""
+CodeReaderService - 文件读取核心逻辑
+
+功能简述:
+    提供文件读取、目录列取和元数据获取的底层实现。
+    与 server.py 分离，便于独立测试。
+
+主要方法清单:
+    - read_file: 读取文件内容（支持行范围）
+    - list_directory: 列出目录内容
+    - get_file_info: 获取文件元数据
+"""
+
+# ==================== 导入依赖 ====================
+
+import logging
+import mimetypes
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from timeverse_code_reader.cache import FileCache
+from timeverse_code_reader.language_map import detect_language
+
+logger = logging.getLogger(__name__)
+
+# ==================== 工作区根目录 ====================
+
+# 优先使用 PROJECT_ROOT 环境变量，兜底当前工作目录
+PROJECT_ROOT = os.environ.get("PROJECT_ROOT", os.getcwd())
+
+# ==================== 全局缓存实例 ====================
+
+# MCP 子进程长驻，缓存跨多次 tool_call 复用
+_file_cache = FileCache()
+
+
+def _resolve_path(file_path: str) -> Path:
+    """
+    将文件路径解析为绝对路径
+
+    Args:
+        file_path: 用户传入的文件路径
+
+    Returns:
+        解析后的绝对路径 Path 对象
+    """
+    p = Path(file_path)
+    if not p.is_absolute():
+        p = Path(PROJECT_ROOT) / p
+    return p.resolve()
+
+
+# ==================== 核心服务 ====================
+
+
+class CodeReaderService:
+    """文件读取服务"""
+
+    @staticmethod
+    def read_file(
+        file_path: str,
+        start_line: int | None = None,
+        end_line: int | None = None,
+    ) -> str:
+        """
+        读取文件内容
+
+        支持按行范围读取，不设自动截断阈值。
+        大文件由 LLM 上下文窗口自然截断。
+
+        Args:
+            file_path: 文件路径
+            start_line: 起始行号（从 1 开始）
+            end_line: 结束行号
+
+        Returns:
+            文件内容的纯文本字符串
+
+        Raises:
+            FileNotFoundError: 文件不存在
+            ValueError: 行号参数不合法
+        """
+        path = _resolve_path(file_path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {path}")
+        if not path.is_file():
+            raise ValueError(f"路径不是文件: {path}")
+
+        # 全量读取：尝试走缓存
+        if start_line is None and end_line is None:
+            cached = _file_cache.get(path)
+            if cached is not None:
+                return cached
+
+        content = path.read_text(encoding="utf-8", errors="replace")
+
+        # 全量读取：写入缓存（行范围读取不缓存，因为内容已被截取）
+        if start_line is None and end_line is None:
+            _file_cache.set(path, content)
+
+        if start_line is not None or end_line is not None:
+            lines = content.splitlines(keepends=True)
+            total_lines = len(lines)
+
+            if start_line is None:
+                start_line = 1
+            if end_line is None:
+                end_line = total_lines
+
+            if start_line < 1:
+                raise ValueError(f"start_line 必须 >= 1，当前值: {start_line}")
+            if end_line > total_lines:
+                raise ValueError(f"end_line ({end_line}) 超出文件总行数 ({total_lines})")
+            if start_line > end_line:
+                raise ValueError(f"start_line ({start_line}) 不能大于 end_line ({end_line})")
+
+            content = "".join(lines[start_line - 1 : end_line])
+
+        return content
+
+    @staticmethod
+    def list_directory(dir_path: str) -> list[dict]:
+        """
+        列出目录内容（不递归）
+
+        Args:
+            dir_path: 目录路径
+
+        Returns:
+            目录条目列表，每个条目包含 name, type, size
+
+        Raises:
+            FileNotFoundError: 目录不存在
+            NotADirectoryError: 路径不是目录
+        """
+        path = _resolve_path(dir_path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"目录不存在: {path}")
+        if not path.is_dir():
+            raise NotADirectoryError(f"路径不是目录: {path}")
+
+        entries = []
+        for entry in sorted(path.iterdir()):
+            try:
+                stat_info = entry.stat()
+                entries.append(
+                    {
+                        "name": entry.name,
+                        "type": "dir" if entry.is_dir() else "file",
+                        "size": stat_info.st_size if entry.is_file() else None,
+                    }
+                )
+            except (PermissionError, OSError) as e:
+                logger.warning(f"跳过无法访问的条目 {entry}: {e}")
+                continue
+
+        return entries
+
+    @staticmethod
+    def get_file_info(path_str: str) -> dict:
+        """
+        获取文件或目录的元数据
+
+        返回文件大小、最后修改时间、编程语言类型、行数等信息。
+
+        Args:
+            path_str: 文件或目录路径
+
+        Returns:
+            元数据字典
+        """
+        path = _resolve_path(path_str)
+
+        if not path.exists():
+            return {
+                "exists": False,
+                "is_file": False,
+                "is_dir": False,
+                "error": f"路径不存在: {path_str}",
+            }
+
+        stat_info = path.stat()
+        is_file = path.is_file()
+        is_dir = path.is_dir()
+
+        modified_ts = stat_info.st_mtime
+        modified_at = datetime.fromtimestamp(modified_ts, tz=timezone.utc).isoformat()
+
+        result: dict = {
+            "exists": True,
+            "is_file": is_file,
+            "is_dir": is_dir,
+            "size_bytes": stat_info.st_size if is_file else None,
+            "size_display": CodeReaderService._format_size(stat_info.st_size) if is_file else None,
+            "modified_at": modified_at,
+        }
+
+        if is_file:
+            language = detect_language(path.name)
+            if language:
+                result["language"] = language
+
+            mime_type, _ = mimetypes.guess_type(path.name)
+            if mime_type:
+                result["mime_type"] = mime_type
+
+            result["encoding"] = "utf-8"
+
+            try:
+                content = path.read_bytes()
+                if b"\x00" not in content[:1024]:
+                    result["line_count"] = content.count(b"\n")
+                else:
+                    result["is_binary"] = True
+            except Exception:
+                pass
+
+        return result
+
+    @staticmethod
+    def _format_size(size_bytes: int) -> str:
+        """格式化文件大小显示"""
+        size = float(size_bytes)
+        for unit in ["B", "KB", "MB", "GB"]:
+            if size < 1024:
+                return f"{size:.1f} {unit}"
+            size /= 1024
+        return f"{size:.1f} TB"

timeverse_code_reader/language_map.py

@@ -0,0 +1,186 @@
+"""
+语言检测映射 - 文件扩展名到编程语言的映射
+
+功能简述:
+    提供 40+ 种常见编程语言的文件扩展名到标准化语言名称的映射。
+    与 timeverse-code-editor 的语言策略保持一致。
+
+主要方法:
+    - detect_language: 根据文件名检测编程语言类型
+"""
+
+import os
+
+# ==================== 语言扩展名映射 ====================
+
+_LANGUAGE_MAP: dict[str, str] = {
+    # Python
+    ".py": "Python",
+    ".pyi": "Python",
+    ".pyx": "Python",
+    ".pyw": "Python",
+    # TypeScript
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".mts": "TypeScript",
+    ".cts": "TypeScript",
+    # JavaScript
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    # Go
+    ".go": "Go",
+    # Rust
+    ".rs": "Rust",
+    ".rlib": "Rust",
+    # Java
+    ".java": "Java",
+    ".class": "Java",
+    # Kotlin
+    ".kt": "Kotlin",
+    ".kts": "Kotlin",
+    # C & C++
+    ".c": "C",
+    ".h": "C",
+    ".cpp": "C++",
+    ".hpp": "C++",
+    ".cc": "C++",
+    ".cxx": "C++",
+    ".hxx": "C++",
+    # C#
+    ".cs": "C#",
+    # Swift
+    ".swift": "Swift",
+    # Ruby
+    ".rb": "Ruby",
+    ".erb": "Ruby",
+    ".gemspec": "Ruby",
+    # PHP
+    ".php": "PHP",
+    ".phtml": "PHP",
+    # Shell
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    ".zshrc": "Shell",
+    ".profile": "Shell",
+    ".bashrc": "Shell",
+    # HTML
+    ".html": "HTML",
+    ".htm": "HTML",
+    ".xhtml": "HTML",
+    # CSS
+    ".css": "CSS",
+    ".scss": "SCSS",
+    ".sass": "Sass",
+    ".less": "Less",
+    # SQL
+    ".sql": "SQL",
+    # YAML / JSON
+    ".yaml": "YAML",
+    ".yml": "YAML",
+    ".json": "JSON",
+    ".jsonc": "JSON with Comments",
+    # TOML
+    ".toml": "TOML",
+    # Markdown
+    ".md": "Markdown",
+    ".mdx": "MDX",
+    # Lua
+    ".lua": "Lua",
+    # Dart
+    ".dart": "Dart",
+    # Scala
+    ".scala": "Scala",
+    # Elixir
+    ".ex": "Elixir",
+    ".exs": "Elixir",
+    # Haskell
+    ".hs": "Haskell",
+    ".lhs": "Haskell",
+    # R
+    ".r": "R",
+    ".R": "R",
+    ".rmd": "R Markdown",
+    # Perl
+    ".pl": "Perl",
+    ".pm": "Perl",
+    # Zig
+    ".zig": "Zig",
+    # GraphQL
+    ".graphql": "GraphQL",
+    ".gql": "GraphQL",
+    # Protocol Buffers
+    ".proto": "Protocol Buffers",
+    # Docker
+    "Dockerfile": "Dockerfile",
+    "Containerfile": "Dockerfile",
+    # Makefile
+    "Makefile": "Makefile",
+    "makefile": "Makefile",
+    "GNUmakefile": "Makefile",
+    # Terraform
+    ".tf": "Terraform",
+    ".tfvars": "Terraform",
+    # Vue
+    ".vue": "Vue",
+    # Svelte
+    ".svelte": "Svelte",
+    # Astro
+    ".astro": "Astro",
+    # Prisma
+    ".prisma": "Prisma",
+    # CMake
+    ".cmake": "CMake",
+    "CMakeLists.txt": "CMake",
+    # Nix
+    ".nix": "Nix",
+    # ReasonML / OCaml
+    ".ml": "OCaml",
+    ".mli": "OCaml",
+    ".re": "ReasonML",
+}
+
+# 无扩展名的特殊文件名映射（如 Dockerfile, Makefile）
+_NAMELESS_MAP: dict[str, str] = {
+    "Dockerfile": "Dockerfile",
+    "Containerfile": "Dockerfile",
+    "Makefile": "Makefile",
+    "GNUmakefile": "Makefile",
+    "CMakeLists.txt": "CMake",
+}
+
+
+def detect_language(filename: str) -> str | None:
+    """
+    根据文件名检测编程语言类型
+
+    优先匹配文件扩展名，再匹配特殊文件名（如 Dockerfile, Makefile）。
+
+    Args:
+        filename: 文件名（可包含路径）
+
+    Returns:
+        标准化语言名称，无法识别返回 None
+
+    Example:
+        >>> detect_language("main.py")
+        'Python'
+        >>> detect_language("Dockerfile")
+        'Dockerfile'
+        >>> detect_language("unknown.xyz")
+        None
+    """
+    base = os.path.basename(filename)
+
+    # 先尝试完全匹配特殊文件名
+    if base in _NAMELESS_MAP:
+        return _NAMELESS_MAP[base]
+
+    # 再按扩展名匹配
+    _, ext = os.path.splitext(base)
+    if ext:
+        return _LANGUAGE_MAP.get(ext.lower())
+
+    return None

timeverse_code_reader/server.py

@@ -0,0 +1,105 @@
+"""
+timeverse-code-reader MCP 服务器 - 文件读取工具
+
+功能简述:
+    使用 FastMCP 框架实现的标准 stdio MCP 服务器。
+    提供 3 个文件读取工具，可通过任何 MCP 客户端调用。
+
+主要工具清单:
+    - read_file: 读取文件内容（支持行范围）
+    - list_directory: 列出目录内容
+    - get_file_info: 获取文件元数据
+
+使用示例:
+    # 作为独立进程运行
+    timeverse-code-reader
+
+    # 在 MCP 客户端中配置
+    {
+        "command": "timeverse-code-reader",
+        "args": []
+    }
+"""
+
+# ==================== 导入依赖 ====================
+
+from mcp.server import FastMCP
+
+from timeverse_code_reader.handler import CodeReaderService
+
+# ==================== MCP 服务器初始化 ====================
+
+# 创建 MCP 服务器实例
+app = FastMCP("timeverse-code-reader")
+
+# ==================== 工具注册 ====================
+
+
+@app.tool()
+def read_file(
+    path: str,
+    start_line: int | None = None,
+    end_line: int | None = None,
+) -> str:
+    """
+    读取指定文件的内容
+
+    Args:
+        path: 文件路径，支持绝对路径或基于工作区的相对路径
+        start_line: 起始行号（从 1 开始），不传则从文件开头读取
+        end_line: 结束行号，不传则读到文件结尾
+
+    Returns:
+        文件内容的纯文本字符串
+
+    Raises:
+        FileNotFoundError: 文件不存在
+        ValueError: 行号参数不合法
+    """
+    return CodeReaderService.read_file(path, start_line, end_line)
+
+
+@app.tool()
+def list_directory(path: str) -> list[dict]:
+    """
+    列出指定目录下的文件和子目录（不递归）
+
+    Args:
+        path: 目录路径，支持绝对路径或相对路径
+
+    Returns:
+        条目列表，每项包含 name, type(file/dir), size
+
+    Raises:
+        FileNotFoundError: 目录不存在
+        NotADirectoryError: 路径不是目录
+    """
+    return CodeReaderService.list_directory(path)
+
+
+@app.tool()
+def get_file_info(path: str) -> dict:
+    """
+    获取文件或目录的元数据
+
+    返回文件大小、最后修改时间、编程语言类型、行数等信息。
+
+    Args:
+        path: 文件或目录路径
+
+    Returns:
+        元数据字典，包含 exists, is_file, size_bytes, language 等
+    """
+    return CodeReaderService.get_file_info(path)
+
+
+# ==================== 入口 ====================
+
+
+def main():
+    """命令行入口"""
+    app.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

timeverse_code_reader-0.1.1.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: timeverse-code-reader
+Version: 0.1.1
+Summary: TimeVerse File Reader MCP Tool - 读取文件内容、列出目录、获取文件元数据
+Project-URL: Homepage, https://github.com/elimyliu/timeverse-code-reader
+Project-URL: Issues, https://github.com/elimyliu/timeverse-code-reader/issues
+Author: elimyliu
+License: MIT
+License-File: LICENSE
+Keywords: code-reader,file-reader,mcp,model-context-protocol,timeverse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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

timeverse_code_reader-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+timeverse_code_reader/__init__.py,sha256=Pi64WWIXU0Nmy6Ktz-Djpo-jXv5gDrU8x4g1E7X2iBU,65
+timeverse_code_reader/cache.py,sha256=xxzW408PtwKGMTCNWSyoAKenoXWpmSwDWedwuVeNgDw,2878
+timeverse_code_reader/handler.py,sha256=FEOkxpHo2h-wxG8EBtWA_o_UkTDcj62b-lcvH87Bfao,6860
+timeverse_code_reader/language_map.py,sha256=SW8V8nMOKb9pDs98vNCBjIJ_enaGdGznMIkb9auMg6M,3946
+timeverse_code_reader/server.py,sha256=8MSWPcpD5hjtd9tWHKe9dx1BM7A5-kYNhmqLqzD1UOs,2520
+timeverse_code_reader-0.1.1.dist-info/METADATA,sha256=SOIbwaynpugV5rCJQDtvFL1X4pR6nCctTWQNbgfhJFY,8995
+timeverse_code_reader-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+timeverse_code_reader-0.1.1.dist-info/entry_points.txt,sha256=HLeN1XzaHhqALORnxOiyoTWG89_7rnt6jnZ4cI-OE0c,76
+timeverse_code_reader-0.1.1.dist-info/licenses/LICENSE,sha256=1PQpLpEMW2ZvpQi_e5F9Hwj2mzly0KShtQY9yH9ahnc,1065
+timeverse_code_reader-0.1.1.dist-info/RECORD,,

timeverse_code_reader-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

timeverse_code_reader-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+timeverse-code-reader = timeverse_code_reader.server:main

timeverse_code_reader-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 elimyliu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.