Cotforce Mcp

CotForce-MCP

“为小模型赋予智慧。”
CotForce 强制执行逐步思维链，让拥有 4B 参数的模型成为有条理的推理者。

---

为什么要开发这个项目

一个 40 亿参数的 Gemma 无法解出 SEND + MORE = MONEY。这是一道经典的字母算术谜题——包含 8 个不同数字、5 列和 4 个进位值。一个未经约束的 4B 模型只会随机猜测、虚构数字，并在第 2 列之后忘记进位。

同一个模型，使用 CotForce 后：

Step 1: Analyze the leftmost column. S+M+C3 = MO. Max sum is 19998. ∴ M=1.
Step 2: S+1+C3 = 10+O. With M=1 and carry, O must be 0.
Step 3: D+E = Y+10C1 → C1=1. Now R+C1=9 → C1=0→R=9 (used), C1=1→R=8.
...
Step 11: All digits assigned. 9567 + 1085 = 10652. Verified.

11 个结构化推理步骤。零幻觉。答案正确。

CotForce 不会让小模型变得更聪明，而是强制它们先思考，再开口——这往往就是它们所需要的一切。

---

⚡ 两种模式——一行配置

CotForce 使用 MCP 采样协议（sampling/createMessage）调用大模型。如果你的客户端支持该协议（Claude Desktop、Cursor），就不需要额外配置。

如果不支持，或者你正通过 LMStudio 使用 Gemma 之类的本地模型，则可切换到直接 HTTP 模式：

{
  "mcpServers": {
    "cotforce": {
      "command": "node",
      "args": ["node_modules/@slbdn/cotforce-mcp/index.js"],
      "env": {
        "MODE": "direct",
        "API_BASE_URL": "http://localhost:1234/v1",
        "MODEL": "gemma-4-e4b-it-mlx"
      }
    }
  }
}

就这么简单。上面那个无法解出 SEND+MORE=MONEY 的 4B Gemma，现在通过 CotForce 在 LMStudio 上本地运行。

---

🚀 功能特性

• 严格执行 CoT — 通过严格的系统提示词和少样本示例，强制任何大模型输出有效的 JSON {reasoning, result}。
• 自适应多层解析器 — 采用插件式架构，在优先级排序的处理流程中内置 5 种解析器（直接 JSON、围栏代码块、XML/标签、大括号配对、截断恢复）。可通过 CotParser 接口添加自定义解析器。通过 COT_PARSERS 环境变量选择解析器。
  1. 直接 JSON（移除代码围栏）
  2. Markdown 围栏代码块中的 JSON
  3. XML / 启发式标签提取（<reasoning>、Reasoning:）
  4. 用于解析嵌套 JSON 对象的大括号配对扫描器
• Zod 运行时验证 — 使用严格的架构验证工具参数和解析后的 CoT 输出。
• 温度递增式自动重试 — 最多尝试 3 次（可配置），逐次提高温度并附加修正后缀。
• 每请求独立的拒绝备忘 — 不使用全局可变状态；并发调用工具时也安全。
• 使用 tiktoken 进行令牌预算管理 — 使用 OpenAI 的 cl100k_base 编码精确统计令牌数，并在不可用时回退到字符启发式算法。可通过 REASONING_OVERHEAD 调整。
• 可配置模型 — 设置 MODEL 环境变量以指定模型；不设置则使用主机默认模型。
• 针对不同模型的提示词 — 根据 MODEL 自动为 Claude、GPT-4、Gemini 和 Grok 选择经过调优的系统提示词。
• 通用兼容性 — 支持 MCP 采样（Claude Desktop）或直接调用大模型 HTTP 接口（OpenAI、LMStudio、Ollama，以及任何兼容 OpenAI 的 API）。设置 API_KEY 即可使用直接模式。
• 结构化日志 — 将带时间戳、按级别筛选的日志输出到 stderr（支持 LOG_LEVEL）。
• 输出截断检测 — 检测大模型响应是否达到令牌上限，并附加简洁提示后重试（TRUNCATION_THRESHOLD）。
• 令牌用量公开 — 每个响应都包含输入、输出和预算令牌数，便于调用方优化。
• 用户提供的结果架构 — 可选的 resultSchema 参数会验证 result 字段的类型映射；不匹配时会触发重试。
• 结构化指标 — 在内存中统计请求数、成功/失败率、截断次数、重试次数、延迟和令牌用量，并在关闭时记录。
• 全面的测试套件 — 151 项测试，覆盖解析器处理流程、令牌预算管理、指标、架构验证、重试循环、进度通知、缓存和 MCP 服务集成。

---

📦 安装

npm install @slbdn/cotforce-mcp
# or
git clone https://github.com/islobodan/cotforce-mcp
cd cotforce-mcp
npm install
npm run build

需要 Node.js ≥ 18。

快速开始——Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "cotforce": {
      "command": "npx",
      "args": ["-y", "@slbdn/cotforce-mcp"],
      "env": {
        "MODEL": "claude-3-5-sonnet"
      }
    }
  }
}

无需克隆，无需构建。npx -y 会直接从 npm 获取并运行。

---

🔧 配置

通过环境变量配置服务（全部可选）：

变量	默认值	描述
MODEL	（未设置）	模型名称提示（例如 claude-3-5-sonnet、gpt-4o）。如果为空，则不发送提示，由 MCP 主机决定。
MAX_RETRIES	2	返回原始输出前的重试次数。
BASE_TEMP	0.1	初始采样温度。
TEMP_INCREMENT	0.2	每次重试增加的温度。
TIMEOUT	60000 / 120000	采样超时时间，单位为 ms（60s）。直接 HTTP 模式使用较长的默认值（120s），因为本地模型速度较慢。
CACHE_TTL	3600000	结果缓存 TTL，单位为 ms（默认 1 小时）。设置为 0 可禁用。
CACHE_MAX_ENTRIES	100	淘汰最旧条目前允许缓存的最大结果数。
COT_PARSERS	（全部）	要使用的解析器名称，以逗号分隔（例如 direct-json,fenced-block）。跳过其他解析器。
TRUNCATION_THRESHOLD	0.95	触发截断检测的输出量／预算比率。先尝试恢复被截断的 JSON，然后使用 1.5 倍预算重试。
REASONING_OVERHEAD	800	添加到预算公式中的固定令牌开销。对于输出较冗长的模型，可适当增大。
FALLBACK_MODELS	（未设置）	备用模型列表，以逗号分隔（例如 gpt-4o,claude-3-5-sonnet）。失败时依次尝试。
MODE	auto	auto、sampling 或 direct。如果设置了 API_KEY 且客户端不支持采样，auto 会使用直接 HTTP。
API_KEY	（未设置）	直接 HTTP 模式使用的大模型 API 密钥。本地端点（LMStudio、Ollama）可选。远程提供商（OpenAI、Anthropic 等）必需。
API_BASE_URL	https://api.openai.com	直接 HTTP 模式的基础 URL。对于 LMStudio（http://localhost:1234/v1）或其他提供商，请修改此值。
LOG_LEVEL	INFO	可选值为 DEBUG、INFO、WARN、ERROR。

示例

MODEL=gpt-4o MAX_RETRIES=3 BASE_TEMP=0.2 TEMP_INCREMENT=0.15 LOG_LEVEL=DEBUG npx @slbdn/cotforce-mcp

---

🧪 用法

作为 MCP 工具

将其添加到 MCP 客户端配置中。软件包中包含一个 .mcp.json 文件，供 Cursor、VS Code 和 Windsurf 等客户端自动发现。将下方相关配置复制到客户端设置中：

使用 MCP 采样（Claude Desktop）：

{
  "mcpServers": {
    "cotforce": {
      "command": "node",
      "args": ["/path/to/cotforce-mcp/index.js"],
      "env": {
        "MODEL": "claude-3-5-sonnet",
        "MAX_RETRIES": "2"
      }
    }
  }
}

使用直接大模型 HTTP（LMStudio、OpenAI、Ollama）：

{
  "mcpServers": {
    "cotforce": {
      "command": "node",
      "args": ["/path/to/cotforce-mcp/index.js"],
      "env": {
        "MODE": "direct",
        "API_BASE_URL": "http://localhost:1234/v1",
        "MODEL": "local-model",
        "MAX_RETRIES": "2"
      }
    }
  }
}

注意： LMStudio 或 Ollama 等本地端点无需设置 API_KEY。OpenAI 或 Anthropic 等远程提供商则必须设置。

根目录中的 index.js 是一个启动器，会将请求转交给 dist/index.js。如果缺少构建文件，它会显示有用的错误信息。

---

🩺 故障排查

响应在推理过程中被截断

现象： 大模型响应中出现 finish_reason: "length"。推理在 result 字段出现之前就被截断。

原因： 令牌预算过于紧张。复杂推理（如 SEND+MORE=MONEY）可能需要 3000 个以上的输出令牌，但默认最小值为 4096，而模型级别的默认上限可能有所不同。

解决方法： 增加预算开销：

REASONING_OVERHEAD=1600  # default is 800, raise for verbose models

也可以跳过令牌消耗较多的解析器层，为推理留出更多预算：

COT_PARSERS=direct-json,fenced-block  # skip heuristic and brace-balanced

MCP 客户端超时

你会看到： 在解决方案出现前显示 MCP error -32001: Request timed out。

原因： 复杂的 CoT 推理需要时间——对于 Gemma 这类本地模型，可能需要 60-90 秒。此错误可能来自两个方面：

1. CotForce 自身的超时——直接 HTTP 模式下默认是 120s。由 TIMEOUT 环境变量控制。
2. MCP 客户端的超时——LM Studio、Claude Desktop、Cursor 等各自都有工具调用的默认超时时间（通常为 30-60s）。这与 CotForce 的超时设置相互独立。

解决方法——检查两端：

增加 CotForce 的超时时间：

TIMEOUT=180000  # 3 minutes

检查 MCP 客户端的超时设置：

LM Studio——在 mcp.json 中添加 "timeout"（单位：毫秒）：

{
  "mcpServers": {
    "cotforce": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "TIMEOUT": "180000"
      },
      "timeout": 300000
    }
  }
}

Claude Desktop——无法直接配置工具调用超时时间。一种变通方法是增加 CotForce 的 TIMEOUT，确保在客户端的时间限制内完成，或者使用更快的模型。

Cursor / VS Code——检查 MCP 扩展或 .vscode/mcp.json 中的 timeout 或 requestTimeout 设置。

---

调用工具

{
  "name": "solve_problem",
  "arguments": {
    "prompt": "What is 7 * 8 + 2?"
  }
}

使用结果架构验证

{
  "name": "solve_problem",
  "arguments": {
    "prompt": "List the prime numbers between 10 and 20",
    "resultSchema": {
      "primes": "object",
      "count": "number"
    }
  }
}

如果 result 字段与架构不匹配，服务端会在重试时附上修正提示。

更多示例

请参阅 EXAMPLES.md，其中包含 16 个不同示例，包括：

• 逻辑谜题、概率、文字题
• 代码分析、正则表达式、SQL 查询
• 创意写作、食谱改编
• 使用架构验证的嵌套 JSON
• 使用不同模型和备用方案

响应示例

{
  "content": [{
    "type": "text",
    "text": "🤖 Agentic CoT Result:\n\n**Reasoning:** Step 1: Multiply 7 * 8 = 56. Step 2: Add 2 to get 58.\n\n**Answer:** 58\n\n📊 Token Usage: 42 in / 150 out / 4096 budget"
  }]
}

如果所有重试后仍解析失败，服务端会返回原始 LLM 输出并附上警告。

---

🧩 自定义解析器

解析器是一个按优先级排序的插件管道。五个内置解析器依次运行：

优先级	名称	功能
10	direct-json	将整个输出解析为 JSON（去除 ```json 代码围栏）
20	fenced-block	从 Markdown 代码块中提取 JSON
30	heuristic	查找 <reasoning>/<result> XML 标签或 Reasoning:/Result: 标签
40	brace-balanced	在任意文本中查找第一个括号配对完整的 {}
50	truncated-recovery	从被截断的 JSON 中抢救推理内容（触及令牌限制）

通过 COT_PARSERS 环境变量筛选解析器：

COT_PARSERS=direct-json,fenced-block node index.js

编写自定义解析器：

import { CotParser, AgenticCotSchema } from "@slbdn/cotforce-mcp";

class YamlParser implements CotParser {
  name = "yaml";
  priority = 35; // runs after heuristic, before brace-balanced

  parse(raw: string): { reasoning: string; result: unknown } | null {
    // Custom YAML parsing logic here
    return null; // return null if this output isn't YAML
  }
}

然后以编程方式注册它：

import { defaultParserPipeline, ParserPipeline } from "@slbdn/cotforce-mcp";
const pipeline = defaultParserPipeline();
pipeline.addParser(new YamlParser());
const result = pipeline.parse(rawText);

---

📚 API

工具：solve_problem

• 输入：{ prompt: string }——要解决的问题。
• 输出：以下二者之一：
  • 成功——结构化 CoT 结果。
  • 软失败——所有重试后仍解析失败时返回原始 LLM 输出。

采样 / LLM 调用

CotForce 支持两种调用 LLM 的模式：

MCP 采样（兼容客户端的默认模式）：

• 使用 MCP 原生的 sampling/createMessage
• 客户端选择并调用模型
• 需要客户端支持（例如 Claude Desktop）

直接 HTTP（适用于不支持采样的客户端）：

• 直接调用兼容 OpenAI 的 /v1/chat/completions
• 支持 OpenAI、LMStudio、Ollama 及任何兼容的提供商
• 在 MODE=auto 下，如果设置了 API_KEY 且客户端不支持采样，则会自动启用
• 或通过 MODE=direct 强制启用

两种模式都使用相同的系统提示词，其中包含少样本示例和严格的架构约束。

---

🏗️ 架构

cotforce-mcp/
├── src/
│   ├── index.ts           # MCP server, tool handlers, routing logic
│   └── lib/
│       ├── parser.ts      # Parser pipeline: CotParser interface + 5 plugin parsers + Zod schemas
│       ├── tokens.ts      # tiktoken integration + budget computation
│       ├── prompts.ts     # Model-specific system prompts
│       ├── metrics.ts     # In-memory request/performance counters
│       └── llm.ts         # Direct HTTP LLM client (OpenAI-compatible)
├── tests/
│   ├── cache.test.ts      # 10 unit tests for result caching
│   ├── parser.test.ts     # 47 unit tests for parser layers
│   ├── tokens.test.ts     # 23 unit tests for token budgeting
│   ├── schema.test.ts     # 8 unit tests for result schema validation
│   ├── metrics.test.ts    # 9 unit tests for metrics tracking
│   ├── prompts.test.ts    # 12 unit tests for model-specific prompts
│   ├── llm.test.ts        # 6 tests for direct mode detection
│   ├── retry.test.ts      # 4 integration tests for retry loop
│   ├── progress.test.ts   # 5 unit tests for progress notifications
│   └── server.test.ts     # 9 integration tests via @slbdn/mcp-tester
├── index.js               # Root launcher (delegates to dist/)
├── dist/                  # Compiled TypeScript output
└── package.json

---

🧠 工作原理

1. 系统提示词 强制模型以包含 reasoning 和 result 的 JSON 格式输出。针对 Claude、GPT-4、Gemini、Grok 提供了经过调整的特定版本。
2. 解析器流水线 按优先级依次运行 5 个内置解析器（直接解析 JSON、围栏代码块、XML/标签、大括号平衡、截断恢复）。第一个有效匹配项即为结果。可通过 COT_PARSERS 环境变量和 CotParser 接口添加自定义解析器。
3. 重试逻辑 — 如果解析失败，则注入修正后缀并提高温度。主模型拒绝请求时，支持使用备用模型（FALLBACK_MODELS）。
4. 拒绝记忆 会保存上一次失败的片段，为下一次调用提供上下文（按请求隔离，线程安全）。
5. Token 预算 使用 estimateTokens()（轻量级启发式方法）进行预算计算，并使用 countTokens()（tiktoken）精确计数。通过公式 overhead + inputTokens × 4 动态设置 maxTokens（介于 4096 和 8192 之间）。通过 finish_reason: "length" 检测截断，并在重试前尝试恢复 JSON。

---

🛠️ 开发

git clone https://github.com/islobodan/cotforce-mcp
cd cotforce-mcp
npm install
npm run build      # compile TypeScript to dist/
npm run dev        # tsc --watch
npm run typecheck  # type-check src/ and tests/

脚本

脚本	用途
npm run build	编译 TypeScript（src/ → dist/）
npm run dev	监视模式编译
npm run typecheck	对源代码和测试进行 TypeScript 类型检查
npm test	运行完整的 Jest 测试套件（133 个测试）
npm run test:smoke	通过 mcp-tester CLI 运行快速冒烟测试
npm run test:tools	通过 mcp-tester CLI 列出可用工具

测试

测试套件使用 Jest、ts-jest（ESM）和 @slbdn/mcp-tester 进行 MCP 服务集成测试：

• 解析器测试（tests/parser.test.ts）— 47 个单元测试，涵盖全部 5 个解析器插件、边缘情况和 AgenticCotSchema 验证。
• Token 测试（tests/tokens.test.ts）— 16 个单元测试，涵盖 tiktoken 集成、预算计算和 REASONING_OVERHEAD 调整。
• 架构测试（tests/schema.test.ts）— 8 个单元测试，用于验证用户提供的 resultSchema。
• 指标测试（tests/metrics.test.ts）— 9 个单元测试，涵盖请求计数器、延迟跟踪和 Token 使用量平均值。
• 提示词测试（tests/prompts.test.ts）— 10 个单元测试，用于测试特定模型的提示词选择。
• LLM 测试（tests/llm.test.ts）— 3 个单元测试，用于检测直接 HTTP 模式。
• 服务端测试（tests/server.test.ts）— 11 个集成测试，涵盖工具发现、参数验证、服务端生命周期和并发调用。

可通过 @slbdn/mcp-tester 使用自定义 Jest 匹配器：

expect(tools).toHaveTool("solve_problem");
expect(tools).toHaveToolWithSchema("solve_problem");
expect(result).toReturnTextContaining("Reasoning:");

---

⚠️ 局限性与客观评估

• 没有真正的生产环境监控 — 只有结构化日志；没有聚合指标。
• Token 预算公式是启发式的 — 对于输出特别冗长的模型，可能需要调整。
• 模型提示仅供参考 — 使用哪个模型由 MCP 宿主决定。
• 计划中的改进请参阅 TODO 列表。

---

📄 许可证

MIT © Slobodan Ivkovic

---

⭐ 支持

如果你觉得 CotForce-MCP 有用，不妨为仓库点个星并分享你的反馈！