
Cotforce Mcp
io.github.islobodan由 GitHub 帳號 islobodan 發布v1.1.3更新於 Oct 24, 2026
Give brains to your small models. MCP server enforcing step-by-step Chain-of-Thought.
概覽
一個 MCP 伺服器,強制 LLM 以結構化的逐步思維鏈推理作答,並回傳解析後的推理過程與結果。
- 可以做什麼
- CotForce 提供 solve_problem 工具,以嚴格的系統提示與少樣本範例要求 LLM 輸出包含 reasoning 與 result 的 JSON。它透過依優先順序排列的五個解析器(直接 JSON、圍欄程式碼區塊、XML 或標籤啟發式、括號平衡掃描、截斷復原)解析回覆,並以 Zod 結構驗證輸出,在解析或驗證失敗時提高溫度重試。它可透過 MCP sampling 呼叫模型,也可直接呼叫相容 OpenAI 的 HTTP 端點,並回報 token 用量與指標。
- 適用情境
- 適合希望助理有條理地處理邏輯謎題、數學應用題、程式碼分析等多步驟任務的情境,尤其是容易跳步的小型本機模型。也適合需要結構化推理輸出、可選結果結構驗證與 token 統計的場合。
- 執行需求
- 以本機 Node.js 程序執行(需要 Node.js 18 或更新版本),可從 npm 套件 @slbdn/cotforce-mcp 安裝或從原始碼建置。需要支援 sampling 的 MCP 用戶端,或設定 API_BASE_URL 與 MODEL 使用直接 HTTP 模式;遠端供應商需要 API_KEY,本機端點(如 LM Studio、Ollama)可省略。透過 MODE、MODEL、API_BASE_URL、API_KEY、MAX_RETRIES、TIMEOUT、COT_PARSERS 等環境變數設定。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Cotforce Mcp,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
CotForce-MCP
"Give brains to your small models."
CotForce enforces step-by-step Chain-of-Thought, turning 4B parameter models into methodical reasoners.
Why this exists
A 4-billion-parameter Gemma cannot solve SEND + MORE = MONEY. It's a classic cryptarithmetic puzzle — 8 unique digits, 5 columns, 4 carry values. A bare 4B model guesses randomly. It hallucinates digits. It loses track of carries after column 2.
The same model, with CotForce:
11 structured reasoning steps. Zero hallucinations. Correct answer.
CotForce doesn't make small models smarter. It forces them to think before they speak — which is often all they need.
⚡ Two modes — one line of config
CotForce uses the MCP sampling protocol (sampling/createMessage) to call LLMs. If your client supports it (Claude Desktop, Cursor), nothing extra is needed.
If not — or if you're using a local model like Gemma via LMStudio — switch to direct HTTP mode:
That's it. The same 4B Gemma that couldn't solve SEND+MORE=MONEY above — now with CotForce, working locally through LMStudio.
🚀 Features
- Rigid CoT enforcement — forces any LLM to output valid JSON
{reasoning, result}via strict system prompts and few‑shot examples. - Adaptive multi‑layer parser — plug-in architecture with 5 built-in parsers (direct JSON, fenced blocks, XML/labels, brace-balanced, truncated recovery) in a priority-sorted pipeline. Add custom parsers via
CotParserinterface. Select parsers viaCOT_PARSERSenv var.- Direct JSON (with code‑fence stripping)
- JSON inside markdown fenced blocks
- XML / heuristic label extraction (
<reasoning>,Reasoning:) - Brace‑balancing scanner for nested JSON objects
- Zod runtime validation — validates tool arguments and parsed CoT output with strict schemas.
- Automatic retry with temperature increase — up to 3 attempts (configurable) with increasing temperature and correction suffixes.
- Per‑request rejection memo — no global mutable state; safe under concurrent tool calls.
- Token budgeting with tiktoken — accurate token counting using OpenAI's
cl100k_baseencoding, with fallback to character heuristic. Tweak viaREASONING_OVERHEAD. - Configurable model — set
MODELenvironment variable to hint a specific model; leave unset for host default. - Model-specific prompts — automatically selects tuned system prompts for Claude, GPT-4, Gemini, and Grok based on
MODEL. - Universal compatibility — works with MCP sampling (Claude Desktop) or direct LLM HTTP calls (OpenAI, LMStudio, Ollama, any OpenAI-compatible API). Set
API_KEYto use direct mode. - Structured logging — timestamped, level‑filtered logs to stderr (supports
LOG_LEVEL). - Output truncation detection — detects when the LLM response hits the token limit and retries with a conciseness hint (
TRUNCATION_THRESHOLD). - Token usage exposure — every response includes input / output / budget token counts so callers can optimize.
- User-supplied result schema — optional
resultSchemaparameter validates theresultfield type‑map; mismatches trigger retry. - Structured metrics — in-memory counters for requests, success/fail rates, truncations, retries, latency, and token usage. Logged on shutdown.
- Comprehensive test suite — 151 tests covering parser pipeline, token budgeting, metrics, schema validation, retry loop, progress notifications, caching, and MCP server integration.
📦 Installation
Requires Node.js ≥ 18.
Quick start — Claude Desktop
Add to claude_desktop_config.json:
No clone, no build. npx -y pulls and runs directly from npm.
🔧 Configuration
The server is configured via environment variables (all optional):
Example
🧪 Usage
As an MCP Tool
Add to your MCP client configuration. A .mcp.json file is included in the package for auto-discovery by clients like Cursor, VS Code, and Windsurf. Copy the relevant config below to your client's settings:
With MCP sampling (Claude Desktop):
With direct LLM HTTP (LMStudio, OpenAI, Ollama):
Note:
API_KEYis optional for local endpoints like LMStudio or Ollama. It is required for remote providers like OpenAI or Anthropic.
The root
index.jsis a launcher that delegates todist/index.js. It guards against missing builds with a helpful error message.
🩺 Troubleshooting
Response truncated mid-reasoning
What you see: finish_reason: "length" in the LLM response. The reasoning cuts off before the result field.
Why: The token budget is too tight. Complex reasoning (like SEND+MORE=MONEY) can need 3000+ output tokens, but the default minimum is 4096 — while the default model-level cap can vary.
Fix: Increase the budget overhead:
Or skip token-heavy parser layers to save budget for reasoning:
MCP client timeout
What you see: MCP error -32001: Request timed out before the solution appears.
Why: Complex CoT reasoning takes time — 60-90 seconds for local models like Gemma. This error can come from two places:
- CotForce's own timeout — default 120s for direct HTTP mode. Controlled by the
TIMEOUTenv var. - The MCP client's timeout — LM Studio, Claude Desktop, Cursor, etc. each have their own default timeout for tool calls (often 30-60s). This is separate from CotForce's timeout.
Fix — check both sides:
Increase CotForce's timeout:
Check your MCP client's timeout setting:
LM Studio — add "timeout" to mcp.json (milliseconds):
Claude Desktop — the tool call timeout is not directly configurable. A workaround is to increase CotForce's TIMEOUT to complete within the client's window, or use a faster model.
Cursor / VS Code — check the MCP extension or .vscode/mcp.json for a timeout or requestTimeout setting.
Call the Tool
With Result Schema Validation
If the result field doesn't match the schema, the server retries with a correction hint.
More Examples
See EXAMPLES.md for 16 diverse examples including:
- Logic puzzles, probability, word problems
- Code analysis, regex, SQL queries
- Creative writing, recipe adaptation
- Nested JSON with schema validation
- Usage with different models and fallbacks
Example Response
If parsing fails after all retries, the server returns the raw LLM output with a warning.
🧩 Custom Parsers
The parser is a priority-sorted pipeline of plugins. Five built-in parsers run in order:
Filter parsers via COT_PARSERS env var:
Write a custom parser:
Then register it programmatically:
📚 API
Tool: solve_problem
- Input:
{ prompt: string }— the problem to solve. - Output: either:
- Success — structured CoT result.
- Soft failure — raw LLM output if parsing fails after all retries.
Sampling / LLM Calling
CotForce supports two modes for calling the LLM:
MCP Sampling (default with compatible clients):
- Uses MCP native
sampling/createMessage - Client selects and calls the model
- Requires client support (Claude Desktop, etc.)
Direct HTTP (for clients without sampling support):
- Calls OpenAI-compatible
/v1/chat/completionsdirectly - Works with OpenAI, LMStudio, Ollama, and any compatible provider
- Activated automatically in
MODE=autowhenAPI_KEYis set and client lacks sampling - Or force with
MODE=direct
Both modes use the same system prompt with few‑shot examples and strict schema constraints.
🏗️ Architecture
🧠 How It Works
- System prompt enforces JSON output with
reasoningandresult. Model-specific variants tuned for Claude, GPT-4, Gemini, Grok. - Parser pipeline runs 5 built-in parsers in priority order (direct JSON, fenced blocks, XML/labels, brace-balanced, truncated recovery). First valid match wins. Custom parsers can be added via
COT_PARSERSenv var and theCotParserinterface. - Retry logic — if parsing fails, injects correction suffix and increases temperature. Supports fallback models (
FALLBACK_MODELS) when primary model refuses. - Rejection memory stores a snippet of the last failure to contextualise the next call (scoped per‑request, thread‑safe).
- Token budgeting uses
estimateTokens()(lightweight heuristic) for budget math andcountTokens()(tiktoken) for exact counts. SetsmaxTokensdynamically (between 4096 and 8192) via formulaoverhead + inputTokens × 4. Detects truncation viafinish_reason: "length"and attempts JSON recovery before retrying.
🛠️ Development
Scripts
Testing
The test suite uses Jest with ts-jest (ESM) and @slbdn/mcp-tester for MCP server integration testing:
- Parser tests (
tests/parser.test.ts) — 47 unit tests covering all 5 parser plugins, edge cases, andAgenticCotSchemavalidation. - Token tests (
tests/tokens.test.ts) — 16 unit tests fortiktokenintegration, budget computation, andREASONING_OVERHEADtuning. - Schema tests (
tests/schema.test.ts) — 8 unit tests for user-suppliedresultSchemavalidation. - Metrics tests (
tests/metrics.test.ts) — 9 unit tests for request counters, latency tracking, and token usage averages. - Prompt tests (
tests/prompts.test.ts) — 10 unit tests for model-specific prompt selection. - LLM tests (
tests/llm.test.ts) — 3 unit tests for direct HTTP mode detection. - Server tests (
tests/server.test.ts) — 11 integration tests for tool discovery, argument validation, server lifecycle, and concurrent calls.
Custom Jest matchers are available via @slbdn/mcp-tester:
⚠️ Limitations & Honest Assessment
- No true production monitoring — only structured logs; no aggregated metrics.
- Token budget formula is heuristic — may need tuning for very verbose models.
- Model hints are suggestions — the MCP host decides which model to use.
- See TODO list for planned improvements.
📄 License
MIT © Slobodan Ivkovic
⭐ Support
If you find CotForce-MCP useful, consider starring the repo and sharing your feedback!
來源:README.md,提交 4d5832f
工具
0版本歷史
1- v1.1.3最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分