Cotforce Mcp

CotForce-MCP

「小さなモデルに知能を与えましょう。」
CotForce は段階的な Chain-of-Thought を強制し、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 は小さなモデルを賢くするわけではありません。モデルに話す前に考えることを強制します。それだけで十分なことがよくあります。

---

⚡ 2つのモード — 設定は1行

CotForce は MCP サンプリングプロトコル（sampling/createMessage）を使って LLM を呼び出します。お使いのクライアントが対応していれば（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 強制 — 厳格なシステムプロンプトと少数例を使い、あらゆる LLM に有効な 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）または直接 LLM HTTP 呼び出し（OpenAI、LMStudio、Ollama、OpenAI 互換 API）で動作します。直接モードを使うには API_KEY を設定してください。
• 構造化ログ — タイムスタンプ付きで、ログレベルに応じたログを stderr に出力します（LOG_LEVEL に対応）。
• 出力切り詰めの検出 — LLM の応答がトークン上限に達したことを検出し、簡潔さを促すヒントを付けて再試行します（TRUNCATION_THRESHOLD）。
• トークン使用量の公開 — すべての応答に入力／出力／予算のトークン数が含まれるため、呼び出し側で最適化できます。
• ユーザー指定の結果スキーマ — 任意の resultSchema パラメーターで result フィールドの型マップを検証できます。不一致があると再試行します。
• 構造化メトリクス — リクエスト数、成功率／失敗率、切り詰め、再試行、レイテンシ、トークン使用量をメモリ内カウンターで記録し、シャットダウン時にログへ出力します。
• 包括的なテストスイート — パーサーパイプライン、トークン予算管理、メトリクス、スキーマ検証、再試行ループ、進捗通知、キャッシュ、MCP サーバー統合を網羅する 151件のテスト。

---

📦 インストール

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	サンプリングのタイムアウト（ミリ秒、60秒）です。ローカルモデルは処理が遅いため、直接 HTTP モードではデフォルトが長め（120秒）に設定されています。
CACHE_TTL	3600000	結果キャッシュの TTL（ミリ秒、デフォルトは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 です。auto は、API_KEY が設定されており、クライアントがサンプリングをサポートしていない場合に、直接 HTTP を使用します。
API_KEY	(未設定)	直接 HTTP モードで使用する LLM 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"
      }
    }
  }
}

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

注： LMStudio や Ollama などのローカルエンドポイントでは、API_KEY は任意です。OpenAI や Anthropic などのリモートプロバイダーでは必須です。

ルートの index.js は、dist/index.js に処理を委譲するランチャーです。ビルドが見つからない場合は、分かりやすいエラーメッセージを表示します。

---

🩺 トラブルシューティング

推論の途中で応答が切り捨てられる

表示される内容： LLM の応答に 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 秒ほどかかる場合があります。このエラーは次の 2 か所で発生する可能性があります。

1. CotForce 自体のタイムアウト — 直接 HTTP モードではデフォルトで 120 秒です。TIMEOUT 環境変数で制御します。
2. MCP クライアントのタイムアウト — LM Studio、Claude Desktop、Cursor などには、それぞれツール呼び出しのデフォルトのタイムアウトがあります（多くの場合 30～60 秒）。これは 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 の生の出力を返します。

---

🧩 カスタムパーサー

パーサーは、優先度順に並べられたプラグインのパイプラインです。組み込みパーサー 5 個が次の順序で実行されます。

優先度	名前	機能
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 を呼び出す2 つのモードに対応しています。

MCP サンプリング（対応クライアントでのデフォルト）：

• MCP ネイティブの sampling/createMessage を使用します
• クライアントがモデルを選択して呼び出します
• クライアント側の対応が必要です（Claude Desktop など）

直接 HTTP（サンプリングに対応していないクライアント向け）：

• OpenAI 互換の /v1/chat/completions を直接呼び出します
• OpenAI、LMStudio、Ollama、および互換プロバイダーで動作します
• API_KEY が設定され、クライアントがサンプリングに対応していない場合、MODE=auto で自動的に有効になります
• または 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. トークン予算では、予算計算に 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）、および MCP サーバーの統合テスト用の @slbdn/mcp-tester を使用します。

• パーサーテスト（tests/parser.test.ts）— 5 種類すべてのパーサープラグイン、エッジケース、AgenticCotSchema の検証を網羅する 47 件の単体テスト。
• トークンテスト（tests/tokens.test.ts）— tiktoken の統合、予算計算、REASONING_OVERHEAD の調整を対象とする 16 件の単体テスト。
• スキーマテスト（tests/schema.test.ts）— ユーザーが指定した resultSchema の検証を対象とする 8 件の単体テスト。
• メトリクステスト（tests/metrics.test.ts）— リクエスト数、レイテンシの追跡、トークン使用量の平均を対象とする 9 件の単体テスト。
• プロンプトテスト（tests/prompts.test.ts）— モデル固有のプロンプト選択を対象とする 10 件の単体テスト。
• LLM テスト（tests/llm.test.ts）— 直接 HTTP モードの検出を対象とする 3 件の単体テスト。
• サーバーテスト（tests/server.test.ts）— ツールの検出、引数の検証、サーバーのライフサイクル、並行呼び出しを対象とする 11 件の統合テスト。

カスタム Jest マッチャーは、@slbdn/mcp-tester から利用できます。

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

---

⚠️ 制限事項と率直な評価

• 実稼働環境向けの監視機能はありません — 構造化ログのみで、集約メトリクスはありません。
• トークン予算の計算式はヒューリスティックです — 出力が非常に長いモデルでは、調整が必要になる場合があります。
• モデルのヒントは提案にすぎません — どのモデルを使うかは MCP ホストが決定します。
• 予定されている改善については、TODO リストを参照してください。

---

📄 ライセンス

MIT © Slobodan Ivkovic

---

⭐ サポート

CotForce-MCP が役に立った場合は、リポジトリにスターを付けて、ぜひフィードバックをお寄せください。