Cotforce Mcp
About
Give brains to your small models. MCP server that enforces step-by-step Chain-of-Thought — turns 4B models into methodical reasoners
Explore
- 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 CotParser interface. Select parsers via COT_PARSERS env var.
1. Direct JSON (with code‑fence stripping)
2. JSON inside markdown fenced blocks
3. XML / heuristic label extraction (<reasoning>, Reasoning:)
4. 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_base encoding, with fallback to character heuristic. Tweak via REASONING_OVERHEAD.
- Configurable model — set MODEL environment 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_KEY to 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 resultSchema parameter validates the result field 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.
---
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Cotforce McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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:
{
"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"
}
}
}
}
That's it. The same 4B Gemma that couldn't solve SEND+MORE=MONEY above — now with CotForce, working locally through LMStudio.
---
npm install @slbdn/cotforce-mcp
Add to claude_desktop_config.json:
{
"mcpServers": {
"cotforce": {
"command": "npx",
"args": ["-y", "@slbdn/cotforce-mcp"],
"env": {
"MODEL": "claude-3-5-sonnet"
}
}
}
}
``
No clone, no build.
npx -y pulls and runs directly from npm.
---
The server is configured via environment variables (all optional):
| Variable | Default | Description |
|----------|---------|-------------|
|
MODEL | (not set) | Model name hint (e.g. claude-3-5-sonnet, gpt-4o). If empty, no hint sent – MCP host decides. |
| MAX_RETRIES | 2 | Number of retry attempts before returning raw output. |
| BASE_TEMP | 0.1 | Initial sampling temperature. |
| TEMP_INCREMENT | 0.2 | Temperature added per retry attempt. |
| TIMEOUT | 60000 / 120000 | Sampling timeout in ms (60s). Direct HTTP mode uses longer default (120s) since local models are slower. |
| CACHE_TTL | 3600000 | Result cache TTL in ms (default 1 hour). Set to 0 to disable. |
| CACHE_MAX_ENTRIES | 100 | Maximum cached results before evicting oldest. |
| COT_PARSERS | (all) | Comma-separated parser names to use (e.g., direct-json,fenced-block). Skips others. |
| TRUNCATION_THRESHOLD | 0.95 | Ratio of output/budget that triggers truncation detection. Attempts truncated JSON recovery first, then retries with 1.5x budget. |
| REASONING_OVERHEAD | 800 | Fixed token overhead added to the budget formula. Increase for verbose models. |
| FALLBACK_MODELS | (not set) | Comma-separated list of fallback models (e.g. gpt-4o,claude-3-5-sonnet). Cycled on failure. |
| MODE | auto | auto, sampling, or direct. auto uses direct HTTP when API_KEY is set and client lacks sampling support. |
| API_KEY | (not set) | LLM API key for direct HTTP mode. Optional for local endpoints (LMStudio, Ollama). Required for remote providers (OpenAI, Anthropic, etc.). |
| API_BASE_URL | https://api.openai.com | Base URL for direct HTTP mode. Change for LMStudio (http://localhost:1234/v1) or other providers. |
| LOG_LEVEL | INFO | One of DEBUG, INFO, WARN, ERROR`. |solve_problem
Solves a problem using strict Agentic Chain-of-Thought with adaptive parsing, retry logic, token budgeting (via tiktoken), and configurable model.
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):
{
"mcpServers": {
"cotforce": {
"command": "node",
"args": ["/path/to/cotforce-mcp/index.js"],
"env": {
"MODEL": "claude-3-5-sonnet",
"MAX_RETRIES": "2"
}
}
}
}
With direct LLM 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"
}
}
}
}
> Note: API_KEY is optional for local endpoints like LMStudio or Ollama. It is required for remote providers like OpenAI or Anthropic.
> The root index.js is a launcher that delegates to dist/index.js. It guards against missing builds with a helpful error message.
---
{
"name": "solve_problem",
"arguments": {
"prompt": "What is 7 * 8 + 2?"
}
}
- Input: { prompt: string } — the problem to solve.
- Output: either:
- Success — structured CoT result.
- Soft failure — raw LLM output if parsing fails after all retries.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"cotforce mcp": {
"cotforce": {
"command": "npx",
"args": [
"-y",
"@slbdn/cotforce-mcp"
],
"env": {
"MODE": "direct",
"API_BASE_URL": "http://localhost:1234/v1",
"MODEL": "local-model",
"MAX_RETRIES": "2"
}
}
}
}
}McpServers
{
"cotforce": {
"command": "npx",
"args": [
"-y",
"@slbdn/cotforce-mcp"
],
"env": {
"MODE": "direct",
"API_BASE_URL": "http://localhost:1234/v1",
"MODEL": "local-model",
"MAX_RETRIES": "2"
}
}
}
> "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:
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 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:
{
"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"
}
}
}
}
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 CotParser interface. Select parsers via COT_PARSERS env var.
1. Direct JSON (with code‑fence stripping)
2. JSON inside markdown fenced blocks
3. XML / heuristic label extraction (<reasoning>, Reasoning:)
4. 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_base encoding, with fallback to character heuristic. Tweak via REASONING_OVERHEAD.
- Configurable model — set MODEL environment 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_KEY to 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 resultSchema parameter validates the result field 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
```bash
npm install @slbdn/cotforce-mcp
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
