c4a mcp
用于web交互的模型上下文协议（MCP）服务器 crawl4ai.
该项目旨在通过MCP为AI代理提供先进的网页浏览和数据提取功能 runner 工具。
快速安装（光标）
只需单击一下即可在Cursor中安装此MCP服务器：
**注：** 需要安装并运行Docker。服务器将在容器中运行 `ghcr.io/blghtr/c4a-mcp:latest`.
## MCP服务器安装
### 选项1：一键安装（光标）
单击上面的按钮在Cursor中自动安装，或使用深度链接：
### 选项2：手动安装
添加到您的 `mcp.json` 文件（通常位于 `~/.cursor/mcp.json` 或 `%APPDATA%\Cursor\User\mcp.json` 在Windows上）：
{ "mcpServers": { "c4a-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/blghtr/c4a-mcp:latest" ] } } }
**有环境变量** （对于基于LLM的提取）：
{ "mcpServers": { "c4a-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAI_API_KEY", "-e", "GEMINI_API_KEY", "ghcr.io/blghtr/c4a-mcp:latest" ], "env": { "OPENAI_API_KEY": "your-key-here", "GEMINI_API_KEY": "your-key-here" } } } }
**要求：**
- Docker必须安装并运行
- 对于私有存储库，请使用GitHub容器注册表进行身份验证：echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
## 开发设置
### 先决条件
- Python 3.11+
- [紫外线](https://github.com/astral-sh/uv) 用于包管理
### 安装
Install dependencies
uv pip install --system -e ".[dev]"
### 预提交钩子
此项目使用预提交挂钩在提交前自动格式化和lint代码。
**初始设置：**
Install pre-commit hooks
uv run pre-commit install
**用途：**
预提交钩子将自动运行 `git commit`他们将：
- 格式化代码 `black` 和 `ruff format`
- 通过以下方式解决掉毛问题 `ruff`
- 检查YAML/JSON文件是否存在语法错误
- 删除尾随空格并修复文件结尾问题
**手动运行：**
Run hooks on all files
uv run pre-commit run --all-files
Run hooks on staged files only
uv run pre-commit run
### 运行测试
Run all tests
uv run pytest
Run with verbose output
uv run pytest -v
## CI/CD
该项目使用GitHub Actions进行持续集成和部署。
### 工作流程
CI/CD管道(`/.github/workflows/ci-cd.yml`)执行以下操作：
1. **测试**：在Python 3.11和3.12上运行测试
1. **Docker构建**：在推送时构建Docker镜像 `main` 或标签创建
1. **Docker推送**：将映像发布到GitHub容器注册表（ghcr.io）
### Docker镜像
Docker镜像会自动构建并推送到：
ghcr.io/blghtr/c4a-mcp
**可用标签：**
- `latest` -最新承诺 `main` 分支
- `v` -语义版本标签（例如。， `v0.1.0`)
**用途：**
Pull the latest image
docker pull ghcr.io/blghtr/c4a-mcp:latest
Run the container
docker run ghcr.io/blghtr/c4a-mcp:latest
**注：** 对于私有存储库，您需要进行身份验证：
Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
Pull the image
docker pull ghcr.io/blghtr/c4a-mcp:latest
### 本地Docker构建
要在本地构建Docker镜像：
Build the image
docker build -t c4a-mcp:local .
Run the container
docker run c4a-mcp:local
## 环境变量
MCP服务器本身不需要任何环境变量。但是，如果您计划在crawl4ai中使用基于LLM的提取策略，则可能需要为您选择的提供商设置API密钥：
### 可选LLM提供程序API密钥
- `OPENAI_API_KEY` -对于OpenAI模型（gpt-4o、gpt-4o-mini、o1-mini等）
- `ANTHROPIC_API_KEY` -适用于Anthropic模型（claude-3-5连接器等）
- `GEMINI_API_KEY` -适用于Google Gemini型号
- `GROQ_API_KEY` -对于Groq型号
- `DEEPSEEK_API_KEY` -对于DeepSeek模型
只有在爬网配置中使用基于LLM的提取策略时才需要这些。如果没有它们，服务器将正常工作，用于标准爬网。
### 使用.env文件
该项目使用 `python-dotenv`，因此您可以创建 `.env` 项目根目录中的文件：
OPENAI_API_KEY=your_key_here GEMINI_API_KEY=your_key_here
## 故障排除
### Playwright浏览器安装失败
**问题：** `playwright install` 失败或找不到浏览器。
**解决：**
1. **地方发展：**
# Run crawl4ai setup command uv run crawl4ai-setup
# Or manually install browsers uv run playwright install chromium
1. **Docker：**
- 确保Dockerfile包含所有必需的系统库（完整列表请参见Dockerfile）
- 验证Playwright安装步骤是否运行： `RUN playwright install --with-deps chromium`
1. **检查安装：**
uv run crawl4ai-doctor
### MCP连接问题
**问题：** 无法连接到MCP服务器或工具不可用。
**解决：**
1. **验证服务器是否正在运行：**
# Start the server uv run c4a-mcp
1. **检查MCP客户端配置：**
- 确保服务器命令指向： `c4a-mcp` 或 `python -m c4a_mcp`
- 验证传输方法（stdio、SSE等）是否与您的客户端匹配
1. **检查日志：**
- 启用调试日志记录以查看详细的错误消息
- 在服务器日志中查找连接错误
### Docker构建失败
**问题：** Docker构建失败，出现依赖或权限错误。
**解决：**
1. **清除构建缓存：**
docker build --no-cache -t c4a-mcp:local .
1. **检查系统依赖关系：**
- 确保所有Playwright系统库都包含在Dockerfile中
- 验证Python版本是否匹配（3.11+）
1. **权限问题：**
- Dockerfile现在以非root用户（appuser）身份运行
- 如果需要修改文件，请确保正确的所有权
1. **网络问题：**
- 检查是否可以访问PyPI和GitHub容器注册表
- 如果位于代理之后，请考虑使用构建时网络设置
### 测试失败
**问题：** 测试在CI/CD或本地失败。
**解决：**
1. **安装开发依赖关系：**
uv pip install --system -e ".[dev]"
1. **使用详细输出运行测试：**
uv run pytest -v
1. **检查Python版本：**
- 确保已安装Python 3.11+
- 3.11和3.12的CI/CD测试
### 预提交钩子失败
**问题：** 预提交钩子失败或跳过。
**解决：**
1. **更新挂钩：**
uv run pre-commit autoupdate
1. **手动运行：**
uv run pre-commit run --all-files
1. **跳过挂钩（不推荐）：**
git commit --no-verify