Parliamentary NLP MCP Auditor

A Model Context Protocol (MCP) server providing structured tools for auditing hate speech and offensive language in formal Brazilian parliamentary speeches.

Built for institutional speech moderation in a low-resource NLP setting (Brazilian Portuguese): a BERTimbau-family classifier with explicit uncertainty quantification and a stable tool contract for LLM clients (Cursor, Claude Desktop, MCP Inspector).

Table of Contents

1. Summary

2. Architecture

3. Demo

4. Key Features

5. Quickstart via Docker

6. Installation Tutorial

7. Usage Tutorial

8. Connect to Cursor / Claude Desktop

9. Sample Output

10. Project Layout

11. Inference Pipeline

12. Troubleshooting

13. License

Related MCP server: glin-profanity-mcp

Summary

Legislative chambers produce a continuous stream of floor speeches and digital rhetoric. Offensive language, ad-hominem attacks, and hate speech in that stream are costly to review manually and poorly covered by English-centric moderation stacks.

This repository is the serving layer of a parliamentary discourse auditor:

Modeling (corpus, taxonomy, training, metrics, results, figures) lives in a dedicated document:

👉 docs/MODELING.md — full modeling & evaluation specification

Reproducible experiments (notebook + pipeline) and raw tables:

• notebooks/ — experiments_hierarchy_imbalance.ipynb + experimentos_pipeline.py

• docs/results/ — CSV / JSON metrics

• docs/figures/ — heatmaps, confusion matrices, ROC/PR

Runtime model strategy (important)

Override without code changes:

export PARLIAMENTARY_NLP_MODEL_ID="alissonf216/parliamentary-bertimbau-auditor"
parliamentary-nlp-mcp

Canonical labels: NEUTRAL, GENERIC_OFFENSE, TARGETED_OFFENSE, EXPLICIT_HATE_SPEECH.

Architecture

The server is a thin MCP façade over a fine-tuned transformer. Agents talk MCP over stdio; weights load lazily from Hugging Face on the first tool call.

flowchart LR
  subgraph Clients
    Claude[Claude Desktop]
    Cursor[Cursor / IDE agent]
    Inspector[MCP Inspector]
  end

  subgraph "This repository"
    MCP["MCP Server<br/>audit_parliamentary_speech"]
    Engine["Inference engine<br/>tokenize → softmax → Shannon entropy"]
  end

  HF["Hugging Face<br/>parliamentary-bertimbau-auditor"]

  Claude -->|MCP stdio| MCP
  Cursor -->|MCP stdio| MCP
  Inspector -->|MCP stdio| MCP
  MCP --> Engine
  Engine -->|lazy download / cache| HF

Demo

Screen capture of the tool classifying a parliamentary utterance via an MCP client (Claude Desktop, Cursor, or MCP Inspector):

Add your demo: record a short GIF/video of audit_parliamentary_speech returning classification, confidence, and requires_human_review, then place it at docs/demo/mcp-audit-demo.gif (see docs/demo/README.md).

Until a recording is available, use the Sample Output JSON and the MCP Inspector walkthrough below.

Key Features

Quickstart via Docker

Requires Docker with Compose v2.

1 — Build and start the MCP server

git clone https://github.com/alissonf216/parliamentary-nlp-mcp.git
cd parliamentary-nlp-mcp
docker compose up --build

The container entrypoint is parliamentary-nlp-mcp (MCP over stdio). It will look idle in the terminal until a client attaches — that is expected. Model weights download on the first tool call and persist in the hf-cache volume.

Optional overrides (create a local .env or export before compose up):

export PARLIAMENTARY_NLP_MODEL_ID=alissonf216/parliamentary-bertimbau-auditor
# export HF_TOKEN=hf_...   # only if the checkpoint is private
docker compose up --build

2 — Point an MCP client at the container

One-shot interactive run (recommended for Claude Desktop / Cursor):

{
  "mcpServers": {
    "parliamentary-nlp": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/absolute/path/to/parliamentary-nlp-mcp/docker-compose.yml",
        "run",
        "--rm",
        "-i",
        "parliamentary-nlp-mcp"
      ]
    }
  }
}

Or a direct image run after docker compose build:

docker compose run --rm -i parliamentary-nlp-mcp

Prefer a local venv instead? Skip to Installation Tutorial.

Installation Tutorial

Follow these steps from a clean machine. Commands assume macOS / Linux; Windows notes are included inline.

Step 0 — Prerequisites

Check your Python version:

python3 --version
# Expected: Python 3.10.x or newer

If python3 points to 3.9 or older, install a newer interpreter (Homebrew, pyenv, Conda, etc.) and use that binary in the steps below.

Step 1 — Clone the repository

git clone https://github.com/alissonf216/parliamentary-nlp-mcp.git
cd parliamentary-nlp-mcp

Or, if you already have the folder locally:

cd /path/to/parliamentary-nlp-mcp

Step 2 — Create and activate a virtual environment

python3 -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
# .venv\Scripts\Activate.ps1

You should see (.venv) in your shell prompt.

Step 3 — Install the package (editable + dev tools)

pip install -U pip setuptools wheel
pip install -e ".[dev]"

What this does:

• installs mcp, torch, transformers, and project code in editable mode

• adds pytest for the test suite

• registers the console command parliamentary-nlp-mcp

Verify the install:

which parliamentary-nlp-mcp
python -c "import parliamentary_nlp; print(parliamentary_nlp.__version__)"

Step 4 — Run the unit tests (recommended)

Tests mock Hugging Face — no GPU and no model download:

pytest -v

Expected: all tests pass (e.g. 5 passed).

Usage Tutorial

There are three ways to use the auditor: Python API, MCP server + Inspector, or IDE / Claude Desktop.

Option A — Call the model from Python

Useful for notebooks, scripts, and debugging the prediction schema.

from parliamentary_nlp import ParliamentaryModel

# First run downloads and caches the default Hugging Face model
model = ParliamentaryModel()

result = model.predict(
    "Esse parlamentar é um corrupto incompetente e não merece ocupar a cadeira."
)
print(result)

Use your own fine-tuned checkpoint:

model = ParliamentaryModel(
    model_id="alissonf216/parliamentary-bertimbau-auditor"
)
print(model.predict("Senhor presidente, peço a palavra."))

Or via environment variable (also works for the MCP server):

export PARLIAMENTARY_NLP_MODEL_ID="alissonf216/parliamentary-bertimbau-auditor"

Option B — Run the MCP server locally

With the venv active:

parliamentary-nlp-mcp

Equivalents:

python -m parliamentary_nlp
python -m parliamentary_nlp.server

The process speaks MCP over stdio (it will look “idle” in the terminal — that is normal). Stop it with Ctrl+C.

Option C — Interactive demo with MCP Inspector

Best way to try the tool without wiring an IDE yet.

1. Keep the venv activated (so parliamentary-nlp-mcp is on PATH).

2. In the same project directory, run:

npx @modelcontextprotocol/inspector parliamentary-nlp-mcp

3. The Inspector opens in the browser.

4. Connect to the server, then select the tool audit_parliamentary_speech.

5. Pass a Portuguese string in the text argument, for example:

O debate deve ser respeitoso e baseado em evidências.

6. Click Run. The first call may take a minute while the model downloads; later calls are faster.

If npx cannot find the command, pass the absolute path to the binary:

npx @modelcontextprotocol/inspector /absolute/path/to/parliamentary-nlp-mcp/.venv/bin/parliamentary-nlp-mcp

Connect to Cursor / Claude Desktop

Cursor

1. Open Cursor Settings → MCP (or edit your MCP config JSON).

2. Add a server entry. Prefer the absolute path to the venv binary so Cursor does not depend on your shell PATH:

{
  "mcpServers": {
    "parliamentary-nlp": {
      "command": "/absolute/path/to/parliamentary-nlp-mcp/.venv/bin/parliamentary-nlp-mcp",
      "env": {
        "PARLIAMENTARY_NLP_MODEL_ID": "alissonf216/parliamentary-bertimbau-auditor"
      }
    }
  }
}

3. Restart Cursor (or reload MCP servers).

4. In chat, ask something like: “Use the parliamentary NLP auditor on this speech: …” — the client should invoke audit_parliamentary_speech.

Claude Desktop

Edit the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "parliamentary-nlp": {
      "command": "/absolute/path/to/parliamentary-nlp-mcp/.venv/bin/parliamentary-nlp-mcp",
      "env": {
        "PARLIAMENTARY_NLP_MODEL_ID": "alissonf216/parliamentary-bertimbau-auditor"
      }
    }
  }
}

Restart Claude Desktop and confirm the hammer / tools icon lists audit_parliamentary_speech.

Sample Output

Input (PT-BR): "Esse parlamentar é um corrupto incompetente e não merece ocupar a cadeira."

Output schema (illustrative):

{
  "text": "Esse parlamentar é um corrupto incompetente e não merece ocupar a cadeira.",
  "classification": "TARGETED_OFFENSE",
  "confidence": 0.812345,
  "entropy_uncertainty": 0.5412,
  "class_probabilities": {
    "NEUTRAL": 0.052101,
    "GENERIC_OFFENSE": 0.098234,
    "TARGETED_OFFENSE": 0.812345,
    "EXPLICIT_HATE_SPEECH": 0.03732
  },
  "requires_human_review": false
}

Note: With alissonf216/parliamentary-bertimbau-auditor, class_probabilities uses the 4-class research taxonomy above.

Project Layout

parliamentary-nlp-mcp/
├── docs/
│   ├── MODELING.md      # Modeling & evaluation (with figures)
│   ├── demo/            # GIF / screen capture of MCP in action
│   ├── figures/         # Heatmaps, CMs, ROC/PR, bars
│   └── results/         # CSV + JSON experiment tables
├── notebooks/
│   ├── README.md
│   ├── finetune_bertimbau_huggingface.ipynb  # train + save for Hugging Face
│   ├── experiments_hierarchy_imbalance.ipynb
│   └── experimentos_pipeline.py
├── src/parliamentary_nlp/
│   ├── __init__.py
│   ├── __main__.py      # python -m parliamentary_nlp
│   ├── model.py         # PyTorch / Hugging Face inference engine
│   └── server.py        # MCP tool surface
├── tests/
│   └── test_model.py
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── .gitignore
└── README.md

For corpus design, label definitions, training protocol, metrics, and quantitative results, read docs/MODELING.md. To reproduce experiments, start from notebooks/README.md.

Inference Pipeline

1. Tokenize with AutoTokenizer (max_length=512, truncation on).

2. Forward pass via AutoModelForSequenceClassification under torch.no_grad().

3. Softmax over logits → class probabilities.

4. Shannon entropy over the probability vector.

5. Emit the structured AuditResult dictionary consumed by the MCP tool.

Troubleshooting

License

MIT — see LICENSE. Model weights remain under their respective Hugging Face licenses (BERTimbau / fine-tuned checkpoint).

Citation / Research Context

This MCP server is the serving layer of a computational auditor for institutional discourse in Brazilian Portuguese: domain-adapted transformers, calibrated uncertainty, and human-review escalation. Modeling details, experimental protocol, and results are documented in docs/MODELING.md.