jarvis

jarvis（在 PyPI 上发布为 jarvis-mcp）是一个为编程智能体设计的本地优先代码智能层。它以 Model Context Protocol (MCP) 服务器的形式提供，通过 stdio 通信，因此 Claude Code、Cursor、Claude Desktop 或任何其他 MCP 客户端都可以查询已索引的代码库。它没有托管服务，无需身份验证，也没有网络依赖：所有数据都不会离开本机。 两个部分的协作方式 该项目刻意分为写入端（writer）和读取端（reader），两者仅共享一个约定：一个本地数据目录（默认为 ~/.jarvis）。 - 索引 CLI：jarvis index 接收代码库路径，为每个支持的文件构建 Tree-sitter 语法基准，可选地运行该语言的 SCIP 索引器并将输出转换为 SQLite，构建 Zoekt 分片及可选的嵌入向量（embeddings），然后将所有内容发布为一个由小型当前指针选定的不可变快照。 - 运行时：jarvis-server 通过 stdio 暴露工具，由延迟单例（lazy singletons）支撑。zoekt-webserver 在首次搜索时启动，并通过 pidfile 在进程间共享。 查询以只读方式打开已发布的数据库，因此服务路径永不写入。发布过程是原子的；当重新索引切换指针时，读取旧文件的查询仍可继续工作，且任何可选阶段的失败都会保留之前的快照。每次重新索引还会重建该代码库的传出包边（outgoing package edges），而不是将其累积。 九个 MCP 工具 goToDefinition 将符号解析为其定义文件和范围，在有 SCIP 定义覆盖的文件中使用 SCIP 提供，否则使用语法基准声明，每个位置都会标记提供者。findReferences 列出符号的出现位置，仅限 SCIP。callHierarchy 返回调用入栈和出栈，仅限 SCIP。typeHierarchy 返回超类型和子类型，仅限 SCIP。documentSymbols 列出单个文件中定义的符号，根据文件在 SCIP 纲要和 Tree-sitter 声明之间路由。searchCode 执行 Zoekt 词法或正则表达式搜索，支持可选的代码库过滤。semanticSearch 是自然语言搜索，使用互惠排名融合（reciprocal rank fusion）将向量命中、Zoekt 命中和 SCIP 符号定义匹配相结合。blastRadius 显示哪些其他已索引的代码库依赖于某个包（最多两跳）。getIndexStatus 报告发布的提交版本、新鲜度、相对于工作树的陈旧度以及每个工具的提供者能力。 仅限 SCIP 的工具在缺失数据时不会静默返回空结果，而是报告所需的权限、原因和恢复提示。工具失败将作为负载对象返回而非传输错误，因此错误的查询不会导致 stdio 服务器崩溃。 索引与监听 命令包括 jarvis index, list, status, reindex 和 forget，以及使用可选 watchdog 扩展进行自动重新索引（默认防抖时间为五秒）的 jarvis watch。语言通过 git 跟踪文件的扩展名出现频率自动检测，也可通过 --language 覆盖。状态值包括 indexing（索引中）、indexed（已索引）、partial（部分）、degraded（降级）和 failed（失败）；降级运行仍会发布语法基准并以退出码 0 退出，同时记录原因。 要求与限制 该项目明确其定位较为狭窄： - 仅支持 macOS 和 Linux；不支持 Windows。 - 每个代码库仅限一种语言；多语言 monorepos 将按跟踪文件最多的语言进行索引。 - 无需构建的 Tree-sitter 基准覆盖 17 种语言（Python, JavaScript, TypeScript/TSX, Java, Kotlin, Swift, Go, Ruby, Rust, C, C++, C#, PHP, Scala, Bash, SQL），并作为包本身的 pip 依赖安装。 - 精确的 SCIP 导航覆盖四个语言家族：TypeScript/TSX, Python, Java/Kotlin 和 Swift。 - 可选的 SCIP 和 Zoekt 增强需要通过安装脚本安装外部二进制文件：scip (最低 v0.9.0), zoekt-git-index 和 zoekt-webserver, universal-ctags, scip-typescript, scip-python, scip-swift (仅限 macOS arm64) 和 scip-java (仅检测，在拉取 Docker 镜像前会询问)。 - 索引是一个显式步骤；没有任何内容是实时分析的。 - jarvis 是只读的，从不编辑代码。README 将其定位为 Serena 的补充，后者处理语义重命名和重构。 搜索与配置 semanticSearch 需要可选的 semantic 扩展 (lancedb 和 sentence-transformers)，并将基于 Tree-sitter 分块代码的向量搜索与词法结果融合。语义索引遵循 .gitignore，跳过超过 1 MB 的文件和生成文件的启发式判断，所有这些都可以通过 include 标志覆盖。环境变量涵盖数据目录和嵌入查询/文档指令前缀，并能自动检测 bge-m3, e5 和 nomic-embed 模型。 README 还记录了已知的上游 SCIP 限制（类型层级中声明但未写入的关系数据、回填的显示名称和种类、scip-java 无法索引 Android/Gradle 仓库、Kotlin 要求编译器版本精确匹配，以及基于 Maven 的 Java 构建对 bash 版本的要求），并将这些视为底层工具的行为而非 jarvis 的 bug。该插件随附三个 Claude Code 智能体技能：jarvis-setup, jarvis-use 和 jarvis-issues。项目采用 MIT 许可，测试套件使用 pytest 运行，其中调用真实索引器二进制文件的集成测试被单独标记。