warrant-mcp

An MCP (Model Context Protocol) server that provides formal reasoning and argument validation tools for AI agents. Built on established computational argumentation theories — Dung, Toulmin, Walton, Pollock, Prakken, and ASPIC+.

Features

• Dung's Abstract Argumentation Framework: Extensions (grounded, preferred, stable).

• Toulmin Model: Structured argument validation.

• Walton's Schemes: Critical questions for common reasoning patterns.

• Pollock's Defeasible Reasoning: Rebutting and undercutting defeaters.

• Prakken's Dialogue Protocol: Persuasion dialogue management.

• ASPIC+: Disagreement diagnosis.

• Gradual Semantics: Argument scoring (h-Categorizer, Counting).

• Bipolar Argumentation Framework: Support + Attack relations.

Installation

This project uses uv for dependency management.

# Clone the repository
git clone https://github.com/jayden-chmod/warrant-mcp.git
cd warrant-mcp

# Install dependencies
uv sync

Usage

Running the MCP Server

warrant-mcp can be run using uv run.

uv run warrant-mcp

Configure for Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "warrant-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/warrant-mcp",
        "warrant-mcp"
      ]
    }
  }
}

🔧 MCP Tools Reference

warrant-mcp exposes 10 MCP tools that AI agents can call directly. Below is the full reference for each tool.

1. build_argument — Build Structured Argument (Toulmin)

Build a structured argument using Toulmin's model (Claim → Data → Warrant → Backing → Rebuttal → Qualifier).

Parameters:

Example:

{
  "claim": "We should use PostgreSQL instead of MongoDB for this project",
  "data": [
    {"content": "Our data has strong relational structure with foreign keys", "type": "certain"},
    {"content": "Team has 5 years of PostgreSQL experience", "type": "objective"}
  ],
  "warrant": "Relational databases excel with structured, relational data",
  "backing": ["PostgreSQL consistently outperforms MongoDB in JOIN-heavy workloads (TPC-H benchmarks)"],
  "rebuttal": ["If the data schema changes frequently, MongoDB's flexibility may be advantageous"],
  "qualifier": "very likely"
}

Returns: { argument, validation, score }

2. identify_scheme — Identify Walton's Argumentation Scheme

Identify which Walton argumentation scheme matches a claim, or retrieve details for a specific scheme.

Parameters:

Example:

{
  "claim": "We should refactor the auth module before adding OAuth support",
  "context": "The auth module has high cyclomatic complexity and no tests"
}

Returns: { matches, topScheme } — Ranked scheme matches with critical questions.

3. classify_defeater — Classify Counterargument (Pollock)

Classify a counterargument as a rebutting defeater (attacks the conclusion) or undercutting defeater (breaks the reasoning link).

Parameters:

Example:

{
  "target": "PostgreSQL is faster for our workload",
  "content": "The benchmark was run on different hardware with different data distribution",
  "type": "undercutting",
  "evidence_type": "objective"
}

Returns: { defeater, strength, penalty }

4. create_framework — Create Argumentation Framework

Create a Dung Argumentation Framework (AF) or a Bipolar AF with both attack and support relations.

Parameters:

Example:

{
  "arguments": ["A1", "A2", "A3", "A4"],
  "attacks": [["A2", "A1"], ["A3", "A2"]],
  "supports": [["A4", "A1"]]
}

Returns: { type, arguments, attacks, supports }

5. compute_extensions — Compute Acceptable Arguments (Dung)

Compute acceptable arguments using Dung's semantics (grounded, preferred, stable).

Parameters:

Example:

{
  "arguments": ["A", "B", "C"],
  "attacks": [["B", "A"], ["C", "B"]],
  "semantics": "all"
}

Returns: { grounded, preferred, stable } — Sets of acceptable arguments under each semantics.

6. score_arguments — Score Arguments (Gradual Semantics)

Score arguments on a continuous [0, 1] scale using gradual semantics.

Parameters:

Example:

{
  "arguments": ["A", "B", "C"],
  "attacks": [["B", "A"], ["C", "B"]],
  "method": "h-categorizer"
}

Returns: { method, scores } — Arguments sorted by score descending.

7. create_dialogue — Start Dialogue Session (Prakken)

Start a new argumentation dialogue session using Prakken's protocol.

Parameters:

Example:

{
  "topic": "Should we migrate from REST to GraphQL?",
  "participants": ["Proponent", "Opponent"]
}

Returns: Serialized dialogue state with ID, commitment stores, and available moves.

8. dialogue_move — Make a Dialogue Move

Make a speech act move in an active dialogue session.

Parameters:

Speech Act Protocol:

Example:

{
  "dialogue_id": "d-abc123",
  "speaker": "Proponent",
  "act": "claim",
  "content": "GraphQL reduces over-fetching and improves frontend performance"
}

Returns: Updated dialogue state with commitment stores.

9. diagnose_disagreement — Diagnose Disagreement (ASPIC+)

Diagnose WHY two agents disagree, classifying the root cause of the disagreement.

Parameters:

Disagreement Types:

Example:

{
  "agent_a": {
    "claim": "Use microservices",
    "premises": ["System needs to scale independently", "Teams work in isolation"],
    "rules": ["Independent scaling requires service boundaries"]
  },
  "agent_b": {
    "claim": "Use monolith",
    "premises": ["Team is small", "Deployment complexity is a risk"],
    "rules": ["Small teams benefit from simple deployment"]
  }
}

Returns: { diagnosis, suggestedResolutions }

10. list_schemes — List Argumentation Schemes

List all available Walton argumentation schemes with their critical question counts.

Parameters: None

Returns: { schemes: [{ name, title, criticalQuestions }] }

⚡ Skill Commands (Slash Commands)

Skills are shortcut commands that trigger structured reasoning workflows. Use them directly in conversation with an AI agent that has warrant-mcp connected.

/argue — Structured Argumentation

Build a rigorous, evidence-based argument for (or against) a technical claim.

/argue <claim>
/argue --challenge <claim>
/argue --deep <claim>

What it does:

1. Parses the claim type (Causal / Evaluative / Prescriptive / Factual / Authority)

2. Gathers evidence from the codebase and conversation history

3. Builds a Toulmin argument (Claim → Data → Warrant → Backing → Rebuttal → Qualifier)

4. Applies Walton's critical questions for the relevant argumentation scheme

5. Identifies defeaters (Pollock: Rebutting vs Undercutting)

6. Scores the argument using gradual semantics [0, 1]

7. Outputs a structured analysis with score breakdown and actionable recommendation

Example:

/argue "We should migrate from REST to GraphQL for our mobile API"
/argue --challenge "Microservices is the right architecture for our 5-person team"

/debate — Multi-Agent Adversarial Debate

Run a structured adversarial debate between virtual agents to stress-test a technical decision.

/debate <topic>
/debate <topic> --rounds 3
/debate <topic> --focus security
/debate <topic> --full

Participants:

What it produces:

• Full debate transcript with speech acts (Prakken's protocol)

• Commitment stores (what each side publicly committed to and retracted)

• Argumentation framework (arguments + attack/support relations with ASCII map)

• Argument scores via gradual semantics

• Moderator's verdict with winner, consensus solution, and conditions for revisiting

Example:

/debate "Should we rewrite the payment service in Rust?"
/debate "Monorepo vs polyrepo for our growing team" --rounds 3
/debate "Adopting Kubernetes for our infrastructure" --focus cost

/deliberate — Collaborative Multi-Perspective Deliberation

Facilitate a cooperative multi-perspective analysis where virtual experts work together (not against each other) to find the best course of action.

/deliberate <decision question>
/deliberate <decision question> --perspectives 3
/deliberate <decision question> --perspectives "frontend,backend,data"
/deliberate <decision question> --criteria "security,cost,speed"
/deliberate <decision question> --deep

Default Perspectives:

What it produces:

• Perspective analysis with gathered evidence

• Proposals with Walton's Practical Reasoning critical questions answered

• Cross-evaluation with disagreement diagnosis (ASPIC+: factual / inferential / preferential / goal conflict)

• Decision matrix with weighted multi-criteria scores

• Consensus solution with incorporated concerns from all sides

• Dissenting opinions preserved as "canary signals"

• Action plan with concrete steps, checkpoints, and re-deliberation triggers

Example:

/deliberate "How should we handle authentication for our new public API?"
/deliberate "Which database should we use for the analytics pipeline?" --perspectives "data-engineer,backend,devops"
/deliberate "Should we build or buy a feature flag system?" --criteria "cost,integration,flexibility,maintenance"

🤖 Agent Triggers

Agents are autonomous reasoning personas that perform deep, multi-step analysis. They are defined in .claude/agents/ and can be triggered by the AI when executing skill commands in --deep or --full mode.

argue Agent — Structured Argumentation Agent

A rigorous evidence-based argument builder that uses Toulmin's Model, Walton's Schemes, and Pollock's Defeaters.

Triggered by: /argue --deep <claim>

Process:

1. Parse claim type → Gather evidence (with quality tags: [CERTAIN], [OBJECTIVE], [UNCERTAIN], [SUBJECTIVE], [HYPOTHETICAL]) → Build Toulmin argument → Apply Walton's critical questions → Identify defeaters (Pollock) → Calculate argument strength [0, 1]

Score interpretation:

debate Agent — Multi-Agent Debate Orchestrator

Runs a structured adversarial debate using Prakken's Persuasion Dialogue Model with Dung's semantics and gradual scoring.

Triggered by: /debate --full <topic>

Process:

1. Setup 3 virtual debater personas (PRO, OPP, MOD) → Information gathering → Execute Prakken's protocol (speech acts with commitment stores) → Build Bipolar Argumentation Framework → Compute acceptability via gradual semantics → Moderator verdict

deliberate Agent — Collaborative Deliberation Facilitator

Facilitates cooperative multi-perspective analysis using Walton & Krabbe's Deliberation Dialogue model.

Triggered by: /deliberate --deep <question>

Process:

1. Assemble perspectives (4 domain experts) → Information seeking phase → Proposal generation (Walton's Practical Reasoning) → Cross-perspective evaluation with ASPIC+ disagreement diagnosis → Multi-criteria decision matrix → Consensus building → Action plan generation

🧩 Choosing the Right Tool

Development

# Run tests
uv run pytest

# Run specific test
uv run pytest tests/test_core.py -v

# Run with coverage
uv run pytest --cov=warrant_mcp

Project Structure

warrant-mcp/
├── src/warrant_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP server — exposes 10 tools
│   └── core/               # Core argumentation modules
│       ├── dung.py          # Abstract Argumentation Framework
│       ├── bipolar.py       # Bipolar AF (attack + support)
│       ├── gradual.py       # Gradual semantics (h-Categorizer, Counting)
│       ├── toulmin.py       # Toulmin argument model
│       ├── walton.py        # Walton's argumentation schemes
│       ├── pollock.py       # Pollock's defeasible reasoning
│       ├── prakken.py       # Prakken's dialogue protocol
│       └── aspic.py         # ASPIC+ disagreement diagnosis
├── tests/                   # Test suite
├── .claude/
│   ├── agents/              # Agent definitions (autonomous reasoning personas)
│   │   ├── argue.md         # Structured argumentation agent
│   │   ├── debate.md        # Multi-agent debate orchestrator
│   │   └── deliberate.md    # Collaborative deliberation facilitator
│   └── skills/              # Skill definitions (slash commands)
│       ├── argue.md         # /argue skill
│       ├── debate.md        # /debate skill
│       └── deliberate.md    # /deliberate skill
├── pyproject.toml
└── README.md

Theoretical Background

Dung's Abstract Argumentation Framework (1995)

Models arguments and attacks as a directed graph. Semantics determine acceptable arguments:

• Grounded: Skeptical, unique extension.

• Preferred: Credulous, maximal admissible sets.

• Stable: Conflict-free sets that attack everything outside.

Toulmin's Argument Model (1958)

Structures arguments with Claim, Data, Warrant, Backing, Rebuttal, and Qualifier.

Walton's Argumentation Schemes (1996)

Presumptive reasoning templates with critical questions (e.g., Expert Opinion, Consequences, Practical Reasoning, Analogy).

Pollock's Defeasible Reasoning (1987)

Rebutting (contradicts conclusion) vs Undercutting (breaks inference) defeaters.

Prakken's Dialogue Protocol (2006)

Formal dialogue with commitment stores and speech acts (claim, why, concede, retract, since).

ASPIC+ Disagreement Diagnosis

Classifies disagreements as Factual, Inferential, Preferential, or Goal Conflict.

Bipolar Argumentation Framework

Extended AF with both attack and support relations between arguments. Enables richer modeling of argument interactions including supported attacks and secondary attacks.

Gradual Semantics

Scores arguments on a continuous [0, 1] scale instead of binary accept/reject. Methods: h-Categorizer and Counting semantics.

License

MIT