TruthGate MCP server
2026년 11월 14일 커밋Verifies AI agent responses for hallucinations, citation accuracy, numeric drift, and workspace symbol grounding using deterministic rules.
다른 이름 codesphere-u/truthgate
- 스타
- 1
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- MIT
TruthGate MCP란?
Verifies AI agent responses for hallucinations, citation accuracy, numeric drift, and workspace symbol grounding using deterministic rules.
프로젝트 README에서 생성된 요약
TruthGate MCP server 정보
Verifying AI agent responses for hallucinations and citation accuracy is what TruthGate enables for developers building RAG or coding assistants. This MCP server provides a deterministic verification layer that catches errors like phantom citations, numeric drift, and polarity flips without the high latency or cost of using a second LLM. It operates locally via a JSON-RPC 2.0 stdio connection, making it compatible with clients like Claude Desktop, Cursor, or Antigravity.
Users can audit markdown responses against source documents or a local workspace directory to ensure technical accuracy. The server uses eight specific rules, ranging from TG001 for phantom citations to TG008 for checking if code symbols exist in a Python AST or other symbol tables. When a check fails, the system generates a surgical self-correction prompt to help the agent fix the specific error. It is designed for high-performance environments, offering sub-millisecond verification latency.
활용 사례
- 1Audit agent citationsCheck if an AI agent is attributing claims to non-existent or incorrect source documents.
- 2Detect polarity flipsIdentify when an agent incorrectly summarizes a statement by reversing a negation or antonym.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
자동 검사
2026년 11월 16일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능codesphere-u/truthgate is public and reachablegithub.com/codesphere-u/truthgate ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/codesphere-u/truthgate ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기TruthGate (codesphere-u/truthgate)
Deterministic Agent Hallucination Auditor, Citation-Span Entailment Verifier & Workspace Symbol Grounding Engine (with MCP Server)
Why TruthGate?
Even when AI agents use RAG (cortex-mcp, auralis-local) or codebase search tools, they frequently produce subtle, high-severity hallucinations:
- Phantom Citations & Unsupported Claims (
TG001,TG002): The agent appends[doc_99]to a claim or attributes a fabricated statement to[sec_policy]. - Negation & Antonym Polarity Flip (
TG003): The source says "TLS 1.0 is not permitted in production", and the agent summarizes "TLS 1.0 is permitted in production [sec_policy]". - Numeric, Percentage & Currency Drift (
TG004): The tool output reportslatency = 42.8 msorUGX 1,250,000, and the agent writes4.28 msorUGX 125,000. - Hallucinated Code Symbols, File Paths & Line Ranges (
TG006–TG008): Coding agents reference[src/auth/jwt.py#L120-L150]whenjwt.pyonly has 24 lines, or callverify_token_v2()when the function does not exist in the workspace AST. - Expensive LLM-as-a-Judge: Calling a second frontier LLM to audit every response adds 3 seconds of latency and doubles API spend. TruthGate provides a sub-millisecond (
0.12 msP50), zero-dependency deterministic verification gate that catches citation mismatches, polarity inversions, numeric drift, and phantom workspace references—and compiles a surgical self-correction prompt when a check fails.
Architecture
flowchart LR
Resp["Agent Markdown Response"] --> Decomp["ClaimDecomposer\n(Atomic Claims, Citations,\nNumbers, Negations, CodeRefs)"]
Decomp --> Entail["CitationEntailmentVerifier\n(Rules TG001–TG005)"]
Decomp --> Ground["WorkspaceSymbolGrounder\n(Rules TG006–TG008)"]
Docs[("SourceDocument Corpus")] --> Entail
AST[("Workspace Files & AST")] --> Ground
Entail --> Gate{"Verification\nPassed?"}
Ground --> Gate
Gate -- "True" --> Pass["Deliver Grounded Response"]
Gate -- "False" --> Repair["SurgicalRepairCompiler\n(Self-Correction Prompt)"]
Deterministic Verification Rules (TG001–TG008)
| Rule Code | Name | Category | Verdict Status | Severity | Deterministic Check |
|---|---|---|---|---|---|
TG001 |
Phantom Source Citation | Entailment | PHANTOM_CITATION |
CRITICAL |
Claim cites a [source_id] that does not exist in the provided context corpus. |
TG002 |
Low Lexical/Entity Support | Entailment | UNVERIFIED |
HIGH |
IDF-weighted stem and technical-entity overlap between claim and cited source falls below threshold. |
TG003 |
Negation Polarity Inversion | Entailment | CONTRADICTED |
CRITICAL |
High entity overlap with a source sentence, but opposite negation or antonym polarity (enabled/disabled, permitted/prohibited, encrypted/unencrypted, immutable/mutable, synchronous/asynchronous). |
TG004 |
Numeric & Magnitude Drift | Entailment | NUMERIC_DRIFT |
CRITICAL |
Claim introduces a number, percentage, or currency (UGX, USD, EUR, ms, %) that does not match any value in the cited source. |
TG005 |
Uncited Factual Assertion | Entailment | UNVERIFIED |
MEDIUM |
Factual or numeric proposition in strict-grounding mode lacks any supporting [source_id] citation or workspace evidence. |
TG006 |
Non-Existent File Path | Workspace Grounding | BROKEN_CODE_REF |
CRITICAL |
Referenced file path (src/missing.py) does not exist in workspace_root (or attempts path traversal). |
TG007 |
Out-of-Bounds Line Range | Workspace Grounding | BROKEN_CODE_REF |
HIGH |
Referenced line range (file.py#L120-L150) exceeds the actual line count of file.py. |
TG008 |
Phantom Code Symbol | Workspace Grounding | BROKEN_CODE_REF |
CRITICAL |
Referenced function, class, or method (verify_token_v2()) does not exist in the target file's Python AST or TS/JS/Go/Rust symbol table. |
Verified Benchmark Results (40-Scenario Suite)
Reproduce locally via truthgate benchmark:
| Metric | Verified Value | Notes |
|---|---|---|
| Total Scenarios | 40 | 10 Grounded Truthful + 30 Adversarial Hallucinations (TG001–TG008) |
| Precision | 100.0% | 30 / 30 flagged responses are true hallucinations |
| Recall | 100.0% | 30 / 30 adversarial hallucinations caught across all 8 rules |
| False Positive Rate (FPR) | 0.0% | 0 / 10 truthful RAG & coding responses falsely flagged |
| Exact Rule Code Accuracy | 100.0% | 40 / 40 scenarios match exact expected TG001–TG008 rule code |
| P50 Verification Latency | 0.12 ms | Sub-millisecond deterministic execution |
| P95 Verification Latency | 0.37 ms | < 0.5 ms tail latency (10,000x faster than LLM-as-a-Judge) |
Quickstart
Installation
git clone https://github.com/codesphere-u/truthgate.git
cd truthgate
python3 -m pip install -e ".[dev]"
Run the End-to-End Audit & Self-Correction Demo
truthgate demo
Output excerpt:
[Audit Summary] Passed: False | Score: 0.25 | Claims: 1/4 supported | Latency: 1.207 ms
[Claim-by-Claim Verdicts]
- [FAIL:TG003] (CONTRADICTED) TLS 1.0 is permitted in production environments [sec_policy].
- [FAIL:TG004] (NUMERIC_DRIFT) The P95 gateway routing latency is 4.28 ms across East Africa edge nodes [sla_metrics].
- [PASS] (SUPPORTED) Daily instant settlement volume is capped at UGX 1,250,000 for Tier-1 merchant accounts [fin_ledger].
- [FAIL:TG008] (BROKEN_CODE_REF) In `src/auth/jwt.py`, call `verify_token_v2()` to validate bearer tokens.
[Compiled Surgical Self-Correction Prompt]
------------------------------------------------------------------------------------
[TRUTHGATE VERIFICATION FAILED — 3 violation(s) detected: TG003, TG004, TG008]
Rewrite your response to fix ONLY the following deterministic verification failures:
1. [TG003 (Negation Polarity Inversion)] Offending statement: "TLS 1.0 is permitted in production environments [sec_policy]."
- Ground-Truth Evidence: "TLS 1.0 is not permitted in production environments."
...
Python SDK Usage
from truthgate import SourceDocument, TruthGateVerifier
sources = [
SourceDocument(
source_id="sec_policy",
title="Production TLS Policy",
content="TLS 1.0 is not permitted in production environments.",
),
SourceDocument(
source_id="sla_metrics",
title="Gateway Telemetry",
content="The P95 gateway routing latency is 42.8 ms across East Africa edge nodes.",
),
]
verifier = TruthGateVerifier()
result = verifier.verify(
response_text=(
"TLS 1.0 is permitted in production environments [sec_policy]. "
"The P95 gateway routing latency is 4.28 ms across East Africa edge nodes [sla_metrics]."
),
sources=sources,
)
print("Passed:", result.passed)
print("Violations:", result.violation_counts) # {'TG003': 1, 'TG004': 1}
print(result.repair_prompt)
CLI Reference
# 1. Run end-to-end hallucination audit & repair prompt demo
truthgate demo
# 2. Run the 40-scenario benchmark suite (human-readable or JSON)
truthgate benchmark
truthgate benchmark --json
# 3. List all 8 deterministic verification rules (TG001-TG008)
truthgate rules
# 4. Verify an agent response against a JSON sources file and workspace directory
truthgate verify \
--response "TLS 1.0 is not permitted in production environments [sec_policy]." \
--sources-json sources.json \
--workspace . \
--fail-on-violation
# 5. Ground workspace file paths, #Lstart-Lend line ranges, and AST symbols
truthgate ground \
--response "See [models.py](truthgate/models.py#L1-L40) and \`TruthGateVerifier\`." \
--workspace .
# 6. Start the JSON-RPC 2.0 Stdio MCP server
truthgate mcp
# 7. Start the zero-dependency HTTP/SSE MCP server & Dark-Mode Developer Workbench UI
truthgate serve-http --host 127.0.0.1 --port 8000
HTTP Server, Developer Workbench & Streamable MCP
TruthGate includes a zero-dependency HTTP server (truthgate serve-http) and an optional FastAPI ASGI / Vercel entrypoint (api/index.py via pip install -e ".[server]"):
GET /: Interactive dark-mode TruthGate Developer Workbench HTML UI (citation/hallucination auditor, surgical repair prompt viewer, rule matrix, and 40-scenario benchmark runner) whenAccept: text/html; JSON service metadata otherwise.GET&HEADHealth/Telemetry:/health,/healthz,/readyz,/info, and/metrics(Prometheus exposition text or JSON viaAccept: application/json/?format=json).- Streamable HTTP / SSE MCP:
POST /mcp,GET /mcp(SSE onAccept: text/event-stream,405 Allow: POST, OPTIONSotherwise), andPOST /messages. - Domain REST API:
GET /api/rules,POST /api/verify,POST /api/ground,POST /api/decompose,GET|POST /api/demo, andGET|POST /api/benchmark. - Production Hardening:
X-Request-IDecho & sanitization, security headers (X-Content-Type-Options: nosniff,X-Frame-Options: SAMEORIGIN,Referrer-Policy,Cache-Control: no-storeon/api/*),OPTIONSCORS preflight,413body size guard,-32700malformed JSON handling, and zero traceback leaks.
Docker & Smoke Verification
# Build and run the hardened non-root container
docker build -t truthgate:latest .
docker run --rm -p 8000:8000 truthgate:latest
# Run end-to-end HTTP, MCP, security-header, and REST smoke verification
python scripts/smoke_test.py
# Quality & typing checks (PEP 561 py.typed included)
ruff check .
mypy truthgate api scripts
pytest -v --cov=truthgate --cov-fail-under=90
MCP Server Integration
Add truthgate to your Claude Desktop, Cursor, or Antigravity mcp_config.json:
{
"mcpServers": {
"truthgate": {
"command": "truthgate",
"args": ["mcp"]
}
}
}
Exposed MCP Capabilities
- Tools (
tools/list,tools/call):truthgate_verify_response: Verifies an agent response against source documents and an optional workspace directory, returning claim-by-claim verdicts and a surgical repair prompt.truthgate_ground_workspace_refs: Verifies all file paths,#Lstart-Lendline ranges, and AST symbols referenced in markdown text against a workspace directory.truthgate_list_rules: Lists all 8 deterministic verification rules (TG001–TG008).truthgate_run_benchmark: Runs the reproducible 40-scenario benchmark suite.
- Resources (
resources/list,resources/read):truthgate://rules,truthgate://benchmark/scenarios,truthgate://docs/architecture. - Prompts (
prompts/list,prompts/get):audit-response,ground-workspace,surgical-repair.
Part of the Codesphere Agentic Infrastructure Stack
Built by Akandwanaho Ivan Alvin (@codesphere-u), Founder & MD of Codesphere Innovations (U) Limited in Kampala, Uganda:
codesphere-u/cortex-mcp— Hybrid BM25 + Vector Persistent Memory & Context Compression MCP Servercodesphere-u/agentshield— Zero-Trust Runtime Security Firewall & Prompt-Injection Guardrail for AI Agentscodesphere-u/agentflight— Deterministic Black-Box Flight Recorder & Replay Debugger for AI Agentscodesphere-u/synapse-router— Latency/Cost-Aware Multi-Model Semantic Router & Circuit Breakercodesphere-u/patchpilot— Autonomous Code Repair Engine & Anti-Reward-Hacking Patch Verifiercodesphere-u/truthgate— Deterministic Agent Hallucination Auditor, Citation-Span Entailment Verifier & Workspace Symbol Grounding Engine
HTTP/SSE Server, Portal & Docker Deployment
TruthGate also ships with an interactive Developer Workbench & Portal, Streamable HTTP + SSE MCP gateway (/mcp), REST API, Prometheus/JSON telemetry, and Vercel ASGI entrypoint (api/index.py):
# Start the interactive portal + HTTP/SSE MCP server on http://127.0.0.1:8000
truthgate serve-http --host 127.0.0.1 --port 8000
# Run the live HTTP + MCP smoke test
python scripts/smoke_test.py
# Build and run the non-root production container
docker build -t truthgate .
docker run --rm -p 8000:8000 truthgate
Exposed HTTP endpoints:
GET /— Interactive TruthGate Workbench UIGET/HEAD /health,/healthz,/readyz— Readiness and liveness probesGET /metrics— Prometheus text or JSON telemetry (?format=json)POST /mcp(Streamable HTTP) &GET /mcp(SSE or HTTP405JSON-RPC) — MCP tools, resources, and promptsGET /api/rules,GET /api/demo,GET /api/benchmark&POST /api/verify,POST /api/ground,POST /api/decompose— REST verification endpoints
License
MIT License — see LICENSE.
TruthGate MCP 질문
What kind of hallucinations does TruthGate catch?
It detects phantom citations, negation polarity flips, numeric and currency drift, and incorrect code symbols or file paths.
Can TruthGate help fix errors in AI responses?
Yes, it compiles a surgical self-correction prompt that tells the agent exactly how to rewrite its response to fix specific violations.
How does it compare to using an LLM to audit responses?
TruthGate is significantly faster and cheaper, offering sub-millisecond execution compared to the latency and cost of a second frontier LLM.