dir2MCP (Dirstral)

2mcp

将任何本地目录部署为具有索引、检索和引用功能的MCP知识服务器，旨在最大限度地在嵌入、OCR、转录和生成过程中使用Mistral模型。可选层包括ElevenLabs通过专用桥接二进制和x402请求门控（支付/请求门控协议）进行语音输出。

为什么dir2mcp

• 西北风第一管道：

- 嵌入： mistral-embed （文本）+ codestral-embed （代码） - OCR： mistral-ocr-latest - STT默认值： voxtral-mini-latest - RAG一代：Mistral聊天模型

• Single Go二进制(dir2mcp)当地第一州 .dir2mcp/
• 伴随桥二进制(elevenlabs-bridge)ElevenLabs webhook工具
• MCP Streamable HTTP服务器，具有稳定的工具界面
• 多模式摄取：文本/代码、文档提取（文档或OCR）、转录本、结构化注释
• 引文感知检索和RAG式应答
• 可选的主持人支持的x402支付门控 tools/call
• 具有两个二进制文件的回购布局：

- dir2mcp：MCP服务器和索引/运行时主机 - elevenlabs-bridge：ElevenLabs webhook工具的HTTP助手

• dirstral 终端客户端在单独的 dirstral-cli 回购。

安装

安装 dir2mcp 通过Homebrew水龙头：

brew install dirstral/tap/dir2mcp

然后验证：

dir2mcp version

从源代码构建仍然可用作替代方案：

git clone --recurse-submodules https://github.com/Dirstral/dir2mcp
cd dir2mcp
make build

现有克隆： 跑 git submodule update --init --recursive 取 dirstral-spec 子模块。 要将规范更新为最新的固定版本，请执行以下操作： git submodule update --remote dirstral-spec.

运行时先决条件（按场景）

选择与你跑步方式相匹配的行 dir2mcp:

快速入门

构建先决条件（仅限源构建）： 转到1.22+(go.dev/dl)以及 make.

git clone https://github.com/Dirstral/dir2mcp
cd dir2mcp
cp .env.example .env        # add your API keys
# optional: create `.env.local` for local overrides
# (it takes precedence over `.env`)
# cp .env.example .env.local
make build
./dir2mcp up

或者直接构建每个二进制文件：

• go build -o dir2mcp ./cmd/dir2mcp/
• go build -o elevenlabs-bridge ./cmd/elevenlabs-bridge/

服务器在启动时打印其MCP端点URL。将您的MCP客户端指向该URL。 优先级（从高到低）：shell环境变量> .env.local > .env.

当地发展环境

dir2mcp 自动加载两者 .env 和 .env.local 从工作目录中； .env.local 覆盖 .env，并且实际的shell环境变量具有最终优先级。

托管演示烟雾手册

要快速进行托管就绪检查（问题#19范围），请运行：

DIR2MCP_DEMO_URL="https://your-host.example/mcp" \
DIR2MCP_DEMO_TOKEN="" \
./scripts/smoke_hosted_demo.sh

笔记：

• DIR2MCP_DEMO_TOKEN 每当启用身份验证时都需要。
• 该脚本现在运行完整的MCP初始化序列(initialize -> notifications/initialized -> tools/list -> tools/call).
• 如果你的端点是x402门控的， tools/call 返回HTTP 402 随着 PAYMENT-REQUIRED 被视为健康。

它验证了什么：

• initialize 返回HTTP 200和有效的 MCP-Session-Id
• tools/list 返回带有工具元数据的HTTP 200
• tools/call 为了 dir2mcp_list_files 返回HTTP 200或HTTP 402 PAYMENT-REQUIRED 启用x402时

隧道设置（复制/粘贴）

Cloudflare快速隧道（无需帐户的快速模式）：

cloudflared tunnel --url http://127.0.0.1:8087 --no-autoupdate

ngrok（需要经过验证的帐户+authtoken）：

ngrok config add-authtoken 
ngrok http http://127.0.0.1:8087

从本地API获取ngrok公共URL:

curl -sS http://127.0.0.1:4040/api/tunnels \
  | jq -r '.tunnels[] | select(.proto=="https") | .public_url'

如果你没有 jq，从ngrok web UI复制公共URL(http://127.0.0.1:4040).

然后对任一隧道URL运行托管烟雾探测器：

DIR2MCP_DEMO_URL="https://
/mcp" \
DIR2MCP_DEMO_TOKEN="$(cat .dir2mcp/secret.token)" \
./scripts/smoke_hosted_demo.sh

CLI命令

跑步 dir2mcp 无参数打印用法，您可以随时查阅以查看可用命令。 ask, search, open-file，以及 list-files 是传统的兼容性垫片；新客户端/编排器UX属于 dirstral-cli.

MCP工具

配置

YAML配置(.dir2mcp.yaml)

磁盘上的主要配置文件是 .dir2mcp.yaml （由创建 dir2mcp config init). 将其用于持久、非敏感的设置，如连接器定义、默认值和其他选项 您可能希望检查源代码管理。此处定义的值可能会在运行时被以下内容覆盖 环境变量。

环境变量（覆盖/机密）

敏感密钥和临时运行时覆盖是通过环境变量提供的。他们采取 优先于YAML文件中的条目，并且便于API密钥、令牌或设置 因部署而异。常用的变量有：

对于Homebrew和其他已安装的工作流，您可以在 .dir2mcp.yaml:

mistral_max_ocr_payload_bytes: 26214400
ingest_extractor: auto
docling_command: docling --to md --output - {input}

或者覆盖一次运行：

dir2mcp up --mistral-max-ocr-payload-bytes 26214400

服务器标识

每 dir2mcp up 实例报告从索引目录导出的唯一MCP服务器名称。， dir2mcp-stas-legal-a1b2c3 和 dir2mcp-research-notes-9f44ee)使它们在MCP客户端列表中易于区分。

• 默认形状： dir2mcp--，在哪里 ` 是索引目录的模糊基名，以及 ` 哈希其绝对路径（因此该名称在从同一位置重新运行时是稳定的）。
• 开发人员构建（本地构建的二进制文件，没有发布标签-- dir2mcp version 报告 v0.0.0-dev 或 vdev-，可选配 +dirty)使用a dir2mcp-dev-- 前缀，因此从您的仓库运行的开发构建在brew安装的版本旁边显示为一个单独的条目 claude mcp list.
• 通过YAML覆盖(server.name: my-alias)或env(DIR2MCP_SERVER_NAME=my-alias).重写将逐字应用并绕过默认生成的名称，包括 dir2mcp-dev-... dev构建使用的前缀。
• 这 dir2mcp up 横幅打印即贴 claude mcp add --transport http ... 使用此名称的行；您注册的客户端别名由您选择。

身份验证令牌行为

dir2mcp 承载身份验证可以来自：

1. `--auth file:

` （显式文件源）

1. DIR2MCP_AUTH_TOKEN （环境）
2. 自动生成 secret.token 在州目录中(auth=auto 默认）

操作指南：

• 在共享环境中，不要直接在命令行上传递承载令牌。
• 更喜欢令牌文件(`--auth file:

`)或环境变量。

ElevenLabs桥

elevenlabs-bridge 是一个单独的Go助手，用于转发ElevenLabs webhook 呼唤跑步 dir2mcp MCP终点。它从以下位置读取其配置 当前环境，并回归到合理的默认值：

用途：

dir2mcp bridge elevenlabs

# Override defaults when needed.
MCP_URL="http://127.0.0.1:8087/mcp" \
STATE_DIR="/path/to/corpus/.dir2mcp" \
PORT=8088 \
dir2mcp bridge elevenlabs

# Legacy wrapper binary still works and forwards to the same integrated command.
make build-elevenlabs-bridge
./elevenlabs-bridge --state-dir /path/to/corpus/.dir2mcp

如果你 dir2mcp 服务器已使用 --auth none，您可以省略 MCP_TOKEN 和 STATE_DIR.

安全默认值

• 默认侦听地址为本地(127.0.0.1:0)
• --public 绑定到 0.0.0.0 （除非明确 --listen 提供）
• --public 随着 --auth none 除非被拒绝 --force-insecure 已设置
• 浏览器来源已分配（本地主机默认值+显式添加）

可选x402模式

x402是可选的和附加的。配置为 --x402 off|on|required 以及主持人设置。

必填字段 required 模式：

• --x402-facilitator-url
• --x402-resource-base-url
• --x402-network （例如，CAIP-2 eip155:8453)
• --x402-price
• --x402-scheme
• --x402-asset
• --x402-pay-to
• DIR2MCP_X402_FACILITATOR_TOKEN （或等效的秘密来源）

最小示例：

DIR2MCP_X402_FACILITATOR_TOKEN="" \
dir2mcp up \
  --public \
  --listen 0.0.0.0:8092 \
  --x402 required \
  --x402-facilitator-url https:// \
  --x402-resource-base-url https:// \
  --x402-network eip155:8453 \
  --x402-price 1000 \
  --x402-scheme exact \
  --x402-asset usdc \
  --x402-pay-to 0x1111111111111111111111111111111111111111

如果未付费呼叫被正确阻止， tools/call 返回HTTP 402 加 PAYMENT-REQUIRED.

看 目录规范/docs/x402-支付适配器规范.md 对于完整的主持人适配器合同。

项目状态

实现了核心服务器、摄取管道、检索、引用和x402门控。看 问题 正在进行的工作。

生态系统分裂状态

问题 #113 跟踪回购拆分。

• dir2mcp （此仓库）：MCP服务器实现+桥接二进制
• dirstral-spec：规范规范/模式/版本控制
• dirstral-conformance：黑盒一致性线束
• dirstral-cli：客户端/编排器用户体验
• landfall：代码导航MCP服务器产品存根

拆分前审计总结：

• 交叉产品进口：无 dir2mcp 实现（组成边界为MCP）。
• CLI边界： internal/cli 这里是服务器/引导CLI；客户端UX属于 dirstral-cli.
• 落地来源：产品范围来自问题 #112，现在由一个单独的存根回购表示。
• 文档目标映射：

- docs/SPEC.md -> dirstral-spec/docs/SPEC.md - docs/ECOSYSTEM.md -> dirstral-spec/docs/ECOSYSTEM.md - docs/x402-payment-adapter-spec.md -> dirstral-spec/docs/x402-payment-adapter-spec.md

CLI所有权/处置矩阵：

文档

规范性文件保存在 dirstral-spec 子模块（单一真相来源 docs/*.md 这里的文件是指针存根）：

• 目录规格/文档/VISION.md --产品愿景和战略方向
• 目录规范/docs/spec.md --规范行为、模式和运行时契约
• 目录规范/docs/ECOSYSTEM.md --生态系统/市场/发现/支付环境
• 目录规范/docs/x402-支付适配器规范.md --主持人适配器合同
• dir2mcp实现规范版本 0.5.x (版本控制)

发展

make check        # fmt + vet + lint + cyclo + test + build
make cyclo        # gocyclo -over 15 ./internal/ (install: go install github.com/fzipp/gocyclo/cmd/gocyclo@v0.6.0)
make build        # build dir2mcp binary
make build-elevenlabs-bridge  # build ElevenLabs bridge wrapper binary
make benchmark    # run retrieval benchmarks

发布自动化：

• 推a v* 标签触发器 .github/workflows/release.yml 并通过GoReleaser发布工件。
• Homebrew配方更新需要 HOMEBREW_TAP_GITHUB_TOKEN 具有写入权限 dirstral/homebrew-tap.

API注释：

• retrieval.NewEngine 现在需要一个上下文作为其第一个参数：

retrieval.NewEngine(ctx, stateDir, rootDir, cfg).

• Engine.Ask 获得了一个上下文感知变体 AskWithContext

原始的 Ask 继续作为兼容性的薄包装而存在。

make check 包括 make lint，这需要 golangci-lint 本地安装。 make cyclo 运行CI使用的圈复杂度门。CI运行后，Go报告卡会从外部更新；如果徽章延迟，请从此存储库的goreportcard.com报告页面刷新它。

贡献者和代理指南： 代理商.md · CLAUDE.md

许可证

MIT。看 许可证.