# Sourcemux Go

> Go MCP server and CLI for Grok-powered search, fetch, research, and reasoning workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-500tpig-sourcemux-go`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [500tpig](https://agentstack.voostack.com/s/500tpig)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [500tpig](https://github.com/500tpig)
- **Source:** https://github.com/500tpig/sourcemux-go

## Install

```sh
agentstack add mcp-500tpig-sourcemux-go
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SourceMux

[](https://github.com/500tpig/sourcemux-go/actions/workflows/ci.yml)
[](go.mod)
[](LICENSE)

[中文](#中文) | [English](#english)

> **SourceMux is a single-binary CLI + stdio MCP agent research router.**
> It gives agents fast/default search for one-hop work, `profile=auto` heavy
> Grok research when configured, and policy-first URL fetch with quality,
> GitHub-aware, and cheap profiles.
>
> Packaging status: the current verified public baseline is `v0.2.1`
> (checked 2026-06-03): GitHub Release assets, the Homebrew cask in
> `500tpig/homebrew-tap`, the Scoop manifest in `500tpig/scoop-bucket`, and
> the npm package `sourcemux` are published. Future package-manager claims
> still need per-release verification before the docs describe them as
> available.

## 中文

SourceMux 是一个面向 AI Agent、MCP 客户端和命令行自动化的单二进制 CLI + stdio MCP 研究路由器。它把 Grok / OpenAI-compatible endpoint pool、TinyFish、Exa、Tavily、Jina、Firecrawl 等能力接到统一 fallback route：普通查询走快速默认搜索，`research` / `smart-answer` 默认用 `profile=auto` 在适合时切到已配置的 heavy / multi-agent Grok 搜索，URL 抓取默认走 policy-first / quality-first 策略，GitHub URL 优先走 repo-aware enrichment，cheap/zero-key 模式才走 Jina-first。

Firecrawl 通过 SourceMux 自己的 CLI direct commands 和普通 fetch routing
使用，不是 Firecrawl MCP server 集成。默认 `fetch --profile auto` 在
Firecrawl 配置可用时会把普通网页放到质量优先路线，但不会默认开启
Firecrawl clean-content；`fetch --profile quality` 才会打开该额外清理。
`fetch --profile cheap` 才用于轻量、低成本、零 key 优先的 Jina-first 路线。

仓库默认只保存安全示例配置。真实 API key 只应该放在本地 `sourcemux.json`，或用 `--config /path/to/sourcemux.json` 显式指定的本地配置文件里。不要提交真实密钥、私有 provider endpoint 或 provider dashboard 导出文件。

### 适合什么时候用

- 你希望 AI 助手联网搜索当前信息，但要保留可复现的 CLI 命令和 JSON 输出。
- 你想抓取一个 URL 正文，或把网页内容交给后续 Agent / 脚本处理。
- 你想查官方文档、API、SDK、框架用法，并通过 Exa 做文档 / web 搜索。
- 你想生成一个可审计的轻量 research pack：先规划搜索，再收集来源，最后抓取关键页面。
- 你想把同一套搜索能力接入 Codex、Claude Code、Cherry Studio 等 MCP 客户端。

### 默认路由

| 能力 / 命令 | 默认路线 |
| --- | --- |
| `web_search` / `sourcemux search` | Grok endpoint pool -> TinyFish Search -> Exa Search -> Tavily Search |
| `web_fetch` / `sourcemux fetch --profile auto` | GitHub Provider for GitHub URLs; otherwise Firecrawl -> Jina Reader -> Exa Contents -> Tavily Extract -> TinyFish Fetch |
| `sourcemux fetch --profile cheap` | Jina Reader -> Firecrawl -> Exa Contents -> Tavily Extract |
| `docs_search` / `sourcemux docs-search` | Exa docs/web search fallback |
| `research_run` / `sourcemux research` | 规划 query -> 搜索 -> 收集来源 -> 排序 URL -> 抓取高价值页面（默认 `--profile auto`） |
| `smart_answer` / `sourcemux smart-answer` | 先跑 bounded research（默认 `--profile auto`），再交给配置好的 reasoning endpoint 综合回答 |

### 为什么不是只用 Jina 或普通搜索

- Jina Reader 是轻量、零 key 的 URL 正文提取 fallback；它不是质量默认，也不是搜索、文档检索、heavy Grok 或最终综合能力的上限。
- 普通搜索适合一次性找结果；SourceMux 额外提供 agent 友好的 route、fallback、`get_sources`、fetch 验证、bounded research pack 和可复现 JSON。
- 对复杂、当前、对比或高风险问题，`research` / `smart-answer` 默认 `profile=auto`，可以在配置了 heavy Grok profile 时自动用更强搜索，同时仍保留 fallback。

### 公开用户快速开始

公开用户流程需要先把 `sourcemux` 安装到 `PATH`。当前已核验的公开发布基线
（2026-06-03）是 `v0.2.1`：GitHub Release assets、`500tpig/homebrew-tap`
里的 Homebrew cask、`500tpig/scoop-bucket` 里的 Scoop manifest、以及 npm
包 `sourcemux` 都已发布。之后每个版本仍必须先核验 tag、GitHub Release、
tap/cask、bucket manifest 和 npm registry，
再在文档中声称对应包管理器通道可用。普通用户建议显式使用全局配置文件：
`~/.config/sourcemux/sourcemux.json`。

任选一个已发布安装通道：

```bash
go install github.com/500tpig/sourcemux-go/cmd/sourcemux@latest
```

GitHub Release 下载页：

```text
https://github.com/500tpig/sourcemux-go/releases/tag/v0.2.1
```

```bash
brew tap 500tpig/tap
brew install --cask sourcemux
```

不要直接用 `brew install sourcemux`，除非 SourceMux 之后也进入了 Homebrew
core；本项目发布路径是上面的 tap/cask。

```powershell
scoop bucket add 500tpig https://github.com/500tpig/scoop-bucket.git
scoop install 500tpig/sourcemux
```

```bash
npm install -g sourcemux
npx sourcemux version
```

确认安装：

```bash
sourcemux version
sourcemux config path
```

生成用户级配置：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json setup --non-interactive \
  --api-url "https://your-grok-compatible-endpoint.example/v1" \
  --api-key "sk-your-key" \
  --model "grok-4.20-fast" \
  --json
```

检查配置，输出会遮蔽 key：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json config list --json
sourcemux --config ~/.config/sourcemux/sourcemux.json doctor --json
```

跑一次搜索：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json search "今天 Go 生态有哪些重要更新？" --agent
```

显式跑较慢的 heavy Grok 搜索时，用户面向的研究应保留 fallback；只有诊断 profile 本身是否可返回时才禁用 fallback：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json search "复杂搜索问题" --profile heavy --fallback-after 180s --timeout 300s --agent
sourcemux --config ~/.config/sourcemux/sourcemux.json search "ping" --profile heavy --grok-pool-timeout 0 --no-fallback --timeout 120s --json
```

抓取网页正文：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json fetch "https://example.com" --profile auto --agent
sourcemux --config ~/.config/sourcemux/sourcemux.json fetch "https://example.com" --profile cheap --agent
```

`--agent` 适用于 `search` / `fetch` / `research`，会隐含 JSON 输出，并返回短
JSON：source id、质量分、warnings 和 next actions。普通 `--json` 的完整
envelope 契约不变，仍适合脚本和调试。

普通已知 URL 先用 `fetch --profile auto`：GitHub repo / issues / releases /
blob / tree URL 会优先走 GitHub enrichment，普通网页在 Firecrawl 配置可用时
优先用 Firecrawl 抓取，再 fallback 到 Jina / Exa / Tavily / TinyFish。
默认 Firecrawl fetch 对齐官方 scrape 默认值，不开启 clean-content；需要额外
清理时用 `fetch --profile quality`。
只有明确要低成本或零 key sanity check 时才用 `fetch --profile cheap`。需要
Firecrawl-specific flags 时使用 `firecrawl-scrape`；站点结构、URL 盘点或按
主题发现站内链接时才用 `firecrawl-map`。不要安装或调用 Firecrawl MCP。

本地配置示例（只在本机配置文件里填真实 key，不要发到聊天里）：

```json
{
  "firecrawl": {
    "apiURL": "https://api.firecrawl.dev/v2",
    "apiKey": "fc-your-key",
    "enabled": true
  }
}
```

显式 v2 fetch 顺序配置示例（`--profile auto` 会尊重这个顺序；未写 v2 顺序时
使用默认 policy-first 质量策略）：

```json
{
  "version": 2,
  "minimum_profile": "off",
  "capabilities": {
    "main_search": {"providers": []},
    "docs_search": {"providers": []},
    "web_fetch": {
      "providers": [
        {
          "type": "firecrawl",
          "apiURL": "https://api.firecrawl.dev/v2",
          "keys": [
            {"name": "acct-a", "apiKey": "fc-your-key-a"},
            {"name": "acct-b", "apiKey": "fc-your-key-b"}
          ],
          "enabled": true
        },
        {"type": "jina", "apiURL": "https://r.jina.ai"}
      ]
    },
    "web_enhance": {"providers": []}
  }
}
```

填好本地 key 后，smoke 覆盖这三条：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json fetch "https://example.com" --profile auto --json \
  | jq -e '.policy.effective_profile == "auto" and (.content | length > 0)'

sourcemux --config ~/.config/sourcemux/sourcemux.json firecrawl-scrape "https://example.com" --json \
  | jq -e '.source == "Firecrawl Scrape" and .route_decision[0].provider == "firecrawl-scrape" and (.content | length > 0)'

sourcemux --config ~/.config/sourcemux/sourcemux.json firecrawl-map "https://example.com" --search "docs" --limit 100 --json \
  | jq -e '.source == "Firecrawl Map" and .route_decision[0].provider == "firecrawl-map" and (.count >= 0)'
```

离线生成结构化 research plan（不调用网络）：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json plan "对比当前 Go module proxy 方案的风险" --json --depth deep
```

查库 / 框架 / SDK 文档：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json docs-search "next.js middleware auth" --json
```

生成研究包：

```bash
sourcemux --config ~/.config/sourcemux/sourcemux.json research "Evaluate the current status of Go modules" --depth deep --profile auto --agent
```

安装 Agent 路由 skill 时，用户级 scope 会默认使用
`~/.config/sourcemux/sourcemux.json`，无需再把源码 checkout 的
`./sourcemux.json` 带进全局 skill：

```bash
sourcemux bootstrap list-agents
sourcemux bootstrap codex --scope user --dry-run
sourcemux bootstrap codex --scope user
sourcemux bootstrap status --scope user --config-status
```

`bootstrap status --json` 会用生成 skill 的 manifest 检查
`binary_status`、`runtime_config_status` 和 `scope_status`；常见问题码包括
`missing_binary`、`stale_binary`、`missing_config`、`stale_config` 和
`wrong_scope`。修复时用目标 scope 更新明确的二进制与配置路径：

```bash
sourcemux bootstrap update  --scope  --binary  --config 
```

不要把 user-scope skill 静默切到源码 checkout 的配置，也不要假设隐藏配置
fallback。

只有需要安全合并 Codex/Gemini/OpenCode MCP 客户端配置时才加
`--write-config`：

```bash
sourcemux bootstrap codex --scope user --write-config --dry-run --json
```

### 从源码开发

源码 checkout 适合维护者或本地开发。开发模式默认使用项目配置
`./sourcemux.json`，并且生成 project-scope skill：

```bash
git clone https://github.com/500tpig/sourcemux-go.git
cd sourcemux-go
go build -o sourcemux .
./sourcemux --config ./sourcemux.json setup --non-interactive \
  --api-url "https://your-grok-compatible-endpoint.example/v1" \
  --api-key "sk-your-key" \
  --model "grok-4.20-fast" \
  --json
./sourcemux bootstrap codex --scope project --binary "$(pwd)/sourcemux"
```

### 配置文件

SourceMux 只读取一个显式 JSON 配置文件：

- 默认：`./sourcemux.json`
- 显式：`sourcemux --config /path/to/sourcemux.json `
- 兼容旧写法：`sourcemux cli --config /path/to/sourcemux.json `

它不会自动扫描环境变量配置链、`~/.config/sourcemux/*` 或旧的
`endpoints.json`。公开用户流程使用全局配置时，必须像上面的例子一样显式传
`--config ~/.config/sourcemux/sourcemux.json`；`bootstrap --scope user`
只是把这个路径作为生成 skill 的默认显式配置路径。如果你已有旧版
`grok-search.json`，可以改名：

```bash
mv grok-search.json sourcemux.json
```

也可以继续显式指定旧文件：

```bash
sourcemux --config ./grok-search.json config list --json
```

最小配置示例：

```json
{
  "grokEndpoints": [
    {
      "name": "primary",
      "baseURL": "https://your-grok-compatible-endpoint.example/v1",
      "apiKey": "sk-your-key",
      "model": "grok-4.20-fast",
      "sendSearchFlag": false
    }
  ],
  "grokPoolTimeoutSec": 45,
  "logLevel": "INFO"
}
```

安全示例文件：

- [`configs/sourcemux.example.json`](configs/sourcemux.example.json)
- [`configs/sourcemux.reasoning.example.json`](configs/sourcemux.reasoning.example.json)

### 常用命令

| 命令 | 用途 |
| --- | --- |
| `sourcemux search ` | 按 fallback route 做一次网页搜索 |
| `sourcemux docs-search ` | 文档搜索；使用 Exa docs/web search fallback |
| `sourcemux fetch ` | 抓取一个 URL 的正文 |
| `sourcemux map ` | 用 Tavily 发现站点 URL |
| `sourcemux crawl ` | 用 Tavily 抓取站点内容 |
| `sourcemux plan ` | 离线生成搜索 / research plan；默认文本兼容，`--json` 输出结构化计划 |
| `sourcemux research ` | 生成 bounded research pack；Agent 默认用 `--agent` 看短 JSON |
| `sourcemux smart-answer ` | research 后交给 reasoning endpoint 综合 |
| `sourcemux eval-research` | 用离线 fixture cases 验证 research 排序、fetch 和 facts 抽取质量 |
| `sourcemux config path/files/list` | 查看当前配置路径和遮蔽后的有效配置 |
| `sourcemux setup` | 生成本地配置，不必手写 JSON |
| `sourcemux doctor` / `probe` | 本地配置检查 / 显式 live probe |
| `sourcemux bootstrap list-agents/status` | 安装或检查 AI Agent 路由 skill 与 MCP 配置片段 |

### MCP 接入

通用 stdio MCP server 配置：

```json
{
  "type": "stdio",
  "command": "/absolute/path/to/sourcemux",
  "args": ["--config", "/absolute/path/to/sourcemux.json"]
}
```

Claude Code 示例：

```bash
claude mcp add-json sourcemux '{
  "type": "stdio",
  "command": "/absolute/path/to/sourcemux",
  "args": ["--config", "/absolute/path/to/sourcemux.json"]
}'
```

也可以先用内置安装器生成 CLI-first 的 `sourcemux-routing` skill；公开用户
默认走 user scope，项目开发再使用 project scope。只有显式传 `--write-config`
或选择 `mcp-json` / `stdio` 目标时才输出 MCP 配置指导：

```bash
sourcemux bootstrap list-agents
sourcemux bootstrap codex claude-code --scope user --dry-run
sourcemux bootstrap codex --scope user
sourcemux bootstrap codex --write-config --scope user --dry-run --json
sourcemux bootstrap update codex --scope user
sourcemux bootstrap status --scope user --config-status
```

未传 `--write-config` 时，生成的 skill 会要求使用 CLI，并在每个 CLI 示例中带上
安装时配置的 `--config` 路径。传 `--write-config` 后，支持安全写入的目标会生成
MCP-aware skill，并输出更具体的官方 MCP 接入方式：Codex 的
`codex mcp add` / `config.toml`、Claude Code 的
`claude mcp add --transport stdio`、Gemini CLI 的 `gemini mcp add` /
`settings.json`，以及 OpenCode 的 `opencode.json` 配置片段。
`--write-config` 会为 Codex（`.codex/config.toml` / `~/.codex/config.toml`）、
Gemini（`.gemini/settings.json` / `~/.gemini/settings.json`）和 OpenCode
（`opencode.json` / `~/.config/opencode/opencode.json`）安全合并
`sourcemux` MCP 条目，不调用外部 agent CLI，也不会写入 provider API key。
修改已有配置前会创建带时间戳的备份；`--dry-run --json`
会显示将创建备份的原因和路径意图，但不会写文件。当前写入器会保留配置语义、
无关 key 和无关 MCP 条目，但可能重新序列化 Codex TOML、Gemini JSON 和
OpenCode JSONC；注释和原始排版不保证保留，备份文件是回滚路径。
`sourcemux uninstall  --write-config` 只删除 `sourcemux` 条目，
不删除整个配置文件。
生成的 skill 目录会带 `.sourcemux-install.json` manifest；`bootstrap update`
会自动刷新未被用户修改的旧生成 skill。`uninstall` 默认只删除 manifest hash
仍匹配的生成文件；如果用户改过生成 skill，或旧安装没有 manifest，可传
`--force` 先备份再移除。

MCP 侧常用工具：

| 工具 | 用途 |
| --- | --- |
| `web_search` | 紧凑搜索摘要，带 provider fallback 和来源提取 |
| `docs_search` | 文档搜索；使用 Exa docs/web search fallback |
| `get_sources` | 返回上一次 `web_search` 的 URL 列表 |
| `web_fetch` | 抓取网页正文摘要 |
| `web_map` / `web_crawl` | 站点 URL 发现 / 站点抓取 |
| `research_run` | 返回紧凑 research pack |
| `smart_answer` | research 后调用 reasoning endpoint 综合 |
| `get_config_info` | 配置诊断和 Grok `/models` probe |

### 从 grok-search 迁移

项目已改名为 SourceMux：

- GitHub 仓库目标名：`500tpig/sourcemux-go`
- 主命令：`sourcemux`
- 默认配置：`sourcemux.json`

旧的 `cmd/grok-search` 仍保留一个迁移窗口，GoReleaser 也会把 `grok-search` 兼容 binary 一起打包。新文档和新安装请使用 `sourcemux`。

已有本地 clone 在 GitHub 仓库改名后运行：

```bash
git remote set-url origin https://github.com/500tpig/sourcemux-go.git
```

### 更多文档

- [`docs/QUICKSTART.md`](docs/QUICKSTART.md) — 更完整的快速开始。
- [`docs/AI_USAGE.md`](docs/AI_USAGE.md) — AI Agent / MCP / CLI 使用建议。
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 架构图、核心链路和 provider 路由说明。
- [`docs/MIGRATION.md`](docs/MIGRATION.md) — 改名与配置迁移。
- [`docs/RELEASE.md`](docs/RELEASE.md) — 发布、Homebrew、Scoop 和 GoReleaser。

## English

SourceMux is a single-binary CLI + stdio MCP agent research router for search,
fetch, docs lookup, bounded research, and reasoning synthesis. It gives agents
fast/default search for one-hop work, `profile=auto` heavy Grok research when
configured, and policy-first URL fetch with quality, GitHub-aware, and cheap
profiles.

The default routing is:

- `web_search` / `sourcemux search`: Grok endpoint pool -> TinyFish Search -> Exa Search -> Tavily Search
- `web_fetch` / `sourcemux fetch --profile auto`: GitHub Provider for GitHub URLs; otherwise Firecrawl -> Jina Reader -> Exa Contents -> Tavily Extract -> TinyFish Fetch
- `sourcemux fetch --profile quality`: Firecrawl-first and enables Firecrawl clean-content with a longer timeout budget before fallbacks
- `sourcemux fetch --profile cheap`: Jina Reader -> Firecrawl -> Exa Contents -> Tavily Extract
- `docs_search` / `sourcemux docs-search`: Exa docs/web search fallback
- `research_run` / `sourcemux research`: plan queries -> search -> collect sources -> rank URLs -> fetch top pages (defaults to `--profile auto`)
- `smart_answer` / `sourcemux smart-answer`: run bounded research (defaults to `--profile auto`), then synthesize the final answer with a configured OpenAI-compatible reasoning endpoint

Why not just Jina or simple search?

- Jina Reader is a lightweight, zero-key URL extraction fallback. It is the
  cheap profile's first attempt, not the quality default or the ceiling for
  search, docs discovery, heavy Grok search, or synthesis.
- Simple web search returns candidate results. SourceMux adds agent-oriented
  routing, fallback, `get_sources`, fetch verification, bounded research packs,
  and reproducible JSON.
- For complex, current, comparative, or high-risk work, `research` and
  `smart-answer` default to `profile=auto`; `searchPolicy.autoPreference`
  decides when configured heavy Grok profiles are used while fallback remains
  available.

## Features

- Single Go binary for CLI and stdio MCP server modes.
- MCP text responses stay compact; CLI text/JSON remain the canonical full-output surfaces.
- Single explicit JSON config file: `./sourcemux.json` by default, or `--config /path/to/sourcemux.json`.
- Grok/OpenAI-compatible endpoint pool with priority fallback.
- Optional TinyFish, Exa, Tavily, and Jina integrations.
- Source caching via `get_sources` for MCP workflows.
- Bounded research packs for reproducible

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [500tpig](https://github.com/500tpig)
- **Source:** [500tpig/sourcemux-go](https://github.com/500tpig/sourcemux-go)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-500tpig-sourcemux-go
- Seller: https://agentstack.voostack.com/s/500tpig
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.