Repomix MCP Server: Running Your Codebase as a Model Context Protocol Server for AI Assistants-二趣网

Repomix MCP Server: Running Your Codebase as a Model Context Protocol Server for AI Assistants

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix

本文是一份关于如何将 Repomix 以 Model Context Protocol（MCP）服务器形式运行的完整实战指南。它面向希望让 Claude、ChatGPT、Gemini 等 AI 助手直接对本地或远程代码仓库执行打包、检索与读取的开发者：通过--mcp与--sandbox两个核心标志、六大 MCP 工具的完整参数表、以及 VS Code / Cline / Cursor / Claude Desktop / Claude Code / Docker 的全套客户端配置方案，你将能够在几分钟内把 Repomix 接入主流 AI 编程环境，省去手动生成并上传文件的工作，并获得源码级的原理认知。

[!NOTE] 这是一个实验性功能（experimental feature），Repomix 团队将根据用户反馈和真实世界使用情况持续改进。本文所有命令与参数均以当前仓库实际实现为准。

Repomix 为什么需要 MCP 服务器模式

Repomix 的核心能力是把整个仓库打包成单一、AI 友好的文件（XML / Markdown / JSON / Plain）。在传统工作流中，你需要先在终端运行repomix，生成文件，再把文件喂给 LLM。而 MCP 服务器模式改变了这一交互方式：AI 助手可以在对话中直接调用工具完成"打包 → 读取 → 搜索"的闭环，不需要任何人工文件准备。

从源码看，MCP 服务器在启动时会把自身能力描述注入给客户端。在 src/mcp/mcpServer.ts 中，服务器指令（instructions）明确写道：

"Usepack_codebaseorpack_remote_repositoryto consolidate code into a single XML file, usegenerate_skillto create Claude Agent Skills from codebases, useattach_packed_outputto work with existing packed outputs, thenread_repomix_outputandgrep_repomix_outputto analyze it. Perfect for code reviews, documentation generation, bug investigation, GitHub repository analysis, and understanding large codebases."

也就是说，MCP 模式把 Repomix 的整条打包分析流水线（含压缩、Token 计数、安全检查）变成了 AI 助手可以直接触达的标准工具面。

将 Repomix 作为 MCP 服务器运行

启动方式非常简单，只需要--mcp标志：

repomix --mcp

该命令会让 Repomix 进入 MCP 服务器模式，通过标准输入/输出（stdio）与支持 Model Context Protocol 的 AI 助手通信。从源码调用链看，--mcp由 src/cli/actions/mcpAction.ts 处理，最终进入 src/mcp/mcpServer.ts 的runMcpServer：

通过StdioServerTransport建立传输通道（new StdioServerTransport()后server.connect(transport)）；
监听SIGINT/SIGTERM信号，触发server.close()优雅关闭（关闭失败时以退出码 1 结束）；
服务器元数据包括name: 'repomix-mcp-server'与通过getVersion()读取的包版本号。

--mcp标志定义在 src/cli/types.ts 的CliOptions中（mcp?: boolean; sandbox?: boolean | string），sandbox同时支持布尔值或目录字符串——这正是下一节两种沙盒写法的来源。

沙盒模式（Sandbox Mode）：限制文件工具的作用域

为什么需要沙盒

默认情况下，MCP 服务器可以读取宿主用户可读的任何路径。这对于可信的本地助手很方便，但当服务器暴露给不可信客户端或 Agent 时，权限就过宽了。--sandbox标志将服务器的文件工具限制在单一工作区目录内：

# 限制到当前工作目录 repomix --mcp --sandbox # 限制到指定目录 repomix --mcp --sandbox path/to/project

沙盒开启后的两条核心规则

1. 每个路径都相对于工作区根目录（workspace root）。

绝对路径、~（家目录引用）、..穿越段、以及 Windows 盘符 / UNC 路径都会被拒绝；
解析后越出根目录的路径（包括通过符号链接 symlink 逃逸）会被丢弃；
返回的结果与错误消息同样是相对路径，从而不暴露宿主机的任何路径信息。

该规则同样适用于下方工具参考中的directory与path参数：在沙盒模式下，请传入相对于工作区根目录的路径（例如"."、"src"、"src/index.ts"），而不是表格中通常描述的绝对路径。

从源码层面看，这一整套检查实现在 src/mcp/pathScope.ts：

isEscapingPath()拒绝四类输入：path.isAbsolute判定的绝对路径；Windows 盘符相对路径（如C:foo，path.isAbsolute会漏掉这种形式）；~与~/家目录引用；以及任何..穿越段（无论正斜杠还是反斜杠分隔）。注释特别说明，仅以~开头的普通文件名（如~$lock.docx）是允许的，只有家目录引用形式才被拒绝；
resolveWithinRoot()在词法解析后先用isInside()校验候选路径必须位于根内，再通过realpath解析真实路径，捕获"根内链接指向根外"的 symlink 逃逸；若目标尚不存在导致 realpath 失败，则回退到已经过词法约束的路径；
toVirtualPath()把根内绝对路径转换为根相对路径（根自身表示为"."），供结果显示使用，避免宿主路径外泄。

2. 只注册只读、根受限的工具。

沙盒模式下仅注册：pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory。远程打包（pack_remote_repository）、技能生成（generate_skill）与外部输出附加（attach_packed_output）会被禁用，因为它们要么访问网络、要么写入文件、要么引用任意路径。而两个file_system_*工具本身也只在沙盒模式下才注册（见 src/mcp/mcpServer.ts 中if (config.sandboxed)分支）——工作区根目录限定了它们可达的范围。

沙盒是"纵深防御"，不是操作系统级沙箱

文档与源码都强调：这是对工具面的应用层限制（defense in depth），并非 OS 级沙箱。当为不可信客户端托管服务器时，仍应将其运行在平台常规隔离手段之下（容器、专用用户等）。另外需要注意：--sandbox只影响 MCP 服务器，没有--mcp时它不产生任何效果。

沙盒模式下的额外加固（源码细节）

阅读 src/mcp/tools/packCodebaseTool.ts 可以看到，沙盒模式为pack_codebase额外附加了多项加固：

include/ignore 模式越权检查：patternsEscapeRoot()用与打包器相同的 brace-aware 分词（splitPatterns）加 brace 展开（braceExpand）逐 token 检查——防止"{/etc/**,x}"这类花括号备选项走私绝对路径，也剥离前导!取反符后再检查；
强制跳过配置文件：skipLocalConfig: true, skipGlobalConfig: true——因为工作区的repomix.config.*或操作者的全局配置可能设置output.instructionFilePath把工作区外的文件读进 Agent 可见输出，或通过input.processors执行命令；
强制限制文件搜索范围：confineToBaseDir: true作为语法无关的兜底，丢弃任何解析到根目录之外的文件；
禁用 git 排序：gitSortByChanges: false——默认开启的sortByChanges会执行git -C <workspace> log，从而读取不可信工作区的.git/config（例如log.showSignature触发的gpg.program），这是宿主命令执行向量；
错误消息白名单：src/mcp/tools/mcpToolRuntime.ts 的sandboxErrorReason()只根据错误码（ENOENT→ "not found"、EACCES/EPERM→ "permission denied" 等枚举映射）生成固定原因，绝不转发error.message——因为原始消息可能内嵌工作区根、Repomix 安装路径、Node 运行时或操作者家目录等宿主路径。

配置 MCP 服务器：主流 AI 客户端接入指南

要配合 Claude 等 AI 助手使用，需要为客户端配置 MCP 服务器。以下配置均可直接复制使用。

VS Code

可以通过两种方式安装：

使用安装徽章：文档中的 "Install in VS Code" / "Install in VS Code Insiders" 徽章触发的是vscode:mcp/install协议，其底层等价于注册一个名为repomix、命令为npx、参数为["-y", "repomix", "--mcp"]的 MCP 服务器。
使用命令行：

code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

VS Code Insiders 用户：

code-insiders --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

Cline（VS Code 扩展）

编辑cline_mcp_settings.json：

{ "mcpServers": { "repomix": { "command": "npx", "args": [ "-y", "repomix", "--mcp" ] } } }

Cursor

在 Cursor 中，进入Cursor Settings>MCP>+ Add new global MCP server添加新服务器，配置与上述 Cline 配置一致。

Claude Desktop

编辑claude_desktop_config.json，采用与 Cline 配置相同的结构（mcpServers下注册repomix条目）。

Claude Code

使用以下命令直接注册：

claude mcp add repomix -- npx -y repomix --mcp

此外，还可以使用官方 Repomix 插件获得更便捷的体验：插件提供自然语言命令和更简单的设置流程，详见 Claude Code 插件文档。

使用 Docker 替代 npx

不想依赖 npx 时，可以用 Docker 运行 Repomix MCP 服务器（ghcr.io/yamadashy/repomix镜像）：

{ "mcpServers": { "repomix-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/yamadashy/repomix", "--mcp" ] } } }

注意这里使用-i（保持标准输入打开）与--rm（容器退出即清理），因为 MCP 服务器通过 stdio 通信。

可用 MCP 工具详解

当以 MCP 服务器运行时，Repomix 提供以下工具。所有工具的输入输出 Schema 均由 Zod 定义于各工具源文件中，下面参数表与源码实现一一对应。

pack_codebase

将本地代码目录打包为单一文件（默认 XML）供 AI 分析。它分析代码库结构、提取相关代码内容，并生成包含指标（metrics）、文件树（file tree）和格式化代码内容的综合报告。实现见 src/mcp/tools/packCodebaseTool.ts，核心逻辑是构造CliOptions后调用runCli(['.'], targetDirectory, cliOptions)复用完整的 CLI 打包管线。

参数：

参数	必填	默认值	说明
`directory`	是	—	要打包的目录。非沙盒模式传绝对路径；沙盒模式传相对于工作区根目录的路径（如`"."`或`"src"`）
`compress`	否	`false`	启用 Tree-sitter 压缩，在剔除实现细节的同时提取核心代码签名与结构。按文档说明可减少约 70% 的 Token 用量并保持语义。通常非必需，因为`grep_repomix_output`支持增量内容检索
`includePatterns`	否	—	用 fast-glob 模式指定要包含的文件，逗号分隔（如`"*/.{js,ts}"`、`"src/,docs/"`）
`ignorePatterns`	否	—	用 fast-glob 模式额外排除文件，逗号分隔（如`"test/*,.spec.js"`），是对`.gitignore`与内置排除规则的补充
`outputPatterns`	否	—	逐文件包含级别，对应配置文件中的`output.patterns`选项。由`{ "pattern": string, "compress"?: boolean, "directoryStructureOnly"?: boolean }`条目组成的数组。首个匹配的 pattern 生效；`directoryStructureOnly`优先于`compress`；两个标志都不带的匹配会强制保留完整内容（可用于把特定文件从全局`compress`中豁免）。会覆盖目标仓库`repomix.config.json`中的任何`output.patterns`
`topFilesLength`	否	`10`	指标摘要中按大小展示的最大文件数量
`style`	否	`xml`	输出格式：`xml`、`markdown`、`json`或`plain`

示例：

{ "directory": "/path/to/your/project", "compress": true, "includePatterns": "src/**/*.ts,**/*.md", "ignorePatterns": "**/*.log,tmp/", "outputPatterns": [ { "pattern": "src/core/**" }, { "pattern": "docs/**/*", "directoryStructureOnly": true } ], "topFilesLength": 10 }

以上例说明匹配语义（其中compress: true充当未匹配文件的兜底策略）：src/core/下的文件保留完整内容，docs/下的文件仅出现在目录结构中，其余一切被压缩。

返回结构（源码佐证）：工具返回description、result（含指标与文件信息的 JSON 字符串）、directoryStructure（目录树）、outputId（访问打包内容的唯一标识）、outputFilePath、totalFiles与totalTokens。其中outputId由 src/mcp/tools/mcpToolRuntime.ts 的内存注册表outputFileRegistry维护（registerOutputFile/getOutputFilePath），供后续read_repomix_output、grep_repomix_output检索文件路径使用。打包产物落在 Repomix 的临时工作目录（createToolWorkspace()），因此这些工具特别适合文件系统访问受限的环境。

pack_remote_repository

自动 clone 一个 GitHub 远程仓库并打包为单一 XML 文件供 AI 分析。它分析仓库结构并生成综合报告。实现见 src/mcp/tools/packRemoteRepositoryTool.ts。

参数：

参数	必填	默认值	说明
`remote`	是	—	GitHub 仓库 URL 或`user/repo`格式（如`"yamadashy/repomix"`、`"https://github.com/user/repo"`，或带分支的`"https://github.com/user/repo/tree/branch"`）
`compress`	否	`false`	启用 Tree-sitter 压缩，减少约 70% Token 用量并保持语义。通常非必需，因为`grep_repomix_output`支持增量内容检索
`includePatterns`	否	—	用 fast-glob 模式指定要包含的文件，逗号分隔（如`"*/.{js,ts}"`、`"src/,docs/"`）
`ignorePatterns`	否	—	用 fast-glob 模式额外排除文件，逗号分隔（如`"test/*,.spec.js"`），是对`.gitignore`与内置排除规则的补充
`outputPatterns`	否	—	逐文件包含级别，对应配置文件中的`output.patterns`选项，条目结构同`pack_codebase`
`topFilesLength`	否	`10`	指标摘要中按大小展示的最大文件数量
`style`	否	`xml`	输出格式：`xml`、`markdown`、`json`或`plain`

示例：

{ "remote": "yamadashy/repomix", "compress": true, "includePatterns": "src/**/*.ts,**/*.md", "ignorePatterns": "**/*.log,tmp/", "outputPatterns": [ { "pattern": "src/core/**" }, { "pattern": "docs/**/*", "directoryStructureOnly": true } ], "topFilesLength": 10 }

安全细节（源码佐证）：工具回显的远程地址会经过redactUrl()脱敏（见 src/shared/urlRedact.ts）——否则带凭据的远程地址会残留在 MCP 对话记录、客户端日志与模型上下文中。该工具标注为openWorldHint: true，且仅在非沙盒模式下注册（需要网络访问）。

read_repomix_output

读取 Repomix 生成的输出文件内容，支持用行范围指定对超大文件做部分读取。该工具专为直接文件系统访问受限的环境（如 Web 环境、沙盒应用）设计。实现见 src/mcp/tools/readRepomixOutputTool.ts。

参数：

参数	必填	默认值	说明
`outputId`	是	—	要读取的 Repomix 输出文件 ID
`startLine`	否	文件开头	起始行号（基于 1，包含该行）
`endLine`	否	文件结尾	结束行号（基于 1，包含该行）

特性：

专为 Web 环境或沙盒应用设计；
通过 ID 检索此前生成过的输出内容；
无需文件系统访问即可读取已打包代码库；
对大型文件支持部分读取。

示例：

{ "outputId": "8f7d3b1e2a9c6054", "startLine": 100, "endLine": 200 }

源码细节：行号采用 1-based 且包含两端；源码中会校验startLine >= 1、endLine >= 1、startLine <= endLine、起始行不超出文件总行数。对于从不可信路径附加的输出文件（requiresSecretScan），每次提供内容前都会先运行 Secretlint 检查（runSecretLint），发现疑似敏感信息即拒绝返回——这是启发式防护，不是访问边界。

grep_repomix_output

用 grep 式功能在 Repomix 输出文件中检索模式，语法为 JavaScript RegExp；返回匹配行及可选的上下文行。实现见 src/mcp/tools/grepRepomixOutputTool.ts。

参数：

参数	必填	默认值	说明
`outputId`	是	—	要搜索的 Repomix 输出文件 ID
`pattern`	是	—	搜索模式（JavaScript RegExp 语法）
`contextLines`	否	`0`	每个匹配前后显示的上下文行数。指定`beforeLines`/`afterLines`时被覆盖
`beforeLines`	否	—	每个匹配前显示的行数（类似`grep -B`）。优先于`contextLines`
`afterLines`	否	—	每个匹配后显示的行数（类似`grep -A`）。优先于`contextLines`
`ignoreCase`	否	`false`	是否忽略大小写

特性：

使用 JavaScript RegExp 语法实现强大的模式匹配；
支持上下文行以更好地理解匹配结果；
可分别控制前后上下文行数；
支持区分大小写与忽略大小写两种搜索。

示例：

{ "outputId": "8f7d3b1e2a9c6054", "pattern": "function\\s+\\w+\\(", "contextLines": 3, "ignoreCase": false }

源码细节：匹配流程由createRegexPattern（ignoreCase时使用gi标志，非法正则抛出带原因的错误）、searchInLines（逐行line.match(regex)，记录行号、整行内容与匹配文本）、formatSearchResults（生成行号:精确匹配与行号-上下文行的 grep 风格输出，并在上下文区间出现空隙时插入--分隔符）组成。为优化 3–5MB 大输出文件的处理，performGrepSearch只对内容做一次 split 并复用行数组。

file_system_read_file 与 file_system_read_directory

这两个文件系统工具仅在沙盒模式（--sandbox）下可用，此时工作区根目录限定了它们的可达范围；没有--sandbox时它们不会被注册（见 src/mcp/mcpServer.ts）。实现见 src/mcp/tools/fileSystemReadFileTool.ts 与 src/mcp/tools/fileSystemReadDirectoryTool.ts。

file_system_read_file
- 读取相对于工作区根目录的路径上的文件内容（如src/index.ts）；
- 会拒绝匹配已知敏感信息格式（Secretlint 识别 API 密钥、密码等）的内容，作为额外的启发式安全防护——访问边界是工作区根目录，而不是扫描本身；
- 对无效路径返回清晰的错误消息，且不暴露宿主路径。
file_system_read_directory
- 列出相对于工作区根目录的路径上的目录内容（如.或src）；
- 用明确的[FILE]/[DIR]指示符区分文件与子目录；
- 适用于探索项目结构、理解代码库组织方式。

示例：

// 读取文件 const fileContent = await tools.file_system_read_file({ path: 'src/index.ts' }); // 列出目录内容 const dirContent = await tools.file_system_read_directory({ path: 'src' });

当 AI 助手需要以下能力时，这两个工具尤为有用：

分析工作区中的特定文件；
在目录结构中导航；
确认文件的存在性与可访问性。

使用 Repomix 作为 MCP 服务器的优势

直接集成：AI 助手无需手动准备文件即可直接分析你的代码库；
高效工作流：省去手动生成并上传文件的步骤，精简代码分析流程；
一致输出：确保 AI 助手以统一、优化的格式获取代码库；
高级特性：完整复用 Repomix 的全部能力，包括代码压缩、Token 计数与安全检查。

一旦配置完成，你的 AI 助手就能直接调用 Repomix 的能力来分析代码库，让代码分析工作流变得更高效。

典型工作流（从源码与测试推断的推荐用法）

沙盒安全探索：先用file_system_read_directory "."摸清工作区结构，再用file_system_read_file细读关键文件，需要整体分析时调用pack_codebase "."生成打包产物，最后用grep_repomix_output以增量方式检索特定符号——这种"先探索、再打包、后检索"的组合可以最大化 Token 效率，也正是compress参数注释中"通常不需要，因为grep_repomix_output允许增量内容检索"所对应的用法；
远程仓库分析：直接调用pack_remote_repository传入user/repo或完整 URL，随后用read_repomix_output配合startLine/endLine分批阅读大文件，避免一次性消耗过多上下文。

上述工具行为均有对应测试覆盖，例如 tests/mcp/mcpServer.test.ts、tests/mcp/tools/sandbox.contract.test.ts、tests/mcp/tools/fileSystemReadFileTool.sandbox.test.ts 等，可进一步阅读以验证沙盒路径规则、工具注册条件与错误白名单机制。

企业官网建设流程全解析