HHC225/Local_MCP_Server

Local MCP Server

Advanced reasoning tools for AI assistants powered by Model Context Protocol (MCP). This server provides structured thinking methodologies for complex problem-solving.

📁 Project Structure

Local_MCP_Server/
├── main.py                 # Server entry point & tool registration
├── requirements.txt       # Python dependencies
│
├── configs/               # 🆕 Modular configuration system
│   ├── __init__.py       # Configuration loader
│   ├── base.py           # Server & common settings
│   ├── reasoning.py      # Recursive/Sequential/ToT tool configs
│   ├── memory.py         # Conversation Memory tool config
│   ├── planning.py       # Planning & WBS tool configs
│   ├── report.py         # Report Generator tool config
│   ├── vibe.py           # Vibe Coding tool config
│   ├── slack.py          # Slack tools config (DO NOT commit)
│   └── slack.py.template # Slack config template (commit this)
│
├── src/                   # 🆕 Source code directory
│   ├── tools/            # Tool implementations (business logic)
│   │   ├── base.py       # Base tool classes
│   │   ├── memory/       # Memory tools
│   │   │   └── conversation_memory_tool.py
│   │   ├── planning/     # Planning tools
│   │   │   ├── planning_tool.py
│   │   │   └── wbs_execution_tool.py
│   │   ├── reasoning/    # Reasoning tools
│   │   │   ├── recursive_thinking_tool.py
│   │   │   ├── sequential_thinking_tool.py
│   │   │   └── tree_of_thoughts_tool.py
│   │   ├── report/       # Report generation tools
│   │   │   ├── report_generator_tool.py
│   │   │   ├── html_builder_tool.py
│   │   │   └── templates/  # HTML/CSS/JS templates
│   │   │       ├── report_template.html
│   │   │       ├── report_styles.css
│   │   │       └── report_script.js
│   │   ├── slack/        # Slack integration tools
│   │   │   ├── get_thread_content_tool.py
│   │   │   ├── get_single_message_tool.py
│   │   │   ├── post_message_tool.py
│   │   │   ├── post_ephemeral_tool.py
│   │   │   └── delete_message_tool.py
│   │   └── vibe/         # Vibe Coding tool
│   │       └── vibe_coding_tool.py
│   │
│   ├── wrappers/         # MCP registration wrappers
│   │   ├── memory/       # Memory tool wrappers
│   │   │   └── conversation_memory_wrappers.py
│   │   ├── planning/     # Planning tool wrappers
│   │   │   ├── planning_wrapper.py
│   │   │   └── wbs_execution_wrapper.py
│   │   ├── reasoning/    # Reasoning tool wrappers
│   │   │   ├── recursive_thinking_wrappers.py
│   │   │   ├── sequential_thinking_wrapper.py
│   │   │   └── tree_of_thoughts_wrapper.py
│   │   ├── report/       # Report generation wrappers
│   │   │   ├── report_generator_wrapper.py
│   │   │   └── html_builder_wrapper.py
│   │   ├── slack/        # Slack tool wrappers
│   │   │   ├── get_thread_content_wrapper.py
│   │   │   ├── get_single_message_wrapper.py
│   │   │   ├── post_message_wrapper.py
│   │   │   ├── post_ephemeral_wrapper.py
│   │   │   └── delete_message_wrapper.py
│   │   └── vibe/         # Vibe Coding wrapper
│   │       └── vibe_coding_wrapper.py
│   │
│   └── utils/            # Utilities
│       └── logger.py     # Logging configuration
│
├── output/               # All tool-generated outputs
│   ├── chroma_db/        # ChromaDB persistent storage
│   ├── planning/         # WBS and planning files
│   └── reports/          # Generated HTML reports
│
└── docs/                 # Documentation

Architecture Design

Modular Configuration System (🆕):

• configs/: Each tool category has its own config module
  • Easy to add new tools without modifying existing configs
  • Clear separation of concerns per tool category
  • Scalable for dozens of tools

Clear Source Directory Structure (🆕):

• src/: All source code organized under one directory
  • src/tools/: Core tool implementations with business logic
  • src/wrappers/: MCP-specific wrappers with tool descriptions
  • src/utils/: Shared utilities and helpers
• main.py: Central registration point at root level

This structure ensures:

• ✅ Clean separation between config, source, and output
• ✅ Easy maintenance (modify tool configs independently)
• ✅ Scalability (add new tool categories without clutter)
• ✅ Clear distinction between source code and other files

⚡ Quick Start

1. Clone and Install

# Clone repository
git clone https://github.com/HHC225/Local_MCP_Server.git
cd Local_MCP_Server

# Install uv (fast Python package installer)
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# or: pip install uv

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

2. Test Server

python main.py

Expected output:

INFO: Initializing Thinking Tools MCP Server v1.0.0
INFO: Registering Recursive Thinking tools...
INFO: Registering Sequential Thinking tools...
INFO: Registering Tree of Thoughts tools...
INFO: Registering Conversation Memory tools...
INFO: Registering Planning tool...
INFO: Registering WBS Execution tool...
INFO: Registering Slack tools...
INFO: Registering Vibe Coding tool...
INFO: Registering Report Generator tools...

Press Ctrl+C to stop.

3. Configure Your IDE

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "thinking-tools": {
      "command": "/ABSOLUTE/PATH/TO/Local_MCP_Server/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/Local_MCP_Server/main.py"]
    }
  }
}

VSCode/Cursor (macOS/Linux)

Create .vscode/settings.json:

{
  "mcp.servers": {
    "thinking-tools": {
      "command": "/ABSOLUTE/PATH/TO/Local_MCP_Server/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/Local_MCP_Server/main.py"]
    }
  }
}

Important: Replace /ABSOLUTE/PATH/TO/ with your actual path! Use pwd to get it.

VSCode/Cursor (Windows with WSL)

Edit %APPDATA%\Code\User\mcp.json:

{
  "servers": {
    "thinking-tools": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": [
        "-d", "Ubuntu",
        "--cd", "/home/YOUR_USERNAME/Local_MCP_Server",
        "/home/YOUR_USERNAME/Local_MCP_Server/.venv/bin/python3",
        "/home/YOUR_USERNAME/Local_MCP_Server/main.py"
      ],
      "env": {
        "NODE_ENV": "production",
        "CHROMA_DB_PATH": "./chroma_db"
      },
      "type": "stdio"
    }
  }
}

Important:

• Replace YOUR_USERNAME with your WSL username (use whoami in WSL to get it)
• Replace Ubuntu with your WSL distribution name if different (use wsl -l in PowerShell)
• Full path example: /home/john/Local_MCP_Server

4. Restart IDE and Verify

1. Completely close and restart your IDE
2. Claude Desktop: Click 🔌 icon to verify "thinking-tools" server
3. VSCode/Cursor: Check MCP panel for server status

🧠 Available Tools

⚠️ IMPORTANT: Some advanced tools require Claude Sonnet 4 or higher for optimal performance. These are marked with a warning in their documentation.

Store and retrieve complete conversation context using ChromaDB vector database.

Best for: Maintaining full context across conversations, remembering important decisions, building comprehensive knowledge base, updating existing records

Quick Example:

1. Store complete conversation text (full content preserved)
2. Query relevant past conversations with semantic search
3. Get specific conversation by ID
4. Update existing conversations (append info, change status, fix mistakes)
5. Build context-aware responses with complete information

Key Features:

• ✅ Store: Save full conversations with automatic embeddings (no information loss)
• 🔍 Query: Semantic search across complete conversation history
• 📋 List: Browse all stored conversations
• 📖 Get: Retrieve specific conversation by ID
• 🔄 Update: Modify existing conversations without losing ID
• 🗑️ Delete/Clear: Remove individual or all conversations

Important: Always stores complete conversation text to prevent information loss. Optional summaries can be stored in metadata for quick reference.

|

Iterative answer improvement through deep recursive analysis with automatic verification.

Best for: Complex algorithm design, system architecture decisions, deep technical analysis

Quick Example:

1. Initialize session with your problem
2. Run 4-step deep analysis (update_latent)
3. Write improved answer (update_answer)
4. Get result → Auto-verification starts if needed
5. Finalize with verified answer

Step-by-step structured analysis where each thought builds on previous insights.

Best for: API design, database schema planning, code refactoring strategies

Quick Example:

Thought 1: Problem analysis
Thought 2: Initial approach
Thought 3: Refinement (can revise earlier thoughts)
Thought N: Final solution

Explore multiple solution paths with branching, evaluation, and backtracking.

Best for: Technology stack selection, architecture comparisons, multi-option decisions

Quick Example:

1. Create session with problem
2. Add multiple solution approaches
3. Evaluate each with scores
4. Explore promising paths deeper
5. Backtrack from dead ends
6. Select optimal solution

🆕

Create structured Work Breakdown Structures (WBS) with progressive file updates. Redesigned with multi-action architecture for better LLM compatibility.

Best for: Project decomposition, task planning, WBS creation, dependency mapping

Why New Architecture?

• ❌ Old: Single tool with 18+ parameters, WBS generated only at the end
• ✅ New: 5 focused actions, progressive WBS.md updates at each step
• ✅ Better for weaker LLMs, no context loss, clearer prompt chaining

Available Actions:

• planning_initialize: Start session, create initial WBS.md
• planning_add_step: Add planning analysis + WBS items, update file immediately
• planning_finalize: Mark complete, final WBS.md
• planning_status: Check progress
• planning_list: List all sessions

Quick Example:

# 1. Initialize
result = await planning_initialize(
    problem_statement="Build multiplayer 2048 game",
    project_name="Multiplayer 2048"
)
session_id = json.loads(result)["sessionId"]

# 2. Add Step 1 (Main phases)
await planning_add_step(
    session_id=session_id,
    step_number=1,
    planning_analysis="Breaking down into setup, development, testing",
    wbs_items=[
        {"id": "1.0", "title": "Setup", "level": 0, "priority": "High"},
        {"id": "2.0", "title": "Development", "level": 0, "priority": "High"}
    ]
)
# → WBS.md file updated immediately!

# 3. Add Step 2 (Breakdown setup)
await planning_add_step(
    session_id=session_id,
    step_number=2,
    planning_analysis="Detailing setup tasks",
    wbs_items=[
        {"id": "1.1", "title": "Init Repo", "level": 1, "parent_id": "1.0", "priority": "High"},
        {"id": "1.2", "title": "Setup Firebase", "level": 1, "parent_id": "1.0", "priority": "High"}
    ]
)
# → WBS.md file updated again!

# 4. Finalize
await planning_finalize(session_id=session_id)
# → Complete WBS.md ready for execution

Key Benefits:

• ✅ No context loss - Early tasks preserved in file, not just memory
• ✅ Progressive updates - WBS.md updated at each step
• ✅ Clear flow - Each action guides to next step
• ✅ Simple interface - 2-4 parameters per action vs 18+ before
• ✅ Works with weaker LLMs - Simpler, focused instructions

CRITICAL REQUIREMENTS:

• Child items (level > 0) MUST specify parent_id
• Add parents before children
• Dependencies validated for circular references

Systematic task-by-task execution tool for WBS-based project implementation with real-time progress tracking.

Best for: Implementing planned tasks, dependency-aware execution, progress tracking

Quick Example:

1. Start: Load WBS file and create session
2. Continue: Get next executable task
3. Execute: Implement task with thinking analysis
4. Repeat: Continue until all tasks complete

Progressive prompt refinement through structured iterations with LLM-generated suggestions.

Best for: Transforming vague ideas into concrete specifications, two-phase refinement (Idea → System), ready-to-implement project plans

Quick Example:

1. User: "I want to make a fun Tetris game"
2. Tool analyzes → Score: 25/100 (vague) → Needs 3 idea + 2 system steps
3. IDEA PHASE:
   Step 1: What's the core value?
   → LLM generates 5 creative suggestions
   → User selects: "Multiplayer Battle Royale"
   
   Step 2: Key features?
   → LLM generates 5 options based on previous selection
   → User selects preferred approach
   
   Step 3: User experience?
   → Continues refinement...
   
4. SYSTEM PHASE (automatic transition):
   Step 4: Technology stack?
   → LLM suggests 5 tech approaches
   → User selects: "React + Node.js + MongoDB"
   
   Step 5: Deployment strategy?
   → Final technical decisions
   
5. Generate beautiful report with all decisions

Key Features:

• 🎯 Automatic Specificity Analysis: 0-100 score determines refinement steps needed
• � Two-Phase Workflow: Idea refinement → System/Architecture refinement
• 🤖 LLM-Generated Suggestions: Tool provides instructions, LLM creates 5 contextual options
• ⭐ Recommendation System: Each step includes LLM's top pick with reasoning
• 📊 Progress Tracking: Clear step X/Y tracking across both phases
• 📝 Detailed Reports: Beautiful markdown reports with all decisions
• 💾 Session Management: Track multiple refinement sessions simultaneously
• � Integration Ready: Reports work perfectly with Planning and WBS tools

Actions:

1. initialize: Create session with initial prompt → Get specificity analysis
2. get_next: Get next question with LLM instructions for generating 5 suggestions
3. submit: Submit user's selected suggestion → Progress to next step
4. get_status: Check current progress and phase
5. generate_report: Create beautiful final report with all decisions
6. list_sessions: View all active refinement sessions

Workflow:

• Tool calculates specificity score (0-100)
• Determines steps needed based on vagueness
• Two-phase refinement: Idea → System/Architecture
• LLM generates contextual suggestions at each step
• User selections guide the refinement process
• Final report ready for implementation planning

Use Cases:

• Transform vague ideas into concrete specifications
• Systematic decision-making through guided questions
• Bridge concept to technical implementation
• Prepare refined requirements for WBS planning
• Complete project specification from rough ideas

Report Generator

Generate comprehensive IT reports from raw content (Slack messages, JIRA tickets, logs, etc.).

Best for: Incident reports, investigation summaries, analysis documentation, executive summaries

Quick Example:

1. Call generate_report with content
2. LLM returns structured JSON
3. Call build_report_from_json
4. Get professional HTML report

Features:

• Converts raw IT content into professional HTML reports
• Automatic severity assessment and impact analysis
• Executive summary with key takeaways
• Action items and recommendations
• Glassmorphism UI design with responsive layout
• Self-contained HTML files with embedded CSS/JS

Input Types Supported:

• Slack messages and threads
• JIRA tickets and bug reports
• Investigation results and audit findings
• Email threads and support tickets
• Meeting notes and log files
• System monitoring data

Integrate with Slack to retrieve threads, post messages, and manage communications.

Best for: Team collaboration, automated notifications, thread analysis

Quick Example:

1. Get thread content (with all replies) for analysis
2. Get single message (without replies) for quick lookup
3. Post public messages to channels
4. Send private ephemeral messages
5. Delete messages when needed

⚠️ Security Note: This tool requires workspace credentials. Use template file for Git.

🛠️ Tool Comparison

📖 Documentation

• Tools:
• Help:
  • GitHub Issues

⚙️ Configuration

This server uses modular configuration system under configs/ directory - no .env file needed!

Modular Configuration Structure

Each tool category has its own configuration file for better organization:

# configs/base.py - Server & common settings
class ServerConfig:
    SERVER_NAME: str = "Thinking Tools MCP Server"
    LOG_LEVEL: str = "INFO"  # DEBUG, INFO, WARNING, ERROR
    OUTPUT_DIR: Path = BASE_DIR / "output"

# configs/reasoning.py - Recursive/Sequential/ToT settings
class ReasoningConfig:
    ENABLE_RECURSIVE_THINKING: bool = True
    ENABLE_SEQUENTIAL_THINKING: bool = True
    ENABLE_TREE_OF_THOUGHTS: bool = True
    # ... tool-specific settings

# configs/memory.py - Conversation Memory settings
class MemoryConfig:
    ENABLE_CONVERSATION_MEMORY: bool = True
    CHROMA_DB_PATH: str = str(OUTPUT_DIR / "chroma_db")
    # ... tool-specific settings

# configs/planning.py - Planning & WBS settings
class PlanningConfig:
    ENABLE_PLANNING_TOOL: bool = True
    ENABLE_WBS_EXECUTION: bool = True
    WBS_FILENAME: str = "WBS.md"
    # ... tool-specific settings

# configs/vibe.py - Vibe Coding settings
class VibeConfig:
    ENABLE_VIBE_CODING: bool = True
    MAX_REFINEMENT_STAGES: int = 10
    NUM_SUGGESTIONS: int = 3
    # ... tool-specific settings

# configs/report.py - Report Generator settings
class ReportConfig:
    ENABLE_REPORT_GENERATOR: bool = True
    REPORT_OUTPUT_DIR: Path = OUTPUT_DIR / "reports"
    REPORT_MAX_CONTENT_LENGTH: int = 50000
    # ... tool-specific settings

# configs/slack.py - Slack integration settings (see slack.py.template)
class SlackConfig:
    bot_token: str  # From environment variable
    workspace_domain: str = "your-workspace.slack.com"
    default_user_id: str = "U00000000"
    ENABLE_SLACK_TOOLS: bool = True

⚠️ Security Note for Slack:

• Use configs/slack.py.template as template (commit to Git)
• Copy to configs/slack.py with actual credentials (DO NOT commit)
• configs/slack.py is in .gitignore to protect your credentials

Adding New Tool Configurations

1. Create new config file: configs/your_tool.py
2. Define config class with settings
3. Import in configs/__init__.py
4. Use in your tool implementation

Benefits:

• 🎯 Easy to locate tool-specific settings
• 📦 No config file bloat as tools grow
• 🔧 Independent configuration per tool category

Environment Variable Overrides

You can still override settings via environment variables:

# Temporary override for one session
MCP_LOG_LEVEL=DEBUG python main.py

# Or set in your shell profile
export MCP_LOG_LEVEL=DEBUG
export ENABLE_TREE_OF_THOUGHTS=false

Output Directory Structure

All tool-generated files are organized under output/:

output/
├── chroma_db/           # Conversation Memory ChromaDB storage
├── planning/            # Planning tool WBS files
│   └── execution/       # WBS execution session data
└── reports/             # Generated HTML reports
    ├── incident_20251016_143022.html
    ├── investigation_20251016_150134.html
    └── ...

Note: The output/ directory is in .gitignore and created automatically on startup.

💡 Quick Tips

• Adjust Log Level: Edit LOG_LEVEL in config.py or use MCP_LOG_LEVEL env var
• Enable/Disable Tools: Edit ENABLE_*_TOOLS in config.py
• Output Location: All files go to output/ directory (auto-organized)
• Save Session IDs: Keep them in notepad for resuming later
• Use uv for Speed: 10-100x faster than pip for installations

🚀 Why uv?

uv is a fast Python package installer:

• ⚡ 10-100x faster than pip
• 🔒 Built-in dependency resolution
• 🎯 Drop-in replacement for pip

# Common uv commands
uv pip install package_name
uv pip install -r requirements.txt
uv venv

🤝 Contributing

⚠️ Important: All contributions must go through Pull Requests

1. Fork the repository on GitHub
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/Local_MCP_Server.git
3. Create feature branch: git checkout -b feature/your-feature
4. Make changes, test, and submit PR

Direct commits to main branch are NOT allowed.

📄 License

MIT License - see file for details.

Need help? Check the or open an issue!