Context-First-MCP

<div align="center">

Context-First MCP

The MCP server that keeps your AI grounded, coherent, and honest — across every turn.

       

npx context-first-mcp

Works instantly with Claude Desktop · Cursor · VS Code · any MCP client · Vercel remote — zero API keys needed.

</div>

---

37 research-backed tools across 7 layers — context health, state, sandboxing, persistent memory, advanced reasoning, truthfulness verification, orchestration, structured research, and autonomous file export. One context_loop call replaces 6–7 individual tools and returns a unified action directive.

---

Why Your AI Conversations Break Down

Long AI conversations fail in predictable ways. Context-First fixes all four:

| Failure Mode | What Goes Wrong | Context-First Solution | |---|---|---| | Context Drift | AI forgets earlier decisions and intent as the conversation grows | context_loop + detect_drift continuously re-anchor every turn | | Silent Contradiction | New inputs silently overrule established facts — the AI doesn't notice | detect_conflicts compares every input against locked ground truth | | Vague Execution | AI proceeds on underspecified requirements, producing misaligned output | check_ambiguity + abstention_check ask clarifying questions instead of guessing | | Hallucinated Success | Tool outputs look successful but didn't actually achieve the goal | verify_execution rechecks whether the outcome matches the stated intent |

---

What You Get

37 production-ready tools grouped into 7 layers — plus 1 orchestrator that runs them all:

context_loop  ─────────────────────────────────────────────────────────────────
  ├─ Layer 1 · Context Health   (9 tools)   recap, conflict, ambiguity, depth …
  ├─ Layer 2 · Sandbox          (3 tools)   discover_tools, quarantine, merge
  ├─ Layer 3 · Persistent Memory(6 tools)   store, recall, compact, graph …
  ├─ Layer 4 · Advanced Reasoning(5 tools)  InftyThink, Coconut, KAG, MindEvo …
  ├─ Layer 5 · Truthfulness     (7 tools)   NCB, IOE, verify_first, self_critique…
  └─ State + Research Pipeline + Export     (7 tools)

One call. One directive. One score.

{
  "directive": {
    "action": "clarify",
    "contextHealth": 0.62,
    "instruction": "Resolve with the user: (1) Is this a firm requirement? (2) Which framework?",
    "autoExtractedFacts": { "deploy_to": "Vercel" },
    "suggestedNextTools": ["verify_execution", "quarantine_context"]
  }
}

---

Quick Start

npx — zero install

npx context-first-mcp

Claude Desktop

{
  "mcpServers": {
    "context-first": {
      "command": "npx",
      "args": ["-y", "context-first-mcp"]
    }
  }
}

Cursor / VS Code

{
  "mcp": {
    "servers": {
      "context-first": {
        "command": "npx",
        "args": ["-y", "context-first-mcp"]
      }
    }
  }
}

Remote (Streamable HTTP)

{
  "mcpServers": {
    "context-first": {
      "url": "https://context-first-mcp.vercel.app/api/mcp"
    }
  }
}

Deploy your own Vercel instance


---

Tool Reference

Layer 1: Core Context Health (9 tools)

| Tool | Purpose | |------|---------| | context_loop | One-call orchestrator. Runs 8 stages (ingest→recap→conflict→ambiguity→entropy→abstention→discovery→synthesis) and returns a single directive with action, contextHealth score, extracted facts, and suggested next tools | | recap_conversation | Extracts hidden intent, key decisions, and produces consolidated state summaries | | detect_conflicts | Compares new input against ground truth; surfaces contradictions | | check_ambiguity | Identifies underspecified requirements and generates clarifying questions | | verify_execution | Validates whether tool outputs actually achieved the stated goal | | entropy_monitor | Proxy-entropy scoring via lexical diversity, contradiction density, hedge frequency, and n-gram repetition (ERGO) | | abstention_check | 5-dimension confidence scoring — abstains with questions rather than hallucinating (RLAAR) | | detect_drift | Detects conversation drift from the original intent | | check_depth | Evaluates response depth against question complexity |

Layer 1b: State Management (4 tools)

| Tool | Purpose | |------|---------| | get_state | Retrieve confirmed facts and task status | | set_state | Lock in ground truth — subsequent conflict checks run against these values | | clear_state | Reset specific keys or all state | | get_history_summary | Compressed conversation history with intent annotations |

Layer 2: Sandbox & Discovery (3 tools)

| Tool | Method | Purpose | |------|--------|---------| | discover_tools | MCP-Zero + ScaleMCP | Natural-language tool routing — returns only semantically relevant tools, reducing context bloat by up to 98% | | quarantine_context | Multi-Agent Quarantine | Create isolated memory silos for sub-tasks, preventing intent dilution | | merge_quarantine | Multi-Agent Quarantine | Merge silo results with noise filtering — only promoted keys return to main context |

Layer 3: Persistent Memory (6 tools)

| Tool | Purpose | |------|---------| | memory_store | Store findings, decisions, and intermediate results with metadata | | memory_recall | Retrieve relevant memories by semantic query | | memory_compact | Compress and consolidate memory entries | | memory_graph | Build and query a knowledge graph from stored memories | | memory_inspect | Inspect memory store contents and statistics | | memory_curate | Deduplicate and organize memory entries |

Layer 4: Advanced Reasoning (5 tools)

| Tool | Method | Purpose | |------|--------|---------| | inftythink_reason | InftyThink | Infinite-depth reasoning with adaptive stopping | | coconut_reason | Coconut | Chain-of-Continuous-Thought in latent space | | extracot_compress | ExtraCoT | Compress chain-of-thought while preserving reasoning fidelity | | mindevolution_solve | MindEvolution | Evolutionary search over the solution space | | kagthinker_solve | KAG-Thinker | Knowledge-augmented generation with structured thinking |

Layer 5: Truthfulness & Verification (7 tools)

| Tool | Purpose | |------|---------| | probe_internal_state | Probe model consistency across paraphrased prompts | | detect_truth_direction | Detect whether model reasoning is trending toward or away from truth | | ncb_check | Neighborhood consistency check across semantically equivalent inputs | | check_logical_consistency | Verify logical coherence of reasoning chains | | verify_first | Pre-verification before committing to claims | | ioe_self_correct | Intrinsic-extrinsic self-correction | | self_critique | Structured self-critique with improvement suggestions |

Research Pipeline & Export (2 tools)

| Tool | Purpose | |------|---------| | research_pipeline | Structured research orchestration across init → gather → analyze → verify → finalize. Covers all 34 underlying tool-equivalents — state, sandboxing, memory, reasoning, truthfulness, context health. Writes files autonomously to disk as the pipeline runs; no LLM cooperation needed for file output. | | export_research_files | Writes every verified report chunk and/or every raw evidence batch to disk in a single call. |

---

Built on Peer-Reviewed Research

Every core algorithm traces back to a published paper:

| Algorithm | Paper | arXiv | Tool | |-----------|-------|-------|------| | MCP-Zero | Active Tool Request | 2506.01056 | discover_tools | | ScaleMCP | Semantic Tool Grouping | 2505.06416 | discover_tools registry | | ERGO | Entropy-based Quality | 2510.14077 | entropy_monitor | | RLAAR | Calibrated Abstention | 2510.18731 | abstention_check |

Implementation highlights:

• Proxy Entropy (ERGO): 4 response-level proxy signals (lexical diversity, contradiction density, hedge-word frequency, n-gram repetition) replace inaccessible token-level logprobs. Composite score above threshold triggers adaptive context reset.
• TF-IDF Discovery (MCP-Zero): Pure TypeScript, zero external dependencies. Indexes all tool descriptions at startup; cosine similarity routes queries to the top-k relevant tools only.
• Inference-Time Abstention (RLAAR): 5-dimension confidence scoring replaces the RL training loop. Abstains with targeted questions when confidence < threshold — no hallucination fallback.

Export Helper (1 tool)

| Tool | Description | |------|-------------| | export_research_files | Writes research artifacts directly to disk. It can automatically expand and write every verified report chunk without asking the LLM to loop finalize manually, and it can also write every gathered raw-evidence batch even when verify has not passed. |

context_loop Pipeline

context_loop (single MCP tool call)
├── Stage 1: INGEST     — Store messages to session history
├── Stage 2: RECAP      — Extract intents, decisions, summaries
├── Stage 3: CONFLICT   — Detect contradictions against ground truth
├── Stage 4: AMBIGUITY  — Check for underspecified requirements
├── Stage 5: ENTROPY    — Monitor output quality degradation (ERGO)
├── Stage 6: ABSTENTION — Multi-dimensional confidence check (RLAAR)
├── Stage 7: DISCOVERY  — Suggest relevant next tools (MCP-Zero)
└── Stage 8: SYNTHESIS   — Combine signals → action recommendation + LLM directive

Synthesis Priority: abstain > reset > clarify > proceed

Each stage runs with independent error isolation — a failure in one stage doesn't block the others. The result includes per-stage timing, status, and detailed results for observability.

LLM Directive (NEW)

The context_loop response includes a top-level directive object designed for LLM consumption — a compact, actionable instruction that replaces the need to parse nested stage results:

{
  "directive": {
    "action": "clarify",
    "instruction": "Before proceeding, resolve these issues with the user:\n1. Could you specify exactly what you mean?\n2. Is this a firm requirement or still open for discussion?",
    "questions": ["Could you specify exactly what you mean?", "Is this a firm requirement?"],
    "contextHealth": 0.62,
    "autoExtractedFacts": { "framework": "React", "deploy_to": "Vercel" },
    "suggestedNextTools": ["verify_execution", "quarantine_context"]
  }
}

---

How context_loop Works

context_loop (single MCP tool call)
├── Stage 1: INGEST     — Store messages to session history
├── Stage 2: RECAP      — Extract intents, decisions, summaries
├── Stage 3: CONFLICT   — Detect contradictions against ground truth
├── Stage 4: AMBIGUITY  — Check for underspecified requirements
├── Stage 5: ENTROPY    — Monitor output quality degradation (ERGO)
├── Stage 6: ABSTENTION — Multi-dimensional confidence check (RLAAR)
├── Stage 7: DISCOVERY  — Suggest relevant next tools (MCP-Zero)
└── Stage 8: SYNTHESIS  — Combine signals → action + directive

Synthesis priority: abstain > reset > clarify > proceed

Each stage runs with independent error isolation. The directive response field carries everything an LLM needs:

| Field | Description | |-------|-------------| | action | proceed · clarify · reset · abstain | | instruction | Plain-language guidance for the LLM's next step | | questions | Aggregated clarifying questions (ambiguity + abstention + conflicts) | | contextHealth | 0–1 composite score. 1 = healthy, 0 = degraded | | autoExtractedFacts | Key-value facts auto-extracted from user messages and stored as ground truth | | suggestedNextTools | Relevant tools the LLM should consider next |

Smart defaults: currentInput is auto-inferred from the last user message. Facts like "use React" are extracted and stored automatically.

---

Usage Protocol: Getting the Most from Context-First

The #1 mistake: LLMs treat context_loop as optional. It's not — it's the backbone.

Built-in Enforcement (v1.2.1+)

The server ships with four compliance mechanisms that require zero configuration:

1. Server Instructions — Full usage protocol injected at MCP handshake via ServerOptions.instructions
2. Bootstrap Gate — First non-context_loop call appends a strong redirect reminder
3. Cross-Tool Reminders — After 3 consecutive calls without context_loop, reminders appear in tool responses
4. MCP Prompts — context-first-protocol and research-protocol prompt templates available on demand

Reinforce in Your System Prompt (Optional)

When using Context-First MCP:
1. Call context_loop BEFORE any complex task
2. Call context_loop every 2–3 tool calls
3. Call context_loop AFTER generating long-form output
4. ALWAYS follow directive.action (proceed/clarify/reset/abstain/deepen/verify)
5. Use memory_store to save findings; memory_recall to retrieve them

Research Task Workflow

research_pipeline orchestrates memory, phase control, reasoning, and autonomous file writing. It is not a web crawler — bring your own sources from web search, GitHub, fetch tools, PDFs, or any other MCP.

Phase 1 · Init     research_pipeline(init) → sets up state, enables autonomous file writing
Phase 2 · Gather   ONE web search → research_pipeline(gather) → file written to disk → repeat
Phase 3 · Analyze  research_pipeline(analyze) → reasoning engines produce clean analysis file
Phase 4 · Verify   research_pipeline(verify) → context health gate (non-blocking)
Phase 5 · Finalize research_pipeline(finalize) → synthesis.md + all batch files on disk

Automation shortcut:
  export_research_files(outputDir, exportVerifiedReport=true)  → write all report chunks
  export_research_files(outputDir, exportRawEvidence=true)     → write all evidence batches

Autonomous file writing is always on. Files are written to ./context-first-research-output/ by default — no LLM cooperation required. Pass outputDir to override.

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│               @xjtlumedia/context-first-mcp-server            │
│                     (Core — shared logic)                     │
│                                                               │
│  Layer 1: Context Health    (9 tools)                         │
│  Layer 2: Sandbox           (3 tools)                         │
│  Layer 3: Persistent Memory (6 tools)                         │
│  Layer 4: Advanced Reasoning(5 tools)                         │
│  Layer 5: Truthfulness      (7 tools)                         │
│  State (4) · Orchestrator · Pipeline · Export                 │
└──────────────┬───────────────────────┬──────────────────────┘
               │                       │
        ┌──────▼──────┐         ┌──────▼────────┐
        │ stdio-server │         │ remote-server │
        │ (npx local)  │         │   (Vercel)    │
        │   stdio      │         │ Streamable    │
        │  37 tools    │         │    HTTP       │
        └──────────────┘         │   37 tools    │
                                 └───────────────┘

• Core library (@xjtlumedia/context-first-mcp-server): All tool implementations. Zero external API keys — heuristic-based by default.
• stdio-server (context-first-mcp): npx entry point, stdio transport, 37 tools.
• remote-server: Vercel serverless, Streamable HTTP transport, 37 tools.

---

Frontend Demo

Try all 37 tools live in your browser at context-first-mcp.vercel.app.

---

Development

git clone https://github.com/XJTLUmedia/Context-First-MCP.git
cd Context-First-MCP
pnpm install

# Build everything
pnpm build

# Run stdio server
cd packages/stdio-server && pnpm start

# Run frontend
cd packages/frontend && pnpm dev

# Tests
pnpm test

Contributing

See CONTRIBUTING.md.

License

MIT

---

<div align="center">

Context-First MCP · @xjtlumedia/context-first-mcp-server · context-first-mcp

Built for every developer tired of watching their AI lose the plot.

</div>