@gotza02/mathinking 1.2.0 → 1.2.1

package/README.md

@@ -1,366 +1,113 @@
-# 🚀 Intelligent Agent MCP Server
+# 🧠 Mathinking MCP Server (The Brain & The Body)
 
-A powerful Model Context Protocol (MCP) server featuring two core capabilities:
-- **🧠 The Brain** (`sequential_thinking`) - Deep reasoning and planning
-- **🤖 The Body** (`orchestrator`) - Parallel task execution
+A powerful, autonomous Model Context Protocol (MCP) server that empowers AI agents with structured reasoning and real-world execution capabilities.
 
-## 📋 Overview
+- **🧠 The Brain** (`sequential_thinking`) - Deep iterative reasoning with persistent memory.
+- **🤖 The Body** (`orchestrator`) - Real-world task execution with parallel processing, conditional logic, and tool orchestration.
 
-This MCP server enables AI agents to:
-1. Think through complex problems step-by-step with branching and revision
-2. Execute multi-step task plans with parallel processing and dependency management
+## 🚀 Features
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Intelligent Agent Flow                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│   User Query → [sequential_thinking] → Plan → [orchestrator]    │
-│                      (Analysis)              (Execution)          │
-│                          ↓                        ↓               │
-│                   Thought Steps            Parallel Tasks         │
-│                   Branching/Revision       DAG Resolution         │
-│                   Hypothesis Testing       Result Aggregation     │
-│                          ↓                        ↓               │
-│                    Final Plan              Final Results          │
-│                                                                   │
-└─────────────────────────────────────────────────────────────────┘
-```
+### 🧠 The Brain (Sequential Thinking)
+- **Iterative Reasoning:** Think step-by-step with adjustable depth.
+- **Persistent Memory:** Sessions and thoughts are saved automatically to `~/.mathinking/sessions.json`.
+- **Branching & Revision:** Explore alternative paths and correct previous thoughts.
+- **Hypothesis Testing:** Formulate and verify theories with evidence.
 
-## 🛠️ Installation
+### 🤖 The Body (Orchestrator)
+- **Real-World Execution:**
+    - **Web Search:** Integrated search capabilities (Scraping/API).
+    - **Real Fetch:** Fetch real data from URLs (JSON/Text).
+    - **File System:** Read, write, and list local files and directories.
+    - **Shell Execute:** Run bash commands directly.
+- **Conditional Logic (`runIf`):** Tasks can run conditionally based on previous results (e.g., `"${task1.results.length} === 0"`).
+- **Parallel Processing:** Group independent tasks into layers for concurrent execution.
+- **Dependency Resolution:** Automatic DAG (Directed Acyclic Graph) management.
+- **Long-term Memory:** Save and query facts/preferences via `memory_save` and `memory_query`.
 
-```bash
-# Clone or create the project
-cd intelligent-agent-mcp
+---
 
-# Install dependencies
-npm install
+## 🛠️ Installation
 
-# Build TypeScript
-npm run build
+You can run Mathinking immediately without manual cloning using `npx`:
 
-# Run the server
-npm start
+```bash
+npx -y @gotza02/mathinking
 ```
 
+---
+
 ## ⚙️ Configuration
 
-Add to your MCP client configuration (e.g., Claude Desktop):
+### 1. Gemini CLI
+Add to your `~/.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
-    "intelligent-agent": {
-      "command": "node",
-      "args": ["/path/to/intelligent-agent-mcp/dist/index.js"]
+    "mathinking": {
+      "command": "npx",
+      "args": ["-y", "@gotza02/mathinking"],
+      "env": {
+        "BRAVE_SEARCH_API_KEY": "your_key_here"
+      }
     }
   }
 }
 ```
 
----
-
-## 🧠 Tool 1: Sequential Thinking (The Brain)
-
-A sophisticated reasoning system for complex problem-solving.
-
-### Features
-
-| Feature | Description |
-|---------|-------------|
-| **Iterative Thinking** | Step-by-step reasoning with adjustable depth |
-| **Dynamic Adjustment** | Modify thinking steps on-the-fly |
-| **Branching** | Explore alternative solution paths |
-| **Revision** | Correct previous thoughts when errors found |
-| **Hypothesis Testing** | Formulate and verify theories |
-| **Confidence Tracking** | Monitor certainty levels |
-
-### Actions
-
-| Action | Description | Required Params |
-|--------|-------------|-----------------|
-| `start_session` | Begin new thinking session | `problemStatement` |
-| `add_thought` | Add a reasoning step | `sessionId`, `thought` |
-| `create_branch` | Explore alternative | `sessionId`, `branchFromThoughtId` |
-| `revise_thought` | Correct previous thought | `sessionId`, `reviseThoughtId`, `thought` |
-| `set_hypothesis` | Propose testable theory | `sessionId`, `hypothesis` |
-| `verify_hypothesis` | Confirm/refute theory | `sessionId`, `verificationStatus` |
-| `adjust_total_thoughts` | Change thinking depth | `sessionId`, `totalThoughts` |
-| `conclude` | Synthesize final answer | `sessionId`, `thought` |
-| `get_status` | Check session progress | `sessionId` |
-| `get_history` | Review all thoughts | `sessionId` |
-
-### Example Usage
-
-```typescript
-// 1. Start a thinking session
-{
-  "action": "start_session",
-  "problemStatement": "Design a scalable microservices architecture for an e-commerce platform",
-  "totalThoughts": 6
-}
-
-// 2. Add initial analysis
-{
-  "action": "add_thought",
-  "sessionId": "abc-123",
-  "thought": "The core domains are: User Management, Product Catalog, Order Processing, Payment, and Inventory",
-  "thoughtType": "initial_analysis",
-  "confidence": 85
-}
-
-// 3. Set a hypothesis
-{
-  "action": "set_hypothesis",
-  "sessionId": "abc-123",
-  "hypothesis": "Event-driven architecture with Kafka will handle peak loads better than synchronous REST"
-}
-
-// 4. Create a branch to explore alternatives
-{
-  "action": "create_branch",
-  "sessionId": "abc-123",
-  "branchFromThoughtId": "thought-456",
-  "branchLabel": "Option B: GraphQL Federation",
-  "thought": "Alternative approach using GraphQL for unified API layer"
-}
-
-// 5. Verify the hypothesis
-{
-  "action": "verify_hypothesis",
-  "sessionId": "abc-123",
-  "verificationStatus": "verified",
-  "verificationEvidence": "Benchmark shows 3x throughput improvement under load"
-}
-
-// 6. Conclude
-{
-  "action": "conclude",
-  "sessionId": "abc-123",
-  "thought": "Recommended architecture: Event-driven microservices with Kafka, using CQRS pattern for read-heavy services",
-  "confidence": 90
-}
-```
-
----
-
-## 🤖 Tool 2: Orchestrator (The Body)
-
-A DAG-based execution engine for parallel task processing.
-
-### Features
-
-| Feature | Description |
-|---------|-------------|
-| **DAG Execution** | Topological sorting for dependency resolution |
-| **Parallel Processing** | Independent tasks run concurrently |
-| **Tool Chaining** | Reference outputs from previous tasks |
-| **Error Handling** | Graceful degradation with retries |
-| **Result Aggregation** | Combine all task outputs |
+### 2. Claude Desktop
+Add to your `claude_desktop_config.json`:
 
-### Built-in Tools
-
-| Tool | Description | Input |
-|------|-------------|-------|
-| `echo` | Returns input as-is | `{ any: "value" }` |
-| `delay` | Waits specified ms | `{ milliseconds: 1000 }` |
-| `transform` | Text/number transforms | `{ data: "text", operation: "uppercase" }` |
-| `aggregate` | Combine values | `{ values: [...], operation: "sum" }` |
-| `fetch` | HTTP request (simulated) | `{ url: "https://..." }` |
-| `compute` | Math expressions | `{ expression: "a + b", variables: { a: 1, b: 2 } }` |
-
-### Transform Operations
-- `uppercase` / `lowercase` / `reverse` / `length` / `double`
-
-### Aggregate Operations
-- `sum` / `concat` / `array` / `count`
-
-### Actions
-
-| Action | Description | Required Params |
-|--------|-------------|-----------------|
-| `validate_plan` | Check plan validity | `plan` |
-| `execute_plan` | Run the full plan | `plan` |
-| `get_execution_status` | Check previous results | `planId` |
-
-### Example: Parallel Data Processing
-
-```typescript
+```json
 {
-  "action": "execute_plan",
-  "plan": {
-    "planId": "data-pipeline-001",
-    "name": "Parallel Data Pipeline",
-    "tasks": [
-      {
-        "id": "fetch_users",
-        "name": "Fetch Users",
-        "toolName": "fetch",
-        "toolInput": { "url": "https://api.example.com/users" },
-        "dependencies": []
-      },
-      {
-        "id": "fetch_orders",
-        "name": "Fetch Orders",
-        "toolName": "fetch",
-        "toolInput": { "url": "https://api.example.com/orders" },
-        "dependencies": []
-      },
-      {
-        "id": "fetch_products",
-        "name": "Fetch Products",
-        "toolName": "fetch",
-        "toolInput": { "url": "https://api.example.com/products" },
-        "dependencies": []
-      },
-      {
-        "id": "transform_users",
-        "name": "Process Users",
-        "toolName": "transform",
-        "toolInput": { 
-          "data": "${fetch_users.body}", 
-          "operation": "uppercase" 
-        },
-        "dependencies": ["fetch_users"]
-      },
-      {
-        "id": "aggregate_all",
-        "name": "Combine Results",
-        "toolName": "aggregate",
-        "toolInput": { 
-          "values": [
-            "${fetch_users}",
-            "${fetch_orders}",
-            "${fetch_products}"
-          ],
-          "operation": "array"
-        },
-        "dependencies": ["fetch_users", "fetch_orders", "fetch_products"]
+  "mcpServers": {
+    "mathinking": {
+      "command": "npx",
+      "args": ["-y", "@gotza02/mathinking"],
+      "env": {
+        "BRAVE_SEARCH_API_KEY": "your_key_here"
       }
-    ]
+    }
   }
 }
 ```
 
-### Execution Visualization
-
-```
-┌─────────────────────────────────────────────────┐
-│           DAG Execution Visualization           │
-├─────────────────────────────────────────────────┤
-│ Layer 1 (Parallel):                             │
-│   ├── Fetch Users (no deps)                     │
-│   ├── Fetch Orders (no deps)                    │
-│   ├── Fetch Products (no deps)                  │
-│         ↓                                       │
-│ Layer 2 (Parallel):                             │
-│   ├── Process Users ← [fetch_users]             │
-│   ├── Combine Results ← [fetch_users, ...]      │
-└─────────────────────────────────────────────────┘
-```
-
 ---
 
-## 🔗 Integration Workflow
-
-The recommended pattern for complex tasks:
+## 🤖 Orchestrator Built-in Tools
 
-```
-1. User: "Analyze competitors and create a market report"
-
-2. AI calls sequential_thinking:
-   - start_session: "Analyze competitors and create market report"
-   - add_thought: "Need to gather data from multiple sources"
-   - add_thought: "Identify key competitors: A, B, C"
-   - set_hypothesis: "Competitor A leads in market share"
-   - add_thought: "Data sources: financial reports, social media, reviews"
-   - conclude: "Plan: Fetch data in parallel, then synthesize"
-
-3. AI creates execution plan from thinking output
-
-4. AI calls orchestrator:
-   - execute_plan with parallel fetch tasks
-   - Aggregate results
-   - Generate final report
-
-5. Return synthesized results to user
-```
+| Tool | Description | Input Examples |
+|------|-------------|-------|
+| `fetch` | Real HTTP request | `{ "url": "https://api.github.com/repos/..." }` |
+| `web_search` | Search the web | `{ "query": "latest news on MCP" }` |
+| `shell_execute` | Run bash commands | `{ "command": "ls -la" }` |
+| `read_file` | Read local file | `{ "path": "./config.json" }` |
+| `write_file` | Write local file | `{ "path": "notes.txt", "content": "hello" }` |
+| `memory_save` | Save fact to memory | `{ "key": "user_pref", "value": "likes rust" }` |
+| `memory_query` | Query memory | `{ "query": "preference" }` |
+| `compute` | Math evaluation | `{ "expression": "a * 2", "variables": { "a": 10 } }` |
+| `transform` | Text transforms | `uppercase`, `lowercase`, `reverse`, `length` |
+| `aggregate` | Combine results | `sum`, `concat`, `array`, `count` |
 
 ---
 
-## 📊 Error Handling
-
-### Sequential Thinking
-- Invalid sessions return helpful error messages
-- Unverified hypotheses block conclusion
-- Revision history maintained for audit
+## 💡 Advanced Example: Conditional Logic
 
-### Orchestrator
-- Failed tasks don't crash the pipeline
-- Retry support with configurable delays
-- Skipped tasks for unmet dependencies
-- Comprehensive error reporting
+You can define tasks that only run if a certain condition is met:
 
-```typescript
-// Example error response
+```json
 {
-  "success": false,
-  "status": "completed_with_errors",
-  "errors": [
-    {
-      "taskId": "fetch_data",
-      "taskName": "Fetch External Data",
-      "error": "Task timed out after 5000ms",
-      "timestamp": "2024-01-15T10:30:00Z"
-    }
-  ]
+  "id": "backup_plan",
+  "name": "Run if primary fails",
+  "toolName": "shell_execute",
+  "toolInput": { "command": "./fix_script.sh" },
+  "runIf": "${primary_task.status} === 'failed' || ${primary_task.data.length} === 0",
+  "dependencies": ["primary_task"]
 }
 ```
 
 ---
 
-## 🧪 Testing
-
-```bash
-# Run in development mode
-npm run dev
-
-# Build and run
-npm run build && npm start
-```
-
----
-
-## 📁 Project Structure
-
-```
-intelligent-agent-mcp/
-├── package.json
-├── tsconfig.json
-├── src/
-│   ├── index.ts              # MCP Server entry point
-│   ├── tools/
-│   │   ├── sequential-thinking.ts  # The Brain
-│   │   └── orchestrator.ts         # The Body
-│   ├── types/
-│   │   └── index.ts          # TypeScript interfaces
-│   └── utils/
-│       └── dag.ts            # DAG utilities
-└── README.md
-```
-
----
-
 ## 📜 License
 
-MIT
-
----
-
-## 🤝 Contributing
-
-Contributions welcome! Areas of interest:
-- Additional built-in tools for orchestrator
-- Persistent session storage for thinking
-- WebSocket transport support
-- Visualization dashboard
+MIT - Created by @gotza02

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotza02/mathinking",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "MCP Server with sequential thinking (The Brain) and orchestrator (The Body) capabilities",
   "type": "module",
   "main": "dist/index.js",