DevLens MCP
The MCP Server I Built to Kill Alt-Tab. Clean, fast web context, right in your IDE.
Like most developers, I was sick of context-switching between VS Code and the browser for documentation. That was my core frustration. So, I built DevLens: an open-source MCP server because I was curious and wanted a custom solution that was more lightweight than existing tools.
The goal is simple: give your workspace AI (Copilot, Claude, etc.) web access that is structured and token-efficient. DevLens delivers twelve specialized tools via a three-layered architecture built for power and easy deployment.
What is MCP and DevLens's Role?
The MCP (Model Context Protocol) is the standard that lets your AI assistant call external tools (web search, scraping) to act beyond its training data. It gives the AI real-world and real-time ..power.
DevLens's Role is to be the most efficient implementation for web research. DevLens handles the intelligence (Smart Orchestration) and formats the results into clean Markdown. This ensures your workspace AI receives the precise context it needs without the clutter or high token cost of raw HTML.
Why DevLens (Solving the Flow Problem)
DevLens is built on two principles to solve context loss: Technical Composability and Token Efficiency.
Built for the Developer Workflow
- The Problem Solved: No more useless switching between browser and editor. Your coding flow stays intact.
- The Technical Edge: Our layered architecture uses simple primitives that combine powerfully. This means more precise and less costly workflows than existing "monolithic" solutions.
- LLM Context Optimal: Our clean, token-optimized Markdown output is about 70% smaller than raw HTML. This is the secret for fast, accurate AI results in your chat.
- Seamless IDE Integration: Designed to pair perfectly with VS Code Copilot and GitHub Copilot. Web research is injected directly into your editor.
- Deployment Ready: Use it locally for your own work, or deploy it on a server to share with others.
- Smart Orchestration — The system chooses the best tool sequence, automatically.
- Zero Configuration — Install, run. Done.
Developer Personas & Use Cases
| Persona | Problem Solved (The Pain) | DevLens Solution (The Win) |
|---|---|---|
| Nina, the Frontend Developer | Needs a quick fix (e.g., that one CORS config snippet) but hates opening 5 Stack Overflow tabs. | Uses suggest_workflow or search_web + summarize_page to get the validated code snippet instantly in chat. Flow maintained. |
| Kenji, the Staff Engineer | Must compare three serverless vendors for an architecture decision. Needs a single, definitive data dump. | Uses deep_dive to fetch, aggregate, and analyze complex data concurrently. The LLM receives the full, pre-processed report. |
| Sarah, the DevOps Specialist | Has to manually check third-party deployment guides every week for silent, breaking changes. | Uses monitor_changes to passively track content hashes on critical docs, sending an alert only when something actually changes. |
Tools
DevLens gives you 12 specialized tools—think of it like a camera bag of lenses. Pick one, or let the smart system auto-select:
| Layer | Metaphor | Focus | Tools |
|---|---|---|---|
| Primitives | Basic Lenses | Precision & Reliability | search_web, scrape_url, crawl_docs, summarize_page, extract_links |
| Composed | Multi-Lens Systems | Convenience & Aggregation | deep_dive, compare_sources, find_related, monitor_changes |
| Meta | Auto-Focus Intelligence | Guidance & Optimization | suggest_workflow, classify_research_intent, get_server_docs |
Quick Start (Seriously, It's Fast)
Prerequisites
- Python 3.12 or newer
- uv package manager
Installation
# Clone the repository
git clone https://github.com/Y4NN777/devlens-mcp.git
cd devlens-mcp
# Install dependencies
uv sync
# Run the server (STDIO mode)
uv run python -m devlens.server
Configuration du client MCP
Claude Desktop
Add this to claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Option 1: Using launch script (Recommended - Cross-Platform)
{
"mcpServers": {
"devlens": {
"command": "/absolute/path/to/devlens-mcp/launch_mcp.sh",
"args": []
}
}
}
Option 2: Direct uv command
{
"mcpServers": {
"devlens": {
"command": "uv",
"args": ["run", "python", "-m", "devlens.server"],
"cwd": "/absolute/path/to/devlens-mcp"
}
}
}
VS Code Copilot (Recommended - Cross-Platform)
Create .vscode/mcp.json in your workspace:
{
"servers": {
"devlens": {
"command": "/absolute/path/to/devlens-mcp/launch_mcp.sh",
"args": []
}
}
}
Note: The launch_mcp.sh script is cross-platform and automatically:
- Detects your OS (Linux/macOS/Windows)
- Locates
uvinstallation (checks~/.local/bin/uv,~/.cargo/bin/uv, or system PATH) - Uses the correct Python from
.venv(.venv/bin/pythonon Unix,.venv/Scripts/python.exeon Windows) - No manual configuration needed!
Other MCP Clients
Use STDIO transport:
uv run python -m devlens.server
Verify Installation
Test the server is working:
# Test basic functionality
uv run python -c "from devlens.server import mcp; print('DevLens server loaded successfully')"
Usage Examples
Manual Tool Usage
# Simple search
search_web("FastAPI tutorial", limit=5)
# Scrape with metadata
scrape_url("https://docs.python.org", include_metadata=True)
# Multi-source research
deep_dive("Python async best practices", depth=5, parallel=True)
# Compare perspectives
compare_sources("FastAPI vs Flask", ["url1", "url2"])
Smart Orchestration
# Let DevLens recommend the workflow
suggest_workflow("How to integrate payment API in Burkina Faso?")
# Returns:
# - Primary intent: quick_answer (50% confidence)
# - Workflow: [search_web(limit=3), scrape_url]
# - Suggested parameters optimized for intent
# - Fallback strategies if tools fail
With Context
# Provide known URLs to skip search
context = ResearchContext(known_urls=["https://docs.stripe.com"])
suggest_workflow("Stripe payment integration guide", context)
# DevLens adapts:
# - Skips search (URLs already known)
# - Goes straight to crawl_docs or scrape_url
# - Optimizes parameters based on intent
Architecture
DevLens uses a simple, effective layered architecture—the smart bits guide the reliable bits.
- Meta Layer (Intelligence) -> suggests workflows
- Composed Layer (Convenience) -> combines primitives
- Primitive Layer (Reliability) -> uses adapters
- External Services (The Actual Internet)
Key Design Principles:
- Composability — Tiny tools that handle huge tasks.
- Intelligence at the Edges — Smart brain decides, reliable primitives execute.
- Token Optimization — Maximum context, minimum token cost.
- Fail Explicitly — No silent failures. We tell you exactly what broke.
- Developer Velocity First — If it doesn't make you faster, we don't build it.
See ARCHITECTURE.md for the deep dive.
Library Stack (The Ingredients)
| Layer | Library | Purpose | Framework |
|---|---|---|---|
| MCP | fastmcp | MCP protocol implementation | |
| Scraping | crawl4ai | JavaScript-enabled web scraping | |
| Search | ddgs | DuckDuckGo search (no API key) | |
| HTTP | httpx | Fallback HTTP client | |
| Validation | pydantic | Input/output schemas |
Features
Intelligent Scraping
- Exponential backoff retry (because the internet is flaky)
- Metadata extraction (+41% information density)
- Smart filtering (skips all the login/signup/spam garbage)
- Markdown conversion (clean text for the AI)
- Content change detection via hashing
Multi-Source Research
- Parallel content fetching (3x faster)
- Domain diversity filtering
- Comparative analysis across sources
- Progress tracking with success/failure reporting
Smart Orchestration
- 7 research intent patterns (e.g., quick_answer, deep_research, comparison)
- Dynamic workflow generation based on context
- Parameter optimization (limits/depths automatically set for intent)
- Fallback strategies when tools fail
- LRU cache for insane speed (200 entries)
Context Awareness
- Tracks known URLs (no redundant searches)
- Records failed tools (so the AI doesn't try the same thing twice)
- Adapts workflows based on research state
Performance (Proof We Aren't Lying)
| Tool | Duration | Cost | Notes |
|---|---|---|---|
| search_web | 1-2s | Low | DuckDuckGo API |
| scrape_url | 2-5s | Low | Single page fetch |
| crawl_docs | 10-60s | High | Multi-page crawling (big tasks take big time) |
| deep_dive | 5-15s | Medium | Parallel scraping |
| suggest_workflow | <50ms | Minimal | LRU cached |
Documentation
- REQUIREMENTS.md — Project scope and technical requirements
- ARCHITECTURE.md — Software architecture and design philosophy
- TOOLS.md — Comprehensive tool reference with examples
Philosophy
The DevLens Philosophy: Make the hard stuff simple and fast.
- Composability — Build with small, focused primitives that combine
- Intelligence at the Edges — Smart brain, reliable hands
- Developer Velocity — If setup takes more than 5 minutes, it's too much.
- Token Economy — Efficiency is currency.
- Fail Explicitly — We tell you when something breaks.
- Context-Aware — It remembers what happened.
Read the full philosophy in ARCHITECTURE.md.
Examples (In Action)
Quick Answer
Query: "What is FastAPI?"
-> suggest_workflow thinks: quick_answer (50%)
-> Workflow: search_web(limit=3) -> scrape_url
-> Result: Fast answer from the top source. Done.
Deep Research
Query: "Comprehensive guide to mobile payments in Africa"
-> suggest_workflow thinks: deep_research (75%)
-> Workflow: search_web(limit=10) -> deep_dive(depth=10, parallel=true)
-> Result: Multi-source aggregated report, ready for planning.
Documentation Learning
Query: "FastAPI documentation" + known_url
-> suggest_workflow thinks: documentation (80%)
-> Workflow: crawl_docs(max_pages=25) (skips search, goes straight to the docs)
-> Result: Complete documentation with TOC.
Comparison Research
Query: "Compare FastAPI vs Flask"
-> suggest_workflow thinks: comparison (65%)
-> Workflow: search_web -> scrape_url (parallel) -> compare_sources
-> Result: Side-by-side analysis ready for your pull request.
Contributing
Contributions welcome! Keep it simple:
- Add, don't modify — New tools over changing existing ones
- Document why — Explain your design choices
- Test everything — All tools must have validation tests
- Keep it simple — Clarity over cleverness
License
MIT License - See LICENSE for details.
Name origin: DevLens = A developer's lens for viewing the web. Different tools are different lenses (wide-angle, macro, zoom), with smart auto-focus (orchestration) that picks the right lens automatically.