@nbiish/cognitive-tools-mcp 0.9.30 → 2.0.1

package/build/index.js

@@ -1,25 +1,27 @@
 #!/usr/bin/env node
 /**
  * -----------------------------------------------------------------------------
- * Gikendaasowin Aabajichiganan - Core Cognitive Tools MCP Server (v1.2 - Generalized)
+ * Gikendaasowin Aabajichiganan - Agentic Cognitive Tools MCP Server (v2.0)
  *
- * Description: Provides a streamlined suite of cognitive tools for an AI agent,
- *              inspired by research on improving LLM reasoning (like Anthropic's 'think' tool)
- *              applicable across domains (coding, research, planning, etc.).
- *              Focuses on assessment (`assess_cuc_n_mode`) and a central deliberation
- *              hub (`think`) used especially after receiving information/results.
- *              `quick_think` is for trivial steps. CoT/CoD reasoning styles occur within `think`.
- *              Returns Markdown.
+ * Description: Provides cognitive tools for an AI agent based on the
+ * Gikendaasowin Cognitive Framework (v7 Guidelines). Emphasizes
+ * a mandatory structured deliberation cycle (Observe-Orient-Decide-Act)
+ * performed *after* receiving information and *before* significant actions,
+ * ideally using the `think` tool. Supports adaptive reasoning styles
+ * (CoT, CoD/CRP, SCoT) and integrates with potentially dynamic toolsets,
+ * including a preference for Executable Code Actions (CodeAct) if available.
+ * Returns Markdown.
  *
- * Key Principles:
- * 1.  **Structured Deliberation:** Tools guide assessment (`assess_cuc_n_mode`) and
- *     thinking/analysis (`think`, `quick_think`).
- * 2.  **Centralized Analysis (`think`):** The `think` tool is the hub for analysis (results, errors),
- *     planning, reflection, policy checks, and reasoning (CoT/CoD). **Crucially used after info/results.**
- * 3.  **CUC-N Assessment:** `assess_cuc_n_mode` guides initial cognitive depth choice.
- * 4.  **Iterative Loop:** Assess -> [Action/Tool] -> Analyze Result/State (`think`) -> Plan (`think`) -> [Execute].
- * 5.  **Traceability & Reliability:** Tool inputs logged; structured thinking enhances reliability across tasks.
- * 6.  **Markdown Output:** Tool results formatted as Markdown.
+ * Key Principles (v7 Alignment):
+ * 1.  **Mandatory Deliberation:** A structured internal reasoning cycle is required
+ * before non-trivial actions.
+ * 2.  **Centralized Analysis (`think`):** The `think` tool is the preferred mechanism
+ * for the mandatory deliberation cycle (analysis, planning, OODReAct structure).
+ * 3.  **Adaptability:** Assumes the agent adapts to dynamically available tools.
+ * 4.  **CodeAct Preference:** Aligns with agent preference for executable code actions.
+ * 5.  **Adaptive Reasoning:** Supports CoT, CoD/CRP, SCoT styles within `think`.
+ * 6.  **Traceability:** Logs tool usage; `think` tool provides reasoning trace.
+ * 7.  **Markdown Output:** Tool results formatted as Markdown.
  *
  * Protocol:    Model Context Protocol (MCP) over stdio.
  * -----------------------------------------------------------------------------
@@ -29,13 +31,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 // --- Server Definition ---
 const serverInfo = {
-    name: "gikendaasowin-aabajichiganan-mcp",
-    version: "1.2.0", // Incremented version
-    description: `ᑭᑫᓐᑖᓱᐎᓐ ᐋᐸᒋᒋᑲᓇᓐ - Core Cognitive Tools (Generalized v1.2): Focuses on Assess/Think loop, using 'think' for post-result/state analysis across domains (code, research, etc.) to improve reliability. CoT/CoD integrated into 'think'. Returns Markdown.`
+    name: "gikendaasowin-agentic-cognitive-tools-mcp",
+    version: "2.0.0", // Version reflects alignment with v7 guidelines
+    description: `ᑭᑫᓐᑖᓱᐎᓐ ᐋᐸᒋᒋᑲᓇᓐ - Agentic Cognitive Tools (v2.0): Implements Gikendaasowin v7 Guidelines. Facilitates mandatory Observe-Orient-Decide-Act deliberation cycle (using 'think' tool) before actions. Supports adaptive reasoning (CoT, CoD/CRP, SCoT) and dynamic tool environments (incl. CodeAct preference). Returns Markdown.`
 };
 const server = new McpServer(serverInfo);
 // --- Logging Helpers ---
-// [Keep existing logToolCall, logToolResult, logToolError functions]
 /**
  * Logs an incoming tool call to stderr.
  * @param toolName The name of the tool being called.
@@ -66,42 +67,39 @@ function logToolError(toolName, error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     console.error(`[${timestamp}] [MCP Server] ! Tool Error: ${toolName} - ${errorMessage}`);
     logToolResult(toolName, false, errorMessage); // Log failure result as well
-    // Return a structured error message suitable for the LLM
+    // Return a structured error message suitable for the LLM, guiding towards the mandatory deliberation step
     return {
         content: [{
                 type: "text",
-                text: `Error executing tool '${toolName}': ${errorMessage}. Use the 'think' tool to analyze this error, check context, and plan the next step.` // Enhanced suggestion
+                text: `Error executing tool '${toolName}': ${errorMessage}. **Action Required:** Initiate the mandatory deliberation cycle (use the 'think' tool if available) to analyze this error (Observe/Orient), review context/goals, and plan the next corrective step (Decide/Reason/Act(Plan)).`
             }]
     };
 }
-// --- Core Cognitive Deliberation & Refinement Tools ---
+// --- Core Cognitive Deliberation & Refinement Tools (Aligned with v7 Guidelines) ---
 /**
- * Tool: assess_cuc_n_mode
- * Purpose: Initial assessment of task characteristics to guide cognitive strategy selection.
- * Workflow: Call BEFORE starting complex tasks or significantly changing strategy.
- * Output: Returns the full assessment text formatted as Markdown.
+ * Tool: assess_cuc_n_mode (Optional Initial Assessment)
+ * Purpose: Optional initial assessment of task characteristics (Complexity, Uncertainty, Consequence, Novelty)
+ * to *inform* the strategy for the mandatory deliberation cycle.
+ * Workflow: Can be called *optionally* at the start of complex tasks to help frame the initial approach.
+ * The primary, mandatory deliberation happens *later* using `think` or internally.
+ * Output: Returns the assessment text formatted as Markdown.
  */
-server.tool("assess_cuc_n_mode", "**Initial Assessment.** Evaluates task Complexity, Uncertainty, Consequence, Novelty (CUC-N) to guide cognitive strategy. Call before complex tasks (coding, research, multi-step plans). Based on assessment, explicitly select and state whether the next step requires the detailed `think` tool (for analysis, planning, complex results) or the minimal `quick_think` tool (for trivial steps only).", {
-    assessment_and_choice: z.string().describe("Your structured assessment including: 1) Situation/Task Description, 2) CUC-N Ratings (Low/Medium/High for each), 3) Rationale, 4) Recommended Cognitive Strategy (e.g., 'Requires careful step-by-step planning'), 5) Explicit Mode Selection ('Selected Mode: think' or 'Selected Mode: quick_think').")
-}, async ({ assessment_and_choice }) => {
+server.tool("assess_cuc_n_mode", "**(Optional) Initial Task Assessment.** Evaluates task Complexity, Uncertainty, Consequence, Novelty (CUC-N) to *inform* the initial strategy. Call optionally before complex tasks. This assessment helps frame the mandatory deliberation cycle (which uses `think` or occurs internally) but does *not* replace it. Output is your assessment.", {
+    assessment_text: z.string().describe("Your structured CUC-N assessment including: 1) Situation/Task Summary, 2) CUC-N Analysis (Low/Medium/High rationale), 3) Potential Strategy Considerations (e.g., 'Requires careful step-by-step planning via CoT', 'Efficiency via CoD/CRP seems appropriate', 'Need to prioritize CodeAct for file manipulation'). This informs, but does not dictate, the mandatory deliberation step.")
+}, async ({ assessment_text }) => {
     const toolName = 'assess_cuc_n_mode';
     logToolCall(toolName);
     try {
-        const modeRegex = /Selected Mode: (think|quick_think)/i;
-        const modeMatch = assessment_and_choice.match(modeRegex);
-        const selectedMode = modeMatch ? modeMatch[1].toLowerCase() : "unknown";
-        if (assessment_and_choice.trim().length === 0) {
-            throw new Error('Invalid assessment_and_choice: Must be a non-empty string.');
+        if (assessment_text.trim().length === 0) {
+            throw new Error('Invalid assessment_text: Must be a non-empty string containing the CUC-N analysis.');
         }
-        if (!modeMatch) {
-            throw new Error('Invalid assessment: String must include explicit "Selected Mode: think" or "Selected Mode: quick_think".');
-        }
-        logToolResult(toolName, true, `Selected mode (extracted): ${selectedMode}`);
-        console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${assessment_and_choice}`);
+        logToolResult(toolName, true, `Assessment logged (length: ${assessment_text.length})`);
+        console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${assessment_text}`);
+        // Return the assessment text directly
         return {
             content: [{
                     type: "text",
-                    text: assessment_and_choice
+                    text: assessment_text
                 }]
         };
     }
@@ -110,22 +108,32 @@ server.tool("assess_cuc_n_mode", "**Initial Assessment.** Evaluates task Complex
     }
 });
 /**
- * Tool: think
- * Purpose: The **CENTRAL HUB** for structured reasoning, analysis, and planning across all complex tasks.
- * Workflow: Use this tool to **stop and think** *after* receiving information (tool results, calculations, user input, file content) or *before* taking a complex action (generating code, calling critical tools, formulating multi-part answers). Analyze inputs/results, check goals/policies/constraints, verify state, plan next steps, brainstorm, and perform detailed reasoning (CoT/CoD). Essential for reliability, error handling, and managing sequential tasks.
- * Output: Returns the structured thought text itself, formatted as Markdown.
+ * Tool: think (Mandatory Deliberation Hub)
+ * Purpose: The **PREFERRED & CENTRAL HUB** for the **MANDATORY** structured deliberation cycle
+ * (Observe-Orient-Decide-Act).
+ * Workflow: **MUST** be called (if available) *after* receiving new information (tool results, CodeAct output/errors,
+ * USER input, file reads) and *before* executing any non-trivial action (tool call, CodeAct execution,
+ * complex response generation). Use it to analyze inputs, orient context/goals/policies, decide the next
+ * action, reason (CoT, CoD/CRP, SCoT), plan the action details (tool params, CodeAct code), define
+ * verification, and consider risks. Essential for reliability, error handling, and complex tasks.
+ * Output: Returns the structured thought process itself, formatted as Markdown, serving as an internal log.
  */
-server.tool("think", "**Central Hub for Analysis, Planning & Reasoning.** Use this tool to **stop and think**, especially *after* receiving information (tool results, errors, data) or before complex actions (coding, critical decisions). Analyze inputs/results, check goals/policies, verify information, plan next steps, and perform detailed reasoning (CoT/CoD) as needed. Crucial for reliability in coding, research, planning, and error recovery. Structure thought using clear headings (see prompt examples).", {
-    thought: z.string().describe("Your **structured** internal deliberation. MUST follow prompt guidance (Observe, Orient, Decide, Reason, Act, etc.). Include analysis of information/results, context/goal/policy checks, planning, and rationale (CoT/CoD). Crucial for complex tasks.")
+server.tool("think", "**Mandatory Deliberation Hub.** Use this tool (if available) for the required structured deliberation cycle *after* info and *before* action. Input MUST follow the OODReAct structure: ## Observe (analyze inputs/results/errors), ## Orient (context/goals/policy check), ## Decide (next action: tool, CodeAct, query, respond), ## Reason (justify decision; use CoT, CoD/CRP, or SCoT style), ## Act (Plan) (tool params, CodeAct code, response draft), ## Verification (success criteria), ## Risk & Contingency (briefly).", {
+    thought: z.string().describe("Your **structured OODReAct deliberation**. MUST include all sections: Observe, Orient, Decide, Reason (using appropriate CoT/CoD/CRP/SCoT style), Act(Plan) (with specific tool parameters or CodeAct code), Verification, Risk & Contingency. This is critical for documenting the mandatory reasoning process before acting.")
 }, async ({ thought }) => {
     const toolName = 'think';
     logToolCall(toolName);
     try {
+        // Basic validation: Check if it's non-empty and maybe contains expected markers
         if (thought.trim().length === 0) {
-            throw new Error('Invalid thought: Must be a non-empty string containing substantive reasoning, following the prompted structure.');
+            throw new Error('Invalid thought: Must be a non-empty string.');
+        }
+        if (!thought.includes("## Observe:") || !thought.includes("## Orient:") || !thought.includes("## Decide:") || !thought.includes("## Reason:") || !thought.includes("## Act (Plan):")) {
+            throw new Error('Invalid thought structure: Must contain required OODReAct sections (Observe, Orient, Decide, Reason, Act(Plan)).');
         }
-        logToolResult(toolName, true, `Thought logged (length: ${thought.length})`);
+        logToolResult(toolName, true, `Deliberation logged (length: ${thought.length})`);
         console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${thought}`);
+        // Return the thought process itself as the result
         return {
             content: [{
                     type: "text",
@@ -138,13 +146,16 @@ server.tool("think", "**Central Hub for Analysis, Planning & Reasoning.** Use th
     }
 });
 /**
- * Tool: quick_think
- * Purpose: A minimal cognitive step for trivial actions or confirmations.
- * Workflow: Use ONLY for acknowledging *trivial* successes, simple variable passing, or confirming *immediately obvious* next steps where NO analysis, planning, policy check, or complex reasoning (handled by `think`) is needed. Use sparingly; prefer `think` for analyzing any tool output, error, or planning non-trivial actions.
+ * Tool: quick_think (Minimal Cognitive Step - Use With Extreme Caution)
+ * Purpose: A minimal cognitive step ONLY for acknowledging *trivial*, *immediately obvious* successes or state transitions.
+ * Workflow: **STRONGLY DISCOURAGED.** Use ONLY if the mandatory deliberation cycle (`think` or internal) is genuinely unnecessary
+ * because the situation involves absolutely no analysis, planning, policy check, error handling, or complex reasoning.
+ * Example: Confirming receipt of simple data before an already-planned trivial action.
+ * **DO NOT USE** after most tool calls, CodeAct executions, or before any complex action - use `think` instead.
  * Output: Returns the brief thought text, formatted as Markdown.
  */
-server.tool("quick_think", "**Minimal Cognitive Step (Use Sparingly!).** Use ONLY for acknowledging *trivial* successes or confirming *obvious* next steps where NO analysis, planning, or policy check is needed (e.g., 'Action X succeeded, proceeding to Y'). All substantive analysis, error handling, planning, and reasoning (CoT/CoD) belongs in the `think` tool. Prefer `think` after most tool calls or before complex actions.", {
-    brief_thought: z.string().describe("Your **extremely concise** confirmation or trivial thought (e.g., 'Tool success, continue', 'Passing ID to next step'). Must be non-empty but very short. Do NOT use for analysis or planning.")
+server.tool("quick_think", "**(Use Sparingly/Discouraged) Minimal Cognitive Step.** Use ONLY for acknowledging *trivial successes* or confirming *obvious, pre-planned* simple steps where NO analysis/planning/policy check is needed (e.g., 'Data received, proceeding with planned step X'). **The mandatory deliberation cycle (`think` tool or internal) is required for almost all situations.** Prefer `think` after any tool/CodeAct output or error.", {
+    brief_thought: z.string().describe("Your **extremely concise** confirmation for a truly trivial step (e.g., 'Trivial action X succeeded'). Must be non-empty but very short. DO NOT use for analysis, planning, error reflection, or complex reasoning - use the `think` tool for the mandatory deliberation cycle.")
 }, async ({ brief_thought }) => {
     const toolName = 'quick_think';
     logToolCall(toolName);
@@ -152,12 +163,13 @@ server.tool("quick_think", "**Minimal Cognitive Step (Use Sparingly!).** Use ONL
         if (brief_thought.trim().length === 0) {
             throw new Error('Invalid brief_thought: Must be a non-empty string.');
         }
-        // Optional: Add a length check if you want to enforce brevity strictly
-        // if (brief_thought.length > 100) { // Example limit
-        // 	throw new Error('Invalid brief_thought: Input is too long for quick_think. Use think tool for detailed reasoning.');
-        // }
+        // Optional stricter length check to enforce brevity
+        if (brief_thought.length > 150) { // Example limit
+            console.error(`[${new Date().toISOString()}] [MCP Server] WARNING: 'quick_think' input is long. Ensure 'think' wasn't more appropriate.`);
+        }
         logToolResult(toolName, true, `Logged: ${brief_thought.substring(0, 80)}...`);
         console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${brief_thought}`);
+        // Return the brief thought
         return {
             content: [{
                     type: "text",
@@ -170,7 +182,6 @@ server.tool("quick_think", "**Minimal Cognitive Step (Use Sparingly!).** Use ONL
     }
 });
 // --- Server Lifecycle and Error Handling ---
-// [Keep existing shutdown, process event handlers, main function]
 /**
  * Gracefully shuts down the server.
  */
@@ -186,19 +197,19 @@ async function shutdown() {
         process.exit(1);
     }
 }
+// Setup signal handlers
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
+// Setup global error handlers
 process.on('uncaughtException', (error, origin) => {
     const timestamp = new Date().toISOString();
     console.error(`[${timestamp}] [MCP Server] FATAL: Uncaught Exception at: ${origin}`, error);
-    // Attempt graceful shutdown, but exit quickly if it fails
-    shutdown().catch(() => process.exit(1));
+    shutdown().catch(() => process.exit(1)); // Attempt graceful shutdown
 });
 process.on('unhandledRejection', (reason, promise) => {
     const timestamp = new Date().toISOString();
     console.error(`[${timestamp}] [MCP Server] FATAL: Unhandled Promise Rejection:`, reason);
-    // Attempt graceful shutdown, but exit quickly if it fails
-    shutdown().catch(() => process.exit(1));
+    shutdown().catch(() => process.exit(1)); // Attempt graceful shutdown
 });
 // --- Start the Server ---
 /**
@@ -208,10 +219,11 @@ async function main() {
     try {
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        const border = '-----------------------------------------------------';
+        const border = '=====================================================';
         console.error(border);
         console.error(` ${serverInfo.description}`);
         console.error(` Version: ${serverInfo.version}`);
+        console.error(` Aligned with Gikendaasowin v7 Agentic Guidelines`);
         console.error(' Status: Running on stdio, awaiting MCP requests...');
         console.error(border);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nbiish/cognitive-tools-mcp",
-  "version": "0.9.30",
+  "version": "2.0.1",
   "description": "Cognitive Tools MCP: SOTA reasoning suite focused on iterative refinement and tool integration for AI Pair Programming. Enables structured, iterative problem-solving through Chain of Draft methodology, with tools for draft generation, analysis, and refinement. Features advanced deliberation (`think`), rapid checks (`quick_think`), mandatory complexity assessment & thought mode selection (`assess_cuc_n_mode`), context synthesis, confidence gauging, proactive planning, explicit reasoning (CoT), and reflection with content return. Alternative package name for gikendaasowin-aabajichiganan-mcp.",
   "private": false,
   "type": "module",