🧠 Adaptive Graph of Thoughts

                    ╔══════════════════════════════════════╗
                    ║                                      ║
                    ║   🧠 Adaptive Graph of Thoughts 🧠  ║
                    ║                                      ║
                    ║       Intelligent Scientific         ║
                    ║         Reasoning through            ║
                    ║         Graph-of-Thoughts            ║
                    ║                                      ║
                    ╚══════════════════════════════════════╝

Intelligent Scientific Reasoning through Graph-of-Thoughts

**🚀 Next-Generation AI Reasoning Framework for Scientific Research**

Leveraging graph structures to transform how AI systems approach scientific reasoning

📚 Documentation

For comprehensive information on Adaptive Graph of Thoughts, including detailed installation instructions, usage guides, configuration options, API references, contribution guidelines, and the project roadmap, please visit our full documentation site:

➡️ Adaptive Graph of Thoughts Documentation Site

The site now includes interactive Mermaid diagrams and an improved layout.

🔍 Overview

Adaptive Graph of Thoughts leverages a Neo4j graph database to perform sophisticated scientific reasoning, with graph operations managed within its pipeline stages. It implements the Model Context Protocol (MCP) to integrate with AI applications like Claude Desktop, providing an Advanced Scientific Reasoning Graph-of-Thoughts (ASR-GoT) framework designed for complex research tasks.

Key highlights:

Process complex scientific queries using graph-based reasoning
Dynamic confidence scoring with multi-dimensional evaluations
Connects to external databases (PubMed, Google Scholar, Exa Search) for real-time evidence gathering
Built with modern Python and FastAPI for high performance
Dockerized for easy deployment
Modular design for extensibility and customization
Integration with Claude Desktop via MCP protocol

🚀 Quick Start

git clone https://github.com/SaptaDey/Adaptive-Graph-of-Thoughts-MCP-server.git
cd Adaptive-Graph-of-Thoughts-MCP-server
poetry install
poetry run uvicorn src.adaptive_graph_of_thoughts.main:app --reload

Open http://localhost:8000/setup and complete the
wizard. You'll land on the dashboard when finished.

📂 Project Structure

The project is organized as follows (see the documentation site for more details):

Adaptive Graph of Thoughts/
├── 📁 .github/                           # GitHub specific files (workflows)
├── 📁 config/                            # Configuration files (settings.yaml)
├── 📁 docs_src/                          # Source files for MkDocs documentation
├── 📁 src/                               # Source code
│   └── 📁 adaptive_graph_of_thoughts     # Main application package
├── 📁 tests/                             # Test suite
├── Dockerfile                            # Docker container definition
├── docker-compose.yml                    # Docker Compose for development
├── docker-compose.prod.yml               # Docker Compose for production
├── mkdocs.yml                            # MkDocs configuration
├── poetry.lock                           # Poetry dependency lock file
├── pyproject.toml                        # Python project configuration (Poetry)
├── pyrightconfig.json                    # Pyright type checker configuration
├── README.md                             # This file
└── setup_claude_connection.py            # Script for Claude Desktop connection setup (manual run)

🚀 Getting Started

Deployment Prerequisites

Before running Adaptive Graph of Thoughts (either locally or via Docker if not using the provided docker-compose.prod.yml which includes Neo4j), ensure you have:

A running Neo4j Instance: Adaptive Graph of Thoughts requires a connection to a Neo4j graph database.
- APOC Library: Crucially, the Neo4j instance must have the APOC (Awesome Procedures On Cypher) library installed. Several Cypher queries within the application's reasoning stages utilize APOC procedures (e.g., apoc.create.addLabels, apoc.merge.node). Without APOC, the application will not function correctly. You can find installation instructions on the official APOC website.
- Configuration: Ensure that your config/settings.yaml (or corresponding environment variables) correctly points to your Neo4j instance URI, username, and password.
- Indexing: For optimal performance, ensure appropriate Neo4j indexes are created. You can run python scripts/run_cypher_migrations.py to apply the provided Cypher migrations automatically. See Neo4j Indexing Strategy for details.
Note: The provided docker-compose.yml (for development) and docker-compose.prod.yml (for production) already include a Neo4j service with the APOC library pre-configured, satisfying this requirement when using Docker Compose.

Prerequisites

Python 3.11+ (as specified in pyproject.toml, e.g., the Docker image uses Python 3.11.x or 3.12.x, 3.13.x)
Poetry: For dependency management
Docker and Docker Compose: For containerized deployment

Installation and Setup (Local Development)

Clone the repository:

git clone https://github.com/SaptaDey/Adaptive-Graph-of-Thoughts-MCP-server.git
cd Adaptive-Graph-of-Thoughts-MCP-server

Install dependencies using Poetry:
```
poetry install
```
This creates a virtual environment and installs all necessary packages specified in pyproject.toml.
Activate the virtual environment:
```
poetry shell
```

Configure the application:

# Copy example configuration
cp config/settings.example.yaml config/settings.yaml

# Edit configuration as needed
vim config/settings.yaml

Set up environment variables (optional):

# Create .env file for sensitive configuration
echo "LOG_LEVEL=DEBUG" > .env
echo "API_HOST=0.0.0.0" >> .env
echo "API_PORT=8000" >> .env

Secret Management

In production environments, set the SECRETS_PROVIDER environment variable to
aws, gcp, or vault to fetch sensitive values from a supported secrets
manager. Optionally provide <VAR>_SECRET_NAME variables (for example
OPENAI_API_KEY_SECRET_NAME) to control the name of each secret. When a secrets
provider is configured, values for OPENAI_API_KEY, ANTHROPIC_API_KEY, and
NEO4J_PASSWORD are loaded automatically at startup.

Run the development server:

python src/adaptive_graph_of_thoughts/main.py

Alternatively, for more control:

uvicorn adaptive_graph_of_thoughts.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000.

✨ Setup Wizard

An interactive wizard is available to streamline initial configuration.

poetry run python -m agt_setup

Then visit http://localhost:8000/setup to complete the web-based steps.

Setup wizard demo GIF will appear here in the full documentation.

Docker Deployment

graph TB
    subgraph "Development Environment"
        A[👨‍💻 Developer] --> B[🐳 Docker Compose]
    end
    
    subgraph "Container Orchestration"
        B --> C[📦 Adaptive Graph of Thoughts Container]
        B --> D[📊 Monitoring Container]
        B --> E[🗄️ Database Container]
    end
    
    subgraph "Adaptive Graph of Thoughts Application"
        C --> F[⚡ FastAPI Server]
        F --> G[🧠 ASR-GoT Engine]
        F --> H[🔌 MCP Protocol]
    end
    
    subgraph "External Integrations"
        H --> I[🤖 Claude Desktop]
        H --> J[🔗 Other AI Clients]
    end
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style F fill:#fff3e0
    style G fill:#ffebee
    style H fill:#f1f8e9

Quick Start with Docker Compose:

# Build and run all services
docker-compose up --build

# For detached mode (background)
docker-compose up --build -d

# View logs
docker-compose logs -f adaptive-graph-of-thoughts

Individual Docker Container:

# Build the image
docker build -t adaptive-graph-of-thoughts:latest .

# Run the container
docker run -p 8000:8000 -v $(pwd)/config:/app/config adaptive-graph-of-thoughts:latest

Production Deployment:

# Use production compose file
docker-compose -f docker-compose.prod.yml up --build -d

Kubernetes Deployment (Helm)

A minimal Helm chart is provided under helm/agot-server for
running Adaptive Graph of Thoughts on a Kubernetes cluster.

helm install agot helm/agot-server

Customize values in helm/agot-server/values.yaml to set the image repository,
resource limits, and other options.

Notes on Specific Deployment Platforms

Smithery.ai: Deploy using the included smithery.yaml.
- Connect your GitHub repository on Smithery and click Deploy.
- The container listens on the PORT environment variable (default 8000).
- Health Checks rely on the /health endpoint.
- The Dockerfile and docker-compose.prod.yml illustrate the container setup.

Access the Services:
- API Documentation: http://localhost:8000/docs
- Health Check: http://localhost:8000/health
- MCP Endpoint: http://localhost:8000/mcp

🔌 MCP Client Integration

Supported MCP Clients

Adaptive Graph of Thoughts supports integration with various MCP clients:

Claude Desktop - Full STDIO and HTTP support
VS Code - Via MCP extensions
Custom MCP Clients - Generic configuration available

Quick Client Setup

Claude Desktop / VS Code settings

*Configuration content*

##Available MCP Tools
1. scientific_reasoning_query - Advanced scientific reasoning with graph analysis
2. analyze_research_hypothesis - Hypothesis evaluation with confidence scoring
3. explore_scientific_relationships - Concept relationship mapping
4. validate_scientific_claims - Evidence-based claim validation

🔌 API Endpoints

The primary API endpoints exposed by Adaptive Graph of Thoughts are:

MCP Protocol Endpoint: POST /mcp
- This endpoint is used for communication with MCP clients like Claude Desktop.
- Example Request for the asr_got.query method:
  *Configuration content*bash

Run full test suite with coverage using Poetry

poetry run pytest --cov=src --cov-report=html --cov-report=term

Or using Makefile for the default test run

make test

Run specific test categories (using poetry)

poetry run pytest tests/unit/stages/ # Stage-specific tests
poetry run pytest tests/integration/ # Integration tests
poetry run pytest -k "test_confidence" # Tests matching pattern

Type checking and linting (can also be run via Makefile targets: make lint, make check-types)

poetry run mypy src/ --strict # Strict type checking
poetry run ruff check . --fix # Auto-fix linting issues
poetry run ruff format . # Format code

Pre-commit hooks (recommended)

poetry run pre-commit install # Install hooks
poetry run pre-commit run --all-files # Run all hooks (runs Ruff and MyPy)

See Makefile for other useful targets like 'make all-checks'.


## 🖥 Dashboard Tour

*Dashboard demo GIF coming soon.*

## 💻 IDE Integration

Use the `vscode-agot` extension to query the server from VS Code. Run the extension and execute **AGoT: Ask Graph…** from the Command Palette.

## ❓ Troubleshooting

If the server fails to start or setup reports errors, ensure your Neo4j instance is running and the credentials in `.env` are correct. Consult the console output for details.

## 🗺️ Roadmap and Future Directions

We have an exciting vision for the future of Adaptive Graph of Thoughts! Our roadmap includes plans for enhanced graph visualization, integration with more data sources like Arxiv, and further refinements to the core reasoning engine.

For more details on our planned features and long-term goals, please see our [Roadmap](ROADMAP.md) (also available on the documentation site).

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) (also available on the documentation site) for details on how to get started, our branching strategy, code style, and more.

## 📄 License

This project is licensed under the Apache License 2.0. [License](LICENSE).

## 🔒 Security

Please see our [Security Policy](SECURITY.md) for reporting vulnerabilities and details on supported versions.

## 🙏 Acknowledgments

- **NetworkX** community for graph analysis capabilities
- **FastAPI** team for the excellent web framework
- **Pydantic** for robust data validation
- The scientific research community for inspiration and feedback

---

  <p>**Built with ❤️ for the scientific research community**</p>
  <p><em>Adaptive Graph of Thoughts - Advancing scientific reasoning through intelligent graph structures</em></p>

Adaptive Graph Of Thoughts MCP Server