基于 Python 与 uv 构建的 MCP Server 项目骨架，默认集成了官方 FastMCP SDK，开箱即用。
适用于 Claude Desktop、Cherry Studio 等客户端本地接入：
uv sync
uv run playwright install chromium
uv run mcp-server# 默认流式 HTTP 启动
uv run mcp-server --transport streamable-http
# 指定监听地址与端口
uv run mcp-server --transport streamable-http --host 0.0.0.0 --port 8000生产环境下推荐使用 Docker 镜像快速运行（内置 Playwright Chromium）：
docker build -t mcp-server:prod .
docker run --rm -p 8000:8000 mcp-server:prodNote
完整的容器挂载与缓存配置，请参阅 docs/docker.md。
开发环境可通过 compose 同时启动 MCP Server 与 PostgreSQL，并挂载本地源码：
docker compose -f docker-compose.dev.yml up --buildNote
开发容器说明请参阅 docs/docker-development.md。
本项目全新扩展并深度整合了 4 大核心高阶工具能力，完全面向大厂生产规范：
-
网页视觉快照 (
browser_screenshot_url)- 驱动 Headless 浏览器对任意 URL 截取高清长图或特定尺寸快照，支持在已登录会话中执行，为大模型注入第一手“网页视觉感知”。
-
数据图表动态生成器 (
render_data_chart)- 内置两套高端配色系统（Sleek Light / Harmonious Cyber-Dark HSL 渐变色）。
- 集成 Apache ECharts 5.5.0，智能阻断动画（animation: false），毫秒级极速渲染输出玻璃拟态高级数据图表 PNG 图片。
-
RPA 登录态与会话持久化 (
browser_save_session_state/browser_create_session)- 支持将会话的 Cookie、LocalStorage 等存储状态（StorageState）以普通 JSON 形式存盘，拉起新会话时一键注入，免除重复手动登录步骤。
-
零 Poppler 依赖的 PDF 阅读器 (
browser_render_pdf/browser_extract_pdf_text)- 摒弃极其臃肿复杂的 Poppler 依赖，引入
pypdfium2(Google PDFium) 和pypdf纯 Python 引擎。 - 提供非阻塞式线程池托管的高清多页视觉光栅化渲染及结构化文本提取能力。
- 摒弃极其臃肿复杂的 Poppler 依赖，引入
-
Office 办公文档图像渲染器 (
browser_render_docx/browser_render_pptx)- 通过极轻量且高度兼容的无头 LibreOffice 命令行进程，实现 Word（.docx）与 PowerPoint（.pptx）文档的秒级高清光栅化渲染。
- 智能定位器：自适应搜寻系统 PATH、Windows 注册表、标准 Program Files 路径以及 Windows Scoop 默认沙盒路径，实现零配置开箱即用。
为了防止 MCP 服务端与 AI 客户端运行在不同主机（如隔离容器、远程虚拟机或 SaaS 云端）时，本地物理文件路径对 AI 造成误导或泄露服务器隐私，本项目全面启用了严格网络资源模式：
- 物理路径隐去：所有工具（网页截图、PDF 渲染、数据图表、Office 文档渲染等）的返回信息中，严格不含任何服务器本地物理磁盘路径（如
C:\...\mcp-server\runtime\...）。 - 原生 MCP Resource 访问：系统统一且唯一返回符合 MCP 协议规范的 Resource URIs（格式为
render://{filename}）以及 Base64 编码的行内ImageContent。 - 免除额外端口服务：客户端（如 Cursor / Claude Desktop）通过现有的 JSON-RPC 长连接通道发送标准的
resources/read请求，即可实现跨网络下载和预览生成的文件。完全不需要开辟额外的 HTTP 服务器，也不需要映射任何额外的网络端口，极度安全且轻量。
uv sync # 初始化并同步虚拟环境依赖
uv run pytest # 运行测试套件
uv run ruff check # 代码风格与 Lint 检查
uv run ruff format # 代码格式化支持通过环境变量灵活配置服务参数：
- 服务元数据:
MCP_SERVER_NAME,MCP_SERVER_INSTRUCTIONS - HTTP 监听:
MCP_SERVER_HOST,MCP_SERVER_PORT,MCP_SERVER_MOUNT_PATH,MCP_SERVER_STREAMABLE_HTTP_PATH - 日志调试:
MCP_LOG_LEVEL,MCP_LOG_CONSOLE_COLOR,MCP_LOG_FILE_PATH,MCP_LOG_TOOL_ARGS
- docs/: 存放项目长期维护的设计、架构及环境文档（如 development.md、docker.md、docker-development.md）。
- config/: 存放项目级 YAML 配置文件（如
browser_search.yaml）。 - src/mcp_server/: 核心 Python 源码包。
tools/,resources/,prompts/: 注册具体 MCP 能力的分层模块。services/,adapters/,schemas/: 应对复杂业务的业务层、外部对接层及数据模型定义层。
- tests/: 精确映射源码职责的自动化测试套件。
Tip
新增独立 Tool 或设计新分层时，请先阅读 docs/development.md，以确保符合团队代码组织规范与变更原则。