MCP Agentic System
This project implements a dynamic agentic system that integrates with Model Context Protocol (MCP) servers using LangChain and LangGraph for intelligent routing and execution.
Features
- Dynamic Agent Flows: Uses LangGraph to create dynamic reasoning flows that can adapt based on user queries
- MCP Integration: Connects to various MCP servers (Weather, Stocks, Context7) and discovers their tools and resources
- Intelligent Routing: LLM-powered decision making for routing queries to appropriate MCP servers
- Tool Discovery: Automatic discovery of available tools on connected MCP servers
- Resource Discovery: Automatic discovery of available resources on connected MCP servers
- Metadata Management: Comprehensive metadata storage and management for MCP tools and resources
- Standardized Tool Interfaces: Consistent interfaces for interacting with MCP tools
- Caching Layer: Caches LLM responses to optimize transactions and reduce costs
- Streamlit Frontend: Interactive web interface to visualize agent flows and manage the system
- Database Preparation: Ready for database integration with structured metadata
Architecture```
┌─────────────────┐ ┌────────────────────┐ ┌──────────────────┐
│ Streamlit │ │ Node.js Proxy │ │ MCP Servers │
│ Frontend │◄──►│ Server │◄──►│ │
│ │ │ │ │ ┌─────────────┐ │
│ │ │ ┌─────────────┐ │ │ │ WeatherMCP │ │
│ │ │ │ LangGraph │ │ │ └─────────────┘ │
│ │ │ │ Agents │ │ │ │
│ │ │ ├─────────────┤ │ │ ┌─────────────┐ │
│ │ │ │ LLM Caching │ │ │ │ StocksMCP │ │
│ │ │ ├─────────────┤ │ │ └─────────────┘ │
│ │ │ │ MCP Router │ │ │ │
│ │ │ ├─────────────┤ │ │ ┌─────────────┐ │
│ │ │ │ Tool Reg. │ │ │ │ Context7 │ │
│ │ │ ├─────────────┤ │ │ └─────────────┘ │
│ │ │ │ Metadata │ │ │ │
│ │ │ └─────────────┘ │ └──────────────────┘
└─────────────────┘ └────────────────────┘
## Components
### Backend (Node.js)
- **MCP Client**: Connects to various MCP servers using different transports (HTTP, WebSocket, Stdio)
- **LangGraph Agents**: Dynamic reasoning flows that decide which MCP tools to use
- **LLM Integration**: OpenAI integration through LangChain for decision making
- **Tool Registry**: Centralized management of MCP tools with metadata
- **Metadata Manager**: Storage and retrieval of comprehensive tool and resource metadata
- **Caching System**: File-based cache for LLM responses to optimize transactions
- **REST API**: Exposes endpoints for frontend interaction
### Frontend (Streamlit)
- **Agent Flow Visualization**: Shows step-by-step execution of agent reasoning
- **MCP Explorer**: Displays connected MCP servers and their available tools and resources
- **Tool Registry**: Detailed view of all registered tools with metadata
- **Documentation Viewer**: Comprehensive documentation for all MCP tools
- **Resource Explorer**: Detailed view of all available MCP resources
- **Cache Manager**: Allows viewing and clearing of cached LLM responses
## Setup
1. Install backend dependencies:```bash
cd backend
npm install
```
2. Install frontend dependencies:```bash
cd frontend
pip install -r requirements.txt
```
3. Set up environment variables:
Create a `.env` file in the backend directory with your API keys:```
OPENAI_API_KEY=your_openai_api_key
```
4. Run the backend server:```bash
cd backend
npm run dev
```
5. Run the frontend:```bash
cd frontend
streamlit run main.py
```
## API Endpoints
- `GET /mcp/servers` - List connected MCP servers
- `GET /mcp/tools` - Discover tools on all MCP servers
- `GET /mcp/resources` - Discover resources on all MCP servers
- `GET /mcp/metadata` - Get comprehensive metadata for all MCP servers
- `POST /mcp/query` - Execute a tool on an MCP server
- `POST /mcp/tool-details` - Get detailed information about a specific tool
- `POST /mcp/resource-details` - Get detailed information about a specific resource
- `POST /reasoning/execute` - Execute the full agentic reasoning flow
- `GET /tools/registry` - Get all registered tools with metadata
- `GET /tools/signatures` - Get tool signatures for LLM prompting
- `GET /tools/documentation` - Get comprehensive tool documentation
- `POST /tools/refresh` - Refresh the tool registry
- `GET /metadata/database-structure` - Get database-ready structure for metadata
- `GET /cache/stats` - Get cache statistics
- `POST /cache/clear` - Clear the LLM response cache
## Project Structure```
.
├── backend/
│ ├── agentic/
│ │ ├── flow.js # LangGraph agent implementation
│ │ └── reasoning.js # Reasoning flow execution
│ ├── mcp/
│ │ ├── discovery.js # MCP tool and resource discovery
│ │ ├── index.js # MCP exports
│ │ ├── client.js # MCP client connections
│ │ ├── ai.js # LLM integration with caching
│ │ ├── router.js # Query routing
│ │ ├── toolInterface.js # Standardized tool interface
│ │ └── toolRegistry.js # Tool registry management
│ ├── metadata/
│ │ └── manager.js # Metadata storage and management
│ ├── utils/
│ │ └── cache.js # LLM response caching
│ ├── server.js # Main server with enhanced endpoints
│ └── package.json # Dependencies
├── frontend/
│ ├── main.py # Streamlit interface
│ └── requirements.txt # Python dependencies
├── tasks.py # Project tasks
└── README.md # Project documentation
Key Features Implemented
- Dynamic Agent Flows: LangGraph-based agents that can dynamically decide which MCP tools to use based on user queries
- Tool and Resource Discovery: Automatic discovery of available tools and resources on connected MCP servers
- Comprehensive Metadata Management: Rich metadata storage for tools and resources including parameters, return types, examples, usage information, and categories
- Standardized Interfaces: Consistent interfaces for interacting with MCP tools across different servers
- Intelligent Routing: LLM-powered decision making for routing queries to appropriate MCP servers
- Caching Layer: File-based caching for LLM responses to optimize transactions and reduce costs
- Visualization: Streamlit frontend that visualizes the agent reasoning process and comprehensive metadata
- Database Preparation: Structured metadata ready for database integration
- Extensibility: Modular design that makes it easy to add new MCP servers, tools, and resources
How It Works
- User submits a query through the Streamlit frontend
- The query is sent to the LangGraph agent for processing
- The agent uses an LLM to decide which MCP server to route the query to
- The agent discovers available tools and resources on the selected MCP server
- The agent selects the most appropriate tool based on the query
- The agent executes the tool and processes the results
- The agent generates a final response using the LLM
- All LLM responses are cached to optimize future transactions
- The entire process is visualized in the frontend for transparency
This implementation provides a complete foundation for an agentic MCP system that can dynamically adapt to user queries and optimize LLM usage through caching. The system is ready for database integration and can easily accommodate real MCP servers in the future.
