Atom of Thoughts (AoT) MCP Server - Rust Implementation

Decompose complex problems into atomic units of thought for robust reasoning

🧠 Overview

Atom of Thoughts (AoT) is a server that decomposes complex problems into independent atomic units of thought, using the dependencies between these units to deliver more robust reasoning and validated insights. This Rust implementation provides an MCP (Model Context Protocol) server that can be integrated with AI assistants for enhanced reasoning capabilities.

Unlike traditional sequential thinking, AoT enables more powerful problem solving by allowing atomic units of thought to form dependencies with each other, creating a graph of reasoning that can be verified, decomposed, and contracted.

✨ Key Features

• Atomic Reasoning Units: Five distinct atom types for different reasoning stages
• Decomposition-Contraction Mechanism: Break down complex atoms into simpler sub-atoms and contract back after verification
• Dependency Tracking: Manage relationships between reasoning units
• Automatic Termination: Stop reasoning when maximum depth reached or high-confidence conclusion found
• Confidence Scoring: Each atom has a confidence level (0-1) with visual feedback
• MCP Integration: Full Model Context Protocol server implementation
• Two Server Modes: Full AoT (depth 5) and AoT-light (depth 3, faster processing)
• Command Interface: Control decomposition, check termination, get best conclusions

🚀 Quick Start

Prerequisites

• Rust 1.70 or later
• Cargo (comes with Rust)

Installation

# Clone the repository
git clone https://github.com/yourusername/Atom_of_Thoughts_rs.git
cd Atom_of_Thoughts_rs

# Build the project
cargo build --release

# Run tests to verify everything works
cargo test

Running the MCP Server

# Run in debug mode
cargo run

# Run release build for better performance
cargo run --release

The server runs on stdio transport and is ready to accept MCP requests.

🐛 Debugging and Logging

The AoT server uses the standard Rust log crate with env_logger for flexible logging control. Logging is configured via environment variables and supports multiple log levels.

Environment Variables

• RUST_LOG: Controls log level and filtering (standard env_logger variable)

  • Example: export RUST_LOG=debug
  • Levels: error, warn, info, debug, trace
  • Can filter by crate: export RUST_LOG=atom_of_thoughts_rs=debug,info

• AOT_DEBUG: Backward compatibility - maps to RUST_LOG=debug when set

  • Example: export AOT_DEBUG=1
  • Accepts: 1, true, on, yes
  • Only used if RUST_LOG is not already set

Log Output

Logs are written to standard error (stderr) with the following format:

[timestamp] LEVEL crate::module message

Example output:

[2026-03-01T17:22:32Z INFO  atom_of_thoughts_rs::mcp] Starting MCP server
[2026-03-01T17:22:32Z DEBUG atom_of_thoughts_rs::mcp] ServerHandler::get_info called
[2026-03-01T17:22:33Z DEBUG atom_of_thoughts_rs] P1 | premise | Depth: 0 | Dependencies: none | Confidence: 90.00% | Verified: ✗
[2026-03-01T17:22:33Z INFO  atom_of_thoughts_rs] SERVER EVENT: atom_created - premise: P1

Log Levels

• error: Critical errors that prevent operation
• warn: Warnings about potential issues (e.g., max depth reached)
• info: General server events, startup, verification, contraction
• debug: Atom processing details, decomposition events, dependencies
• trace: Verbose atom structure dumps and detailed internal state

Usage Examples

# Basic debug logging
export RUST_LOG=debug
cargo run

# Filter by crate for cleaner output
export RUST_LOG=atom_of_thoughts_rs=debug
cargo run

# Backward compatibility with AOT_DEBUG
export AOT_DEBUG=1
cargo run

# Different log levels
export RUST_LOG=error    # Only errors
export RUST_LOG=info     # Default informational messages
export RUST_LOG=debug    # Debug information
export RUST_LOG=trace    # Very verbose output

🧩 Atom Types

AoT uses five distinct atom types, each with a specific role in the reasoning process:

Atom Type	Symbol	Color	Purpose
Premise	🔍	Blue	Basic assumptions or given information for problem solving
Reasoning	🧠	Green	Logical reasoning process based on other atoms
Hypothesis	💡	Yellow	Proposed solutions or intermediate conclusions
Verification	✓	Magenta	Process to evaluate validity of other atoms (especially hypotheses)
Conclusion	🏆	Red	Verified hypotheses or final problem solutions

Each atom has:

• atomId: Unique identifier (e.g., "P1", "H2", "C3")
• content: Text description of the atom
• dependencies: List of atom IDs this atom depends on
• confidence: Confidence score between 0.0 and 1.0
• isVerified: Whether this atom has been verified
• depth: Depth level in the decomposition tree (0 = root)

🔧 MCP Tools

The server exposes three MCP tools:

1. AoT Tool (Full Implementation)

Name: AoT
Description: Full Atom of Thoughts implementation for complex reasoning tasks.

When to use:

• Solving problems requiring complex reasoning
• Generating hypotheses that need verification from multiple perspectives
• Deriving high-confidence conclusions in critical tasks
• Decision-making requiring multiple verification steps
• Minimizing logical errors

Parameters:

• atomId: Unique identifier for the atom (required)
• content: Actual content of the atom (required)
• atomType: Type of atom: "premise", "reasoning", "hypothesis", "verification", "conclusion" (required)
• dependencies: List of IDs of other atoms this atom depends on (required, can be empty array)
• confidence: Confidence level between 0-1 (required)
• isVerified: Whether this atom has been verified (optional, defaults to false)
• depth: Depth level in decomposition-contraction mechanism (optional, auto-calculated)

Max Depth: 5 levels

Important Notes:

• Conclusions must be verified (isVerified: true) to appear in best_conclusion results
• To verify a conclusion, either create it with isVerified: true or create a verification atom that depends on it
• Verification atoms with isVerified: true automatically verify atoms listed in their dependencies
• The atomcommands tool works with atoms created using the AoT tool (not AoT-light)

2. AoT-light Tool (Fast Processing)

Name: AoT-light
Description: Lightweight version for faster processing and quicker results.

When to use:

• Quick brainstorming sessions
• Time-sensitive problem solving
• Simpler reasoning tasks
• Initial exploration before using full AoT
• Learning or demonstration purposes

Key differences:

• Lower maximum depth (3 instead of 5)
• Simplified verification process
• Immediate conclusion suggestion for high-confidence hypotheses
• Reduced computational overhead
• Optimized for speed rather than exhaustive analysis

Parameters: Same as full AoT tool

Important Notes:

• AoT-light uses a separate server instance from full AoT
• Atoms created with AoT-light are not visible to the atomcommands tool
• For decomposition features or best_conclusion with AoT-light atoms, use the full AoT tool instead
• High-confidence hypotheses (confidence ≥ 0.8) trigger automatic conclusion suggestions

3. Atom Commands Tool (Advanced Control)

Name: atomcommands
Description: Command tool to control decomposition-contraction mechanism and automatic termination.

Commands:

• decompose: Decompose a specified atom into smaller sub-atoms
• complete_decomposition: Complete an ongoing decomposition process
• termination_status: Check termination status of current AoT process
• best_conclusion: Get the verified conclusion with highest confidence
• set_max_depth: Change the maximum depth limit

Parameters:

• command: Command to execute (required)
• atomId: Atom ID (required for decompose command)
• decompositionId: ID of decomposition process (required for complete_decomposition)
• maxDepth: Maximum depth value (required for set_max_depth)

Important Notes:

• best_conclusion only returns verified conclusions (isVerified: true)
• atomcommands works with the full AoT server, not AoT-light server
• To use best_conclusion with AoT-light atoms, recreate them using the full AoT tool
• Conclusions must be verified to appear in results (set isVerified: true or use verification atoms)

🌀 Decomposition-Contraction Mechanism

Decomposition Process

1. Start Decomposition: Break down a complex atom (usually a hypothesis) into simpler sub-atoms
2. Add Sub-atoms: Automatically or manually add atoms to the decomposition
3. Calculate Depth: Sub-atoms get depth = parent depth + 1
4. Complete Decomposition: Mark decomposition as ready for contraction

Contraction Process

1. Verification: When verification atoms verify hypotheses
2. Check Conditions: All sub-atoms must be verified and decomposition completed
3. Calculate Confidence: Average confidence of sub-atoms
4. Update Original: Original atom gets updated confidence and marked as verified
5. Suggest Conclusion: If verified hypothesis has confidence ≥ 0.8, suggest a conclusion

Automatic Features

• Auto-add to decomposition: New atoms automatically added to current decomposition
• Auto-termination: Terminates when max depth reached or strong conclusion found (confidence ≥ 0.9)
• Auto-conclusion: Suggests conclusions for verified hypotheses with confidence ≥ 0.8
• Auto-verification: Verification atoms automatically verify their dependencies

📋 Usage Examples

Example 1: Basic Reasoning Chain

{
  "atomId": "P1",
  "content": "The user wants to find restaurants near them",
  "atomType": "premise",
  "dependencies": [],
  "confidence": 0.9
}

{
  "atomId": "R1",
  "content": "We need to get the user's location first",
  "atomType": "reasoning",
  "dependencies": ["P1"],
  "confidence": 0.8
}

{
  "atomId": "H1",
  "content": "Ask the user for their location or use IP geolocation",
  "atomType": "hypothesis",
  "dependencies": ["R1"],
  "confidence": 0.7
}

Example 2: Verification and Conclusion

{
  "atomId": "V1",
  "content": "IP geolocation is less accurate but faster; asking is more accurate but requires interaction",
  "atomType": "verification",
  "dependencies": ["H1"],
  "confidence": 0.85,
  "isVerified": true
}

{
  "atomId": "C1",
  "content": "Use IP geolocation for quick results, then ask for precise location if needed",
  "atomType": "conclusion",
  "dependencies": ["H1"],
  "confidence": 0.77
}

Example 3: Decomposition Command

{
  "command": "decompose",
  "atomId": "H1"
}

Example 4: Get Termination Status

{
  "command": "termination_status"
}

🧪 Testing

The project includes comprehensive unit tests:

# Run all tests
cargo test

# Run tests with output visible
cargo test -- --nocapture

# Run specific test
cargo test test_decomposition_flow

# Run all tests and show output
cargo test -- --show-output

Test coverage includes:

• Atom type functionality
• Server initialization
• Atom processing and validation
• Decomposition flow
• Verification and contraction
• Termination logic
• Best conclusion retrieval
• Light server functionality

🏗️ Project Structure

Atom_of_Thoughts_rs/
├── Cargo.toml           # Rust dependencies and metadata
├── Cargo.lock           # Dependency lock file
├── README.md            # This file
├── AGENTS.md            # Agent guidelines and conventions
├── memory.ms            # Project information and design notes
├── refference.ts        # TypeScript reference implementation
├── src/
│   ├── lib.rs           # Core library implementation
│   └── main.rs          # Binary entry point with logging setup
└── target/              # Build artifacts (generated)

Key Components in lib.rs:

1. Data Structures:

   • AtomType: Enum with five atom types
   • AtomData: Core atom structure with all fields
   • DecompositionState: Tracks decomposition progress
   • TerminationStatus: Termination condition and reason

2. Core Servers:

   • AtomOfThoughtsServer: Full implementation with max depth 5
   • AtomOfThoughtsLightServer: Lightweight version with max depth 3

3. Error Handling:

   • AtomError: Comprehensive error enum with descriptive messages
   • Result<T>: Type alias for Result<T, AtomError>

4. MCP Integration:

   • AtomOfThoughtsMcpHandler: MCP server handler with three tools
   • AtomRequest: Schema for atom creation requests
   • AtomCommandsRequest: Schema for command requests

5. Core Algorithms:

   • Decomposition management
   • Contraction triggering
   • Confidence calculation
   • Termination checking
   • Dependency validation

6. Logging System:

   • Standard log crate with env_logger integration
   • Environment variable controlled log levels (RUST_LOG)
   • Backward compatibility with AOT_DEBUG variable
   • Multiple log levels: error, warn, info, debug, trace
   • Structured log output with timestamps and crate/module information

🔍 Development

Code Style

• Follows Rust 2024 edition
• Uses cargo fmt for consistent formatting
• cargo clippy -- -D warnings for linting
• Comprehensive documentation with doc comments

Building

# Debug build
cargo build

# Release build
cargo build --release

# Type checking without building
cargo check

# Generate documentation
cargo doc --open

Dependencies

• rmcp: Model Context Protocol implementation (v0.17)
• serde/serde_json: JSON serialization
• anyhow: Error handling
• thiserror: Custom error types
• tokio: Async runtime
• chrono: DateTime handling
• colored: Terminal output coloring
• log: Logging facade
• env_logger: Environment-based logging configuration

📊 Output Format

Atoms are displayed with colored, formatted output:

┌────────────────────────────────────────────────────────────────────────────────┐
│ 💡 HYPOTHESIS:H1 [Depth: 0/5] (✓ Verified) │
├────────────────────────────────────────────────────────────────────────────────┤
│ Ask the user for their location or use IP geolocation                          │
│ Confidence: [████████████████░░░░] 80%                                         │
│ Dependencies: R1                                                               │
└────────────────────────────────────────────────────────────────────────────────┘

Features:

• Colored headers based on atom type
• Confidence bar visualization
• Depth information
• Verification status
• Dependency listing

🎯 When to Use AoT

Ideal Use Cases

1. Complex Decision Making: Multiple factors, uncertain outcomes
2. Problem Solving: Breaking down complex problems into manageable parts
3. Hypothesis Testing: Generating and verifying multiple hypotheses
4. Risk Assessment: Evaluating different scenarios with confidence scores
5. Planning: Step-by-step reasoning with verification at each stage

Comparison: AoT vs AoT-light

Aspect	AoT (Full)	AoT-light
Max Depth	5	3
Processing	Comprehensive	Fast
Verification	Multi-step	Immediate
Use Case	Critical decisions	Quick reasoning
Output Detail	Full analysis	Essential only
Auto-features	All enabled	Simplified

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: cargo test
5. Format code: cargo fmt
6. Check lints: cargo clippy -- -D warnings
7. Commit changes: git commit -m 'Add amazing feature'
8. Push to branch: git push origin feature/amazing-feature
9. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add tests for new functionality
• Update documentation as needed
• Keep commits focused and atomic
• Reference issues in commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Based on the original Atom of Thoughts concept
• Uses the Model Context Protocol (MCP) for AI tool integration
• Inspired by decomposition-contraction mechanisms in cognitive architectures

📚 Resources

• Rust Programming Language
• Model Context Protocol
• Atom of Thoughts Concept
• RMCP Crate Documentation

---