langgraph-claude-azure-mcp by mm-repos - MCP Server

Azure AI Search MCP Server 🔍🤖

An intelligent Model Context Protocol (MCP) server for Azure AI Search integration with Claude Desktop - Transform enterprise document search into natural AI conversations using LangGraph workflows, Google Gemini, and advanced retrieval-augmented generation (RAG).

🔥 Keywords: Azure Cognitive Search, MCP Server, Claude Desktop Integration, LangGraph AI Workflows, Document Retrieval, Enterprise Search, RAG Implementation, AI-Powered Search, Conversational AI, Knowledge Management

🚀 Perfect for: Enterprise search solutions, document analysis platforms, knowledge management systems, AI-powered research tools, intelligent document retrieval, conversational search interfaces, and RAG (Retrieval-Augmented Generation) applications.

Requirements: Python 3.8+ | Azure AI Search Service | Claude Desktop | Google Gemini API (optional)

Features

🔍 Azure AI Search Integration: Connect to your Azure AI Search index
🔄 LangGraph Chain: Intelligent query processing and context retrieval
🧠 Google Gemini Integration: Enhanced document formatting, summarization, and analysis
🎨 Enhanced Visualizations: Grandalf layouts, Mermaid diagrams, and ASCII art
📊 LangSmith Tracing: Full observability and debugging of chain executions
🐍 MCP Protocol: Expose functionality as tools that Claude can use directly
⚙️ Configurable: Easy setup with environment variables
🔧 Pydantic Validation: Type-safe configuration and data validation
🌍 Environment Management: Secure credential handling with python-dotenv
🎭 Persona-Driven Responses: Two distinct AI personas for different output styles
📝 JSON-Based Prompts: Easily editable prompt templates
🧪 Comprehensive Testing: Full test suite with multiple scenarios

Technical Stack
Quick Setup
Configuration
Google Gemini Setup
Claude Desktop Integration
Project Structure
Architecture Overview
Available Tools
Visualization Tools
Testing
Development
LangSmith Monitoring
Troubleshooting

Technical Stack

Core Technologies

Python 3.8+: Modern Python with asyncio support
LangChain/LangGraph: AI workflow orchestration and state management
Azure AI Search: Cloud-based document indexing and retrieval
Google Gemini: Large language model for content processing
Model Context Protocol (MCP): Standard protocol for AI tool integration

Configuration & Validation

Pydantic v2: Type-safe configuration models with automatic validation
python-dotenv: Environment variable management and secrets handling
Structured Logging: Comprehensive error tracking and debugging

Visualization & Development

Grandalf: Advanced graph layout algorithms for LangGraph visualization
Mermaid: Professional diagram generation for documentation
LangSmith: Observability and tracing for AI chain executions
Pytest: Comprehensive testing framework with async support

Quick Setup

Clone and Install:

git clone https://github.com/codewith-mm/langgraph-claude-azure-mcp.git
cd langgraph-claude-azure-mcp
pip install -e .

Configure Environment: Copy .env.example to .env and fill in your credentials:

# On Windows (PowerShell):
Copy-Item .env.example .env
# On macOS/Linux:
cp .env.example .env

Run the MCP Server:
```
azure-search-mcp
```

Configuration

Create a .env file in the project root with the following variables:

# Azure AI Search
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_API_KEY=your-search-admin-key
AZURE_SEARCH_INDEX_NAME=your-index-name

# Google Gemini (for enhanced AI processing)
GOOGLE_API_KEY=your-google-api-key
GEMINI_MODEL=gemini-1.5-flash
GEMINI_TEMPERATURE=0.1

# LangSmith (for tracing and debugging)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your-langsmith-api-key
LANGCHAIN_PROJECT=azure-search-mcp

Google Gemini Setup

Get API Key: Visit Google AI Studio
Create API Key: Generate a new API key for your project
Add to Environment: Set GOOGLE_API_KEY in your .env file

The server will automatically:

Use Google Gemini for document formatting and summarization when API key is configured
Fall back to basic formatting if no API key is provided
Create proper LangChain chains that appear in LangSmith tracing

Claude Desktop Integration

Step 1: Locate Claude Desktop Configuration

Claude Desktop stores its configuration in a JSON file. Example (Windows):

%APPDATA%/Claude/claude_desktop_config.json

Step 2: MCP Server Configuration

Add this configuration to your Claude Desktop config file (update paths as needed for your environment):

{
   "mcpServers": {
      "azure-search-mcp": {
         "command": "python",
         "args": [
            "-m",
            "azure_search_mcp"
         ],
         "cwd": "../langgraph-claude-azure-mcp",
         "env": {
            "PYTHONPATH": "../langgraph-claude-azure-mcp/src"
         }
      }
   }
}

Step 3: Testing the Integration

Ask Claude to:

Search for CEO compensation:

"Can you search for CEO compensation information using the Azure Search tool?"

Analyze executive pay:

"Use the search tool to find and analyze executive compensation data"

Get document summaries:

"Search for salary information and provide a summary"

Project Structure

langgraph-claude-azure-mcp/
├── README.md                    # This comprehensive guide
├── pyproject.toml               # Python project configuration
├── pytest.ini                   # Pytest configuration
├── .env.example               # Environment variables template
├── claude_mcp_config.json     # Claude Desktop MCP configuration
├── visualize.py               # Quick visualization launcher
│
├── src/                       # Source code
│   └── azure_search_mcp/      # Main package
│       ├── __init__.py        # Package initialization
│       ├── __main__.py        # CLI entry point
│       ├── config.py          # Configuration management
│       ├── prompts.json       # JSON-based prompt templates
│       ├── prompt_manager.py  # Prompt loading and management
│       ├── azure_search.py    # Azure AI Search client
│       ├── chain.py           # LangGraph chain implementation  
│       └── server.py          # MCP server implementation
│
├── tests/                     # Comprehensive test suite
│   ├── test_chain.py          # Chain functionality tests
│   ├── test_integration.py    # Integration tests
│   ├── test_env_loading.py    # Environment configuration tests
│   ├── verify_claude_setup.py # Claude setup verification
│   └── run_tests.py           # Test runner script
│
├── visualization/             # Graph visualization tools
│   ├── dynamic_graph_viz.py   # Main visualization engine
│   └── visualize_launcher.py  # Launcher script
│
├── tools/                     # Development and debug tools
│   ├── debug_tools_timeout.py # Debugging utilities
│   └── test_prompts_list.py   # Prompt testing tools
│
└── docs/                      # Specialized documentation
    ├── guides/                # Setup guides
    │   └── CLAUDE_SETUP_GUIDE.md # Detailed Claude setup
    └── development/           # Development documentation
        └── [various dev docs] # Technical implementation details

Architecture Overview

Core Components

chain.py - LangGraph-based workflow engine
- SearchState management
- Three output formats (structured, summary, analysis)
- Persona-driven prompt routing
prompt_manager.py - JSON-based prompt system
- Dynamic template loading
- Two persona management (Financial Analyst and Search Quality Rater)
- Hot-reloadable configurations
server.py - MCP server implementation
- Tool definitions and handlers
- Claude Desktop integration
- Error handling and logging
azure_search.py - Azure AI Search client
- Document retrieval
- Vector and hybrid search
- Result formatting
config.py - Configuration management
- Environment variable handling with python-dotenv
- Service configurations (Azure, Gemini, LangSmith)
- Pydantic-based validation and type safety
- Secure defaults and configuration validation

Key Features

🎭 Persona-Driven Responses: Two distinct AI personas for different output styles
🔄 LangGraph Workflow: State-based processing with intelligent routing
📝 JSON-Based Prompts: Easily editable prompt templates
🔍 Azure AI Search: Advanced document retrieval capabilities
🧠 Gemini Integration: Google's LLM for content processing
📊 LangSmith Tracing: Comprehensive observability
🐍 Claude Desktop: Native MCP integration
🔧 Pydantic Models: Type-safe configuration with automatic validation
🌍 Secure Configuration: Environment-based secrets management with python-dotenv

Available Tools

search_documents: Search for relevant documents in Azure AI Search using text queries
get_document_context: Retrieve detailed context from specific documents by their IDs
search_and_summarize: Search and get a summarized view of results
search_with_analysis: Search with relevance analysis

Each tool supports different output formats:

structured: Detailed formatting with clear sections
summary: Concise overview with key points
analysis: In-depth analysis with insights and recommendations

Visualization Tools

The system includes comprehensive graph visualization capabilities for inspecting LangGraph structures:

Quick Visualization

# Comprehensive visualization
python visualize.py full

# Demo all methods
python visualize.py demo

Built-in Method

from azure_search_mcp.chain import AzureSearchChain

chain = AzureSearchChain()
chain.print_graph_diagram()  # Prints dynamic graph structure

Features

🎨 Mermaid Diagrams: Color-coded nodes with professional styling
🖼️ ASCII Art: Terminal-friendly graph representations
📐 Advanced Layouts: Grandalf integration for enhanced positioning
📁 File Export: Export diagrams as .mmd and .json files
🔄 100% Dynamic: Automatically adapts to any graph structure changes
🏷️ Type Detection: Shows node types and state structure

Example Output

Mermaid Diagram

graph TD
   validate_input["Validate Input"]
   search_documents["Search Documents"]
   prepare_context["Prepare Context"]
   summarize_results["Summarize Results"]
   analyze_results["Analyze Results"]
   format_structured["Format Structured"]
   handle_error["Handle Error"]
   END((END))

   validate_input -->|continue| search_documents
   validate_input -->|error| handle_error
   search_documents -->|continue| prepare_context
   search_documents -->|error| handle_error
   prepare_context -->|summary| summarize_results
   prepare_context -->|analysis| analyze_results
   prepare_context -->|structured| format_structured
   summarize_results --> END
   analyze_results --> END
   format_structured --> END
   handle_error --> END

   style validate_input fill:#fff3e0,stroke:#ff9800,stroke-width:2px
   style search_documents fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
   style prepare_context fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
   style summarize_results fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
   style analyze_results fill:#fffde7,stroke:#fbc02d,stroke-width:2px
   style format_structured fill:#fbe9e7,stroke:#d84315,stroke-width:2px
   style handle_error fill:#ffebee,stroke:#c62828,stroke-width:2px
   style END fill:#eeeeee,stroke:#616161,stroke-width:2px

ASCII Art

🎨 ASCII DIAGRAM:
──────────────────────────────────────────────────────────────────────────────
      □ validate_input
         │   │
         │   └─(continue)──► □ search_documents
         │           │   │
         │           │   └─(continue)──► □ prepare_context
         │           │           │
         │           │           ├─(summary)──► □ summarize_results ──► ◉ END
         │           │           ├─(analysis)─► □ analyze_results ─────► ◉ END
         │           │           └─(structured)─► □ format_structured ─► ◉ END
         │           └─(error)────► □ handle_error ────────────────────► ◉ END
         └─(error)────► □ handle_error ────────────────────────────────► ◉ END
──────────────────────────────────────────────────────────────────────────────

Testing

Essential Test Suite

The test suite has been streamlined to include only the most essential tests:

Core Chain Tests (test_chain.py)
- Chain functionality and state management
- Search tool functionality
- Routing logic and conditional edges
- Prompt template validation
Integration Tests (test_integration.py)
- End-to-end MCP server functionality
- Search functionality validation
- Server initialization and protocol compliance
Environment Configuration (test_env_loading.py)
- Environment variable loading
- Configuration validation
- API key verification
Claude Setup Verification (verify_claude_setup.py)
- MCP server command validation
- Claude Desktop integration check

Running Tests

# Run all essential tests
python tests/run_tests.py

# Run specific test categories
python -m pytest tests/test_chain.py -v
python -m pytest tests/test_integration.py -v

# Run environment check only
python tests/test_env_loading.py

Development

Setup Development Environment

Install development dependencies:
```
pip install -e ".[dev]"
```
Run tests:
```
pytest
```
Format code:
```
black src/
ruff check src/   ```
```

Adding Features

Adding Tests: Place in tests/ directory with test_*.py naming
Modifying Prompts: Edit src/azure_search_mcp/prompts.json
Configuration: Update src/azure_search_mcp/config.py
New Tools: Add to src/azure_search_mcp/server.py

Project Tasks

The following VS Code tasks are available:

Start MCP Server: Launch the MCP server for testing
Start MCP Server (Conda): Launch using conda environment
Test MCP Server (Standalone): Run standalone tests

LangSmith Monitoring

Setup LangSmith (Recommended)

LangSmith provides excellent tracing and monitoring for your MCP server:

Sign up for LangSmith: Visit smith.langchain.com
Get your API key: Go to Settings → API Keys → Create API Key

Update your .env file with your real LangSmith API key:

LANGCHAIN_API_KEY=lsv2_pt_your_actual_api_key_here

Test the integration by running the MCP server and checking the LangSmith dashboard

Benefits of LangSmith Integration

📊 Trace Operations: All search operations and performance metrics
🔍 Debug Issues: Search queries and results debugging
📈 Monitor Usage: Usage patterns and response times
🚨 Get Alerts: Error notifications and performance issues
🔗 View Traces: Detailed execution traces for each Claude interaction

What Gets Traced

✅ Individual tool calls from Claude
✅ Azure AI Search query execution
✅ Document retrieval and formatting
✅ LangGraph workflow execution
✅ Performance metrics and timing

Troubleshooting

Common Issues

Claude doesn't see the tools

Solution: Check the config file path and restart Claude Desktop completely

MCP server fails to start

Solution: Test the server manually:

cd .\langgraph-claude-azure-mcp\src
python -m azure_search_mcp

Authentication errors

Solution: Verify your .env file has the correct Azure Search credentials

No search results

Solution: Test your Azure Search index manually to ensure it has documents

Import or dependency errors

Solution: Ensure all dependencies are installed:
```
pip install -e .
```

Configuration Files Summary

Claude Desktop Config Location:

.\AppData\Roaming\Claude\claude_desktop_config.json

MCP Server Location:

.\langgraph-claude-azure-mcp\src\azure_search_mcp\

Environment Variables:

.\langgraph-claude-azure-mcp\.env

LangSmith Integration:

✅ Tracing configured and ready
📊 Monitors all search operations
🔗 Dashboard: https://smith.langchain.com
🧪 Test by using the MCP server with Claude

�🎉 You're all set! Your Azure AI Search MCP server is ready to provide intelligent document retrieval and analysis to Claude Desktop, with comprehensive visualization tools and optional LangSmith monitoring for performance insights.

📈 SEO Keywords

Azure AI Search, MCP Server, Claude Desktop, LangGraph, RAG, Retrieval Augmented Generation, Document Search, AI Search Integration, Model Context Protocol, Enterprise Search, Conversational AI, Knowledge Management, Semantic Search, NLP, Machine Learning, Chatbots, Search Engine, Information Retrieval, Python AI, Azure Integration

mm-repos/langgraph-claude-azure-mcp

Azure AI Search MCP Server 🔍🤖

Features

Table of Contents

Technical Stack

Core Technologies

Configuration & Validation

Visualization & Development

Quick Setup

Configuration

Google Gemini Setup

Claude Desktop Integration

Step 1: Locate Claude Desktop Configuration

Step 2: MCP Server Configuration

Step 3: Testing the Integration

Project Structure

Architecture Overview

Core Components

Key Features

Available Tools

Visualization Tools

Quick Visualization

Built-in Method

Features

Example Output

Mermaid Diagram

ASCII Art

Testing

Essential Test Suite

Running Tests

Development

Setup Development Environment

Adding Features

Project Tasks

LangSmith Monitoring

Setup LangSmith (Recommended)

Benefits of LangSmith Integration

What Gets Traced

Troubleshooting

Common Issues

Claude doesn't see the tools

MCP server fails to start

Authentication errors

No search results

Import or dependency errors

Configuration Files Summary

📈 SEO Keywords