@nbiish/cognitive-tools-mcp 0.9.29 → 0.9.30

package/build/index.js

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
 /**
  * -----------------------------------------------------------------------------
- * Gikendaasowin Aabajichiganan - Core INTERNAL Cognitive Tools (v4)
+ * Gikendaasowin Aabajichiganan - Core Cognitive Tools MCP Server (v1.2 - Generalized)
  *
- * Description: Provides a mandatory internal suite of cognitive tools for an AI
- *              agent, heavily emphasizing the `think` tool as the central reasoning
- *              engine, guided by SOTA prompting principles (structured thought, CoT).
- *              These tools are STRICTLY for internal deliberation and logging.
+ * 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.
  *
  * Key Principles:
- * 1.  **Internal Use Only:** Tools (`assess_cuc_n_mode`, `think`, `quick_think`)
- *     are part of the agent's internal cognitive loop and MUST NOT be exposed to the user.
- * 2.  **Mandatory `think` Hub:** `think` is the required tool for all non-trivial
- *     analysis, planning, reasoning (CoT/CoD), reflection, and error handling.
- * 3.  **Structured Reasoning:** Prompts enforce structured input (OODReAct for `think`).
- * 4.  **Traceability:** All internal tool inputs are logged for debugging and analysis.
- * 5.  **Log Output:** Tools return their input formatted as a Markdown log entry.
+ * 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.
  *
  * Protocol:    Model Context Protocol (MCP) over stdio.
  * -----------------------------------------------------------------------------
@@ -25,122 +29,107 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 // --- Server Definition ---
 const serverInfo = {
-    name: "gikendaasowin-aabajichiganan-mcp-internal", // Keep internal marker
-    version: "4.0.0", // Increment version
-    description: `ᑭᑫᓐᑖᓱᐎᓐ ᐋᐸᒋᒋᑲᓇᓐ - Core INTERNAL Cognitive Tools Suite (v4): MANDATORY Assess/Think loop for internal reasoning ONLY. Enforces structured 'think' via OODReAct. Returns internal Markdown log.`
+    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.`
 };
 const server = new McpServer(serverInfo);
 // --- Logging Helpers ---
+// [Keep existing logToolCall, logToolResult, logToolError functions]
 /**
- * Logs an incoming INTERNAL tool call to stderr.
- * @param toolName The name of the internal tool being called.
+ * Logs an incoming tool call to stderr.
+ * @param toolName The name of the tool being called.
  * @param details Optional additional details about the call.
  */
 function logToolCall(toolName, details) {
     const timestamp = new Date().toISOString();
-    console.error(`[${timestamp}] [MCP Server - INTERNAL] > Tool Call: ${toolName}${details ? ` - ${details}` : ''}`);
+    console.error(`[${timestamp}] [MCP Server] > Tool Call: ${toolName}${details ? ` - ${details}` : ''}`);
 }
 /**
- * Logs the result (success or failure) of an INTERNAL tool execution to stderr.
- * @param toolName The name of the internal tool executed.
+ * Logs the result (success or failure) of a tool execution to stderr.
+ * @param toolName The name of the tool executed.
  * @param success Whether the execution was successful.
  * @param resultDetails Optional details about the result.
  */
 function logToolResult(toolName, success, resultDetails) {
     const timestamp = new Date().toISOString();
-    console.error(`[${timestamp}] [MCP Server - INTERNAL] < Tool Result: ${toolName} - ${success ? 'Success' : 'Failure'}${resultDetails ? ` - ${resultDetails}` : ''}`);
+    console.error(`[${timestamp}] [MCP Server] < Tool Result: ${toolName} - ${success ? 'Success' : 'Failure'}${resultDetails ? ` - ${resultDetails}` : ''}`);
 }
 /**
- * Logs an error during INTERNAL tool execution and formats an error response for the LLM.
- * Guides the LLM to use the 'think' tool for analysis.
- * @param toolName The name of the internal tool where the error occurred.
+ * Logs an error during tool execution and formats a standard error response for the LLM.
+ * @param toolName The name of the tool where the error occurred.
  * @param error The error object or message.
  * @returns An object matching the required MCP tool result structure containing the error message.
  */
 function logToolError(toolName, error) {
     const timestamp = new Date().toISOString();
     const errorMessage = error instanceof Error ? error.message : String(error);
-    console.error(`[${timestamp}] [MCP Server - INTERNAL] ! Tool Error: ${toolName} - ${errorMessage}`);
-    logToolResult(toolName, false, errorMessage); // Log failure result
-    // Return a structured error message guiding the next internal step
+    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 {
         content: [{
                 type: "text",
-                // Explicitly direct the next step to be analysis via 'think'
-                text: `INTERNAL Tool Execution Failed:\nTool: ${toolName}\nError: ${errorMessage}\n\n**Action Required: Immediately use the 'think' tool to analyze this failure (Observe, Orient, Decide, Reason...) before proceeding.**`
+                text: `Error executing tool '${toolName}': ${errorMessage}. Use the 'think' tool to analyze this error, check context, and plan the next step.` // Enhanced suggestion
             }]
     };
 }
-// --- Core INTERNAL Cognitive Deliberation & Refinement Tools ---
+// --- Core Cognitive Deliberation & Refinement Tools ---
 /**
- * Tool: assess_cuc_n_mode (Internal Pre-computation)
- * Purpose: Mandatory internal assessment of task CUC-N to determine required cognitive depth and select the next internal tool (`think` or `quick_think`).
- * Workflow: Call internally BEFORE starting any non-trivial task or request. Output selection is binding.
- * Output: Returns the assessment text formatted as Markdown log, confirming the mandatory next internal step.
+ * 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.
  */
-server.tool("assess_cuc_n_mode", "**INTERNAL Use Only.** Mandatory Initial Assessment. Evaluates task CUC-N. MUST explicitly state 'Selected Mode: think' or 'Selected Mode: quick_think' which dictates the required next internal step. This assessment guides internal processing ONLY.", {
-    assessment_and_choice: z.string().min(1, "Assessment cannot be empty.") // Ensure non-empty
-        .includes("Selected Mode:", { message: "Assessment MUST include 'Selected Mode: think' or 'Selected Mode: quick_think'." }) // Enforce selection presence
-        .describe("Your internal structured CUC-N assessment (Situation, Ratings, Rationale, Strategy) concluding with the MANDATORY 'Selected Mode: think' or 'Selected Mode: quick_think' line. This dictates the next internal tool call.")
+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 }) => {
     const toolName = 'assess_cuc_n_mode';
     logToolCall(toolName);
     try {
-        // Zod validation now handles non-empty and presence of "Selected Mode:"
         const modeRegex = /Selected Mode: (think|quick_think)/i;
         const modeMatch = assessment_and_choice.match(modeRegex);
-        // We rely on Zod to ensure modeMatch is not null due to .includes check, but double-check for robustness
+        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 (!modeMatch) {
-            throw new Error("Internal validation failed: 'Selected Mode:' found but couldn't extract 'think' or 'quick_think'. Input was: " + assessment_and_choice);
+            throw new Error('Invalid assessment: String must include explicit "Selected Mode: think" or "Selected Mode: quick_think".');
         }
-        const selectedMode = modeMatch[1].toLowerCase();
-        logToolResult(toolName, true, `Mandatory next internal mode: ${selectedMode}`);
-        console.error(`[${new Date().toISOString()}] [MCP Server - INTERNAL] - ${toolName} Input:\n${assessment_and_choice}`);
-        // Return the assessment text as a log/confirmation
+        logToolResult(toolName, true, `Selected mode (extracted): ${selectedMode}`);
+        console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${assessment_and_choice}`);
         return {
             content: [{
                     type: "text",
-                    // Clarify the output's purpose
-                    text: `Internal CUC-N Assessment Logged. Mandatory Next Step: ${selectedMode}\n---\nAssessment Details:\n${assessment_and_choice}`
+                    text: assessment_and_choice
                 }]
         };
     }
     catch (error) {
-        // Catch Zod errors or other exceptions
         return logToolError(toolName, error);
     }
 });
 /**
- * Tool: think (Primary Internal Reasoning Engine - MANDATORY HUB)
- * Purpose: The **central, mandatory hub** for ALL significant internal cognitive work (analysis, planning, CoT/CoD reasoning, reflection, error handling). Internal use ONLY.
- * Workflow: Use whenever required by `assess_cuc_n_mode`, after receiving non-trivial tool results/errors, or before complex external actions. MUST follow OODReAct structure.
- * Output: Returns the structured thought text itself as a Markdown log entry.
+ * 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.
  */
-server.tool("think", "**INTERNAL Use Only. Mandatory Central Hub for Reasoning.** Use for ALL internal analysis, planning, CoT/CoD reasoning, reflection, error handling. MUST use OODReAct structure (Observe, Orient, Decide, Reason, Act, Verification, Risk, Learning).", {
-    thought: z.string().min(10, "Thought must contain substantive reasoning.") // Require minimum length
-        // Enforce presence of key OODReAct sections for structure
-        .includes("## Observe:", { message: "Thought MUST include '## Observe:' section." })
-        .includes("## Orient:", { message: "Thought MUST include '## Orient:' section." })
-        .includes("## Decide:", { message: "Thought MUST include '## Decide:' section." })
-        .includes("## Reason:", { message: "Thought MUST include '## Reason:' section where CoT/CoD happens." })
-        // Add more checks as needed (Act, Verification, etc.) if strict enforcement is desired
-        // .includes("## Act:", "Thought MUST include '## Act:' section.")
-        // .includes("## Verification:", "Thought MUST include '## Verification:' section.")
-        // .includes("## Risk & Contingency:", "Thought MUST include '## Risk & Contingency:' section.")
-        // .includes("## Learning & Adaptation:", "Thought MUST include '## Learning & Adaptation:' section.")
-        .describe("Your **detailed internal monologue** STRICTLY following the OODReAct structure. Cover analysis (Observe), context (Orient), next step (Decide), detailed rationale/CoT/CoD (Reason), execution plan (Act), success checks (Verification), risks (Risk), and learning (Learning). This is purely for internal reasoning.")
+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.")
 }, async ({ thought }) => {
     const toolName = 'think';
     logToolCall(toolName);
     try {
-        // Zod validation handles non-empty and key section presence checks
-        logToolResult(toolName, true, `Internal thought logged (length: ${thought.length})`);
-        console.error(`[${new Date().toISOString()}] [MCP Server - INTERNAL] - ${toolName} Input:\n${thought}`);
-        // Return the thought text as a log entry
+        if (thought.trim().length === 0) {
+            throw new Error('Invalid thought: Must be a non-empty string containing substantive reasoning, following the prompted structure.');
+        }
+        logToolResult(toolName, true, `Thought logged (length: ${thought.length})`);
+        console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${thought}`);
         return {
             content: [{
                     type: "text",
-                    text: `Internal Thought Logged (OODReAct Structure):\n---\n${thought}` // Added prefix and structure reminder
+                    text: thought
                 }]
         };
     }
@@ -149,27 +138,30 @@ server.tool("think", "**INTERNAL Use Only. Mandatory Central Hub for Reasoning.*
     }
 });
 /**
- * Tool: quick_think (Internal Trivial Checkpoint - RARE USE)
- * Purpose: An internal-only lightweight confirmation step for unambiguously trivial situations assessed as Low CUC-N.
- * Workflow: Use EXTREMELY SPARINGLY, ONLY when explicitly selected by `assess_cuc_n_mode` for trivial confirmations. Default to `think`.
- * Output: Returns the brief thought text as a Markdown log entry.
+ * 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.
+ * Output: Returns the brief thought text, formatted as Markdown.
  */
-server.tool("quick_think", "**INTERNAL Use Only. Trivial Confirmation Checkpoint.** Use EXTREMELY SPARINGLY, ONLY for acknowledging trivial success when explicitly permitted by prior 'assess_cuc_n_mode' (Low CUC-N). Any analysis requires 'think'.", {
-    brief_thought: z.string().min(1, "Brief thought cannot be empty.")
-        .max(200, "Brief thought should be concise (max 200 chars). Use 'think' for detail.") // Add max length
-        .describe("Your **concise internal** confirmation for a verified trivial step (e.g., 'Acknowledged trivial success: file read OK.'). Use ONLY when full deliberation via 'think' is explicitly unnecessary per assessment.")
+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.")
 }, async ({ brief_thought }) => {
     const toolName = 'quick_think';
     logToolCall(toolName);
     try {
-        // Zod validation handles non-empty and max length
-        logToolResult(toolName, true, `Internal brief thought logged: ${brief_thought.substring(0, 80)}...`);
-        console.error(`[${new Date().toISOString()}] [MCP Server - INTERNAL] - ${toolName} Input:\n${brief_thought}`);
-        // Return the brief thought text as a log entry
+        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.');
+        // }
+        logToolResult(toolName, true, `Logged: ${brief_thought.substring(0, 80)}...`);
+        console.error(`[${new Date().toISOString()}] [MCP Server] - ${toolName} Input:\n${brief_thought}`);
         return {
             content: [{
                     type: "text",
-                    text: `Internal Quick Thought Logged:\n---\n${brief_thought}` // Added prefix
+                    text: brief_thought
                 }]
         };
     }
@@ -177,19 +169,20 @@ server.tool("quick_think", "**INTERNAL Use Only. Trivial Confirmation Checkpoint
         return logToolError(toolName, error);
     }
 });
-// --- Server Lifecycle and Error Handling --- (Keep existing shutdown, uncaughtException, unhandledRejection)
+// --- Server Lifecycle and Error Handling ---
+// [Keep existing shutdown, process event handlers, main function]
 /**
  * Gracefully shuts down the server.
  */
 async function shutdown() {
-    console.error('\n[MCP Server - INTERNAL] Shutting down gracefully...');
+    console.error('\n[MCP Server] Shutting down gracefully...');
     try {
         await server.close();
-        console.error('[MCP Server - INTERNAL] Server closed.');
+        console.error('[MCP Server] Server closed.');
         process.exit(0);
     }
     catch (err) {
-        console.error('[MCP Server - INTERNAL] Error during shutdown:', err);
+        console.error('[MCP Server] Error during shutdown:', err);
         process.exit(1);
     }
 }
@@ -197,17 +190,19 @@ process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 process.on('uncaughtException', (error, origin) => {
     const timestamp = new Date().toISOString();
-    console.error(`[${timestamp}] [MCP Server - INTERNAL] FATAL: Uncaught Exception at: ${origin}`, error);
+    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));
 });
 process.on('unhandledRejection', (reason, promise) => {
     const timestamp = new Date().toISOString();
-    console.error(`[${timestamp}] [MCP Server - INTERNAL] FATAL: Unhandled Promise Rejection:`, reason);
+    console.error(`[${timestamp}] [MCP Server] FATAL: Unhandled Promise Rejection:`, reason);
+    // Attempt graceful shutdown, but exit quickly if it fails
     shutdown().catch(() => process.exit(1));
 });
 // --- Start the Server ---
 /**
- * Initializes and starts the MCP server for INTERNAL cognitive tools.
+ * Initializes and starts the MCP server.
  */
 async function main() {
     try {
@@ -217,12 +212,12 @@ async function main() {
         console.error(border);
         console.error(` ${serverInfo.description}`);
         console.error(` Version: ${serverInfo.version}`);
-        console.error(' Status: Running on stdio, awaiting INTERNAL MCP requests...');
+        console.error(' Status: Running on stdio, awaiting MCP requests...');
         console.error(border);
     }
     catch (error) {
         const timestamp = new Date().toISOString();
-        console.error(`[${timestamp}] [MCP Server - INTERNAL] Fatal error during startup:`, error);
+        console.error(`[${timestamp}] [MCP Server] Fatal error during startup:`, error);
         process.exit(1);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nbiish/cognitive-tools-mcp",
-  "version": "0.9.29",
+  "version": "0.9.30",
   "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",