World Bank Documents MCP Agent

A structured MCP-based document discovery system for the World Bank Documents & Reports API, built with:

• FastMCP for exposing tools as an MCP server
• LangGraph / LangChain for agent orchestration
• Groq LLM for reasoning and tool selection
• World Bank Documents API for search, filtering, metadata retrieval, and facet discovery

This project lets an LLM-powered agent query World Bank reports using a local MCP server over stdio, making it useful for interview demos, MCP experimentation, and building intelligent research assistants.

---

🏗️ Architecture

User Question
    ↓
LangGraph / LangChain Agent
    ↓
MultiServerMCPClient
    ↓
FastMCP Server (stdio)
    ↓
World Bank MCP Tools
    ├── search_documents
    ├── filter_documents
    ├── get_document
    └── get_facets
    ↓
World Bank Documents API

Component Overview

• Client Agent (client/agent_client.py)

  • Accepts user questions
  • Connects to the MCP server through MultiServerMCPClient
  • Lets the LLM decide which tool to call
  • Produces a final natural-language answer

• MCP Server (server/wb_docs_mcp.py)

  • Exposes World Bank document tools over stdio
  • Validates and normalizes tool inputs
  • Wraps World Bank API operations in MCP-compatible functions

• Tool Layer (server/tools/)

  • Handles all World Bank API interactions

  • Builds and normalizes query parameters

  • Uses a shared API client for requests

  • Extracts structured results (documents, facets)

  • Returns consistent responses using safe_result and safe_error

  • Supports filtering, search, pagination, and sorting

  • search.py → Full-text search with fallback + sorting

  • filter.py → Structured filtering (country, topic, date)

  • document.py → Retrieve document by ID

  • facets.py → Discover valid filter values

• Schema Layer (server/schemas.py)

  • Defines structured input models for all MCP tools
  • Keeps the interface clean and validation consistent

---

🚀 Features

• ✅ MCP Server exposing structured tools
• ✅ Integration with World Bank public API (no authentication required)
• ✅ Agentic client with multi-step tool execution
• ✅ Natural language query support
• ✅ Pydantic validation for robust inputs
• ✅ Error handling & pagination support

---

🧩 Project Structure

WorldBank_MCP/
├── server/
│   ├── __init__.py
│   ├── wb_docs_mcp.py           # MCP server with tools
│   ├── schemas.py               # Pydantic input schemas
│   ├── config.py                # constants & settings                
│   ├── utils.py                 # helper logic 
│   ├── api_client.py            # API request implementation
│   └── tools/
│       ├── __init__.py
│       ├── search.py            # search_documents implementation
│       ├── filter.py            # filter_documents implementation
│       ├── document.py          # get_document implementation
│       └── facets.py            # get_facets implementation
│
├── client/
│   ├── __init__.py
│   └── agent_client.py          # Agent loop (LLM + MCP tools)
│
├── requirements.txt             # Python dependencies
├── .gitignore
└── .env.example                 # Environment variables template 
└── README.md

---

🔧 MCP Tools

1. search_documents

Use this as the first tool for most natural-language questions.

Best for:

• broad topic search
• unknown filter values
• initial exploration

Example:

• “climate resilience in Kenya”
• “education financing in Africa”
• “water security in Brazil”

---

2. filter_documents

Use this when exact structured filters are already known.

Supported filters:

• count_exact
• topic_exact
• docty_exact
• strdate
• enddate

Best for:

• narrowing results after discovery
• exact country/topic/type filtering
• time-bounded report lookup

---

3. get_document

Retrieves full metadata for a specific document by its World Bank document ID.

Best for:

• inspecting a selected result
• retrieving richer metadata
• building a final grounded answer

---

4. get_facets

Returns valid exact values for supported filter fields.

Supported facet fields:

• docty_exact
• lang_exact
• count_exact
• topic_exact

Best for:

• discovering valid country names
• discovering exact topic values
• avoiding guessed filters

---

🤖 LLM Choice

We use Groq (llama-3.1-8b-instant) because:

• ⚡ Very fast inference
• 💰 Free tier available
• 🔧 Supports tool/function calling natively
• 🌐 No local GPU required

---

⚡ Quick Start

Prerequisites

• Python 3.14 or above
• A virtual environment
• Groq API key
• Internet access for the World Bank API

Note: Python 3.14 may cause compatibility warnings with some LangChain / Pydantic integrations.

---

📦 Installation

1. Clone the repository

git clone <your-repo-url>
cd WorldBank_MCP

2. Create and activate a virtual environment

Windows PowerShell

python -m venv venv
venv\Scripts\activate

macOS / Linux

python -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

---

🔐 Environment Variables

Create a .env file in the project root:

groq_model=your_groq_model
groq_api_key=your_groq_api_key_here

If your client uses additional provider keys or tracing variables, add them there as well.

---

▶️ Running the Project

Run the agent client

python client/agent_client.py

You can then ask questions like:

• What World Bank reports exist on climate resilience in Kenya? 
• Find documents about education financing in Sub-Saharan Africa published between 2019 and 2022. 
• What document types does the World Bank publish most frequently? 
• Find the most recent economic sector work on Indonesia. 
• List all languages the World Bank publishes documents in. 
• Find project documents related to water and sanitation in Brazil. 

---

💬 Example Queries & Responses

Sample-01

Ask a question or Type 'exit' to quit: What World Bank reports exist on climate resilience in Kenya? 

=== Response ===
The World Bank has several reports on climate resilience in Kenya, including:

1. Kenya - Coastal Region Water Security And Climate Resilience Project : Environmental Assessment
2. Kenya - Coastal Region Water Security and Climate Resilience Project : Resettlement Plan (Vol. 4 of 4) : Resettlement Action Plan 2 for Mwache Multipurpose Dam Project
3. Kenya - Climate Smart Agriculture Project : Environmental Assessment (Vol. 6 of 8) : Environmental and Social Impact Assessment Report for the Rehabilitation of Kamola Water Pan, East Yimbo Location Bondo Sub County in Siaya County
4. Kenya - Climate Smart Agriculture Project : Environmental Assessment (Vol. 4 of 8) : Environmental and Social Impact Assessment Report for the Desilting and Rehabilitation of Kivuno Water Pan in Sorget-Tendeno Ward, Kipkelion East Sub-County
5. Kenya - Climate Smart Agriculture Project : Environmental Assessment (Vol. 3 of 8) : Environmental and Social Impact Assessment Report for the Kimana Livestock Sale Yard in Kimana Ward, Kajiado South Sub-County, Kajiado County
6. Kenya - Climate Smart Agriculture Project : Environmental Assessment (Vol. 1 of 2) : Environmental Management Plan for Aekumi Rock Catchment, Tharaka Nithi County
7. Kenya - Nairobi Metropolitan Services Improvement Project : resettlement plan : Final abbreviated resettlement action plan report in the construction of Kangundo-Kenol, Kenol-Koma, Katumani-Mombasa road, and rehabilitation of Kenol-Machakos Town-Katumani Link Road Project
8. Kenya - Nairobi Metropolitan Services Improvement Project : Environmental Assessment (Vol. 27 of 41) : Environmental and social impact assessment report for construction of Karandini market

These reports are available on the World Bank website and provide information on the environmental and social impacts of various projects in Kenya, including climate resilience initiatives.

Sample-02

Ask a question or Type 'exit' to quit: Find documents about education financing in Sub-Saharan Africa published between 2019 and 2022

=== Response ===
The search results did not provide any documents about education financing in Sub-Saharan Africa published between 2019 and 2022. However, the following documents were found:

1. Project Information Document - Adolescent Girls Initiative for Learning and Empowerment - P170664 (2020)
2. Concept Project Information Document (PID) - Ten Million Adolescent Girls Project - P170664 (2019)
3. Additional Financing Environmental and Social Review Summary (ESRS) - Nigeria COVID-19 Preparedness and Response Project Additional Financing - P177076 (2021)    
4. Concept Stage Program Information Document (PID) - Edo Economic Transformation Program for Results - P169921 (2019)
5. Concept Project Information Document (PID) - Sustainable Procurement, Environmental and Social Standards Enhancement Project (SPESSE) - P169405 (2019)
6. Project Information Document - Sustainable Procurement, Environmental and Social Standards Enhancement Project (SPESSE) - P169405 (2019)

These documents may not be directly related to education financing in Sub-Saharan Africa, but they may provide some relevant information or context.

Sample-03

Ask a question or Type 'exit' to quit: What document types does the World Bank publish most frequently?

=== Response ===
The World Bank publishes most frequently the following document types:

1. Procurement Plan
2. Implementation Status and Results Report
3. Auditing Document
4. Working Paper
5. Brief
6. Agreement
7. Environmental Assessment
8. Report
9. Project Information Document
10. Announcement

These are the top 10 most frequent document types published by the World Bank, based on the data provided by the get_facets tool.

Sample-04

Ask a question or Type 'exit' to quit: Find the most recent economic sector work on Indonesia. 

=== Response ===
The most recent economic sector work on Indonesia is the "Indonesia - Tourism Development Project : environmental assessment : Kerangka pengelolaan lingkungan dan sosial" document, with an ID of 29890113, published on January 19, 2018. The document discusses the development objective of the Tourism Development Program Project for Indonesia, which is to improve tourism-relevant road quality and basic services accessibility, strengthen local economy linkages to tourism, and promote private investment in three tourism destinations in Indonesia. The document also highlights some of the negative impacts and mitigation measures related to the project.

---

🔄 How the Agent Works

1. The user asks a question in natural language.
2. The LangGraph/LangChain agent analyzes the query.
3. The agent selects an MCP tool exposed by the server.
4. The MCP server validates inputs and calls the corresponding tool.
5. The tool queries the World Bank API.
6. The result is returned to the agent.
7. The agent converts the tool output into a final user-friendly response.

---

🔮 Future Enhancements

• Add result ranking / summarization
• Add citation-aware final answers
• Support multiple MCP servers in one client
• Add Streamlit or FastAPI UI
• Add local caching for repeated document queries

---