context-first-mcp

npx context-first-mcp

37 个基于研究成果的工具，涵盖 7 个层面——上下文健康、状态、沙盒、持久记忆、高级推理、真实性验证、编排、结构化研究和自主文件导出。一次 context_loop 调用即可取代 6–7 个独立工具，并返回统一的操作指令。

为什么 AI 对话会出问题

较长的 AI 对话会以可预见的方式失败。Context-First 可解决以下全部四类问题：

你将获得什么

37 个可用于生产环境的工具，分为 7 个层面——另有 1 个编排器可运行所有工具：

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)

一次调用。一个指令。一个分数。

{
  "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"]
  }
}

快速开始

npx——无需安装

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"]
      }
    }
  }
}

远程（Streamable HTTP）

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

部署你自己的 Vercel 实例

工具参考

第 1 层：核心上下文健康（9 个工具）

第 1b 层：状态管理（4 个工具）

第 2 层：沙箱与发现（3 个工具）

第 3 层：持久化记忆（6 个工具）

第 4 层：高级推理（5 个工具）

第 5 层：真实性与验证（7 个工具）

研究流程与导出（2 个工具）

基于同行评审研究构建

每种核心算法均源自已发表的论文：

实现亮点：

• 代理熵（ERGO）： 使用 4 种响应级代理信号（词汇多样性、矛盾密度、模糊措辞频率、n 元语法重复）替代无法访问的词元级 logprobs。综合分数超过阈值时，会触发自适应上下文重置。
• TF-IDF 发现（MCP-Zero）： 纯 TypeScript 实现，无外部依赖。启动时为所有工具描述建立索引；通过余弦相似度，将查询路由到仅包含最相关工具的 top-k 集合。
• 推理时弃答（RLAAR）： 使用 5 维置信度评分替代强化学习训练循环。置信度低于阈值时，会通过有针对性的问题弃答，不使用幻觉回退方案。

导出助手（1 个工具）

context_loop 流水线

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

综合优先级： abstain > reset > clarify > proceed

每个阶段都会独立运行并隔离错误——某个阶段发生故障不会阻塞其他阶段。结果包含各阶段的耗时、状态和详细结果，便于观察。

LLM 指令（新增）

context_loop 响应包含一个顶层 directive 对象，专为 LLM 消费而设计——它是一条简洁、可执行的指令，无需解析嵌套的阶段结果：

{
  "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"]
  }
}

context_loop 的工作原理

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

综合优先级： abstain > reset > clarify > proceed

每个阶段都会独立运行并隔离错误。directive 响应字段包含 LLM 所需的一切信息：

智能默认值： currentInput 会根据最后一条用户消息自动推断。像“使用 React”这样的事实会自动提取并存储。

使用协议：充分利用 Context-First

最常见的错误： LLM 将 context_loop 视为可选项。事实并非如此——它是整个流程的支柱。

内置强制机制（v1.2.1+）

服务内置了四种合规机制，无需任何配置：

1. 服务说明 — 通过 ServerOptions.instructions 在 MCP 握手时注入完整使用协议
2. 启动门控 — 首次调用非 context_loop 工具时，会追加一条强制重定向提醒
3. 跨工具提醒 — 连续 3 次调用未使用 context_loop 后，工具响应中会出现提醒
4. MCP 提示词 — 可按需使用 context-first-protocol 和 research-protocol 提示词模板

在系统提示词中强化（可选）

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_pipeline 可协调记忆、阶段控制、推理和自主文件写入。它不是网页爬虫——请自行从网页搜索、GitHub、抓取工具、PDF 或其他 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

始终启用自主文件写入。 文件默认写入 ./context-first-research-output/——无需 LLM 协作。传入 outputDir 可覆盖默认值。

架构

┌──────────────────────────────────────────────────────────────┐
│               @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    │
                                 └───────────────┘

• 核心库（@xjtlumedia/context-first-mcp-server）：所有工具实现。无需外部 API 密钥——默认基于启发式方法。
• stdio-server（context-first-mcp）：npx 入口点、stdio 传输，包含 37 个工具。
• remote-server：Vercel 无服务器架构、Streamable HTTP 传输，包含 37 个工具。

前端演示

在浏览器中访问 context-first-mcp.vercel.app，试用全部 37 个工具。

开发

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.md。

许可证

MIT