Skip to content

ronsilver/mast-mcp

BranchesTags

Repository files navigation

MAST-MCP

Codacy Badge

Multi-provider active validation layer for the MCP sequential-thinking server. Drop-in replacement that challenges each reasoning step with local or cloud LLMs before returning the result to the calling agent.

Works with Ollama, OpenAI, Anthropic, Google Gemini, Amazon Bedrock, GitHub Models, OpenRouter, and any OpenAI-compatible endpoint.

Validation modes

Mode Behavior
validate Critic only — identifies issues + strengths
debate Critic + Judge — verdict + suggested revision
debono De Bono Six Thinking Hats (7 sequential hats)
actor_critic Iterative Critic+Judge loop until convergence
brainstorm N parallel generators + synthesizer
tot Tree of Thoughts (parallel branches + voter)
kalman Bayesian fusion of quality scores
workflow Pipeline of modes chained in sequence
passive Passthrough (no validation)

Table of Contents

Why

The upstream sequential-thinking MCP server is passive — it only persists thoughts. If the main LLM hallucinates or anchors on a bad assumption, nothing corrects it. MAST adds an active validation loop using small local models (3B–8B) for privacy and cost, or any frontier model for max quality. The same MCP tool API — drop-in compatible with the original.

Quick Start

Install via uvx

uvx --from git+https://github.com/ronsilver/mast-mcp.git mast-server

Verify setup

mast-server --doctor

Checks backend connectivity, validates credentials, and lists required vs available models for the active mode.

Providers

MAST ships with 7 backend implementations, all interchangeable via MAST_PROVIDER or the mast.toml config file.

Ollama

Default provider. Local-first; no API key required.

MAST_PROVIDER=ollama \
OLLAMA_BASE_URL=http://localhost:11434 \
CRITIC_MODEL=mistral:7b-instruct \
JUDGE_MODEL=deepseek-r1:8b \
mast-server

Ollama Cloud supported via the same provider with OLLAMA_BASE_URL=https://ollama.com/api + OLLAMA_CLOUD_API_KEY=sk-xxx.

OpenAI

MAST_PROVIDER=openai \
OPENAI_API_KEY=sk-xxx \
CRITIC_MODEL=gpt-4o-mini \
JUDGE_MODEL=gpt-4o-mini \
mast-server

Also accepts OPENAI_BASE_URL to point at vLLM, LM Studio, TGI, or any OpenAI-compatible endpoint.

Anthropic

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

MAST_PROVIDER=gemini \
GEMINI_API_KEY=xxx \
CRITIC_MODEL=gemini-2.0-flash \
JUDGE_MODEL=gemini-2.0-flash \
mast-server

Bedrock

Dual authentication supported:

# Token auth (no boto3 needed)
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 (requires 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 Models

MAST_PROVIDER=github \
GITHUB_TOKEN=ghp_xxx \
CRITIC_MODEL=gpt-4o-mini \
JUDGE_MODEL=gpt-4o-mini \
mast-server

OpenRouter

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

Configuration

Three layers, merged in this order (highest precedence wins):

  1. Environment variables — MAST_*, OPENAI_*, ANTHROPIC_*, etc.
  2. Config file — mast.toml or mast.json with ${VAR} interpolation
  3. Built-in defaults — defined in source code

Config File (mast.toml)

Place mast.toml in any of these locations (first found wins):

  • $MAST_CONFIG_FILE (any path)
  • ./mast.toml or ./mast.json
  • ~/.config/mast/config.toml or ~/.config/mast/config.json

The file supports ${VAR} interpolation with optional defaults:

# mast.toml — copied from mast.toml.example
[provider]
default = "openai"                    # or ${MAST_PROVIDER:-openai}

[provider.openai]
api_key = ${OPENAI_API_KEY}            # required, resolved at load

[provider.bedrock]
auth_method = "token"                  # or ${BEDROCK_AUTH_METHOD:-iam}
region = "us-east-1"                   # or ${AWS_REGION:-us-east-1}
token = ${BEDROCK_TOKEN}               # bearer token when auth=token

[provider.ollama]
base_url = "http://localhost:11434"    # or ${OLLAMA_BASE_URL:-http://localhost:11434}

[strategy]
default = "debate"                     # or ${MAST_MODE:-debate}
dir = "~/.config/mast/strategies"      # custom strategies dir

[agents]
critic_model = "gpt-4o-mini"           # or ${CRITIC_MODEL:-gpt-4o-mini}
judge_model  = "gpt-4o-mini"

[modes.debono]
blue_open_model = "qwen2.5:3b"
# ... (7 hats)

[modes.workflow]
stages = "debate,kalman"

${VAR} rules:

  • ${VAR} — replaced by env var value. Error if unset (fail fast).
  • ${VAR:-default} — replaced by env var, or default if unset/empty.
  • Lowercase identifiers are not expanded.
  • See mast.toml.example for the full template.

Security: mast.toml is gitignored by default. Never commit it with real credentials.

Environment Variables

Provider selection

Variable Default Description
MAST_PROVIDER ollama One of: ollama, openai, anthropic, gemini, bedrock, github, openrouter. If unset, auto-detect from available credentials
MAST_BASE_URL — Generic base URL override
MAST_API_KEY — Generic API key (provider-specific keys take precedence)
MAST_CONFIG_FILE — Explicit path to mast.toml

Ollama

Variable Default Description
OLLAMA_BASE_URL http://localhost:11434 Ollama server endpoint
OLLAMA_CLOUD_API_KEY — Bearer token for https://ollama.com/api
OLLAMA_TOP_P 0.9 Top-p sampling

OpenAI-compatible

Variable Default Description
OPENAI_API_KEY — OpenAI API key
OPENAI_BASE_URL — Override for vLLM/LM Studio/TGI

Anthropic

Variable Default Description
ANTHROPIC_API_KEY — Anthropic API key

Gemini

Variable Default Description
GEMINI_API_KEY — Google Gemini API key

Bedrock

Variable Default Description
BEDROCK_AUTH_METHOD iam iam (SigV4 via boto3) or token (bearer via httpx)
BEDROCK_TOKEN — Bearer token (required when BEDROCK_AUTH_METHOD=token)
AWS_REGION us-east-1 Bedrock region
AWS_PROFILE — AWS CLI profile (iam only)
AWS_ACCESS_KEY_ID — Explicit IAM creds (optional)
AWS_SECRET_ACCESS_KEY — Explicit IAM creds (optional)
AWS_SESSION_TOKEN — STS session token (optional)

GitHub Models

Variable Default Description
GITHUB_TOKEN — GitHub PAT for Models inference

OpenRouter

Variable Default Description
OPENROUTER_API_KEY — OpenRouter API key

Server / behavior

Variable Default Description
MAST_MODE debate Default validation mode
MAST_TIMEOUT_MS 15000 Per-call backend timeout
MAST_FORMAT_MODE schema Ollama JSON format: schema, json, text
MAST_SKIP_THRESHOLD_CHARS 20 Skip validation for thoughts under this many chars
MAST_CACHE_TTL_S 300 Validation cache TTL (stochastic modes always bypass)
MAST_MAX_HISTORY 50 Max thoughts retained in server memory
MAST_HISTORY_WINDOW 3 Most recent thoughts shown in full to agents
MAST_HISTORY_MAX_TOKENS 1500 Max tokens in history context
MAST_LOG_LEVEL INFO Log level: DEBUG, INFO, WARN, ERROR
MAST_STRATEGY_DIR — Custom strategy plugins directory (e.g. ~/.config/mast/strategies)
DISABLE_THOUGHT_LOGGING false Suppress console thought output
MAST_COLOR_THOUGHTS false ANSI colours in console output

Agent models

Variable Default Description
CRITIC_MODEL mistral:7b-instruct Critic model (validate, debate, actor_critic, workflow)
JUDGE_MODEL deepseek-r1:8b Judge model (debate, actor_critic, workflow)

Mode-specific

Variable Default Mode
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 Skip Red hat entirely
ACTOR_CRITIC_MAX_ROUNDS 3 actor_critic
BRAINSTORM_MODELS llama3:8b,mistral:7b brainstorm (comma-separated)
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 convergence threshold
KALMAN_ACCEPT_THRESHOLD 0.70 kalman min score to accept
MAST_WORKFLOW_STAGES debate,kalman workflow chain

Precedence

For any given field, the value is resolved in this order:

real env var > ${VAR} expanded > ${VAR:-default} > literal in file > code default

Examples:

Source api_key = "sk-xxx" ${OPENAI_API_KEY} (env set) ${OPENAI_API_KEY} (env unset)
env OPENAI_API_KEY=sk-yyy sk-yyy wins sk-yyy wins sk-xxx wins
env unset sk-xxx wins error sk-xxx wins

Provider Selection Guide

Priority If you need... Recommended provider
Privacy, free, offline Local inference Ollama (3B–8B models)
Best quality Frontier reasoning Anthropic (claude-3-5-sonnet) or Gemini (gemini-2.0-flash)
Cheapest cloud Pay-per-token minimal cost OpenRouter (DeepSeek, Llama, etc.)
GitHub Copilot users Already have GitHub token GitHub Models
AWS enterprise IAM roles, VPC, audit logs Bedrock (iam)
Self-hosted OpenAI vLLM, LM Studio, llama.cpp server OpenAI + OPENAI_BASE_URL override
Multi-model router Switch models per request OpenRouter with provider:model syntax

MCP Client Configuration

Add to your MCP client config (claude_desktop_config.json, ~/.cursor/mcp.json, .vscode/mcp.json, etc.).

Ollama (default)

{
  "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

{
  "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 (Six Hats)

{
  "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"
      }
    }
  }
}

Migration from v0.2.x (Ollama-only)

If upgrading from mast-ollama, replace the server name "mast-ollama" with "mast-mcp" in your client config and rename any references to the old GitHub repo. The mast-server entry point is preserved.

Modes

Mode Behavior Extra latency
passive Identical to upstream sequential-thinking (passthrough) 0 ms
validate Critic only ~1x critic model
debate Critic + Judge ~2x
debono De Bono Six Hats: Blue, White, Green, Yellow, Black, Red, Blue Close ~5s
actor_critic Iterative Critic+Judge loop up to ACTOR_CRITIC_MAX_ROUNDS ~2x × rounds
brainstorm N parallel generators + Synthesizer ~2x × N models
tot N parallel branch generators + Voter ~2x × N branches
kalman N scorers + Bayesian fusion ~1x × N scorers
workflow Pipeline of modes chained in sequence Sum of stages

Tools

sequentialthinking (drop-in compatible)

Same as upstream sequential-thinking plus optional MAST fields:

  • mode: override the server default for this step
  • skipValidation: bypass validation for this specific thought

mast_debate (extended)

Same schema as sequentialthinking plus optional model overrides per call:

  • criticModel, judgeModel — override the Critic/Judge models
  • debonoPrimaryModel, debonoCreativeModel — override primary/creative (debono)

When no mode is specified, defaults to debate. Explicit mode from the client is respected.

Custom Strategies

MAST ships with 9 built-in strategies. You can add more via two mechanisms:

Entry points (pip packages)

Publish a Python package with an entry point in pyproject.toml:

[project.entry-points."mast.strategies"]
my_strategy = "my_pkg.strategies:MyStrategy"

MyStrategy must expose a name attribute and an async run method matching the Strategy protocol.

Local directory (MAST_STRATEGY_DIR)

Drop a .py file in ~/.config/mast/strategies/ (or wherever MAST_STRATEGY_DIR points):

# ~/.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:
        # ... your custom validation logic ...
        return None

MAST auto-discovers *.py files in this directory at startup. Built-in strategy names win on conflict (warnings logged).

Architecture

LLM Client → MCP sequentialthinking tool
                    ↓
              MAST Server (mast-mcp)
              ├── __main__.py        (entry point)
              ├── _upstream.py       (1:1 port of upstream lib.ts)
              ├── config.py          (Pydantic settings + mast.toml)
              ├── config_loader.py   (TOML/JSON + ${VAR} resolver)
              ├── agents/
              │   ├── protocols.py   (ChatBackend ABC)
              │   ├── registry.py    (provider factory + auto-detect)
              │   ├── base.py        (OllamaBackend)
              │   ├── backends/
              │   │   ├── openai.py  (OpenAICompatBackend)
              │   │   ├── openrouter.py
              │   │   ├── github.py
              │   │   ├── anthropic.py
              │   │   ├── gemini.py
              │   │   └── bedrock.py (iam + token dual-auth)
              │   ├── critic.py, judge.py, debono.py
              │   ├── actor_critic.py, brainstorm.py
              │   ├── tot.py, kalman.py
              │   └── _json_utils.py (shared defensive parser)
              ├── validation/
              │   ├── orchestrator.py (mode dispatch)
              │   ├── cache.py       (LRU+TTL)
              │   ├── strategy.py    (Strategy Protocol)
              │   ├── registry.py    (entry-point + dir loader)
              │   ├── strategies/    (9 built-in placeholders)
              │   └── schemas.py     (Pydantic models)
              └── prompts/
                  ├── debate/, debono/, brainstorm/, tot/, kalman/

Development

uv venv
source .venv/bin/activate
uv sync --extra dev

# Run all tests (343 expected)
make test

# Coverage (terminal + HTML report, gate ≥ 70%)
make coverage

# Lint, format, type check
make lint
make format
make typecheck

# Full check (lint + format + type + test)
make check

# Install Bedrock extra (optional)
uv sync --extra bedrock

# Verify backend connectivity
mast-server --doctor

Changelog

See CHANGELOG.md for release history.

License

MIT — based on modelcontextprotocol/servers (MIT).

About

Multi-Agent Sequential Thinking with Ollama — Active validation layer for the MCP sequential-thinking server.

Topics

python ai mcp multi-agent agents llm ollama model-context-protocol sequential-thinking

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.2.0 Latest
Jun 1, 2026

Packages

 
 
 

Contributors

Languages