Y4NN777/devlens-mcp

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

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:

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 uv installation (checks ~/.local/bin/uv, ~/.cargo/bin/uv, or system PATH)
• Uses the correct Python from .venv (.venv/bin/python on Unix, .venv/Scripts/python.exe on 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)

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)

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.