WeKnora/mcp-server/INSTALL.md

WeKnora MCP Server 安装和使用指南

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 设置环境变量

# Linux/macOS
export WEKNORA_BASE_URL="http://localhost:8080/api/v1"
export WEKNORA_API_KEY="your_api_key_here"

# Windows PowerShell
$env:WEKNORA_BASE_URL="http://localhost:8080/api/v1"
$env:WEKNORA_API_KEY="your_api_key_here"

# Windows CMD
set WEKNORA_BASE_URL=http://localhost:8080/api/v1
set WEKNORA_API_KEY=your_api_key_here

3. 运行服务器

有多种方式运行服务器：

方式 1: 使用主入口点 (推荐)

python main.py

方式 2: 使用原始启动脚本

python run_server.py

方式 3: 直接运行服务器模块

python weknora_mcp_server.py

方式 4: 作为 Python 模块运行

python -m weknora_mcp_server

作为 Python 包安装

开发模式安装

pip install -e .

安装后可以使用命令行工具：

weknora-mcp-server
# 或
weknora-server

生产模式安装

pip install .

构建分发包

# 构建源码分发包和轮子
python setup.py sdist bdist_wheel

# 或使用 build 工具
pip install build
python -m build

命令行选项

主入口点 main.py 支持以下选项：

python main.py --help                 # 显示帮助信息
python main.py --check-only           # 仅检查环境配置
python main.py --verbose              # 启用详细日志
python main.py --version              # 显示版本信息

环境检查

运行以下命令检查环境配置：

python main.py --check-only

这将显示：

• WeKnora API 基础 URL 配置
• API 密钥设置状态
• 依赖包安装状态

故障排除

1. 导入错误

如果遇到 ImportError，请确保：

• 已安装所有依赖：pip install -r requirements.txt
• Python 版本兼容（推荐 3.8+）
• 没有文件名冲突

2. 连接错误

如果无法连接到 WeKnora API：

• 检查 WEKNORA_BASE_URL 是否正确
• 确认 WeKnora 服务正在运行
• 验证网络连接

3. 认证错误

如果遇到认证问题：

• 检查 WEKNORA_API_KEY 是否设置
• 确认 API 密钥有效
• 验证权限设置

开发模式

项目结构

WeKnoraMCP/
├── __init__.py              # 包初始化文件
├── main.py                  # 主入口点
├── run_server.py           # 原始启动脚本
├── weknora_mcp_server.py   # MCP 服务器实现
├── requirements.txt        # 依赖列表
├── setup.py               # 安装脚本
├── MANIFEST.in            # 包含文件清单
├── LICENSE                # 许可证
├── README.md              # 项目说明
└── INSTALL.md             # 安装指南

添加新功能

1. 在 WeKnoraClient 类中添加新的 API 方法
2. 在 handle_list_tools() 中注册新工具
3. 在 handle_call_tool() 中实现工具逻辑
4. 更新文档和测试

测试

# 运行基本测试
python test_imports.py

# 测试环境配置
python main.py --check-only

# 测试服务器启动
python main.py --verbose

部署

Docker 部署

创建 Dockerfile：

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
RUN pip install -e .

ENV WEKNORA_BASE_URL=http://localhost:8080/api/v1
EXPOSE 8000

CMD ["weknora-mcp-server"]

系统服务

创建 systemd 服务文件 /etc/systemd/system/weknora-mcp.service：

[Unit]
Description=WeKnora MCP Server
After=network.target

[Service]
Type=simple
User=weknora
WorkingDirectory=/opt/weknora-mcp
Environment=WEKNORA_BASE_URL=http://localhost:8080/api/v1
Environment=WEKNORA_API_KEY=your_api_key
ExecStart=/usr/local/bin/weknora-mcp-server
Restart=always

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl enable weknora-mcp
sudo systemctl start weknora-mcp

支持

如果遇到问题，请：

1. 查看日志输出
2. 检查环境配置
3. 参考故障排除部分
4. 提交 Issue 到项目仓库: https://github.com/NannaOlympicBroadcast/WeKnoraMCP/issues