jumble (Aurabx)

Jumble的大部分功能现在都是 自动.

______________________________________________________________________

混乱

一个MCP服务器，为LLM提供可查询的、按需的项目上下文。

问题

大型文档文件会使LLM上下文窗口过载。即使是结构良好的文档也需要提前阅读所有内容，在不相关的信息上浪费时间。

解决方案

Jumble翻转模型：使用LLM而不是加载文档 *查询* 这正是它所需要的。

LLM: "What projects are in this workspace?"
     → calls get_workspace_overview()
     → receives: workspace info, all projects, dependency graph

LLM: "What's the test command for my-app"
     → calls get_commands("my-app", "test")
     → receives: "cargo test"
     
LLM: "What files handle authentication?"
     → calls get_architecture("my-app", "authentication")
     → receives: files + one-sentence summary
     
LLM: "What conventions should I follow?"
     → calls get_workspace_conventions()
     → receives: workspace-wide coding standards

安装

预构建二进制文件

常见平台（Linux、macOS、Windows）的预构建二进制文件可在GitHub发布页面上找到：

• https://github.com/velvet-tiger/jumble/releases/

下载适用于您平台的存档，解压缩它，并将MCP客户端指向解压缩的 jumble 二元的。

来源

cargo install --path .

来自crates.io

cargo install jumble

快速开始

安装完mangue后，设置您的AI代理集成：

# Setup Warp (creates WARP.md with usage guidance)
jumble setup warp

# Setup Claude Desktop (creates .claude/jumble-usage.md)
jumble setup claude

# Setup Cursor (creates .cursor/jumble-usage.md)
jumble setup cursor

# Setup Windsurf (creates .windsurf/jumble-usage.md)
jumble setup windsurf

# Setup Codex (creates .codex/jumble-usage.md)
jumble setup codex

# Use --global to create config in home directory instead
jumble setup cursor --global

每个设置命令将：

• 创建使用文档，指导AI代理有效地使用杂乱
• 检查杂乱是否配置为MCP服务器
• 如果需要，提供精确的复制粘贴配置
• 警告如果 .jumble/project.toml 缺失

配置

Jumble通过扫描以下内容来发现项目 .jumble/project.toml 文件夹。它还寻找 .jumble/workspace.toml 在根目录下进行工作空间级别的配置。

启动时，Jumble还会在以下位置查找全局配置文件 ~/.jumble/jumble.toml （或特定于平台的主目录）。如果此文件 不存在，Jumble将用最小值创建它

[jumble]

为未来选项保留的部分。

项目和工作区元数据在服务器启动时加载一次，并缓存在内存中。如果你改变任何 .jumble/* 文件，重新启动 jumble 处理或调用 reload_workspace 工具（见下文），无需重新启动即可获取更改。

通过以下方式设置根目录：

1. JUMBLE_ROOT 环境变量
2. --root CLI参数
3. 当前工作目录（默认）

与Warp一起使用

推荐： 使用setup命令自动配置扭曲：

jumble setup warp

这创造了 WARP.md 告诉Warp的人工智能代理的指导：

• 始终从以下内容开始 get_workspace_overview() 进入工作空间时
• 何时使用每个杂乱工具（在建议命令、进行更改等之前）
• 如何处理缺失的上下文
• 完整的工作流程示例

您可以在WARP.md中强制更新混乱部分：

jumble setup warp --force

手动MCP配置

添加到曲速MCP配置中：

{
  "jumble": {
    "command": "jumble",
    "args": ["--root", "/path/to/your/workspace"]
  }
}

使用Claude Desktop

推荐： 使用setup命令：

# Project-specific (creates .claude/jumble-usage.md)
jumble setup claude

# Global (creates ~/.claude/jumble-usage.md)
jumble setup claude --global

setup命令创建了一个全面的使用指南，并检查Claude Desktop中是否配置了混乱。

手动MCP配置

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jumble": {
      "command": "/path/to/jumble",
      "args": ["--root", "/path/to/your/workspace"]
    }
  }
}

Jumble从多个来源自动发现技能：

• .jumble/skills/*.md -项目特定的扁平化技能
• ~/.jumble/skills/*.md -跨项目共享个人/全球扁平技能
• .claude/skills/**/SKILL.md -克劳德式结构化技能（项目本地）
• ~/.claude/skills/**/SKILL.md -个人/全球克劳德风格结构化技能
• .codex/skills/**/SKILL.md -Codex风格的结构化技能（项目本地和 $HOME)

结构化技能（Claude/Codex格式）可以包括配套资源，如 scripts/, references/, docs/, assets/，以及 examples/ 子目录。当你用 get_skill，会自动列出伴随文件。

与Windsurf一起使用

推荐： 使用setup命令：

# Project-specific (creates .windsurf/jumble-usage.md)
jumble setup windsurf

# Global (creates ~/.codeium/windsurf/jumble-usage.md)
jumble setup windsurf --global

手动MCP配置

Windsurf的Cascade MCP配置使用与Claude Desktop的配置相同的形状。创建或编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "jumble": {
      "command": "/absolute/path/to/jumble",
      "args": ["--root", "/path/to/your/workspace"]
    }
  }
}

重新启动Windsurf，以便Cascade重新加载MCP服务器，然后验证 jumble 出现在工具列表中。

使用游标

推荐： 使用setup命令：

# Project-specific (creates .cursor/jumble-usage.md and .cursor/mcp.json)
jumble setup cursor

# Global (creates ~/.cursor/jumble-usage.md and ~/.cursor/mcp.json)
jumble setup cursor --global

手动MCP配置

游标从读取MCP配置 mcp.json 在您的项目中 .cursor 目录或您的主目录。

全局配置（适用于所有项目），在 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "jumble": {
      "command": "/absolute/path/to/jumble",
      "args": ["--root", "/path/to/your/workspace"]
    }
  }
}

或者，添加相同的内容 mcpServers 阻止 .cursor/mcp.json 在单个项目中确定范围 jumble 仅限于该项目。

使用Codex

推荐： 使用setup命令：

# Project-specific (creates .codex/jumble-usage.md)
jumble setup codex

# Global (creates ~/.codex/jumble-usage.md)
jumble setup codex --global

手动MCP配置

Codex将MCP配置存储在 ~/.codex/config.toml.

使用Codex CLI：

codex mcp add jumble -- /absolute/path/to/jumble --root /path/to/your/workspace

或编辑 ~/.codex/config.toml 直接：

[mcp_servers.jumble]
command = "/absolute/path/to/jumble"
args = ["--root", "/path/to/your/workspace"]

重新启动Codex IDE扩展或TUI，并确认 jumble 被列为MCP服务器。

创建上下文文件

上下文文件被设计为由读取它们的相同AI代理创建。看 授权.md 完整的指南。

示例提示：

Create jumble context for this project.

Read the AUTHORING.md guide at /path/to/jumble/AUTHORING.md, then examine this project's structure to create:

1. .jumble/project.toml (required) - Extract project info from manifest files, identify key commands, map architectural concepts to files
2. .jumble/conventions.toml - Capture patterns to follow and gotchas to avoid (look at existing code patterns, comments, and any constitution.md or similar files)
3. .jumble/docs.toml - Index the docs/ directory if it exists, with one-line summaries

Jumble核心概念

这些字段出现在 .jumble/project.toml / .jumble/workspace.toml 并且是MCP工具向AI展示的内容。

• 命令 ([commands])

- 命名的、可复制粘贴的CLI命令的小地图（例如。 build, test, lint, run, dev). - 被...使用 get_commands(project, command_type) 和 get_project_info(..., field: "commands") 所以AI可以告诉你 *确切地* 如何在不猜测的情况下构建、测试或运行项目。

• 入口点 ([entry_points])

- 项目最重要源文件的标签（例如。 main = "src/main.rs", api = "src/api/mod.rs"). - 表面在 get_project_info(project) 因此，AI在探索新代码库时可以直接跳到正确的文件。

• 概念/架构 ([concepts.*])

- 每个概念都用简短的摘要和文件列表描述了一个架构区域，例如： - concepts.authentication.files = ["src/auth/mod.rs"] - concepts.authentication.summary = "JWT-based auth via middleware" - get_architecture(project, concept) 返回一个概念的完整描述和文件列表。 - get_related_files(project, query) 按名称/摘要搜索所有概念以查找相关文件（例如“数据库”、“路由”）。

• 文件索引 (.jumble/docs.toml)

- 一个包含一行摘要的轻量级人工编写文档索引（README、设计文档、ADR等）。 - get_docs(project) 列出所有主题和摘要，以便AI在阅读之前选择正确的文档。 - get_docs(project, topic) 返回单个文档的解析文件系统路径。

• 编码约定和陷阱 (.jumble/conventions.toml 和工作空间 [conventions] / [gotchas])

- 项目级别 conventions.toml 捕捉单个项目要遵循的模式和要避免的锐边。 - 工作空间级别 [conventions] / [gotchas] 在 .jumble/workspace.toml 描述跨项目标准和陷阱。 - get_conventions(project, ...) 返回特定于项目的约定/陷阱。 - get_workspace_conventions(...) 返回工作区范围的标准或陷阱。

• 相关项目 ([related_projects])

- 描述同一工作区中的项目如何相互依赖： - upstream = ["shared-lib"] → 这个项目所依赖的。 - downstream = ["examples"] → 依赖于此的项目。 - get_workspace_overview() 使用它来构建一个简单的文本依赖图，这样AI就可以看到项目是如何组合在一起的。

• 工作区 (.jumble/workspace.toml)

- 描述整个工作区/monorepo：名称、描述和共享约定/gotshas。 - get_workspace_overview() 返回工作区元数据以及所有项目的列表。 - get_workspace_conventions() 返回适用于多个项目的工作区级约定和陷阱。

项目背景

创建一个 .jumble/project.toml 在每个项目中：

[project]
name = "my-project"
description = "One-line description"
language = "rust"

[commands]
build = "cargo build --release"
test = "cargo test"
lint = "cargo clippy"

[entry_points]
main = "src/main.rs"

[concepts.authentication]
files = ["src/auth/mod.rs"]
summary = "JWT-based auth via middleware"

[related_projects]
upstream = ["shared-lib"]    # projects this depends on
downstream = ["examples"]    # projects that depend on this

工作区上下文

创建一个 .jumble/workspace.toml 在工作空间根目录下：

[workspace]
name = "My Workspace"
description = "Monorepo for my projects"

[conventions]
error_handling = "Use anyhow for apps, thiserror for libraries"
testing = "Unit tests in same file, integration tests in tests/"

[gotchas]
feature_flags = "Features enabled by one project affect all dependents"

可选文件

• .jumble/conventions.toml -项目特定惯例和陷阱
• .jumble/docs.toml -带摘要的文档索引
• .jumble/skills/*.md -常见操作的特定任务技能（项目本地）
• ~/.jumble/skills/*.md -跨项目应用的个人/全球技能

看 授权.md 完整的指南。

可用工具

工作区工具

get_workspace_overview

返回工作区信息、所有带有描述的项目和依赖关系图。 先叫这个 了解工作空间结构。

get_workspace_overview()

get_workspace_conventions

返回适用于所有项目的工作区级别约定和陷阱。

get_workspace_conventions()
get_workspace_conventions(category: "gotchas")

reload工作空间

从磁盘重新加载工作区和项目元数据。编辑后使用此功能 .jumble 如果您想避免重新启动MCP服务器，请使用文件。

reload_workspace()

get_jumble_authoring_prompt

返回一个规范提示，您可以将其提供给AI助手生成 .jumble 任何项目的上下文文件（项目、工作区、约定、文档）。

get_jumble_authoring_prompt()

项目工具

list_项目

列出所有已发现的项目及其描述。

get_project_info

返回有关项目的元数据（描述、语言、版本、入口点）。

get_project_info(project: "my-project")
get_project_info(project: "my-project", field: "dependencies")

get_命令

返回项目的可执行命令。

get_commands(project: "my-project")
get_commands(project: "my-project", command_type: "test")

get_体系结构

返回特定架构概念的文件和摘要。

get_architecture(project: "my-project", concept: "authentication")

获取相关文件

搜索概念并返回匹配的文件。

get_related_files(project: "my-project", query: "database")

get_conventions

返回特定于项目的编码约定和gotchas。

get_conventions(project: "my-project")
get_conventions(project: "my-project", category: "gotchas")

get_docs

返回包含摘要的文档索引或特定文档的路径。

get_docs(project: "my-project")
get_docs(project: "my-project", topic: "configuration")

list_skills/get_skill

列出或检索常见操作的特定任务技能。

list_skills(project: "my-project")
get_skill(project: "my-project", topic: "add-endpoint")

人工智能辅助创作

Jumble的设计使AI可以为任何项目生成上下文文件：

1. schema.json -用于验证的机器可读模式
2. 授权.md -如何填充每个字段的启发式方法

当被要求“为项目X创建混乱的上下文”时，人工智能应该：

1. 阅读AUTHORING.md了解启发法
2. 检查项目的清单文件、目录结构和README
3. 生成 .jumble/project.toml （必填）
4. 可选择生成 conventions.toml, docs.toml和技能

模式验证

使用附带的JSON模式验证您的TOML文件：

# With taplo
taplo check .jumble/project.toml --schema /path/to/jumble/schema.json

许可证

麻省理工学院