{
  "markdown": "# CotForce-MCP\n\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)\n[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)\n\n> **\"Give brains to your small models.\"**  \n> CotForce enforces step-by-step Chain-of-Thought, turning 4B parameter models into methodical reasoners.\n\n---\n\n### Why this exists\n\nA **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.\n\n**The same model, with CotForce:**\n\n```\nStep 1: Analyze the leftmost column. S+M+C3 = MO. Max sum is 19998. ∴ M=1.\nStep 2: S+1+C3 = 10+O. With M=1 and carry, O must be 0.\nStep 3: D+E = Y+10C1 → C1=1. Now R+C1=9 → C1=0→R=9 (used), C1=1→R=8.\n...\nStep 11: All digits assigned. 9567 + 1085 = 10652. Verified.\n```\n\n**11 structured reasoning steps. Zero hallucinations. Correct answer.**\n\nCotForce doesn't make small models smarter. It forces them to **think before they speak** — which is often all they need.\n\n---\n\n### ⚡ Two modes — one line of config\n\nCotForce uses the **MCP sampling protocol** (`sampling/createMessage`) to call LLMs. If your client supports it (Claude Desktop, Cursor), nothing extra is needed.\n\nIf not — or if you're using a **local model** like Gemma via LMStudio — switch to direct HTTP mode:\n\n```json\n{\n  \"mcpServers\": {\n    \"cotforce\": {\n      \"command\": \"node\",\n      \"args\": [\"node_modules/@slbdn/cotforce-mcp/index.js\"],\n      \"env\": {\n        \"MODE\": \"direct\",\n        \"API_BASE_URL\": \"http://localhost:1234/v1\",\n        \"MODEL\": \"gemma-4-e4b-it-mlx\"\n      }\n    }\n  }\n}\n```\n\nThat's it. The same 4B Gemma that couldn't solve SEND+MORE=MONEY above — now with CotForce, working locally through LMStudio.\n\n---\n\n## 🚀 Features\n\n- **Rigid CoT enforcement** — forces any LLM to output valid JSON `{reasoning, result}` via strict system prompts and few‑shot examples.\n- **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.\n  1. Direct JSON (with code‑fence stripping)\n  2. JSON inside markdown fenced blocks\n  3. XML / heuristic label extraction (`<reasoning>`, `Reasoning:`)\n  4. Brace‑balancing scanner for nested JSON objects\n- **Zod runtime validation** — validates tool arguments and parsed CoT output with strict schemas.\n- **Automatic retry with temperature increase** — up to 3 attempts (configurable) with increasing temperature and correction suffixes.\n- **Per‑request rejection memo** — no global mutable state; safe under concurrent tool calls.\n- **Token budgeting with tiktoken** — accurate token counting using OpenAI's `cl100k_base` encoding, with fallback to character heuristic. Tweak via `REASONING_OVERHEAD`.\n- **Configurable model** — set `MODEL` environment variable to hint a specific model; leave unset for host default.\n- **Model-specific prompts** — automatically selects tuned system prompts for Claude, GPT-4, Gemini, and Grok based on `MODEL`.\n- **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.\n- **Structured logging** — timestamped, level‑filtered logs to stderr (supports `LOG_LEVEL`).\n- **Output truncation detection** — detects when the LLM response hits the token limit and retries with a conciseness hint (`TRUNCATION_THRESHOLD`).\n- **Token usage exposure** — every response includes input / output / budget token counts so callers can optimize.\n- **User-supplied result schema** — optional `resultSchema` parameter validates the `result` field type‑map; mismatches trigger retry.\n- **Structured metrics** — in-memory counters for requests, success/fail rates, truncations, retries, latency, and token usage. Logged on shutdown.\n- **Comprehensive test suite** — **151 tests** covering parser pipeline, token budgeting, metrics, schema validation, retry loop, progress notifications, caching, and MCP server integration.\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @slbdn/cotforce-mcp\n# or\ngit clone https://github.com/islobodan/cotforce-mcp\ncd cotforce-mcp\nnpm install\nnpm run build\n```\n\nRequires **Node.js ≥ 18**.\n\n### Quick start — Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cotforce\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@slbdn/cotforce-mcp\"],\n      \"env\": {\n        \"MODEL\": \"claude-3-5-sonnet\"\n      }\n    }\n  }\n}\n```\n\nNo clone, no build. `npx -y` pulls and runs directly from npm.\n\n---\n\n## 🔧 Configuration\n\nThe server is configured via environment variables (all optional):\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MODEL` | *(not set)* | Model name hint (e.g. `claude-3-5-sonnet`, `gpt-4o`). If empty, no hint sent – MCP host decides. |\n| `MAX_RETRIES` | `2` | Number of retry attempts before returning raw output. |\n| `BASE_TEMP` | `0.1` | Initial sampling temperature. |\n| `TEMP_INCREMENT` | `0.2` | Temperature added per retry attempt. |\n| `TIMEOUT` | `60000` / `120000` | Sampling timeout in ms (60s). Direct HTTP mode uses longer default (120s) since local models are slower. |\n| `CACHE_TTL` | `3600000` | Result cache TTL in ms (default 1 hour). Set to `0` to disable. |\n| `CACHE_MAX_ENTRIES` | `100` | Maximum cached results before evicting oldest. |\n| `COT_PARSERS` | *(all)* | Comma-separated parser names to use (e.g., `direct-json,fenced-block`). Skips others. |\n| `TRUNCATION_THRESHOLD` | `0.95` | Ratio of output/budget that triggers truncation detection. Attempts truncated JSON recovery first, then retries with 1.5x budget. |\n| `REASONING_OVERHEAD` | `800` | Fixed token overhead added to the budget formula. Increase for verbose models. |\n| `FALLBACK_MODELS` | *(not set)* | Comma-separated list of fallback models (e.g. `gpt-4o,claude-3-5-sonnet`). Cycled on failure. |\n| `MODE` | `auto` | `auto`, `sampling`, or `direct`. `auto` uses direct HTTP when `API_KEY` is set and client lacks sampling support. |\n| `API_KEY` | *(not set)* | LLM API key for direct HTTP mode. Optional for local endpoints (LMStudio, Ollama). Required for remote providers (OpenAI, Anthropic, etc.). |\n| `API_BASE_URL` | `https://api.openai.com` | Base URL for direct HTTP mode. Change for LMStudio (`http://localhost:1234/v1`) or other providers. |\n| `LOG_LEVEL` | `INFO` | One of `DEBUG`, `INFO`, `WARN`, `ERROR`. |\n\n### Example\n\n```bash\nMODEL=gpt-4o MAX_RETRIES=3 BASE_TEMP=0.2 TEMP_INCREMENT=0.15 LOG_LEVEL=DEBUG npx @slbdn/cotforce-mcp\n```\n\n---\n\n## 🧪 Usage\n\n### As an MCP Tool\n\nAdd 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:\n\n**With MCP sampling** (Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"cotforce\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/cotforce-mcp/index.js\"],\n      \"env\": {\n        \"MODEL\": \"claude-3-5-sonnet\",\n        \"MAX_RETRIES\": \"2\"\n      }\n    }\n  }\n}\n```\n\n**With direct LLM HTTP** (LMStudio, OpenAI, Ollama):\n```json\n{\n  \"mcpServers\": {\n    \"cotforce\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/cotforce-mcp/index.js\"],\n      \"env\": {\n        \"MODE\": \"direct\",\n        \"API_BASE_URL\": \"http://localhost:1234/v1\",\n        \"MODEL\": \"local-model\",\n        \"MAX_RETRIES\": \"2\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** `API_KEY` is optional for local endpoints like LMStudio or Ollama. It is required for remote providers like OpenAI or Anthropic.\n\n> The root `index.js` is a launcher that delegates to `dist/index.js`. It guards against missing builds with a helpful error message.\n\n---\n\n## 🩺 Troubleshooting\n\n### Response truncated mid-reasoning\n\n**What you see:** `finish_reason: \"length\"` in the LLM response. The reasoning cuts off before the `result` field.\n\n**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.\n\n**Fix:** Increase the budget overhead:\n\n```bash\nREASONING_OVERHEAD=1600  # default is 800, raise for verbose models\n```\n\nOr skip token-heavy parser layers to save budget for reasoning:\n\n```bash\nCOT_PARSERS=direct-json,fenced-block  # skip heuristic and brace-balanced\n```\n\n### MCP client timeout\n\n**What you see:** `MCP error -32001: Request timed out` before the solution appears.\n\n**Why:** Complex CoT reasoning takes time — 60-90 seconds for local models like Gemma. This error can come from **two places**:\n\n1. **CotForce's own timeout** — default 120s for direct HTTP mode. Controlled by the `TIMEOUT` env var.\n2. **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.\n\n**Fix — check both sides:**\n\nIncrease CotForce's timeout:\n```bash\nTIMEOUT=180000  # 3 minutes\n```\n\nCheck your MCP client's timeout setting:\n\n**LM Studio** — add `\"timeout\"` to `mcp.json` (milliseconds):\n```json\n{\n  \"mcpServers\": {\n    \"cotforce\": {\n      \"command\": \"node\",\n      \"args\": [\"index.js\"],\n      \"env\": {\n        \"TIMEOUT\": \"180000\"\n      },\n      \"timeout\": 300000\n    }\n  }\n}\n```\n\n**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.\n\n**Cursor / VS Code** — check the MCP extension or `.vscode/mcp.json` for a `timeout` or `requestTimeout` setting.\n\n---\n\n### Call the Tool\n\n```json\n{\n  \"name\": \"solve_problem\",\n  \"arguments\": {\n    \"prompt\": \"What is 7 * 8 + 2?\"\n  }\n}\n```\n\n### With Result Schema Validation\n\n```json\n{\n  \"name\": \"solve_problem\",\n  \"arguments\": {\n    \"prompt\": \"List the prime numbers between 10 and 20\",\n    \"resultSchema\": {\n      \"primes\": \"object\",\n      \"count\": \"number\"\n    }\n  }\n}\n```\n\nIf the `result` field doesn't match the schema, the server retries with a correction hint.\n\n### More Examples\n\nSee [EXAMPLES.md](EXAMPLES.md) for 16 diverse examples including:\n- Logic puzzles, probability, word problems\n- Code analysis, regex, SQL queries\n- Creative writing, recipe adaptation\n- Nested JSON with schema validation\n- Usage with different models and fallbacks\n\n### Example Response\n\n```json\n{\n  \"content\": [{\n    \"type\": \"text\",\n    \"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\"\n  }]\n}\n```\n\nIf parsing fails after all retries, the server returns the raw LLM output with a warning.\n\n---\n## 🧩 Custom Parsers\n\nThe parser is a priority-sorted pipeline of plugins. Five built-in parsers run in order:\n\n| Priority | Name | What it does |\n|----------|------|-------------|\n| 10 | `direct-json` | Parses whole output as JSON (strips ` ```json` fences) |\n| 20 | `fenced-block` | Extracts JSON from markdown code blocks |\n| 30 | `heuristic` | Looks for `<reasoning>`/`<result>` XML tags or `Reasoning:`/`Result:` labels |\n| 40 | `brace-balanced` | Finds first balanced `{}` in arbitrary text |\n| 50 | `truncated-recovery` | Salvages reasoning from truncated JSON (hit token limit) |\n\n**Filter parsers via `COT_PARSERS` env var:**\n```bash\nCOT_PARSERS=direct-json,fenced-block node index.js\n```\n\n**Write a custom parser:**\n```ts\nimport { CotParser, AgenticCotSchema } from \"@slbdn/cotforce-mcp\";\n\nclass YamlParser implements CotParser {\n  name = \"yaml\";\n  priority = 35; // runs after heuristic, before brace-balanced\n\n  parse(raw: string): { reasoning: string; result: unknown } | null {\n    // Custom YAML parsing logic here\n    return null; // return null if this output isn't YAML\n  }\n}\n```\n\nThen register it programmatically:\n```ts\nimport { defaultParserPipeline, ParserPipeline } from \"@slbdn/cotforce-mcp\";\nconst pipeline = defaultParserPipeline();\npipeline.addParser(new YamlParser());\nconst result = pipeline.parse(rawText);\n```\n\n---\n\n## 📚 API\n\n### Tool: `solve_problem`\n\n- **Input**: `{ prompt: string }` — the problem to solve.\n- **Output**: either:\n  - **Success** — structured CoT result.\n  - **Soft failure** — raw LLM output if parsing fails after all retries.\n\n### Sampling / LLM Calling\n\nCotForce supports **two modes** for calling the LLM:\n\n**MCP Sampling** (default with compatible clients):\n- Uses MCP native `sampling/createMessage`\n- Client selects and calls the model\n- Requires client support (Claude Desktop, etc.)\n\n**Direct HTTP** (for clients without sampling support):\n- Calls OpenAI-compatible `/v1/chat/completions` directly\n- Works with OpenAI, LMStudio, Ollama, and any compatible provider\n- Activated automatically in `MODE=auto` when `API_KEY` is set and client lacks sampling\n- Or force with `MODE=direct`\n\nBoth modes use the same system prompt with few‑shot examples and strict schema constraints.\n\n---\n\n## 🏗️ Architecture\n\n```\ncotforce-mcp/\n├── src/\n│   ├── index.ts           # MCP server, tool handlers, routing logic\n│   └── lib/\n│       ├── parser.ts      # Parser pipeline: CotParser interface + 5 plugin parsers + Zod schemas\n│       ├── tokens.ts      # tiktoken integration + budget computation\n│       ├── prompts.ts     # Model-specific system prompts\n│       ├── metrics.ts     # In-memory request/performance counters\n│       └── llm.ts         # Direct HTTP LLM client (OpenAI-compatible)\n├── tests/\n│   ├── cache.test.ts      # 10 unit tests for result caching\n│   ├── parser.test.ts     # 47 unit tests for parser layers\n│   ├── tokens.test.ts     # 23 unit tests for token budgeting\n│   ├── schema.test.ts     # 8 unit tests for result schema validation\n│   ├── metrics.test.ts    # 9 unit tests for metrics tracking\n│   ├── prompts.test.ts    # 12 unit tests for model-specific prompts\n│   ├── llm.test.ts        # 6 tests for direct mode detection\n│   ├── retry.test.ts      # 4 integration tests for retry loop\n│   ├── progress.test.ts   # 5 unit tests for progress notifications\n│   └── server.test.ts     # 9 integration tests via @slbdn/mcp-tester\n├── index.js               # Root launcher (delegates to dist/)\n├── dist/                  # Compiled TypeScript output\n└── package.json\n```\n\n---\n\n## 🧠 How It Works\n\n1. **System prompt** enforces JSON output with `reasoning` and `result`. Model-specific variants tuned for Claude, GPT-4, Gemini, Grok.\n2. **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_PARSERS` env var and the `CotParser` interface.\n3. **Retry logic** — if parsing fails, injects correction suffix and increases temperature. Supports fallback models (`FALLBACK_MODELS`) when primary model refuses.\n4. **Rejection memory** stores a snippet of the last failure to contextualise the next call (scoped per‑request, thread‑safe).\n5. **Token budgeting** uses `estimateTokens()` (lightweight heuristic) for budget math and `countTokens()` (tiktoken) for exact counts. Sets `maxTokens` dynamically (between 4096 and 8192) via formula `overhead + inputTokens × 4`. Detects truncation via `finish_reason: \"length\"` and attempts JSON recovery before retrying.\n\n---\n\n## 🛠️ Development\n\n```bash\ngit clone https://github.com/islobodan/cotforce-mcp\ncd cotforce-mcp\nnpm install\nnpm run build      # compile TypeScript to dist/\nnpm run dev        # tsc --watch\nnpm run typecheck  # type-check src/ and tests/\n```\n\n### Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm run build` | Compile TypeScript (`src/` → `dist/`) |\n| `npm run dev` | Watch mode compilation |\n| `npm run typecheck` | TypeScript type-checking for source and tests |\n| `npm test` | Run full Jest test suite (133 tests) |\n| `npm run test:smoke` | Quick smoke test via `mcp-tester` CLI |\n| `npm run test:tools` | List available tools via `mcp-tester` CLI |\n\n### Testing\n\nThe test suite uses **Jest** with **ts-jest** (ESM) and **`@slbdn/mcp-tester`** for MCP server integration testing:\n\n- **Parser tests** (`tests/parser.test.ts`) — 47 unit tests covering all 5 parser plugins, edge cases, and `AgenticCotSchema` validation.\n- **Token tests** (`tests/tokens.test.ts`) — 16 unit tests for `tiktoken` integration, budget computation, and `REASONING_OVERHEAD` tuning.\n- **Schema tests** (`tests/schema.test.ts`) — 8 unit tests for user-supplied `resultSchema` validation.\n- **Metrics tests** (`tests/metrics.test.ts`) — 9 unit tests for request counters, latency tracking, and token usage averages.\n- **Prompt tests** (`tests/prompts.test.ts`) — 10 unit tests for model-specific prompt selection.\n- **LLM tests** (`tests/llm.test.ts`) — 3 unit tests for direct HTTP mode detection.\n- **Server tests** (`tests/server.test.ts`) — 11 integration tests for tool discovery, argument validation, server lifecycle, and concurrent calls.\n\nCustom Jest matchers are available via `@slbdn/mcp-tester`:\n\n```typescript\nexpect(tools).toHaveTool(\"solve_problem\");\nexpect(tools).toHaveToolWithSchema(\"solve_problem\");\nexpect(result).toReturnTextContaining(\"Reasoning:\");\n```\n\n---\n\n## ⚠️ Limitations & Honest Assessment\n\n- **No true production monitoring** — only structured logs; no aggregated metrics.\n- **Token budget formula is heuristic** — may need tuning for very verbose models.\n- **Model hints are suggestions** — the MCP host decides which model to use.\n- See [TODO list](TODO.md) for planned improvements.\n\n---\n\n## 📄 License\n\nMIT © Slobodan Ivkovic\n\n---\n\n## ⭐ Support\n\nIf you find CotForce-MCP useful, consider starring the repo and sharing your feedback!\n",
  "bytes": 17884,
  "sha": "317e57fe0362b3ea66e84209d6dee5b70eb1af9e84f4af8665587a522d5f77f8",
  "repo_slug": "islobodan/cotforce-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_islobodan_cotforce_mcp_baf70d54/readme"
}