npm package: @gotza02/sequential-thinking
Description: MCP server for sequential thinking and problem solving (Extended with Web Search & Graph)
Author: Anthropic, PBC
Latest version: 10000.2.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @gotza02/sequential-thinking

**The Elite "Brain" for AI Agents.**
An advanced Model Context Protocol (MCP) server that equips AI with structured reasoning, web search capabilities, and safety protocols.

## 🚀 Features

### 🧠 Sequential Thinking Engine
Forces the AI to think before acting using a strict block-based flow:
- **Analysis:** Understand the problem deeply.
- **Planning:** Formulate a step-by-step plan.
- **Execution:** Perform actions (with tool support).
- **Observation:** Analyze results (Mandatory step).
- **Reflection:** Critique the outcome and adjust.

### 🛡️ Coding Safety Net (New!)
- **Auto-Backup:** Automatically creates `.bak` backups before modifying any file via `deep_code_edit`.
- **Destructive Action Protection:** Prevents accidental data loss during code refactoring.

### ⚽ Sports Intelligence (v10000.1.4+)
- **API Data Integration:** Direct API access for H2H, form, and odds (API-Football, Football-Data, SportsDB)
- **Smart Query Optimization:** Skips web search when API has data, assesses data quality (0-100 score)
- **Structured Output:** JSON analysis with probability ranges, value bets, and confidence scores
- **Uncertainty Quantification:** Probability ranges (e.g., 45% ± 10%) based on data quality
- **Value Detection:** Auto-detect value bets with Kelly Criterion stake recommendations
- **Adaptive Caching:** Dynamic TTL based on match timing (odds: 1-15 min, stats: 24 hours)
- **Dual-Source Deep Dive:** Simultaneously scrapes news (BBC, Sky) and stats (Understat, FBref)
- **Smart xG Extraction:** "Smart Extractor" for accurate Expected Goals data
- **Fallback Protection:** Intelligent warning system when API keys are missing

### 🌐 Web Search Integration
- Built-in support for **Exa**, **Brave**, **Google Search**, and **DuckDuckGo** (New!).
- Allows the AI to "pause and research" during the thinking process.

## 🛠️ Recent Updates (v10000.0.7+)

### 🔒 Security & Stability
- **Enhanced Shell Protection:** Blocks dangerous shell metacharacters and risky commands (e.g., `curl | sh`, `rm -rf`).
- **ReDoS Protection:** Validates regex patterns to prevent Denial of Service attacks.
- **Path Safety:** Strict path traversal checks to keep operations within the project root.
- **Resource Limits:** Enforces file size limits (10MB) for editing and parsing to prevent memory exhaustion.

### ⚡ Performance & Caching
- **Graph Caching:** Implemented intelligent caching for the Knowledge Graph (max 1000 files) to speed up analysis.
- **Rate Limiting:** Added request rate limiting for HTTP endpoints and search providers.
- **Auto-Cleanup:** Automatically manages backup files (keeps last 10) and prunes old thought history.

### ✨ New Capabilities
- **DuckDuckGo Support:** Added a no-API-key search provider fallback.
- **Graceful Shutdown:** Ensures data (thoughts, notes) is saved correctly when the server stops.
- **Enhanced API:** Improved `/health` endpoint with system stats and added pagination to `/api/notes`.

## 📦 Installation

```bash
npx -y @gotza02/sequential-thinking
```

## 🔧 Claude Code Configuration

Add to your `~/.claude/CLAUDE.md` or project-specific `.claude/CLAUDE.md`:

```json
{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@gotza02/sequential-thinking"],
      "env": {
        "BRAVE_API_KEY": "your_brave_key",
        "EXA_API_KEY": "your_exa_key",
        "API_FOOTBALL_KEY": "your_api_football_key"
      }
    }
  }
}
```

## 🛠️ Available MCP Tools

### 🧠 Thinking & Analysis Tools
| Tool | Description |
|------|-------------|
| `sequentialthinking` | Structured problem-solving with Analysis → Planning → Execution → Observation → Reflection |
| `analyze_football_match_v2` | Comprehensive football match analysis with API + web search |
| `analyze_football_match_structured` | JSON output match analysis with probabilities & value bets |
| `get_live_scores` | Live football scores with caching |
| `get_match_details` | Detailed match information by ID |

### ⚽ Sports Analysis Tools
| Tool | Description |
|------|-------------|
| `get_team_stats` | Team statistics and performance metrics |
| `compare_teams` | Head-to-head team comparison |
| `get_player_stats` | Player statistics and form |
| `odds_comparison` | Compare betting odds across markets |
| `value_bet_calculator` | Calculate Kelly Criterion & value bets |
| `track_prediction` | Log sports predictions for ROI tracking |
| `resolve_prediction` | Update prediction results |
| `analyze_roi` | Analyze betting performance statistics |

### 🔍 Search & Research Tools
| Tool | Description |
|------|-------------|
| `brave_web_search` | Web search via Brave Search API |
| `exa_web_search` | Neural web search via Exa API |
| `duckduckgo_search` | Anonymous web search (no API key) |
| `web_read` | Read and extract content from URLs |

### 💻 Code Management Tools
| Tool | Description |
|------|-------------|
| `deep_code_edit` | Structural code editing with auto-backup |
| `add_code_snippet` | Store reusable code patterns |
| `search_code` | Semantic code search |
| `get_project_graph` | Analyze codebase structure |

### 🧠 Intelligent Code Analysis (v10000.1.7+)
| Tool | Description |
|------|-------------|
| `intelligent_code_analyze` | AI-powered code analysis with quality scoring, metrics, and issue detection |
| `intelligent_impact_analysis` | Predict impact of code changes with risk scoring and affected files |
| `intelligent_semantic_search` | Search code by concept/meaning, not just text |
| `intelligent_refactor_suggest` | Get intelligent refactoring suggestions with code examples |
| `intelligent_code_compare` | Compare two code snippets or files with detailed diff analysis |
| `intelligent_code_autofix` | Auto-fix common issues (trailing whitespace, missing semicolons, optimize imports) |

### 📝 Knowledge & Notes Tools
| Tool | Description |
|------|-------------|
| `add_note` | Create and store notes |
| `search_notes` | Search through stored notes |
| `create_knowledge_node` | Add node to knowledge graph |
| `query_knowledge_graph` | Query relationships in knowledge graph |

### 👤 Human Interface Tools
| Tool | Description |
|------|-------------|
| `ask_human` | Request human input/clarification |
| `request_workflow_approval` | Get approval for multi-step workflows |

## 📋 System Instructions

**Quick Start:** Copy [`CLAUDE.md`](./CLAUDE.md) to your `~/.claude/CLAUDE.md` or project root.

## 🤖 System Instructions for Claude Code

Add this to your Claude Code settings for optimal use:

```markdown
SYSTEM INSTRUCTION: SmartAgent Elite Controller

You are an AI assistant with access to the Sequential Thinking MCP server.

CRITICAL DIRECTIVES:
1. ALWAYS use sequentialthinking tool for complex tasks
2. Use web search for up-to-date information (never hallucinate)
3. For sports analysis:
   - Use analyze_football_match_v2 for detailed text analysis
   - Use analyze_football_match_structured for JSON/probability data
   - Check value_bet_calculator for betting recommendations
4. Use deep_code_edit for structural code changes (creates backups)
5. For intelligent code analysis:
   - Use intelligent_code_analyze for quality scoring and metrics
   - Use intelligent_impact_analysis before making changes
   - Use intelligent_semantic_search to find related code
   - Use intelligent_refactor_suggest for improvement ideas
   - Use intelligent_code_autofix to clean up common issues (dryRun first!)
6. Track predictions with track_prediction for ROI analysis
7. Check code quality dashboard at http://localhost:3001/api/code-quality

TOOL PRIORITY:
- Information needed → web_search (Brave/Exa/DuckDuckGo)
- Problem solving → sequentialthinking
- Sports data → analyze_football_match_* tools
- Code editing → deep_code_edit
- Code analysis → intelligent_code_analyze
- Change impact → intelligent_impact_analysis
- Human input → ask_human

SAFETY PROTOCOLS:
- Auto-backup enabled for all file edits
- Destructive actions require human approval
- Rate limiting active on all external APIs
```

## 🔐 Required Environment Variables

| Variable | Purpose | Required For |
|----------|---------|--------------|
| `BRAVE_API_KEY` | Brave Search API | Web search |
| `EXA_API_KEY` | Exa Neural Search | Advanced web search |
| `API_FOOTBALL_KEY` | API-Football | Sports data (RapidAPI) |
| `FOOTBALL_DATA_KEY` | Football-Data.org | Alternative sports API |
| `SPORTS_DB_KEY` | TheSportsDB | Backup sports API |

**Note:** DuckDuckGo search works without API keys as a fallback.