mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-06-04 13:30:32 +08:00
feat: 添加了配套mcp服务器包
This commit is contained in:
言言学姐
lyingbug
411
mcp-server/EXAMPLES.md
Normal file
411
mcp-server/EXAMPLES.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# WeKnora MCP Server 使用示例
|
||||
|
||||
本文档提供了 WeKnora MCP Server 的详细使用示例。
|
||||
|
||||
## 基本使用
|
||||
|
||||
### 1. 启动服务器
|
||||
|
||||
```bash
|
||||
# 推荐方式 - 使用主入口点
|
||||
python main.py
|
||||
|
||||
# 检查环境配置
|
||||
python main.py --check-only
|
||||
|
||||
# 启用详细日志
|
||||
python main.py --verbose
|
||||
```
|
||||
|
||||
### 2. 环境配置示例
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export WEKNORA_BASE_URL="http://localhost:8080/api/v1"
|
||||
export WEKNORA_API_KEY="your_api_key_here"
|
||||
|
||||
# 或者在 .env 文件中设置
|
||||
echo "WEKNORA_BASE_URL=http://localhost:8080/api/v1" > .env
|
||||
echo "WEKNORA_API_KEY=your_api_key_here" >> .env
|
||||
```
|
||||
|
||||
## MCP 工具使用示例
|
||||
|
||||
以下是各种 MCP 工具的使用示例：
|
||||
|
||||
### 租户管理
|
||||
|
||||
#### 创建租户
|
||||
```json
|
||||
{
|
||||
"tool": "create_tenant",
|
||||
"arguments": {
|
||||
"name": "我的公司",
|
||||
"description": "公司知识管理系统",
|
||||
"business": "technology",
|
||||
"retriever_engines": {
|
||||
"engines": [
|
||||
{"retriever_type": "keywords", "retriever_engine_type": "postgres"},
|
||||
{"retriever_type": "vector", "retriever_engine_type": "postgres"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 列出所有租户
|
||||
```json
|
||||
{
|
||||
"tool": "list_tenants",
|
||||
"arguments": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 知识库管理
|
||||
|
||||
#### 创建知识库
|
||||
```json
|
||||
{
|
||||
"tool": "create_knowledge_base",
|
||||
"arguments": {
|
||||
"name": "产品文档库",
|
||||
"description": "产品相关文档和资料",
|
||||
"embedding_model_id": "text-embedding-ada-002",
|
||||
"summary_model_id": "gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 列出知识库
|
||||
```json
|
||||
{
|
||||
"tool": "list_knowledge_bases",
|
||||
"arguments": {}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取知识库详情
|
||||
```json
|
||||
{
|
||||
"tool": "get_knowledge_base",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 混合搜索
|
||||
```json
|
||||
{
|
||||
"tool": "hybrid_search",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456",
|
||||
"query": "如何使用API",
|
||||
"vector_threshold": 0.7,
|
||||
"keyword_threshold": 0.5,
|
||||
"match_count": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 知识管理
|
||||
|
||||
#### 从URL创建知识
|
||||
```json
|
||||
{
|
||||
"tool": "create_knowledge_from_url",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456",
|
||||
"url": "https://docs.example.com/api-guide",
|
||||
"enable_multimodel": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 列出知识
|
||||
```json
|
||||
{
|
||||
"tool": "list_knowledge",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456",
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取知识详情
|
||||
```json
|
||||
{
|
||||
"tool": "get_knowledge",
|
||||
"arguments": {
|
||||
"knowledge_id": "know_789012"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 模型管理
|
||||
|
||||
#### 创建模型
|
||||
```json
|
||||
{
|
||||
"tool": "create_model",
|
||||
"arguments": {
|
||||
"name": "GPT-4 Chat Model",
|
||||
"type": "KnowledgeQA",
|
||||
"source": "openai",
|
||||
"description": "OpenAI GPT-4 模型用于知识问答",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-...",
|
||||
"is_default": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 列出模型
|
||||
```json
|
||||
{
|
||||
"tool": "list_models",
|
||||
"arguments": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 会话管理
|
||||
|
||||
#### 创建聊天会话
|
||||
```json
|
||||
{
|
||||
"tool": "create_session",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456",
|
||||
"max_rounds": 10,
|
||||
"enable_rewrite": true,
|
||||
"fallback_response": "抱歉，我无法回答这个问题。",
|
||||
"summary_model_id": "gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取会话详情
|
||||
```json
|
||||
{
|
||||
"tool": "get_session",
|
||||
"arguments": {
|
||||
"session_id": "sess_345678"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 列出会话
|
||||
```json
|
||||
{
|
||||
"tool": "list_sessions",
|
||||
"arguments": {
|
||||
"page": 1,
|
||||
"page_size": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 聊天功能
|
||||
|
||||
#### 发送聊天消息
|
||||
```json
|
||||
{
|
||||
"tool": "chat",
|
||||
"arguments": {
|
||||
"session_id": "sess_345678",
|
||||
"query": "请介绍一下产品的主要功能"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 块管理
|
||||
|
||||
#### 列出知识块
|
||||
```json
|
||||
{
|
||||
"tool": "list_chunks",
|
||||
"arguments": {
|
||||
"knowledge_id": "know_789012",
|
||||
"page": 1,
|
||||
"page_size": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 删除知识块
|
||||
```json
|
||||
{
|
||||
"tool": "delete_chunk",
|
||||
"arguments": {
|
||||
"knowledge_id": "know_789012",
|
||||
"chunk_id": "chunk_456789"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 完整工作流程示例
|
||||
|
||||
### 场景：创建一个完整的知识问答系统
|
||||
|
||||
```bash
|
||||
# 1. 启动服务器
|
||||
python main.py --verbose
|
||||
|
||||
# 2. 在 MCP 客户端中执行以下步骤：
|
||||
```
|
||||
|
||||
#### 步骤 1: 创建租户
|
||||
```json
|
||||
{
|
||||
"tool": "create_tenant",
|
||||
"arguments": {
|
||||
"name": "技术文档中心",
|
||||
"description": "公司技术文档知识管理",
|
||||
"business": "technology"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 步骤 2: 创建知识库
|
||||
```json
|
||||
{
|
||||
"tool": "create_knowledge_base",
|
||||
"arguments": {
|
||||
"name": "API文档库",
|
||||
"description": "所有API相关文档"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 步骤 3: 添加知识内容
|
||||
```json
|
||||
{
|
||||
"tool": "create_knowledge_from_url",
|
||||
"arguments": {
|
||||
"kb_id": "返回的知识库ID",
|
||||
"url": "https://docs.company.com/api",
|
||||
"enable_multimodel": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 步骤 4: 创建聊天会话
|
||||
```json
|
||||
{
|
||||
"tool": "create_session",
|
||||
"arguments": {
|
||||
"kb_id": "知识库ID",
|
||||
"max_rounds": 5,
|
||||
"enable_rewrite": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 步骤 5: 开始对话
|
||||
```json
|
||||
{
|
||||
"tool": "chat",
|
||||
"arguments": {
|
||||
"session_id": "会话ID",
|
||||
"query": "如何使用用户认证API？"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理示例
|
||||
|
||||
### 常见错误和解决方案
|
||||
|
||||
#### 1. 连接错误
|
||||
```json
|
||||
{
|
||||
"error": "Connection refused",
|
||||
"solution": "检查 WEKNORA_BASE_URL 是否正确，确认服务正在运行"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 认证错误
|
||||
```json
|
||||
{
|
||||
"error": "Unauthorized",
|
||||
"solution": "检查 WEKNORA_API_KEY 是否设置正确"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 资源不存在
|
||||
```json
|
||||
{
|
||||
"error": "Knowledge base not found",
|
||||
"solution": "确认知识库ID是否正确，或先创建知识库"
|
||||
}
|
||||
```
|
||||
|
||||
## 高级配置示例
|
||||
|
||||
### 自定义检索配置
|
||||
```json
|
||||
{
|
||||
"tool": "hybrid_search",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456",
|
||||
"query": "搜索查询",
|
||||
"vector_threshold": 0.8,
|
||||
"keyword_threshold": 0.6,
|
||||
"match_count": 15
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义会话策略
|
||||
```json
|
||||
{
|
||||
"tool": "create_session",
|
||||
"arguments": {
|
||||
"kb_id": "kb_123456",
|
||||
"max_rounds": 20,
|
||||
"enable_rewrite": true,
|
||||
"fallback_response": "根据现有知识，我无法准确回答您的问题。请尝试重新表述或联系技术支持。"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
1. **批量操作**: 尽量批量处理知识创建和更新
|
||||
2. **缓存策略**: 合理设置搜索阈值以平衡准确性和性能
|
||||
3. **会话管理**: 及时清理不需要的会话以节省资源
|
||||
4. **监控日志**: 使用 `--verbose` 选项监控性能指标
|
||||
|
||||
## 集成示例
|
||||
|
||||
### 与 Claude Desktop 集成
|
||||
在 Claude Desktop 的配置文件中添加：
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"weknora": {
|
||||
"command": "python",
|
||||
"args": ["path/to/main.py"],
|
||||
"env": {
|
||||
"WEKNORA_BASE_URL": "http://localhost:8080/api/v1",
|
||||
"WEKNORA_API_KEY": "your_api_key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
项目仓库: https://github.com/NannaOlympicBroadcast/WeKnoraMCP
|
||||
|
||||
### 与其他 MCP 客户端集成
|
||||
参考各客户端的文档，配置服务器启动命令和环境变量。
|
||||
|
||||
## 故障排除
|
||||
|
||||
如果遇到问题：
|
||||
1. 运行 `python main.py --check-only` 检查环境
|
||||
2. 使用 `python main.py --verbose` 查看详细日志
|
||||
3. 检查 WeKnora 服务是否正常运行
|
||||
4. 验证网络连接和防火墙设置
|
||||
Reference in New Issue
Block a user