内容
# MAST-MCP
[](https://app.codacy.com/gh/ronsilver/mast-mcp/dashboard)
多提供商主动验证层，用于 [MCP 顺序思考](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) 服务器。可直接替换，通过本地或云端大型语言模型（LLM）挑战每个推理步骤，然后将结果返回给调用代理。
支持 Ollama、OpenAI、Anthropic、Google Gemini、Amazon Bedrock、GitHub 模型、OpenRouter 和任何 OpenAI 兼容的端点。
## 验证模式
| 模式 | 行为 |
|---|---|
| `validate` | 仅评论者 — 识别问题 + 优势 |
| `debate` | 评论者 + 裁判 — 裁决 + 建议修订 |
| `debono` | 德博诺六顶思考帽（7 个顺序帽） |
| `actor_critic` | 迭代评论者 + 裁判循环，直到收敛 |
| `brainstorm` | N 个并行生成器 + 综合器 |
| `tot` | 思维树（并行分支 + 投票者） |
| `kalman` | 质量分数的贝叶斯融合 |
| `workflow` | 按顺序链接的模式管道 |
| `passive` | 直通（无验证） |
## 目录
- [为什么](#为什么)
- [快速开始](#快速开始)
- [提供商](#提供商)
- [Ollama](#ollama)
- [OpenAI](#openai)
- [Anthropic](#anthropic)
- [Gemini](#gemini)
- [Bedrock](#bedrock)
- [GitHub 模型](#github-模型)
- [OpenRouter](#openrouter)
- [配置](#配置)
- [配置文件（`mast.toml`）](#配置文件masttoml)
- [环境变量](#环境变量)
- [优先级](#优先级)
- [提供商选择指南](#提供商选择指南)
- [MCP 客户端配置](#mcp-客户端配置)
- [模式](#模式)
- [工具](#工具)
- [自定义策略](#自定义策略)
- [架构](#架构)
- [开发](#开发)
- [更新日志](#更新日志)
- [许可证](#许可证)
## 为什么
上游 `sequential-thinking` MCP 服务器是被动的 — 它只保留思维。如果主 LLM 出现幻觉或基于错误的假设，什么都不会纠正它。MAST 添加了一个主动验证循环，使用小型本地模型（3B-8B）用于隐私和成本，或使用任何前沿模型用于最大质量。相同的 MCP 工具 API — 与原始 API 兼容。
## 快速开始
### 通过 `uvx` 安装
```bash
uvx --from git+https://github.com/ronsilver/mast-mcp.git mast-server
```
### 验证设置
```bash
mast-server --doctor
```
检查后端连接性，验证凭证，并列出活动模式所需的模型。
## 提供商
MAST 配备了 7 个后端实现，均可通过 `MAST_PROVIDER` 或 `mast.toml` 配置文件互换。
### Ollama
默认提供商。本地优先；不需要 API 密钥。
```bash
MAST_PROVIDER=ollama \
OLLAMA_BASE_URL=http://localhost:11434 \
CRITIC_MODEL=mistral:7b-instruct \
JUDGE_MODEL=deepseek-r1:8b \
mast-server
```
[Ollama 云](https://ollama.com/pricing) 通过相同的提供商支持，`OLLAMA_BASE_URL=https://ollama.com/api` + `OLLAMA_CLOUD_API_KEY=sk-xxx`。
### OpenAI
```bash
MAST_PROVIDER=openai \
OPENAI_API_KEY=sk-xxx \
CRITIC_MODEL=gpt-4o-mini \
JUDGE_MODEL=gpt-4o-mini \
mast-server
```
也接受 `OPENAI_BASE_URL` 以指向 vLLM、LM Studio、TGI 或任何 OpenAI 兼容的端点。
### Anthropic
```bash
MAST_PROVIDER=anthropic \
ANTHROPIC_API_KEY=sk-ant-xxx \
CRITIC_MODEL=claude-3-5-sonnet-20241022 \
JUDGE_MODEL=claude-3-5-sonnet-20241022 \
mast-server
```
### Gemini
```bash
MAST_PROVIDER=gemini \
GEMINI_API_KEY=xxx \
CRITIC_MODEL=gemini-2.0-flash \
JUDGE_MODEL=gemini-2.0-flash \
mast-server
```
### Bedrock
支持双重身份验证：
```bash
# Token auth（不需要 boto3）
MAST_PROVIDER=bedrock \
BEDROCK_AUTH_METHOD=token \
BEDROCK_TOKEN=xxx \
AWS_REGION=us-east-1 \
CRITIC_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0 \
mast-server
# IAM auth（需要 boto3 — pip install mast-mcp[bedrock]）
MAST_PROVIDER=bedrock \
BEDROCK_AUTH_METHOD=iam \
AWS_REGION=us-east-1 \
AWS_PROFILE=default \
CRITIC_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0 \
mast-server
```
### GitHub 模型
```bash
MAST_PROVIDER=github \
GITHUB_TOKEN=ghp_xxx \
CRITIC_MODEL=gpt-4o-mini \
JUDGE_MODEL=gpt-4o-mini \
mast-server
```
### OpenRouter
```bash
MAST_PROVIDER=openrouter \
OPENROUTER_API_KEY=sk-or-xxx \
CRITIC_MODEL=anthropic/claude-3.5-sonnet \
JUDGE_MODEL=anthropic/claude-3.5-sonnet \
mast-server
```
## 配置
三个层次，按此顺序合并（优先级最高者胜）:
1. **环境变量** — `MAST_*`、`OPENAI_*`、`ANTHROPIC_*` 等。
2. **配置文件** — `mast.toml` 或 `mast.json`，带有 `${VAR}` 插值。
3. **内置默认值** — 在源代码中定义。
### 配置文件（`mast.toml`）
将 `mast.toml` 放在以下任意位置（找到第一个为准）：
- `$MAST_CONFIG_FILE`（任意路径）
- `./mast.toml` 或 `./mast.json`
- `~/.config/mast/config.toml` 或 `~/.config/mast/config.json`
文件支持 `${VAR}` 插值，带有可选默认值：
```toml
# mast.toml — 从 mast.toml.example 复制
[provider]
default = "openai" # 或 ${MAST_PROVIDER:-openai}
[provider.openai]
api_key = ${OPENAI_API_KEY} # 必需，在加载时解析
[provider.bedrock]
auth_method = "token" # 或 ${BEDROCK_AUTH_METHOD:-iam}
region = "us-east-1" # 或 ${AWS_REGION:-us-east-1}
token = ${BEDROCK_TOKEN} # token 认证时的 bearer token
[provider.ollama]
base_url = "http://localhost:11434" # 或 ${OLLAMA_BASE_URL:-http://localhost:11434}
[strategy]
default = "debate" # 或 ${MAST_MODE:-debate}
dir = "~/.config/mast/strategies" # 自定义策略目录
[agents]
critic_model = "gpt-4o-mini" # 或 ${CRITIC_MODEL:-gpt-4o-mini}
judge_model = "gpt-4o-mini"
[modes.debono]
blue_open_model = "qwen2.5:3b"
# ... （7 顶帽子）
[modes.workflow]
stages = "debate,kalman"
```
**`${VAR}` 规则：**
- `${VAR}` — 由环境变量值替换。如果未设置，则 **错误** （快速失败）。
- `${VAR:-default}` — 由环境变量替换，或如果未设置/为空，则为 `default`。
- 小写标识符不扩展。
- 参见 [`mast.toml.example`](mast.toml.example) 获取完整模板。
> **安全：** `mast.toml` 默认被 gitignore。**绝不** 提交包含真实凭证的文件。
### 环境变量
#### 提供商选择
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MAST_PROVIDER` | `ollama` | 以下之一：`ollama`、`openai`、`anthropic`、`gemini`、`bedrock`、`github`、`openrouter`。如果未设置，则根据可用凭证自动检测 |
| `MAST_BASE_URL` | — | 通用基准 URL 重写 |
| `MAST_API_KEY` | — | 通用 API 密钥（提供商特定密钥优先） |
| `MAST_CONFIG_FILE` | — | `mast.toml` 的显式路径 |
#### Ollama
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama 服务器端点 |
| `OLLAMA_CLOUD_API_KEY` | — | `https://ollama.com/api` 的 bearer token |
| `OLLAMA_TOP_P` | `0.9` | top-p 采样 |
#### OpenAI 兼容
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OPENAI_API_KEY` | — | OpenAI API 密钥 |
| `OPENAI_BASE_URL` | — | vLLM/LM Studio/TGI 的重写 |
#### Anthropic
| 变量 | 默认值 | 描述 |
|---|---|---|
| `ANTHROPIC_API_KEY` | — | Anthropic API 密钥 |
#### Gemini
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GEMINI_API_KEY` | — | Google Gemini API 密钥 |
#### Bedrock
| 变量 | 默认值 | 描述 |
|---|---|---|
| `BEDROCK_AUTH_METHOD` | `iam` | `iam`（通过 boto3 的 SigV4）或 `token`（通过 httpx 的 bearer） |
| `BEDROCK_TOKEN` | — | bearer token（当 `BEDROCK_AUTH_METHOD=token` 时） |
| `AWS_REGION` | `us-east-1` | Bedrock 区域 |
| `AWS_PROFILE` | — | AWS CLI 配置文件（仅限 iam） |
| `AWS_ACCESS_KEY_ID` | — | 显式 IAM 凭证（可选） |
| `AWS_SECRET_ACCESS_KEY` | — | 显式 IAM 凭证（可选） |
| `AWS_SESSION_TOKEN` | — | STS 会话令牌（可选） |
#### GitHub 模型
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GITHUB_TOKEN` | — | GitHub PAT，用于 Models 推理 |
#### OpenRouter
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OPENROUTER_API_KEY` | — | OpenRouter API 密钥 |
#### 服务器 / 行为
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MAST_MODE` | `debate` | 默认验证模式 |
| `MAST_TIMEOUT_MS` | `15000` | 每次调用的后端超时 |
| `MAST_FORMAT_MODE` | `schema` | Ollama JSON 格式：`schema`、`json`、`text` |
| `MAST_SKIP_THRESHOLD_CHARS` | `20` | 思想长度低于此字符数时跳过验证 |
| `MAST_CACHE_TTL_S` | `300` | 验证缓存 TTL（随机模式始终绕过） |
| `MAST_MAX_HISTORY` | `50` | 服务器内存中保留的最大思想数 |
| `MAST_HISTORY_WINDOW` | `3` | 代理显示的最新思想数 |
| `MAST_HISTORY_MAX_TOKENS` | `1500` | 历史上下文中的最大 token 数 |
| `MAST_LOG_LEVEL` | `INFO` | 日志级别：`DEBUG`、`INFO`、`WARN`、`ERROR` |
| `MAST_STRATEGY_DIR` | — | 自定义策略插件目录（例如 `~/.config/mast/strategies`） |
| `DISABLE_THOUGHT_LOGGING` | `false` | 禁止控制台思想输出 |
| `MAST_COLOR_THOUGHTS` | `false` | 控制台输出中的 ANSI 颜色 |
#### 代理模型
| 变量 | 默认值 | 描述 |
|---|---|---|
| `CRITIC_MODEL` | `mistral:7b-instruct` | 评论者模型（validate、debate、actor_critic、workflow） |
| `JUDGE_MODEL` | `deepseek-r1:8b` | 裁判模型（debate、actor_critic、workflow） |
#### 模式特定
| 变量 | 默认值 | 模式 |
|---|---|---|
| `DEBONO_BLUE_OPEN_MODEL` | `qwen2.5:3b` | debono |
| `DEBONO_WHITE_MODEL` | `qwen2.5:3b` | debono |
| `DEBONO_GREEN_MODEL` | `qwen2.5:1.5b` | debono |
| `DEBONO_YELLOW_MODEL` | `qwen2.5:3b` | debono |
| `DEBONO_BLACK_MODEL` | `qwen2.5:3b` | debono |
| `DEBONO_RED_MODEL` | `qwen2.5:1.5b` | debono |
| `DEBONO_BLUE_CLOSE_MODEL` | `qwen2.5:3b` | debono |
| `DEBONO_SKIP_RED` | `false` | 跳过红色帽子 |
| `ACTOR_CRITIC_MAX_ROUNDS` | `3` | actor_critic |
| `BRAINSTORM_MODELS` | `llama3:8b,mistral:7b` | brainstorm（逗号分隔） |
| `BRAINSTORM_SYNTH_MODEL` | `qwen2.5:14b` | brainstorm |
| `TOT_BRANCH_MODELS` | `llama3:8b,mistral:7b,qwen2.5:7b` | tot |
| `TOT_VOTER_MODEL` | `deepseek-r1:8b` | tot |
| `KALMAN_SCORER_MODELS` | `mistral:7b,qwen2.5:7b,phi3:mini` | kalman |
| `KALMAN_P_THRESHOLD` | `0.18` | kalman 收敛阈值 |
| `KALMAN_ACCEPT_THRESHOLD` | `0.70` | kalman 最低接受分数 |
| `MAST_WORKFLOW_STAGES` | `debate,kalman` | workflow 链 |
## 优先级
对于任何给定字段，值按以下顺序解析：
```text
真实环境变量 > ${VAR} 扩展 > ${VAR:-默认值} > 文件中的字面值 > 代码默认值
```
示例：
| 来源 | `api_key = "sk-xxx"` | `${OPENAI_API_KEY}`（环境变量设置） | `${OPENAI_API_KEY}`（环境变量未设置） |
|---|---|---|---|
| 环境变量 `OPENAI_API_KEY=sk-yyy` | `sk-yyy` 胜 | `sk-yyy` 胜 | `sk-xxx` 胜 |
| 环境变量未设置 | `sk-xxx` 胜 | **错误** | `sk-xxx` 胜 |
## 提供商选择指南
| 优先级 | 如果您需要... | 推荐提供商 |
|---|---|---|
| 隐私、免费、离线 | 本地推理 | **Ollama**（3B-8B 模型） |
| 最佳质量 | 前沿推理 | **Anthropic** (`claude-3-5-sonnet`) 或 **Gemini** (`gemini-2.0-flash`) |
| 最便宜的云 | 按令牌付费的最低成本 | **OpenRouter**（DeepSeek、Llama 等） |
| GitHub Copilot 用户 | 已经拥有 GitHub 令牌 | **GitHub 模型** |
| AWS 企业 | IAM 角色、VPC、审计日志 | **Bedrock**（iam） |
| 自托管 OpenAI | vLLM、LM Studio、llama.cpp 服务器 | **OpenAI** + `OPENAI_BASE_URL` 重写 |
| 多模型路由器 | 按请求切换模型 | **OpenRouter**，使用 `provider:model` 语法 |
## MCP 客户端配置
将以下内容添加到您的 MCP 客户端配置中（`claude_desktop_config.json`、`~/.cursor/mcp.json`、`/.vscode/mcp.json` 等）：
### Ollama（默认）
```json
{
"mcpServers": {
"mast-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/ronsilver/mast-mcp.git", "mast-server"],
"env": {
"MAST_PROVIDER": "ollama",
"OLLAMA_BASE_URL": "http://localhost:11434",
"CRITIC_MODEL": "mistral:7b-instruct",
"JUDGE_MODEL": "deepseek-r1:8b",
"MAST_MODE": "debate"
}
}
}
}
```
### OpenAI
```json
{
"mcpServers": {
"mast-mcp": {
"command": "uvx",
"args": ["mast-mcp"],
"env": {
"MAST_PROVIDER": "openai",
"OPENAI_API_KEY": "sk-xxx",
"CRITIC_MODEL": "gpt-4o-mini",
"JUDGE_MODEL": "gpt-4o-mini",
"MAST_MODE": "debate"
}
}
}
}
```
### Debono（六顶思考帽）
```json
{
"mcpServers": {
"mast-mcp": {
"command": "uvx",
"args": ["mast-mcp"],
"env": {
"MAST_PROVIDER": "ollama",
"MAST_MODE": "debono",
"DEBONO_BLUE_OPEN_MODEL": "qwen2.5:3b",
"DEBONO_WHITE_MODEL": "qwen2.5:3b",
"DEBONO_GREEN_MODEL": "qwen2.5:1.5b",
"DEBONO_YELLOW_MODEL": "qwen2.5:3b",
"DEBONO_BLACK_MODEL": "qwen2.5:3b",
"DEBONO_RED_MODEL": "qwen2.5:1.5b",
"DEBONO_BLUE_CLOSE_MODEL": "qwen2.5:3b"
}
}
}
}
```
### 从 v0.2.x 迁移（仅限 Ollama）
如果从 `mast-ollama` 升级，请在客户端配置中将服务器名称 `"mast-ollama"` 替换为 `"mast-mcp"`，并重命名对旧 GitHub 仓库的任何引用。`mast-server` 入口点保留。
## 模式
| 模式 | 行为 | 额外延迟 |
|---|---|---|
| `passive` | 与上游顺序思考相同（直通） | 0 毫秒 |
| `validate` | 仅评论者 | ~1 倍评论者 |
| `debate` | 评论者 + 裁判 | ~2 倍 |
| `debono` | 德博诺六顶思考帽：蓝色、白色、绿色、黄色、黑色、红色、蓝色关闭 | ~5 秒 |
| `actor_critic` | 迭代评论者 + 裁判循环，直到收敛 | ~2 倍 × 轮数 |
| `brainstorm` | N 个并行生成器 + 综合器 | ~2 倍 × N 个模型 |
| `tot` | N 个并行分支生成器 + 投票者 | ~2 倍 × N 个分支 |
| `kalman` | N 个评分器 + 贝叶斯融合 | ~1 倍 × N 个评分器 |
| `workflow` | 按顺序链接的模式管道 | 阶段总和 |
## 工具
### `sequentialthinking`（兼容）
与上游顺序思考相同，带有可选的 MAST 字段：
- `mode`：为此步骤重写服务器默认值
- `skipValidation`：为此特定思想绕过验证
### `mast_debate`（扩展）
与 `sequentialthinking` 相同的架构，带有每调用可选的模型重写：
- `criticModel`、`judgeModel` — 重写评论者/裁判模型
- `debonoPrimaryModel`、`debonoCreativeModel` — 重写主要/创造性（debono）
当未指定 `mode` 时，默认为 `debate`。客户端的显式 `mode` 受到尊重。
## 自定义策略
MAST 配备了 9 种内置策略。您可以通过两种机制添加更多策略：
### 入口点（pip 包）
在 `pyproject.toml` 中发布带有入口点的 Python 包：
```toml
[project.entry-points."mast.strategies"]
my_strategy = "my_pkg.strategies:MyStrategy"
```
`MyStrategy` 必须公开一个 `name` 属性和一个与 `Strategy` 协议匹配的异步 `run` 方法。
### 本地目录（`MAST_STRATEGY_DIR`）
将 `.py` 文件放入 `~/.config/mast/strategies/`（或 `MAST_STRATEGY_DIR` 指向的位置）：
```python
# ~/.config/mast/strategies/redteam.py
from typing import Any
from mast.validation.strategy import Strategy
class RedTeamStrategy:
name = "redteam"
async def run(
self,
thought,
history,
upstream_response,
*,
critic_model=None,
judge_model=None,
backend,
cache,
) -> Any:
# ... 您的自定义验证逻辑 ...
return None
```
MAST 在启动时自动发现此目录中的 `*.py` 文件。内置策略名称在冲突时优先（记录警告）。
## 架构
```text
LLM 客户端 → MCP 顺序思考工具
↓
MAST 服务器（mast-mcp）
├── __main__.py （入口点）
├── _upstream.py （上游库的 1:1 端口）
├── config.py （Pydantic 设置 + mast.toml）
├── config_loader.py （TOML/JSON + ${VAR} 解析器）
├── agents/
│ ├── protocols.py （聊天后端 ABC）
│ ├── registry.py （提供商工厂 + 自动检测）
│ ├── base.py （OllamaBackend）
│ ├── backends/
│ │ ├── openai.py （OpenAICompatBackend）
│ │ ├── openrouter.py
│ │ ├── github.py
│ │ ├── anthropic.py
│ │ ├── gemini.py
│ │ └── bedrock.py （iam + token 双重身份验证）
│ ├── critic.py, judge.py, debono.py
│ ├── actor_critic.py, brainstorm.py
│ ├── tot.py, kalman.py
│ └── _json_utils.py （共享防御解析器）
├── validation/
│ ├── orchestrator.py （模式调度）
│ ├── cache.py （LRU+TTL）
│ ├── strategy.py （策略协议）
│ ├── registry.py （入口点 + 目录加载器）
│ ├── strategies/ （9 个内置占位符）
│ └── schemas.py （Pydantic 模型）
└── prompts/
├── debate/, debono/, brainstorm/, tot/, kalman/
```
## 开发
```bash
uv venv
source .venv/bin/activate
uv sync --extra dev
# 运行所有测试（343 个预期）
make test
# 覆盖率（终端 + HTML 报告，门槛 ≥ 70%）
make coverage
# 整理、格式化、类型检查
make lint
make format
make typecheck
# 完整检查（整理 + 格式化 + 类型 + 测试）
make check
# 安装 Bedrock 额外功能（可选）
uv sync --extra bedrock
# 验证后端连接性
mast-server --doctor
```
## 更新日志
请参阅 [CHANGELOG.md](CHANGELOG.md) 获取发布历史。
## 许可证
MIT — 基于 [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) （MIT）。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器