This MCP server enables intelligent country exploration and content generation through three core tools:
Web Search - Search the internet for country information, including cultural, historical, and geographic details
Unsplash Image Search - Find high-quality photos with:
Customizable results (1-30 photos, default: 10)
Orientation filtering (landscape, portrait, or squarish)
Full metadata including photographer credits and URLs
Dice Rolling - Roll dice using standard notation (e.g., "2d6") with configurable number of rolls
The server is designed to integrate with LangGraph agents to generate comprehensive country profiles: researching content via web search, finding 10 relevant images from Unsplash, and producing rich markdown documents with embedded images and photographer credits.
Utilizes LangChain MCP adapters to integrate various tools and services within the agent workflow
Uses LangGraph for agent orchestration to create intelligent workflows that combine web search, image retrieval, and content generation for country profile creation
Integrates with OpenAI's GPT-4 language model to power the LangGraph agent for intelligent country exploration and content generation
Provides tools for searching and retrieving high-quality images from Unsplash's photo library, including support for orientation filters and photographer credits
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Country Explorer MCP Server create a profile for Japan with beautiful landscape images"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project demonstrates a complete MCP (Model Context Protocol) server integrated with LangGraph to create beautiful country profiles with embedded images.
Related MCP server: Unsplash MCP Server
🔍 MCP Server with Unsplash Search API integration
🤖 LangGraph Agent for intelligent country exploration
🖼️ 10 Images per Country with photographer credits
📄 Beautiful Markdown Profiles with embedded images
🧪 Comprehensive Test Suite for validation
📁 Organized Project Structure with profiles/ and tests/ folders
mcp-demo/
├── country_explorer.py # Main LangGraph app (10 images)
├── server.py # MCP server with Unsplash API
├── profiles/ # 📁 Generated country profiles
│ ├── india_profile.md
│ ├── japan_profile.md
│ ├── uganda_profile.md
│ └── usa_profile.md
├── tests/ # 📁 Test files
│ ├── test_country_explorer.py
│ ├── test_unsplash.py
│ └── search_5_mountains.py
└── .env # API keysPython 3.13+
Unsplash API key
OpenAI API key
Clone the repository:
git clone https://github.com/anilsharmay/mcp-demo.git
cd mcp-demoInstall dependencies:
uv syncConfigure environment variables:
Create .env file with your API keys:
UNSPLASH_API_KEY=your_unsplash_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
TAVILY_API_KEY=your_tavily_api_key_hereStart the MCP server:
uv run mcp dev server.pyRun the Country Explorer:
uv run python country_explorer.pyRun tests:
cd tests && uv run python test_country_explorer.pyThe MCP server provides these tools:
unsplash_search: Search for beautiful images with orientation filters
web_search: Search the web for country information
roll_dice: Roll dice with custom notation
The Country Explorer agent:
Researches countries using web search
Finds 10 beautiful images via Unsplash
Creates rich markdown profiles with embedded images
Includes photographer credits and links
Each country profile includes:
Cultural information and history
Geographic details and landmarks
10 high-quality images with credits
Clean markdown formatting for easy viewing
India Profile:
Switzerland Profile:
USA Profile:
Run the comprehensive test suite:
# Test MCP server
uv run python tests/test_unsplash.py
# Test Country Explorer
cd tests && uv run python test_country_explorer.py
# Test mountain search
uv run python tests/search_5_mountains.pyAdd to your Cursor MCP settings:
{
"mcpServers": {
"unsplash-mcp-server": {
"command": "uv",
"args": ["--directory", ".", "run", "server.py"]
}
}
}MCP (Model Context Protocol) - Server framework
LangGraph - Agent orchestration
LangChain MCP Adapters - Tool integration
Unsplash API - Image search
OpenAI GPT-4 - Language model
Python 3.13 - Runtime environment
This project demonstrates:
✅ MCP Server Development with custom API integration
✅ LangGraph Agent Creation with tool orchestration
✅ Beautiful Output Generation with embedded images
✅ Clean Project Organization and testing
✅ Real-world Application of AI agent frameworks
Perfect for showcasing MCP + LangGraph integration! 🌍✨
Roll the dice with the given notation
| Name | Required | Description | Default |
|---|---|---|---|
| notation | Yes | ||
| num_rolls | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to mention the format of accepted notation, whether the roll is random, any constraints, error behavior, or the return value. This is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it is under-specified. Every sentence is technically earned but the content is insufficient. It is concise at the expense of usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple tool, the description is incomplete for an agent to use it correctly. It does not explain the expected notation syntax or the number of rolls, and while an output schema exists, the description does not help connect inputs to outputs. The description needs more detail to be functionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It only vaguely references 'notation' and completely ignores the 'num_rolls' parameter. The description provides essentially no semantic information beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is essentially a restatement of the tool name ('roll dice') with a vague reference to 'given notation'. It communicates the basic action but adds no detail about what notation is or how it differs from other tools. It's minimally clear but not strongly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any context about suitable scenarios. The description simply states the action without implying any usage conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for photos on Unsplash using the given query.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| num_results | No | ||
| orientation | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic action but lacks critical details: no mention of rate limits, authentication requirements, pagination behavior, or what the output contains (though an output schema exists). For a search tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a search tool and front-loads the core functionality without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, search functionality) and the existence of an output schema (which handles return values), the description is minimally complete. However, with no annotations and poor parameter documentation, it leaves gaps in behavioral understanding and parameter usage that could hinder effective tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so parameters are undocumented in the schema. The description mentions 'using the given query' which only addresses one of three parameters (query, num_results, orientation). It doesn't explain what num_results controls or what orientation values are acceptable. The description adds minimal value beyond the schema's parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('photos on Unsplash'), making the purpose immediately understandable. It distinguishes from sibling tools like 'roll_dice' and 'web_search' by specifying the Unsplash photo domain. However, it doesn't explicitly differentiate from potential alternative photo search tools beyond the Unsplash context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While it's clearly for searching Unsplash photos, there's no mention of when to choose this over 'web_search' (which might also find photos) or other hypothetical photo sources. No prerequisites, limitations, or comparative context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web for information about the given query
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It does not mention whether the tool is read-only, what kind of results it returns, any potential side effects, or limitations. The description simply restates the action without adding safety or behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is appropriately sized and front-loaded. It contains no fluff or redundant words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple and has an output schema, the description lacks essential contextual information such as when to use it, what the query parameter entails, and any behavioral details. Given the absence of annotations and minimal parameter guidance, the description is insufficient for fully correct tool invocation in ambiguous situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and only one parameter, the description should explain what constitutes a valid query, any formatting requirements, or how the query is used. It only says 'about the given query,' which adds no meaningful detail beyond the parameter name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a web search for the given query, using the specific verb 'search' and resource 'the web'. It implicitly distinguishes itself from sibling tools like github_search_repositories by specifying the web as the scope, but it does not explicitly name or contrast with alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus other sibling tools. It does not mention any preconditions, alternatives, or specific contexts, leaving the agent to infer usage only from the tool's name and generic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0roll_dice1 field changedInput schema / titleAdded value: +"roll_diceArguments"unsplash_search1 field changedInput schema / titleAdded value: +"unsplash_searchArguments"web_search1 field changedInput schema / titleAdded value: +"web_searchArguments"roll_diceunsplash_searchweb_searchScored across 3 tools
Each tool has a clearly distinct purpose with no ambiguity: roll_dice is for dice rolling, unsplash_search is for photo searches, and web_search is for general web searches. The domains are completely separate, making misselection unlikely.
The naming is inconsistent with mixed conventions: roll_dice uses snake_case, unsplash_search uses snake_case, and web_search uses snake_case, but the verb styles vary (roll vs. search). There is no predictable pattern like verb_noun consistency across tools.
With only 3 tools, the set feels thin for a server named 'Country Explorer MCP Server', which suggests a domain focused on country-related exploration. The tools do not align with this purpose, indicating a significant mismatch in scope.
The tool surface is severely incomplete for the stated purpose of country exploration. There are no tools for retrieving country data, demographics, maps, or other relevant information, leaving obvious gaps that will cause agent failures in this domain.
Web search, URL content extraction to Markdown, site mapping, and recursive web crawler.
Turn any URL into clean Markdown and structured data. Scrape, crawl, search and extract.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Send quick greetings, scrape website content, and generate text or images on demand. Perform web s…
