内容
# Minecraft Wiki MCP 服务器
[](README.md) [](README_CN.md)
## 项目概述
基于 **MCP** 的 **Minecraft Wiki** 后端服务器，提供便捷的 Minecraft Wiki 内容访问服务。现在支持通过 **uvx** 快速部署，无需复杂配置。
注意：本项目仅提供示例 Minecraft Wiki API。如需本地 API 部署或 SSE 支持，请访问 [该项目](https://github.com/rice-awa/minecraft-wiki-fetch-api) 获取更多信息。
### 功能
- 🔍 **Wiki 内容搜索**：通过关键词搜索 Minecraft Wiki 页面
- 📄 **页面内容获取**：获取完整页面内容，支持 Wikitext、HTML 和 Markdown 格式
- 📝 **Wikitext 支持**：获取原始 Wiki 源代码（推荐用于 Token 效率）
- 📚 **批量页面获取**：高效批量获取多个页面
- ✅ **页面存在性检查**：快速检查页面是否存在
- 🏥 **健康监测**：监控后端 Wiki API 服务状态
- 🚀 **一键部署**：通过 uvx 快速安装和运行
- ⚙️ **环境变量**：灵活的配置，无需配置文件
- 💻 **命令行参数**：通过命令行参数覆盖配置
## 快速开始
### 🚀 推荐：使用 uvx
无需安装，直接运行：
```bash
# 基本用法（默认配置）
uvx mc-wiki-fetch-mcp
# 使用自定义 API URL
MC_WIKI_API_BASE_URL=http://localhost:3000 uvx mc-wiki-fetch-mcp
# 启用详细日志
MC_WIKI_LOG_LEVEL=DEBUG uvx mc-wiki-fetch-mcp
# 使用命令行参数
uvx mc-wiki-fetch-mcp --api-url http://localhost:3000 --log-level DEBUG
# 显示帮助信息
uvx mc-wiki-fetch-mcp --help
```
### 💻 与 Claude Desktop 集成
1. **查找配置文件位置：**
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**：`~/.config/claude/claude_desktop_config.json`
2. **编辑配置文件：**
```json
{
"mcpServers": {
"minecraft-wiki": {
"command": "uvx",
"args": ["mc-wiki-fetch-mcp"],
"env": {
"MC_WIKI_API_BASE_URL": "http://mcwiki.rice-awa.top"
}
}
}
}
```
3. **重启 Claude Desktop**
## 配置选项
### 环境变量配置
| 环境变量 | 描述 | 默认值 |
|-----------|-------------|---------------|
| `MC_WIKI_API_BASE_URL` | Wiki API 基地址 | `http://mcwiki.rice-awa.top` |
| `MC_WIKI_API_TIMEOUT` | API 请求超时（秒） | `30` |
| `MC_WIKI_API_MAX_RETRIES` | 最大重试次数 | `3` |
| `MC_WIKI_DEFAULT_FORMAT` | 默认输出格式 | `wikitext` |
| `MC_WIKI_DEFAULT_LIMIT` | 默认搜索结果数量 | `10` |
| `MC_WIKI_MAX_BATCH_SIZE` | 最大批量处理数量 | `20` |
| `MC_WIKI_MAX_CONCURRENCY` | 最大并发请求数 | `5` |
| `MC_WIKI_MCP_NAME` | MCP 服务器名称 | `Minecraft Wiki MCP (stdio)` |
| `MC_WIKI_MCP_DESCRIPTION` | MCP 服务器描述 | 自动生成 |
| `MC_WIKI_LOG_LEVEL` | 日志级别 | `INFO` |
### 命令行参数
```bash
uvx mc-wiki-fetch-mcp --help
```
| 参数 | 描述 |
|-----------|-------------|
| `--api-url` | Wiki API 基地址（覆盖环境变量） |
| `--timeout` | API 请求超时（秒） |
| `--max-retries` | 最大重试次数 |
| `--log-level` | 日志级别（DEBUG/INFO/WARNING/ERROR） |
| `--version` | 显示版本信息 |
| `--help` | 显示帮助信息 |
## 配置示例
### 基本配置示例
```bash
# 设置环境变量
export MC_WIKI_API_BASE_URL="http://localhost:3000"
export MC_WIKI_LOG_LEVEL="DEBUG"
# 运行服务器
uvx mc-wiki-fetch-mcp
```
### Claude Desktop 高级配置
```json
{
"mcpServers": {
"minecraft-wiki": {
"command": "uvx",
"args": [
"mc-wiki-fetch-mcp",
"--api-url", "http://localhost:3000",
"--log-level", "INFO"
],
"env": {
"MC_WIKI_DEFAULT_LIMIT": "20",
"MC_WIKI_MAX_BATCH_SIZE": "50"
}
}
}
}
```
## 传统安装（开发者）
如果需要修改代码或开发：
```bash
# 克隆仓库
git clone <repository-url>
cd mc-wiki-fetch-mcp
# 安装依赖
pip install -e .
# 运行
mc-wiki-fetch-mcp
```
## 🛠️ 可用工具
| 工具名称 | 描述 | 主要参数 |
|-----------|-------------|-----------------|
| `search_wiki` | 搜索 Wiki 内容 | `query`, `limit`, `namespaces` |
| `get_wiki_page` | 获取页面内容 | `page_name`, `format`（wikitext/html/markdown/both），`use_cache` |
| `get_wiki_pages_batch` | 批量获取页面 | `pages`, `format`, `concurrency` |
| `check_page_exists` | 检查页面存在性 | `page_name` |
| `check_wiki_api_health` | 健康检查 | 无参数 |
### 使用示例
#### 在 Claude Desktop 中使用
配置完成后，可以直接在 Claude Desktop 中提问：
```
请帮助我搜索关于红石的信息
获取钻石页面的详细内容
检查“红石电路”页面是否存在
批量获取“钻石”、“红石”和“附魔”页面的内容
```
## 🔧 高级配置
### 配置优先级
配置优先级顺序（从高到低）：
1. 命令行参数
2. 环境变量
3. 默认值
### 配置参数描述
| 参数 | 描述 | 默认值 | 可选值 |
|-----------|-------------|---------------|-----------------|
| API 基地址 | Wiki API 服务地址 | `http://mcwiki.rice-awa.top` | 任意有效 URL |
| 请求超时 | API 请求超时 | `30 秒` | 正整数（秒） |
| 最大重试次数 | 请求失败重试次数 | `3 次` | 正整数 |
| 默认格式 | 页面内容输出格式 | `wikitext` | `wikitext`, `html`, `markdown`, `both` |
| 搜索限制 | 默认搜索结果数量 | `10` | 1-50 |
| 批量处理数量 | 最大批量处理页面数量 | `20` | 1-100 |
| 并发请求数 | 最大并发请求数 | `5` | 1-20 |
### 日志配置
```bash
# 不同日志级别
MC_WIKI_LOG_LEVEL=DEBUG uvx mc-wiki-fetch-mcp # 详细调试信息
MC_WIKI_LOG_LEVEL=INFO uvx mc-wiki-fetch-mcp # 基本信息
MC_WIKI_LOG_LEVEL=WARNING uvx mc-wiki-fetch-mcp # 仅警告和错误
MC_WIKI_LOG_LEVEL=ERROR uvx mc-wiki-fetch-mcp # 仅错误
```
## 🐛 故障排除
### 常见问题
#### 1. uvx 命令未找到
**问题**：`uvx: command not found`
**解决方案**：
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或使用 pip
pip install uv
```
#### 2. 无法连接 Wiki API
**问题**：工具调用返回连接错误
**解决方案**：
1. 检查环境变量配置：
```bash
echo $MC_WIKI_API_BASE_URL
```
2. 测试 API 连接：
```bash
curl http://your-api-url/health
```
3. 启用详细日志：
```bash
MC_WIKI_LOG_LEVEL=DEBUG uvx mc-wiki-fetch-mcp
```
#### 3. Claude Desktop 中工具不可见
**问题**：配置后，MCP 工具在 Claude Desktop 中不可见
**解决方案**：
1. 确认 uvx 可用：
```bash
uvx mc-wiki-fetch-mcp --version
```
2. 检查 Claude Desktop 日志
3. 重启 Claude Desktop
### 调试提示
#### 启用详细日志
```bash
# 启动服务器并查看详细日志
MC_WIKI_LOG_LEVEL=DEBUG uvx mc-wiki-fetch-mcp 2>debug.log
# 查看日志
tail -f debug.log
```
#### 测试配置
```bash
# 测试特定配置
MC_WIKI_API_BASE_URL=http://localhost:3000 \
MC_WIKI_LOG_LEVEL=DEBUG \
uvx mc-wiki-fetch-mcp --help
```
#### 验证环境变量
```bash
# 检查当前环境变量
env | grep MC_WIKI
# 或在 Python 中检查
python -c "import os; print({k:v for k,v in os.environ.items() if k.startswith('MC_WIKI')})"
```
## 📖 相关文档
- [UVX 打包总结](docs/UVX_PACKAGING_SUMMARY.md) - UVX 打包和环境变量配置
- [API 文档](docs/API_DOCUMENTATION.md) - 详细 API 接口文档
- [使用指南](docs/USAGE_GUIDE.md) - 深入使用教程
- [项目完成总结](docs/PROJECT_COMPLETION_SUMMARY.md) - 项目开发总结
## 🤝 贡献
欢迎提交 Issues 和 Pull Requests 以改进项目！
## 📄 许可证
本项目使用 MIT 许可证。有关详细信息，请参见 [LICENSE](./LICENSE) 文件。
## 🆘 获取帮助
如果您遇到问题或需要帮助：
1. 检查此 README 的故障排除部分
2. 检查 [docs/](docs/) 目录中的详细文档
3. 提交一个 Issue 描述您的问题
4. 检查日志文件以获取详细的错误信息
---
**快速开始提示**：
- 🚀 **推荐**：使用 `uvx mc-wiki-fetch-mcp` 快速开始
- 💻 **Claude Desktop**：在配置中使用 `uvx` 命令和环境变量
- ⚙️ **自定义**：通过环境变量或命令行参数调整配置
- 🔧 **开发**：克隆仓库并使用 `pip install -e .` 进行开发
