🛠️ DevTools MCP 服务器

一个轻量级的 模型上下文协议（MCP） 服务器，为任何兼容 MCP 的 LLM 客户端（Claude Desktop、Claude Code、Cursor 等）提供开发者工具箱：网页抓取、日志检查、实时网络搜索，以及对 SQLite 或 Postgres/Supabase 的只读 SQL 查询——全部通过一个服务器实现。

🔗 在线演示： Glama MCP 链接 — 一旦列出，即可直接在浏览器中试用这些工具（参见 部署）。

📖 概述

DevTools MCP 通过 MCP 暴露四个工具，使 LLM 助手能够：

• 从任何网页提取干净、可读的文本

• 跟踪本地日志文件以调试错误

• 在编写代码之前搜索实时网络以获取最新文档

• 对本地 SQLite 文件 或 实时 Postgres/Supabase 数据库运行只读 SELECT 查询

每个工具都是一个简单、可测试的 Python 函数——除了你自己可选的 Supabase 项目外，这里不依赖任何付费 API。

Related MCP server: MCP Server Toolkit

✨ 功能

🏗️ 架构

┌──────────────────────┐
│    MCP Client         │   (Claude Desktop / Claude Code / Cursor / etc.)
└──────────┬────────────┘
           │ MCP protocol (stdio)
┌──────────▼────────────┐
│  DevTools MCP Server   │   FastMCP("DevTools")   — server.py
│                        │
│  ┌──────────────────┐  │
│  │ fetch_markdown    │  │──▶ requests + BeautifulSoup ──▶ any URL
│  ├──────────────────┤  │
│  │ read_log          │  │──▶ local filesystem
│  ├──────────────────┤  │
│  │ search_web        │  │──▶ DDGS (DuckDuckGo, key-free)
│  ├──────────────────┤  │
│  │ query_database     │  │──▶ _is_safe_select()  (SQL safety gate)
│  │                    │  │      │
│  │                    │  │      ├──▶ _query_sqlite()   ──▶ local .db file
│  │                    │  │      └──▶ _query_postgres() ──▶ Postgres / Supabase
│  └──────────────────┘  │
└────────────────────────┘

query_database 如何决定查询发送到哪里

query_database(db_path_or_url, sql_query, limit)
        │
        ▼
  _is_safe_select(sql_query)?
        │
   ┌────┴────┐
   NO         YES
   │           │
 reject   does db_path_or_url start with
 query    "postgres://" or "postgresql://" ?
              │
        ┌─────┴─────┐
        YES           NO
        │             │
 _query_postgres()  _query_sqlite()

_is_safe_select 是一个严格的闸门，只允许单个、简单的 SELECT 语句——不允许 INSERT/UPDATE/DELETE/DROP/ALTER 等，也不允许用 ; 链接的堆叠查询。这一点很重要，因为 SQL 文本是由 LLM 生成的，而不是手动输入的——这个闸门是为了防止幻觉或篡改的查询修改或破坏你的数据。

技术栈：

• fastmcp — MCP 服务器框架；通过 @mcp.tool 将 Python 函数转换为 MCP 工具

• requests + beautifulsoup4 — 网页抓取

• ddgs — 无需密钥的实时网络搜索（原 duckduckgo-search）

• sqlite3 — Python 内置，用于本地数据库查询

• psycopg2 — Postgres/Supabase 客户端，仅在使用 Postgres URL 时惰性导入

• python-dotenv — 加载本地 .env 变量

• pytest + pytest-mock — 测试套件

📂 项目结构

.
├── venv/                # Local virtual environment (not committed)
├── .env                 # Local secrets — real keys/paths, never committed
├── .gitignore
├── README.md
├── requirements.txt      # Runtime + dev/test dependencies
├── server.py             # Main MCP server — all 4 tools live here
├── test_server.py        # Pytest suite covering all 4 tools
├── Dockerfile             # Optional — only needed for Glama's hosted deployment
├── glama.json             # Optional — repo attribution for Glama's listing
└── smithery.yaml         # Optional — only relevant if also listing on Smithery

🚀 快速开始

1. 克隆仓库

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

2. 创建虚拟环境并安装依赖

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

pip install -r requirements.txt

3. 配置环境变量（可选）

server.py 在启动时调用 load_dotenv()，因此本地 .env 文件中的任何变量都会被自动加载。当前工具都不 需要 环境变量——query_database 将连接信息作为直接参数——但你可能仍然需要一个 .env 文件以方便本地使用：

# Only needed if you want a default connection string handy locally.
# Real credentials should live here and nowhere else.
SUPABASE_DB_URL=postgresql://postgres:your-password@db.xxxxxxxx.supabase.co:5432/postgres

⚠️ 切勿提交你的 .env 文件。 它已通过 .gitignore 排除。

注意：这与 Supabase 项目的 SUPABASE_URL / SUPABASE_KEY（用于 REST/JS 客户端）不同。query_database 通过 psycopg2 直接与 Postgres 通信，因此它需要来自 Supabase 仪表板的 Postgres 连接字符串（位于 设置 → 数据库 → 连接字符串），而不是 API URL/密钥对。

4. 本地运行服务器

python server.py

这将通过 stdio 启动 MCP 服务器，准备连接到任何 MCP 客户端。

🔌 连接到 Claude Desktop / Claude Code

将服务器添加到你的 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "devtools": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

重启客户端——四个工具（fetch_markdown、read_log、search_web、query_database）将作为助手可调用的函数出现。

🧰 工具参考

fetch_markdown(url: str) -> str

获取网页，去除 <script>、<style>、<nav> 和 <footer> 标签，并返回清理后的纯文本（上限为 8,000 个字符）。

fetch_markdown("https://docs.python.org/3/library/asyncio.html")

read_log(file_path: str, lines: int = 50) -> str

读取本地文本/日志文件的最后 lines 行。

read_log("/var/log/app/error.log", lines=100)

search_web(query: str, max_results: int = 3) -> str

在 DuckDuckGo 上搜索给定查询，并返回每个结果的标题、链接和摘要。

search_web("fastapi background tasks example")

query_database(db_path_or_url: str, sql_query: str, limit: int = 50) -> str

对以下目标运行 只读 SELECT：

• 本地 SQLite 文件（传入文件路径），或

• Postgres/Supabase 数据库（传入以 postgres:// 或 postgresql:// 开头的连接字符串）

结果以 {column: value} 字典列表的形式返回，上限为 limit 行。

query_database("app.db", "SELECT * FROM users WHERE status = 'active'", limit=5)
query_database("postgresql://user:pass@host:5432/db", "SELECT id, email FROM users", limit=10)

安全保证：

• 只允许以 SELECT 开头的查询

• 任何包含 INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、GRANT、REVOKE、CREATE 或 ATTACH 的查询都会被拒绝

• 堆叠查询（SELECT ...; DROP TABLE ...）会被拒绝

• 已知限制：检查是子字符串匹配，而不是完整的 SQL 解析器——像 SELECT * FROM updates_log 这样的无害查询也会被拒绝，因为它包含子字符串 update。这是故意选择“宁可误报，不可漏报”的权衡。

🧪 测试

项目附带一个包含 27 个测试的 pytest 套件，覆盖所有四个工具，完全离线运行，通过模拟网络调用和临时 tmp_path 夹具——不会触及真实的文件、数据库或网站。

pip install -r requirements.txt
pytest test_server.py -v

覆盖内容：

• _is_safe_select — 10 多个用例，涵盖有效选择、每个禁止的关键字、堆叠查询以及已知的误报行为

• query_database（SQLite）— 基本选择、limit、WHERE 过滤、阻止不安全的查询、文件缺失、表缺失、空结果集以及 Postgres URL 路由（模拟）

• read_log — 尾部行为、文件缺失、默认行数

• fetch_markdown — HTML 剥离和错误处理（网络模拟）

• search_web — 结果格式化、空结果、错误处理（网络模拟）

_query_postgres 本身在此套件中未针对真实数据库进行测试——只测试了决定 是否 调用它的路由逻辑。实时测试它需要真实的 Postgres/Supabase 连接字符串，该字符串绝不应硬编码到测试文件中或提交到仓库。

🌐 部署

选项 A — Glama（免费目录列表 + 浏览器检查器）

在 glama.ai/mcp 提交此仓库的 GitHub URL——Glama 直接从源代码索引你的工具，无需构建或清单。访问者可以获得浏览器内检查器，无需本地安装即可试用 fetch_markdown、read_log、search_web 和 query_database。

可选：添加 glama.json（已包含）以将列表声明/归属于你的 GitHub 账户。

选项 B — Glama 托管部署（Glama 为你运行，24/7）

将 Glama GitHub 应用连接到该仓库，它会将包含的 Dockerfile 构建为运行实例，位于 Glama 网关之后（托管 TLS、认证、日志）。在采用此路径之前，请查看 glama.ai/mcp/hosting 了解当前计划详情。

选项 C — Smithery

⚠️ 截至 2026 年初，Smithery 不再接受通过 GitHub 的新 免费 托管部署——这现在需要付费计划。Smithery 上的免费路径是将此服务器注册为 外部服务器（即你自己托管——例如通过上述 Glama 托管选项——然后只需将 Smithery 的列表指向该 URL）。smithery.yaml 仍包含在此仓库中，以防你选择该路线；请参阅 smithery.ai 了解当前详情，因为他们的托管模式正在积极变化。

🔐 环境变量

query_database 在凭据方面有意保持无状态——工具内部不会从环境变量读取任何内容，因此默认情况下不会在服务器端存储任何数据库凭据。

🗺️ 路线图

• 针对一次性 Postgres/Supabase 实例添加真实的集成测试（仅限 CI，凭据永不提交）

• 用适当的 SQL 解析器（例如 sqlparse）替换基于子字符串的 SQL 关键字检查，以消除误报

• 为 search_web 和 fetch_markdown 添加缓存

• 为托管的 Smithery 部署添加认证层

🤝 贡献

欢迎贡献、问题和功能请求——请随时提交 PR 或 issue。

📄 许可证

本项目根据 MIT 许可证 授权。