Ultrascript Tools MCP

         ██  ██
         ██  ██  ██    ██████ █████▄  ▄████▄
         ██  ██  ██      ██   ██▄▄██▄ ██▄▄██
         ██  ██  ██      ██   ██   ██ ██  ██
         ██  ██  ██████  ██   ██   ██ ██  ██
         ▀████▀          ▄████ ▄████▄ █████▄ █████
                         ██    ██  ██ ██  ██ ██▄▄▄
                         ▀████ ▀████▀ █████▀ ██▄▄▄

](https://www.npmjs.com/package/ultracode)   ](https://nodejs.org/)

用于快速准确代码工作的代码库RAG

🌐 语言EN 俄

______________________________________________________________________

用于AI编码代理的MCP服务器。构建完整的代码结构图（实体、关系、控制流、复杂性）和语义向量索引。AI代理查询图形而不是读取文件，并通过行引用获得精确、详尽的答案。

为什么这很重要

如果没有结构化索引，探索代码库的AI代理必须 grep → 读取文件→ 跟踪进口→ grep再次→ 读取更多文件。每一步都需要花费代币和时间。丢失的连接会导致修复不完整。代理中断代码、检查、修复、再次中断——对于单个任务，这个循环可以重复10-20次。

使用UltraCode，同一代理可以 一次MCP呼叫 并在一个响应中返回所有受影响的实体、它们的关系、调用者和影响。没有文件读取循环，没有丢失的连接。

实践中有什么变化

索引速度

中等项目（约500个文件）的完整索引在中完成 3-5秒 （并行解析+批处理SQL+流式嵌入）。大型项目，如VS Code（约180万LOC，7000多个文件）-- 约82秒 包括全嵌入生成。之后， GitWatcher 索引仅更改文件——通常 200ms以下 每次更改。

安装

该项目针对以下方面进行了优化 包子 （另一种JavaScript运行时），运行速度提高了50%。

Bun+UltraCode （推荐--安装+设置）：

# macOS / Linux
curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bun i -g ultracode --trust && ultracode-setup

# Windows (PowerShell)
irm bun.sh/install.ps1 | iex; bun i -g ultracode --trust; ultracode-setup

仅限UltraCode （Bun已安装）：

bun i -g ultracode --trust && ultracode-setup

npm （可选--安装+设置）：

npm install -g ultracode && ultracode-setup

如果 ultracode-setup npm安装后失败（路径与bun冲突），使用： node "$(npm root -g)/ultracode/dist/cli/setup-command.js"

为什么 --trust 为了Bun？ 默认情况下，Bun会阻止安装后脚本。 --trust 允许本地插件构建（better-sxlite3、cbor extract、protobufjs）——所有合法的依赖项。

备注：对于不同语言的完整代码分析，需要运行时： - TypeScript/JavaScript-内置（TypeScript编译器API） - Python——需要Python 3.8+(python --version) - Java/Kotlin——需要JRE 11+(java --version) - Go--需要Go 1.18+(go version) - Rust——需要Rust工具链(rustc --version) - C#需要。NET SDK 8+(dotnet --version) - Zig——内置（基于正则表达式，不需要Zig工具链） - C/C++——需要Clang 12+(clang --version)

Claude代码配置 (~/.claude.json):

{
  "mcpServers": {
    "ultracode": {
      "command": "ultracode"
    }
  }
}

配置： .autodoc/claude.cfg/add-to-claude.md

本地模型设置

局部模型用于智能任务：嵌入模型用于语义搜索，LLM用于AutoDoc。这将从您的主AI代理中删除令牌成本。

安装后，安装向导将启动并下载和配置所需的一切。

步骤1：嵌入提供者 （语义搜索）

GTX xx50/xx60笔记本电脑的注意事项（GPU热节流） 笔记本电脑上的预算NVIDIA GPU（GTX 1650/1660、RTX 3050/3060、RTX 4050/4060）经常受到功率限制限制的限制，这会使TEI/vLLM嵌入吞吐量下降约1000 emb/s。GPU达到功率限制（PL1）并在批处理过程中停止运行。 通过修复 油门停止 （Windows）： 1. TPL 按钮→ set PL1 最大功率（笔记本电脑为55-75W）， PL2 最大功率（90-120W）， 涡轮增压时间限制 → 28 秒（最大），启用 夹钳PL1/PL2 （TPL按钮变绿） 1. 主窗口→ 速度换档-EPP → 0 （最大性能，减少CPU限制） 1. BD PROCHOT 偏移 → 0 （禁用GPU的CPU热触发） 1. 限制原因 → 检查阻塞的内容（如果是“MS Platform”--忽略） 1. 应用 → 保存配置文件。CPU为GPU提供热预算，TEI批次稳定。 这通常会给出 +1000电磁脉冲/秒 受影响的硬件。

步骤2:LLM提供者 （自动文档，重构）

向导会自动执行以下操作：

• 检测您的GPU（NVIDIA Turing/Ampere/Ada/Hopper/Blackwell\*）
• 为您的硬件推荐最佳型号
• 安装选定的提供程序
• 将配置保存到系统目录

重新运行向导： ``bash # Bun bunx ultracode setup # Node.js npx ultracode setup ``

\*对于Blackwell（RTX 50xx），使用非官方的TEI分叉

AUTODOC设置

要激活自动文档模式，请创建 .autodoc 项目根目录中的文件夹，并启用LLM使用（最容易使用相同的claude）。

在启用自动文档模式的情况下运行UltraCode后：

1. 在所有包含源代码（来自支持的语言）的文件夹中，将创建AUTODOC.md文件，并使用目录中列出文件的模板。
2. LLM将遍历这些文件，并在AUTODOC.md中生成描述——文件中的代码具体做什么。

在此之后，您可以自己（或在AI代理的帮助下）在.autodoc目录中创建所需的项目概述文件，并在需要的地方在autodoc.md文件中添加“人类描述”。在那里，您可以直接引用文件中的代码行（为了描述代码块的开始和结束，请使用两个数字。例如：FILE:XX-ZZ）。UltraCode将跟踪代码更改，并自动更新所有代码引用以保持其最新状态。它不会触及文档文本。

macOS苹果硅（MLX嵌入）

通过Apple MLX框架（Metal GPU）原生嵌入支持：

• MLX提供商 自动检测macOS ARM64并使用Metal GPU
• 安装向导将MLX设置为Apple Silicon上的默认值
• 模型： intfloat/multilingual-e5-base （768d）， intfloat/multilingual-e5-small （384d）， BAAI/bge-m3 （1024d，8K上下文）
• 自动安装带有依赖项的Python venv，从HuggingFace下载模型

# Re-run wizard to switch to MLX:
bunx ultracode setup
# Select "MLX" → auto-setup venv + model + server on port 8087

GPU加速（CUDA/WIGPU/金属）

# macOS: Metal backend for CUDA-like acceleration
# Build requirements:
#   - Xcode Command Line Tools: xcode-select --install
#   - Homebrew: https://brew.sh
#   - CMake: brew install cmake
./node_modules/ultracode/scripts/build-native-libs-macos.sh

特性

MCP服务器提供 78工具 用于代码分析和修改。

搜索与导航

代码分析

静态跟踪和调试

所有跟踪和诊断工具均支持 highlightRecentChanges=true --交叉引用发现了具有Prolly Tree提交历史的实体，并注释了最近修改的代码。这有助于确定可能的根本原因：首先要查找崩溃呼叫链或决策点中最近更改的实体。

架构图

代码修改

代码验证

文档（AutoDoc）

Git集成

多代理工作树支持

多个AI代理可以并行工作，每个代理在单独的分支上的git工作树中。UltraCode通过以下方式检测所有工作树是否属于同一存储库 repoIdentity --一个稳定的哈希 git-common-dir所有工作树共享一个索引、一个数据库和一个服务器进程。

从代理编排器启动

任何编排器（Claude Code、自定义脚本、CI/CD）都可以启动具有完整代码智能的并行代理。每个代理通过轻量级 ultracode.com 代理（约700KB，跨平台）。

步骤1：创建工作树

cd /path/to/your/project

# Create a worktree per agent (each on its own branch)
git worktree add ../wt-auth   -b feature/auth   main
git worktree add ../wt-pay    -b feature/payments main
git worktree add ../wt-tests  -b feature/tests    main

步骤2：使用UltraCode MCP启动代理

每个代理都连接到 运行相同的UltraCode服务器 通过命名管道（Windows）或Unix套接字（Linux/macOS）。代理二进制文件处理连接、自动启动和初始化握手。

# Agent 1: auth feature
ultracode.com --pipe \
  --directory ../wt-auth \
  --branch feature/auth \
  --agent-id auth-agent

# Agent 2: payments feature
ultracode.com --pipe \
  --directory ../wt-pay \
  --branch feature/payments \
  --agent-id pay-agent

# Agent 3: test writing
ultracode.com --pipe \
  --directory ../wt-tests \
  --branch feature/tests \
  --agent-id test-agent

步骤3：在中配置 claude_desktop_config.json 或MCP客户端

{
  "mcpServers": {
    "ultracode-auth": {
      "command": "ultracode.com",
      "args": ["--pipe", "--directory", "/path/to/wt-auth",
               "--branch", "feature/auth", "--agent-id", "auth-agent"]
    },
    "ultracode-pay": {
      "command": "ultracode.com",
      "args": ["--pipe", "--directory", "/path/to/wt-pay",
               "--branch", "feature/payments", "--agent-id", "pay-agent"]
    }
  }
}

运作原理

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Agent #1   │   │  Agent #2   │   │  Agent #3   │
│  wt-auth    │   │  wt-pay     │   │  wt-tests   │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       │ stdin/stdout    │ stdin/stdout    │ stdin/stdout
       ▼                 ▼                 ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ultracode.com│ │ ultracode.com│ │ ultracode.com│
│   (proxy)    │ │   (proxy)    │ │   (proxy)    │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                │
       └────────┬───────┘────────┬───────┘
                │  Named Pipe    │
                ▼                ▼
        ┌───────────────────────────────┐
        │     UltraCode MCP Server      │
        │   (single process, shared)    │
        │                               │
        │  repoIdentity: same for all   │
        │  Index: shared base + deltas  │
        │  Locks: per branch            │
        └───────────────────────────────┘

• 共享索引：所有工作台使用一个 repoIdentity → 一个数据库，一个FAISS索引池
• 分支隔离：每个代理对其自己的分支增量进行索引；不同分支的并行索引是安全的
• 锁协调：如果两个代理位于同一分支上，则只有一个索引--另一个等待并跳过
• 会话发现：代理可以通过以下方式互相查看 list_worktree_agents --可用于任务切换
• 子模块/子树感知：子模块有自己的 repoIdentity；子树被检测为父仓库的一部分

清理

# Remove worktrees when done
git worktree remove ../wt-auth
git worktree remove ../wt-pay
git worktree remove ../wt-tests

# Or via MCP tool (from any agent):
# cleanup_worktree({ branch: "feature/auth" })

版本历史（Prolly树）

Prolly Tree以提交级粒度存储完整的实体历史。超越时间旅行，它为 最近更改上下文 特点：10个诊断工具(analyze_stacktrace, detect_patterns, analyze_state_chaos, trace_flow, trace_backwards, trace_data_flow, analyze_state_impact, find_decision_points, analyze_code_impact, analyze_hotspots)可以通过以下方式用最近更改的实体状态注释其结果 highlightRecentChanges=true这意味着人工智能代理不仅能看到“损坏的地方”，还能看到“最近可能导致损坏的地方发生了什么变化”

语义合并

快照和安全

代码图和索引

度量和监控

______________________________________________________________________

附加功能

演出

• SIMD/WebAssembly --内置CPU加速
• CUDA/FAISS --大型项目的GPU加速
• WebGPU/黎明 --跨平台GPU加速
• 流媒体索引 --并行解析和索引
• 本地嵌入 --无外部API的TEI/Ollama/vLLM/MLX

语言支持

传说：

• 实体 --函数、类、接口、类型、枚举、变量
• 关系 --导入、调用、扩展、实现、引用
• 指标 --圈、认知复杂性、控制流、文档
• 类型 --类型推理、类型引用、泛型

每种语言的详细信息： .autodoc/特性/语言解析器.md

低资源语言倡议

00000001生命很重要！

我们有意投资于对鲜为人知但前景光明的语言和框架的一流支持，这样他们的社区就可以获得主流生态系统所享有的强大代码智能。

目前支持： Zig——完整的实体提取、关系、控制流和复杂性度量。Swift——完整的实体，包括SwiftUI属性包装器、继承/协议一致性分割、控制流。

更多语言即将到来。如果你最喜欢的小众语言值得更好的工具-- 打开一个问题.

框架

内置文档（MCP提示）

您可以添加 简短提示 您的系统提示将帮助AI代理了解UltraCode功能。

• 快速启动 --快速启动和工具选择
• 工具参考 --72种工具的完整参考
• 工作流 --准备好的场景：分析、重构、重复检测
• 追踪指南 --跟踪与调试指南

UltraCode代理

• 任务分配 --将复杂任务移交给 /ultracode 代理
• 最大效率 --代理自己选择最佳工具
• 综合分析 --在一个请求中搜索、跟踪、重构
• 自然语言 --用你自己的话描述任务

客户端-服务器体系结构

• 每台机器一个流程 --运行多个AI代理时，只运行一个UltraCode实例
• 节省10+GB RAM --而不是内存中的N个索引副本——一个共享
• 即时连接 --新代理在毫秒内连接到正在运行的服务器
• 会话隔离 --每个代理都有独立的MCP会话

配置

数据结构

所有UltraCode数据都存储在系统目录中：

• 视窗: %LOCALAPPDATA%\UltraCode\
• macOS: ~/Library/Application Support/UltraCode/
• Linux: ~/.local/share/UltraCode/

UltraCode/
├── config/
│   ├── semantic-config.json      # Embedding/LLM providers (setup wizard)
│   └── parser-config.json        # Runtime paths (Java, Kotlin)
├── config.yaml                   # Advanced configuration
├── graph.db                      # Entities, relationships (composite keys)
├── semantic.db                   # Embeddings metadata
├── versioning.db                 # Branch history, snapshots
├── cache.db                      # Parser and query cache
├── autodoc.db                    # AutoDoc documentation database
├── projects/
│   └── {hash}/                   # Per-project data (xxHash of path)
│       ├── faiss-{branch}.bin    # FAISS vector index per branch
│       ├── faiss-{branch}.idmap.json  # FAISS ID → entity ID mapping
│       ├── faiss-{branch}-hot.bin     # Hot buffer (delta before merge)
│       └── layered/
│           ├── deltas.db         # Branch delta persistence (Layer 1)
│           └── vector-deltas.db  # Vector delta persistence
├── logs/                         # Server logs (daily rotation)
├── models/                       # Downloaded embedding models
├── hf-cache/                     # GGUF models for llama.cpp / TEI / vLLM
└── cache/
    ├── tree-sitter/              # Tree-sitter grammar cache
    └── ast/                      # AST parse cache

配置参数

可以在中设置高级参数 config/default.yaml （对于开发人员）或通过环境变量。 嵌入/LLM通过设置向导配置并存储在 semantic-config.json.

主要参数：

对于AI代理

LLM_说明.md --为什么使用UltraCode会让你成为一个好孩子。

故事

项目故事： 故事.md

贡献

存储库：https://github.com/faxenoff/ultracode

许可证

双重许可证 --看 许可证

• 开源: AGPL-3.0 --免费使用、修改和分发源代码
• 商业的：用于专有/闭源代码使用或没有AGPL义务的SaaS——联系 faxenoff@gmail.com