@gotza02/sequential-thinking 10000.2.1 → 10000.2.2

package/README.md.bak

@@ -0,0 +1,197 @@
+# @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.