Context First Mcp

npx context-first-mcp

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:

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

[Deploy with Vercel]

Tool Reference

Layer 1: Core Context Health (9 tools)

Layer 1b: State Management (4 tools)

Layer 2: Sandbox & Discovery (3 tools)

Layer 3: Persistent Memory (6 tools)

Layer 4: Advanced Reasoning (5 tools)

Layer 5: Truthfulness & Verification (7 tools)

Research Pipeline & Export (2 tools)

Built on Peer-Reviewed Research

Every core algorithm traces back to a published paper:

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)

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:

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 task2. Call context_loop every 2–3 tool calls3. Call context_loop AFTER generating long-form output4. 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 writingPhase 2 · Gather   ONE web search → research_pipeline(gather) → file written to disk → repeatPhase 3 · Analyze  research_pipeline(analyze) → reasoning engines produce clean analysis filePhase 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.gitcd Context-First-MCPpnpm install
# Build everythingpnpm build
# Run stdio servercd packages/stdio-server && pnpm start
# Run frontendcd packages/frontend && pnpm dev
# Testspnpm test

Contributing

See CONTRIBUTING.md.

License

MIT