Documentation

Overview

Context-First MCP is a Model Context Protocol server that acts as a Context Custodian for LLM conversations. It addresses four structural gaps that degrade AI conversation quality over time.

Installation

Option 1: npx (recommended)

npx context-first-mcp

Option 2: Global install

npm install -g context-first-mcp

Option 3: Remote endpoint

https://context-first-mcp.vercel.app/api/mcp

Tool Reference

recap_conversationLost in Conversation

Analyzes conversation history to extract hidden intents, key decisions, and produces a consolidated state summary.

Parameter	Type	Description
sessionId	string	Session identifier (default: 'default')
messages	array	Array of {role, content, turn} message objects
lookbackTurns	number	Number of turns to analyze (default: 5)

detect_conflictsContext Clash

Compares new user input against established conversation ground truth.

Parameter	Type	Description
sessionId	string	Session identifier
newMessage	string	The new user message to check

check_ambiguityCalibration & Trust

Analyzes a requirement for underspecification and returns clarifying questions.

Parameter	Type	Description
requirement	string	The requirement to analyze
context	string?	Additional domain context

verify_executionBenchmark vs Reality

Validates that tool output actually achieved the stated goal.

Parameter	Type	Description
goal	string	What was supposed to happen
output	string	What actually happened
expectedIndicators	string[]?	Strings that indicate success

get_stateState Management

Retrieve conversation ground truth — confirmed facts, decisions, and task status.

Parameter	Type	Description
sessionId	string	Session identifier
keys	string[]?	Specific keys to retrieve

set_stateState Management

Lock in a confirmed fact or decision.

Parameter	Type	Description
sessionId	string	Session identifier
key	string	State key
value	any	Value to store
source	string?	Provenance (e.g., 'user-confirmed')

clear_stateState Management

Remove specific keys or reset all conversation ground truth.

Parameter	Type	Description
sessionId	string	Session identifier
keys	string[]?	Keys to clear (omit for all)

get_history_summaryHistory Compression

Compressed conversation history with annotations and decision tracking.

Parameter	Type	Description
sessionId	string	Session identifier
maxTokens	number	Target summary length (default: 500)

Layer 2 — Advanced Tools

Research-backed tools for entropy monitoring, tool discovery, context quarantine, and verifiable abstention.

discover_toolsActive Discovery (MCP-Zero)

Describe what you need in natural language. Semantic routing returns only relevant tools, reducing context bloat by up to 98%.

Parameter	Type	Description
query	string	Natural language description of the capability needed
maxResults	number	Maximum tools to return (default: 5)
threshold	number	Minimum relevance score 0-1 (default: 0.1)

quarantine_contextContext Quarantine

Isolate a sub-task in a memory silo. Creates a quarantine zone with its own state, preventing technical noise from polluting primary conversation intent.

Parameter	Type	Description
sessionId	string	Session identifier
siloName	string	Name for the quarantine silo
ttlSeconds	number	Time-to-live in seconds (default: 300)
initialKeys	Record<string, unknown>?	Initial state to seed the silo

merge_quarantineContext Quarantine

Merge quarantined context back into the main conversation. Selectively reintegrate findings from isolated sub-tasks.

Parameter	Type	Description
sessionId	string	Session identifier
siloName	string	Name of the silo to merge
keysToMerge	string[]?	Specific keys to merge (omit for all)
discardAfterMerge	boolean	Remove silo after merge (default: true)

entropy_monitorEntropy Detection (ERGO)

Monitor proxy entropy metrics to detect confusion spikes. Returns composite entropy score and sub-metrics. Triggers adaptive context reset when drift exceeds threshold.

Parameter	Type	Description
sessionId	string	Session identifier
content	string	Content to analyze for entropy
threshold	number	Entropy threshold for drift alert (default: 0.7)
autoReset	boolean	Auto-trigger context reset on spike (default: false)

abstention_checkVerifiable Abstention (RLAAR)

Evaluates whether the model has enough verified information to proceed. Scores confidence across 5 dimensions and abstains with clarifying questions rather than hallucinating.

Parameter	Type	Description
sessionId	string	Session identifier
claim	string	The assertion the model wants to make
threshold	number	Minimum confidence to proceed (default: 0.7)
dimensions	string[]?	Specific dimensions to evaluate (omit for all 5)

Research Foundations

Layer 2 features are grounded in peer-reviewed research. Each tool maps to a specific paper's methodology.

MCP-Zero: Tool Discovery via Self-RoutingarXiv:2506.01056

Tool: discover_tools

Semantic embedding-based routing that matches natural language capability descriptions to tool metadata. Eliminates the need to expose all tools in the system prompt.

ERGO: Entropy-Regulated Generative OrchestrationarXiv:2510.14077

Tool: entropy_monitor

Four proxy entropy metrics (lexical diversity, contradiction density, hedge-word frequency, repetition score) combined into a composite score. Detects output drift and triggers adaptive resets.

RLAAR: Reinforcement Learning for Abstention and Active RetrievalarXiv:2510.18731

Tool: abstention_check

Multi-dimensional confidence scoring across state completeness, recency, contradiction-free assessment, ambiguity-free assessment, and source quality. Models learn when to abstain vs. proceed.

ScaleMCP: Scaling Model Context ProtocolarXiv:2505.06416

Tool: quarantine_context / merge_quarantine

Hierarchical state management with quarantine zones. Sub-tasks get isolated memory silos with TTL-based expiry to prevent context pollution.

Architecture

┌─────────────────────────────────────────────────────────────┐
│        @xjtlumedia/context-first-mcp-server                 │
│                                                             │
│  Layer 1 (Core)              Layer 2 (Research-Backed)      │
│  ─────────────               ──────────────────────         │
│  recap_conversation          discover_tools (MCP-Zero)      │
│  detect_conflicts            quarantine_context (ScaleMCP)  │
│  check_ambiguity             merge_quarantine (ScaleMCP)    │
│  verify_execution            entropy_monitor (ERGO)         │
│  get/set/clear_state         abstention_check (RLAAR)       │
│  get_history_summary                                        │
│                                                             │
│           State Engine + Analysis Pipeline                   │
└──────────┬──────────────────────┬───────────────────────────┘
           │                      │
    ┌──────▼──────┐        ┌──────▼──────┐
    │ stdio-server │        │remote-server│
    │   (npx)      │        │  (Vercel)   │
    │ Transport:   │        │ Transport:  │
    │   stdio      │        │ Streamable  │
    │              │        │    HTTP     │
    └──────────────┘        └─────────────┘