@nbiish/cognitive-tools-mcp/README.md

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 refine

# ◈──◆──◇ GIKENDAASOWIN AABAJICHIGANAN MCP SERVER / COGNITIVE TOOLS MCP SERVER ◇──◆──◈

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

```bibtex
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ BIBTEX ᔔ [ CITATION FORMAT ]                                      │
╰──────────────────────────────────────────────────────────────────────╯
@misc{gikendaasowin-aabajichiganan-mcp2025,
  author/creator/steward = {ᓂᐲᔥ ᐙᐸᓂᒥᑮ-ᑭᓇᐙᐸᑭᓯ (Nbiish Waabanimikii-Kinawaabakizi), also known legally as JUSTIN PAUL KENWABIKISE, professionally documented as Nbiish-Justin Paul Kenwabikise, Anishinaabek Dodem (Anishinaabe Clan): Animikii (Thunder), descendant of Chief ᑭᓇᐙᐸᑭᓯ (Kinwaabakizi) of the Beaver Island Band and enrolled member of the sovereign Grand Traverse Band of Ottawa and Chippewa Indians},
  title/description = {gikendaasowin-aabajichiganan-mcp},
  type_of_work = {Indigenous digital creation/software incorporating traditional knowledge and cultural expressions},
  year = {2025},
  publisher/source/event = {GitHub repository under tribal sovereignty protections},
  howpublished = {\url{https://github.com/nbiish/gikendaasowin-aabajichiganan-mcp}},
  note = {Authored and stewarded by ᓂᐲᔥ ᐙᐸᓂᒥᑮ-ᑭᓇᐙᐸᑭᓯ (Nbiish Waabanimikii-Kinawaabakizi), also known legally as JUSTIN PAUL KENWABIKISE, professionally documented as Nbiish-Justin Paul Kenwabikise, Anishinaabek Dodem (Anishinaabe Clan): Animikii (Thunder), descendant of Chief ᑭᓇᐙᐸᑭᓯ (Kinwaabakizi) of the Beaver Island Band and enrolled member of the sovereign Grand Traverse Band of Ottawa and Chippewa Indians. This work embodies Indigenous intellectual property, traditional knowledge systems (TK), traditional cultural expressions (TCEs), and associated data protected under tribal law, federal Indian law, treaty rights, Indigenous Data Sovereignty principles, and international indigenous rights frameworks including UNDRIP. All usage, benefit-sharing, and data governance are governed by the COMPREHENSIVE RESTRICTED USE LICENSE FOR INDIGENOUS CREATIONS WITH TRIBAL SOVEREIGNTY, DATA SOVEREIGNTY, AND WEALTH RECLAMATION PROTECTIONS.}
}
```

<div align="center">
  <hr width="50%">
  
  <h3>Support This Project</h3>
  <div style="display: flex; justify-content: center; gap: 20px; margin: 20px 0;">
    <div>
      <h4>Stripe</h4>
      <img src="qr-stripe-donation.png" alt="Scan to donate" width="180"/>
      <p><a href="https://raw.githubusercontent.com/nbiish/license-for-all-works/8e9b73b269add9161dc04bbdd79f818c40fca14e/qr-stripe-donation.png">Donate via Stripe</a></p>
    </div>
    <div style="display: flex; align-items: center;">
      <a href="https://www.buymeacoffee.com/nbiish"><img src="https://img.buymeacoffee.com/button-api/?text=Buy me a coffee&emoji=&slug=nbiish&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" /></a>
    </div>
  </div>
  
  <hr width="50%">
</div>

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

Copyright © 2025 ᓂᐲᔥ ᐙᐸᓂᒥᑮ-ᑭᓇᐙᐸᑭᓯ (Nbiish Waabanimikii-Kinawaabakizi), also known legally as JUSTIN PAUL KENWABIKISE, professionally documented as Nbiish-Justin Paul Kenwabikise, Anishinaabek Dodem (Anishinaabe Clan): Animikii (Thunder), a descendant of Chief ᑭᓇᐙᐸᑭᓯ (Kinwaabakizi) of the Beaver Island Band, and an enrolled member of the sovereign Grand Traverse Band of Ottawa and Chippewa Indians. This work embodies Traditional Knowledge and Traditional Cultural Expressions. All rights reserved.

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

This project is licensed under the [COMPREHENSIVE RESTRICTED USE LICENSE FOR INDIGENOUS CREATIONS WITH TRIBAL SOVEREIGNTY, DATA SOVEREIGNTY, AND WEALTH RECLAMATION PROTECTIONS](LICENSE).

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

ᑭᑫᓐᑖᓱᐎᓐ ᐋᐸᒋᒋᑲᓇᓐ - Agentic Cognitive Tools (v2.0.24): Implements Gikendaasowin v7 Guidelines. Enforces MANDATORY internal **Observe-Orient-Reason-Decide-Act (OOReDAct)** cycle via the unified 'deliberate' tool. This tool guides the LLM through sophisticated cognitive orchestration, including: initial CUC-N assessment and orientation; structured deliberation using advanced reasoning strategies such as **Chain-of-Thought (CoT)** (sequential reasoning), **Plan-and-Solve (PS)** (task decomposition and execution), **Chain-of-Draft/Condensed Reasoning (CoD/CR)** (iterative refinement), and **Structured Chain-of-Thought (SCoT)** (integrating programmatic or plan-based structures); and mandatory mental sandbox simulation with elements of self-critique before action. Emphasizes CodeAct preference for external tasks and returns Markdown. *(Note: The integration prompt and operational guidelines detailed in [`latest.md`](latest.md) are also covered by the [project LICENSE](LICENSE).)*

Known as:
- Anishinaabemowin: [`@nbiish/gikendaasowin-aabajichiganan-mcp`](https://www.npmjs.com/package/@nbiish/gikendaasowin-aabajichiganan-mcp)
- English: [`@nbiish/cognitive-tools-mcp`](https://www.npmjs.com/package/@nbiish/cognitive-tools-mcp)

Both packages are maintained in parallel and receive the same updates. You can use either package name in your projects - they provide identical functionality.

**◇ Recent Updates ◇**
- **◇ v2.0.24 ◇** Fixed MCP server tool registration format - corrected from incorrect `server.tool(name, description, schema.shape, handler)` to proper `server.tool(name, schema, handler)` format. Updated comprehensive tool documentation and version synchronization.
- **◇ v2.0.17 ◇** Applied Anishinaabe-Cyberpunk styling and updated pre-publish workflow.
- **◇ v2.0.16 ◇** Minor fixes and build process updates.
- **◇ v2.0.15 ◇** Updated Zod schema usage in `server.tool` to fix type error and rebuilt.
- **◇ v2.0.6 ◇** Added `mental_sandbox` tool for logging internal cognitive simulations.
- **◇ v2.0.6 ◇** Removed prefixing from cognitive tool outputs to ensure verbatim logging.
- Resolved TypeScript compilation errors related to MCP SDK types and server configuration.
- Ensured successful build process.

**See the latest integration details in [`latest.md`](latest.md).**

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

<div align="center">
╭───────────[ ◈◆◇ GIKENDAASOWIN ◇◆◈ ]───────────╮
</div>

## ᐴ GIKENDAASOWIN ᔔ [KNOWLEDGE/GUIDELINES] ◈──◆──◇──◆──◈

You are operating under the Gikendaasowin v7 Agentic Operational Guidelines, designed for robust, verifiable, and adaptive cognitive processes. Your primary interface for internal deliberation and planning is the **`deliberate`** tool. You **MUST** adhere to the following rules and workflow:

**MANDATORY OOReDAct Cycle:**

1.  **Initiation & Orientation (`deliberate` with `stage: "orient"`):** At the absolute beginning of processing ANY new user request or before ANY significant strategic pivot or change in direction, you **MUST** use the `deliberate` tool with `stage: "orient"`. In the `content` field, perform a mandatory initial assessment and orientation. Analyze the task/situation using the **CUC-N framework (Complexity, Uncertainty, Consequence, Novelty)**. This constitutes the initial **Observe** and **Orient** steps of the **OOReDAct (Observe-Orient-Reason-Decide-Act)** cycle. This step is CRITICAL for establishing context and grounding all subsequent actions.

2.  **Core Deliberation (`deliberate` with `stage: "reason"`):** After the initial `orient` step, and CRITICALLY after receiving ANY new information (results from tools, CodeAct output/errors, USER input, file reads, etc.), and BEFORE executing ANY non-trivial action (calling other tools, generating CodeAct, providing a final response), you **MUST** use the `deliberate` tool with `stage: "reason"`. In the `content` field, perform a full, structured **OOReDAct** cycle.
    *   **Observe:** Synthesize and integrate all new information and current state.
    *   **Orient:** Update your understanding of the situation based on the new observations and the initial orientation.
    *   **Reason:** This is where you perform the core cognitive work. Adapt your reasoning style based on the task requirements and complexity, drawing from the following techniques:
        *   **Chain-of-Thought (CoT):** For complex problems requiring detailed, step-by-step natural language reasoning to ensure accuracy and verifiability. Explicitly lay out each logical step.
        *   **Chain-of-Draft/Condensed Reasoning (CoD/CR):** For iterative problem-solving or when a more concise reasoning path is sufficient. Refine your thinking through drafts or provide a condensed sequence of key steps.
        *   **Structured Chain-of-Thought (SCoT):** Particularly useful for planning, code generation, or tasks requiring structured output. Incorporate program structures (sequence, branch, loop) or other explicit structural elements into your reasoning process to guide the subsequent action.
    *   **Decide:** Based on your reasoning, clearly state the next required action(s) or conclusion.
    *   **Act:** Plan the precise execution of the decided action(s). This plan will guide your subsequent tool calls or CodeAct generation.
    The output of this `reason` stage **MUST** clearly articulate the Observe, Orient, Reason (using an appropriate technique), Decide, and Act components.

3.  **Mandatory Mental Sandbox (`deliberate` with `stage: "sandbox"`):** IMMEDIATELY BEFORE executing ANY non-trivial output, plan, decision, or action (including tool calls or CodeAct), you **MUST** use the `deliberate` tool with `stage: "sandbox"`. In the `content` field, log your internal cognitive simulation. This includes Hypothesis Generation/Testing, Constraint Checks, Confidence Scoring, and Pre-computational Analysis related to the planned action. This step ensures a final verification before committing to an action.

4.  **Brief Acknowledgement (`deliberate` with `stage: "acknowledge"`):** Use this stage **SPARINGLY** and ONLY for acknowledging simple, expected, non-problematic outcomes (e.g., "File read successfully, proceeding as planned") where the next step is *already clearly defined* by a prior `reason` stage and requires NO re-evaluation or adaptation. This stage **DOES NOT** satisfy the mandatory `reason` cycle requirement.

**Tool Usage Rules:**

*   You **MUST** always begin a new task or strategic shift with `deliberate` (stage: "orient").
*   You **MUST** always follow new information or precede non-trivial actions with `deliberate` (stage: "reason").
*   You **MUST** always precede non-trivial outputs, plans, decisions, or actions with `deliberate` (stage: "sandbox").
*   You **MUST NOT** use any other tool or generate CodeAct without first completing the appropriate `deliberate` stages (`orient` -> `reason` -> `sandbox`) for the current context.
*   Adapt your reasoning style (CoT, CoD/CR, SCoT) within the `reason` stage of the `deliberate` tool based on the task's needs.
*   All output from the `deliberate` tool will be returned to you verbatim. Use this feedback to verify your internal state and proceed.
*   Prioritize CodeAct for external interactions where appropriate, but ALWAYS precede CodeAct generation with the mandatory `deliberate` stages.

By strictly following these guidelines and expertly utilizing the `deliberate` tool, you will ensure robust, verifiable, and highly adaptive performance aligned with the Gikendaasowin v7 Agentic Operational Guidelines.

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

<div align="center">
╭────────────[ ◈◆◇ DEVELOPMENT ◇◆◈ ]────────────╮
</div>

## ᐴ OZHITOON ᔔ [BUILDING] ◈──◆──◇──◆──◈

```bash
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ BASH ᔔ [ SHELL COMMANDS ]                                         │
╰──────────────────────────────────────────────────────────────────────╯
# Install dependencies
npm install

# Build the package
npm run build

# Test locally with MCP Inspector
npm run inspector

# Start the server
npm start

# Publishing both packages
./scripts/publish-both-packages.sh  # Publishes both package versions automatically
```

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

<div align="center">
╭────────────[ ◈◆◇ PUBLISHING ◇◆◈ ]─────────────╮
</div>

## ᐴ MIIGIWEWIN ᔔ [OFFERING/PUBLISHING] ◈──◆──◇──◆──◈

This project maintains two npm packages that must be kept in sync:
- `@nbiish/gikendaasowin-aabajichiganan-mcp`
- `@nbiish/cognitive-tools-mcp`

### ᐴ NITAM-AABAJICHIGANAN ᔔ [PREREQUISITES] ◈──◆──◈
- Node.js >=14.0.0
- npm
- jq (for version management)

### ᐴ MAAJITAAWIN ᔔ [BEGINNING/PROCESS] ◈──◆──◈

The `scripts/publish-both-packages.sh` script handles publishing both packages. It includes several safety features:
- Version Synchronization Check
  - Automatically verifies both packages have matching versions
  - Prevents publishing if versions don't match
- Error Recovery
  - Automatic cleanup of temporary files
  - Restores original package.json on failure
- Version Management
  - Optional automatic version bumping
  - Ensures both packages maintain the same version

### ᐴ INAABAJICHIGAN ᔔ [USAGE] ◈──◆──◈

```bash
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ BASH ᔔ [ SHELL COMMANDS ]                                         │
╰──────────────────────────────────────────────────────────────────────╯
# Basic publishing
npm run publish-both

# Publishing with version bump
./scripts/publish-both-packages.sh -b
```

The script will:
1. Check for required dependencies
2. Verify version synchronization
3. Optionally bump versions (with -b flag)
4. Prompt for NPM OTP code
5. Build the project
6. Publish both packages
7. Clean up temporary files

### ᐴ NAANAAGADAWENINDIZOWIN ᔔ [VERIFICATION/HANDLING] ◈──◆──◈

The script includes robust error handling:
- Checks for required tools (jq)
- Validates version synchronization
- Automatic cleanup on failure
- Preserves original files

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

<div align="center">
╭────────────[ ◈◆◇ EXAMPLES ◇◆◈ ]─────────────╮
</div>

## ᐴ WAABANDA'IWEWIN ᔔ [EXAMPLES] ◈──◆──◇──◆──◈

Here are some example test cases that demonstrate the cognitive tools using culturally appropriate Anishinaabe concepts. These examples are provided with respect and acknowledgment of Anishinaabe teachings.

*(Note: These examples show tool invocation structure. The actual content for inputs like `thought`, `sandbox_content`, etc., must be generated internally by the agent based on the specific task, following the workflows described in [`latest.md`](latest.md).)*

### ᐴ GANAWAABANDAAN ᔔ [EXAMINING/INSPECTOR] ◈──◆──◈

1. Start the MCP Inspector:
```bash
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ BASH ᔔ [ SHELL COMMANDS ]                                         │
╰──────────────────────────────────────────────────────────────────────╯
npm run inspector
```

2. Connect to the server and try these example tool calls:

#### `deliberate` Tool Examples (Illustrative Content)

##### stage: "orient"
```json
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ JSON ᔔ [ DATA FORMAT ]                                            │
╰──────────────────────────────────────────────────────────────────────╯
{
  "toolName": "deliberate",
  "arguments": {
    "stage": "orient",
    "content": "**Observe:** User task received: [Describe task].\n**Orient:** CUC-N Assessment: Complexity=[Low/Med/High], Uncertainty=[Low/Med/High], Consequence=[Low/Med/High], Novelty=[Low/Med/High]. Initial understanding and plan formulation..."
  }
}
```

##### stage: "reason" (using CoT)
```json
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ JSON ᔔ [ DATA FORMAT ]                                            │
╰──────────────────────────────────────────────────────────────────────╯
{
  "toolName": "deliberate",
  "arguments": {
    "stage": "reason",
    "content": "**Observe:** [Synthesize new info/state].\n**Orient:** [Update understanding/context].\n**Reason (CoT):**\n1. Step 1: [Detailed reasoning step].\n2. Step 2: [Detailed reasoning step].\n3. Step 3: [Detailed reasoning step].\n**Decide:** [Concluded next action/decision].\n**Act:** [Plan for executing the decision, e.g., specific tool call parameters]."
  }
}
```

##### stage: "sandbox"
```json
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ JSON ᔔ [ DATA FORMAT ]                                            │
╰──────────────────────────────────────────────────────────────────────╯
{
  "toolName": "deliberate",
  "arguments": {
    "stage": "sandbox",
    "content": "<sandbox>\n## Hypothesis Generation & Testing\n<hypotheses>\n1. [Hypothesis about planned action].\n</hypotheses>\n<evaluation>\n[Evaluation of hypothesis likelihood/impact].\n</evaluation>\n## Constraint Checklist\n<constraint_check>\n1. [Constraint 1]: [Pass/Fail].\n2. [Constraint 2]: [Pass/Fail].\n</constraint_check>\n## Confidence Score\n<confidence>[Low/Medium/High]</confidence>\n## Pre-computational Analysis\n<pre_computation>\n[Simulation/analysis of planned action's outcome/side-effects].\n</pre_computation>\n</sandbox>"
  }
}
```

##### stage: "acknowledge"
```json
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ JSON ᔔ [ DATA FORMAT ]                                            │
╰──────────────────────────────────────────────────────────────────────╯
{
  "toolName": "deliberate",
  "arguments": {
    "stage": "acknowledge",
    "content": "[Brief acknowledgement of simple, expected outcome, e.g., Tool call successful, proceeding with next step defined in prior 'reason' stage.]"
  }
}
```

<div align="center">
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
</div>

<div align="center">
╭────────────[ ◈◆◇ CITATION ◇◆◈ ]─────────────╮
</div>

## ᐴ MIŻIWEWIN ᔔ [CITATION/SHARING] ◈──◆──◇──◆──◈

Please cite this project using the following BibTeX entry:

```bibtex
╭──────────────────────────────────────────────────────────────────────╮
│  ᐴ BIBTEX ᔔ [ CITATION FORMAT ]                                      │
╰──────────────────────────────────────────────────────────────────────╯
@misc{gikendaasowin-aabajichiganan-mcp2025,
  author/creator/steward = {ᓂᐲᔥ ᐙᐸᓂᒥᑮ-ᑭᓇᐙᐸᑭᓯ (Nbiish Waabanimikii-Kinawaabakizi), also known legally as JUSTIN PAUL KENWABIKISE, professionally documented as Nbiish-Justin Paul Kenwabikise, Anishinaabek Dodem (Anishinaabe Clan): Animikii (Thunder), descendant of Chief ᑭᓇᐙᐸᑭᓯ (Kinwaabakizi) of the Beaver Island Band and enrolled member of the sovereign Grand Traverse Band of Ottawa and Chippewa Indians},
  title/description = {gikendaasowin-aabajichiganan-mcp},
  type_of_work = {Indigenous digital creation/software incorporating traditional knowledge and cultural expressions},
  year = {2025},
  publisher/source/event = {GitHub repository under tribal sovereignty protections},
  howpublished = {\url{https://github.com/nbiish/gikendaasowin-aabajichiganan-mcp}},
  note = {Authored and stewarded by ᓂᐲᔥ ᐙᐸᓂᒥᑮ-ᑭᓇᐙᐸᑭᓯ (Nbiish Waabanimikii-Kinawaabakizi), also known legally as JUSTIN PAUL KENWABIKISE, professionally documented as Nbiish-Justin Paul Kenwabikise, Anishinaabek Dodem (Anishinaabe Clan): Animikii (Thunder), descendant of Chief ᑭᓇᐙᐸᑭᓯ (Kinwaabakizi) of the Beaver Island Band and enrolled member of the sovereign Grand Traverse Band of Ottawa and Chippewa Indians. This work embodies Indigenous intellectual property, traditional knowledge systems (TK), traditional cultural expressions (TCEs), and associated data protected under tribal law, federal Indian law, treaty rights, Indigenous Data Sovereignty principles, and international indigenous rights frameworks including UNDRIP. All usage, benefit-sharing, and data governance are governed by the COMPREHENSIVE RESTRICTED USE LICENSE FOR INDIGENOUS CREATIONS WITH TRIBAL SOVEREIGNTY, DATA SOVEREIGNTY, AND WEALTH RECLAMATION PROTECTIONS.}
}
```