feat: upgrade marker/mcp stack and release docs

Author: barlowliu

AGENTS.md

@@ -0,0 +1,65 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->
+
+## 项目定位与目标
+
+`any2markdown` 是一个文档转 Markdown 服务，当前实现目标是：
+- 同时提供 `MCP` 与 `RESTful API` 两种调用方式；
+- 支持 `PDF`、`Word(docx/doc)`、`Excel(xlsx/xls)` 转换；
+- 提供图片提取、文档校验、批量转换、基础结构分析能力；
+- 统一由 `src/any2markdown_mcp/` 下处理器与工具层实现核心逻辑。
+
+## 代码结构速览
+
+- `src/any2markdown_mcp/server.py`：FastMCP 入口，注册 MCP 工具与 REST 路由。
+- `src/any2markdown_mcp/tools/`：MCP 工具函数层（参数协议、响应组装）。
+- `src/any2markdown_mcp/processors/`：文档处理核心逻辑（PDF/Word/Excel）。
+- `src/any2markdown_mcp/api/`：REST API Handler 与请求/响应模型。
+- `src/any2markdown_mcp/config.py`：环境变量与默认配置。
+
+## 代码规范与工程约束
+
+### Python 与风格
+
+- Python 版本基线：`>=3.10,<3.14`（推荐 `3.13`，见 `pyproject.toml`）。
+- 行宽按 `88` 字符控制（Black/isort 配置已定义）。
+- 新增或修改函数优先补全类型注解，保持 `mypy` 严格配置兼容。
+- 保持异步接口一致性：工具与处理链路使用 `async`。
+
+### 功能与接口约束
+
+- 输入文件类型受 `allowed_file_types` 限制：`pdf/docx/doc/xlsx/xls`。
+- 默认最大文件大小：`100MB`（`max_file_size`）。
+- 默认服务端口：`3000`，MCP 路径：`/mcp`，REST 前缀：`/api/v1`。
+- 转换接口默认 `include_content=false`，避免在响应中返回大文本正文。
+
+### 资源与运行约束
+
+- 首次 PDF 能力使用可能触发模型下载，依赖 `~/.cache/marker` 与 HuggingFace/Torch 缓存目录。
+- 项目当前文档中存在“规划态”和“实现态”混合内容；修改功能时应同步更新文档，避免与实际代码偏离。
+- 仓库当前未包含 `tests/` 目录；如新增测试需与现有 `pytest` 配置保持一致。
+
+## 修改原则（给协作代理）
+
+- 优先做“最小可验证改动”，避免无关重构。
+- 变更接口或配置项时，至少同步更新以下文档之一：
+  - `README.md`
+  - `docs/*.md` 对应专题文档
+  - `openspec/project.md`（项目约定变更）
+- 涉及新增能力、破坏性变更、架构级调整时，先按 `openspec/AGENTS.md` 走 proposal 流程，再实现代码。

Dockerfile

@@ -4,11 +4,10 @@ FROM python:3.11-slim
 # 设置工作目录
 WORKDIR /app
 
-# 直接配置pip使用阿里云源（避免系统包管理器问题）
-RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && \
-    pip config set global.timeout 120 && \
-    pip config set global.trusted-host mirrors.aliyun.com && \
-    pip config set install.trusted-host mirrors.aliyun.com
+# 构建时可注入依赖源（默认官方 PyPI）
+ARG PIP_INDEX_URL=https://pypi.org/simple
+RUN pip config set global.index-url ${PIP_INDEX_URL} && \
+    pip config set global.timeout 120
 
 # 复制依赖文件
 COPY requirements-prod.txt ./requirements.txt
@@ -80,4 +79,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
     CMD python -c "import requests; requests.get('http://localhost:3000/api/v1/status', timeout=5)" || exit 1
 
 # 使用优化的入口脚本（以root用户运行）
-ENTRYPOINT ["./docker-entrypoint.sh"] 
+ENTRYPOINT ["./docker-entrypoint.sh"] 

README-en.md

@@ -1,7 +1,7 @@
 # Any2Markdown MCP Server
 
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
-[![MCP Protocol](https://img.shields.io/badge/MCP-1.10%2B-green.svg)](https://modelcontextprotocol.io/)
+[![Python Version](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://python.org)
+[![MCP Protocol](https://img.shields.io/badge/MCP-1.26%2B-green.svg)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
 
@@ -32,7 +32,7 @@ A high-performance document conversion server that supports both **Model Context
 ## 🚀 Quick Start
 
 ### Prerequisites
-- Python 3.9+ 
+- Python 3.10 - 3.13 (validated on Python 3.13; 3.14 is not recommended yet)
 - 4GB+ RAM (for AI models)
 - 10GB+ disk space (for model cache)
 
@@ -43,12 +43,15 @@ A high-performance document conversion server that supports both **Model Context
 git clone https://github.com/WW-AI-Lab/any2markdown.git
 cd any2markdown
 
-# Create virtual environment
-python -m venv .venv
+# Create virtual environment (Python 3.13 recommended)
+python3.13 -m venv .venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 
-# Install dependencies
-pip install -r requirements.txt
+# Install dependencies (Huawei mirror by default)
+PIP_CONFIG_FILE=.pip/pip.conf pip install -r requirements.txt
+
+# Or use one-command bootstrap
+./scripts/setup_venv.sh
 ```
 
 ### Quick Start
@@ -110,8 +113,8 @@ python run_server.py
 # Test RESTful API
 python test_restful_api.py
 
-# Test MCP Protocol  
-python test_streamable_client.py
+# Test MCP Protocol (official SDK, streamable-http)
+python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx
 
 # Check service status
 ./scripts/deploy.sh status
@@ -349,7 +352,7 @@ pytest --cov=src/any2markdown_mcp --cov-report=html
 
 # Test specific functionality
 python test_restful_api.py      # REST API tests
-python test_streamable_client.py # MCP protocol tests
+python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx # MCP protocol tests
 ```
 
 ## 📊 Performance
@@ -432,4 +435,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Made with ❤️ by the Any2Markdown team** 
+**Made with ❤️ by the Any2Markdown team** 

README.md

@@ -1,7 +1,7 @@
 # Any2Markdown MCP 服务器
 
-[![Python 版本](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
-[![MCP 协议](https://img.shields.io/badge/MCP-1.10%2B-green.svg)](https://modelcontextprotocol.io/)
+[![Python 版本](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://python.org)
+[![MCP 协议](https://img.shields.io/badge/MCP-1.26%2B-green.svg)](https://modelcontextprotocol.io/)
 [![许可证](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![构建状态](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
 
@@ -32,7 +32,7 @@
 ## 🚀 快速开始
 
 ### 系统要求
-- Python 3.9+ 
+- Python 3.10 - 3.13（已验证 Python 3.13，暂不建议 3.14）
 - 4GB+ 内存（用于 AI 模型）
 - 10GB+ 磁盘空间（用于模型缓存）
 
@@ -43,15 +43,18 @@
 git clone https://github.com/WW-AI-Lab/any2markdown.git
 cd any2markdown
 
-# 创建虚拟环境
-python -m venv .venv
+# 创建虚拟环境（推荐使用 Python 3.13）
+python3.13 -m venv .venv
 source .venv/bin/activate  # Windows: .venv\Scripts\activate
 
 # 准备环境变量文件
 cp env.example .env
 
-# 安装依赖
-pip install -r requirements.txt
+# 安装依赖（默认使用华为镜像）
+PIP_CONFIG_FILE=.pip/pip.conf pip install -r requirements.txt
+
+# 或一键安装
+./scripts/setup_venv.sh
 ```
 
 ### 快速启动
@@ -113,8 +116,8 @@ python run_server.py
 # 测试 RESTful API
 python test_restful_api.py
 
-# 测试 MCP 协议
-python test_streamable_client.py
+# 测试 MCP 协议（官方 SDK，streamable-http）
+python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx
 
 # 检查服务状态
 ./scripts/deploy.sh status
@@ -436,7 +439,7 @@ pytest --cov=src/any2markdown_mcp --cov-report=html
 
 # 测试特定功能
 python test_restful_api.py      # REST API 测试
-python test_streamable_client.py # MCP 协议测试
+python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx  # MCP 协议测试
 ```
 
 ## dify集成
@@ -516,4 +519,4 @@ pytest
 - [ ] 支持 PowerPoint (PPTX) 转换
 - [ ] 图片类型PDF转换效果优化
 - [ ] Kubernetes 部署清单
-- [ ] 云存储集成
+- [ ] 云存储集成

docs/README.md

@@ -135,13 +135,13 @@ any2markdown/
 # 克隆项目
 cd any2markdown
 
-# 创建虚拟环境 (Python 3.9+)
-python -m venv venv
+# 创建虚拟环境 (Python 3.10 - 3.13，推荐 3.13)
+python3.13 -m venv venv
 source venv/bin/activate  # macOS/Linux
 # venv\Scripts\activate   # Windows
 
-# 安装依赖
-pip install -r requirements.txt
+# 安装依赖（默认使用华为镜像）
+PIP_CONFIG_FILE=.pip/pip.conf pip install -r requirements.txt
 ```
 
 ### 2. 启动服务器
@@ -230,4 +230,4 @@ curl -X POST http://localhost:8080/mcp \
 
 **🎯 目标**: 创建一个高性能、可扩展、标准化的文档转换MCP服务器，提供比传统API更好的开发体验和集成能力。
 
-**🚀 愿景**: 成为MCP生态系统中文档处理的标准解决方案，支持多种文档格式和输出选项。 
+**🚀 愿景**: 成为MCP生态系统中文档处理的标准解决方案，支持多种文档格式和输出选项。