Grounded Support Agent

What grounded-support-agent does

The grounded-support-agent MCP server provides a governed support workflow for questions that should be answered from a fixed knowledge base. It separates evidence gathering from the final decision: the knowledge base and resolver determine whether a question can be resolved, while generated wording is used only after that decision allows an answer.

The server has three possible outcomes. A covered question is resolved with an answer, source citation, and confidence information. A partially relevant question that does not meet the configured bar is escalated with related passages. A question outside the knowledge base is also escalated, without allowing the system to invent an answer. Mixed questions containing an in-scope and out-of-scope request are treated as unsafe to resolve.

How it works

The grounded-support-agent MCP server uses standard-library BM25 retrieval together with term-coverage checks. Explicit thresholds in the resolver decide whether the retrieved material supports resolution. The MCP layer is a thin client of that decision engine; it does not independently calculate a verdict.

Responses include provenance linking the result to the knowledge-base material used. With the same question and unchanged KB, the MCP response is deterministic and does not include wall-clock data. This makes the result reproducible for testing and review.

The retrieval design favors safe escalation over unsupported resolution. It can miss heavily paraphrased or synonym-heavy questions and escalate them even when the KB contains a relevant answer. The repository documents a retrieval seam where a semantic retriever could later provide evidence to the same deterministic threshold gate, but no semantic retriever is included.

Setup and configuration

The repository requires Python 3.9 or newer and uses the standard library for its core. Running the local command needs no package installation, API key, backend, or network access:

python3 ask.py "how do I reset my password?"
python3 ask.py --json "can I get a refund after 30 days?"

From a checkout, inspect the MCP contract with:

python3 mcp_server/server.py --contract

To run the MCP server over stdio using the SDK, install the mcp package and start it with python3 -m mcp_server.server. A PyPI distribution is prepared for uvx grounded-support-agent, but the README states that this form is available only after publication. The packaged knowledge base is bundled in the wheel, so the standalone package does not require a repository checkout.

Tools and capabilities

The grounded-support-agent MCP server exposes these read-only, idempotent MCP tools:

• list_topics lists the documents and headings available for grounding.
• get_evidence returns ranked passages and their text without deciding whether to resolve or escalate.
• resolve_or_escalate returns the final verdict, answer or handoff information, citations, confidence data, and provenance.

Knowledge-base documents are also available through read-only resources using the kb://document/{doc} pattern. The support_triage prompt describes an understand-then-resolve flow for hosts. Each tool advertises explicit read-only, non-destructive, idempotent, and closed-world hints.

The repository includes an evaluation command that measures answerable-question resolution, paraphrase recall, correct handoffs, and hallucinations. Its required safety property is zero confident wrong answers for the supplied evaluation set.

Limitations and notes

Coverage depends on the knowledge base shipped with the project and on lexical retrieval. Questions phrased far from the stored wording may be escalated rather than resolved. The project does not ship the proposed semantic-retrieval upgrade.

The MCP server is intended to act as a component inside an orchestrated agent system. It does not connect to a ticketing platform or external support backend in the supplied material. The available examples and core operation are local, with no API key required.