WeKnora/mcp-server/EXAMPLES.md

WeKnora MCP Server 使用示例

本文档提供了 WeKnora MCP Server 的详细使用示例。

基本使用

1. 启动服务器

# 推荐方式 - 使用主入口点
python main.py

# 检查环境配置
python main.py --check-only

# 启用详细日志
python main.py --verbose

2. 环境配置示例

# 设置环境变量
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 工具的使用示例：

租户管理

创建租户

{
  "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"}
      ]
    }
  }
}

列出所有租户

{
  "tool": "list_tenants",
  "arguments": {}
}

知识库管理

创建知识库

{
  "tool": "create_knowledge_base",
  "arguments": {
    "name": "产品文档库",
    "description": "产品相关文档和资料",
    "embedding_model_id": "text-embedding-ada-002",
    "summary_model_id": "gpt-3.5-turbo"
  }
}

列出知识库

{
  "tool": "list_knowledge_bases",
  "arguments": {}
}

获取知识库详情

{
  "tool": "get_knowledge_base",
  "arguments": {
    "kb_id": "kb_123456"
  }
}

混合搜索

{
  "tool": "hybrid_search",
  "arguments": {
    "kb_id": "kb_123456",
    "query": "如何使用API",
    "vector_threshold": 0.7,
    "keyword_threshold": 0.5,
    "match_count": 10
  }
}

知识管理

从URL创建知识

{
  "tool": "create_knowledge_from_url",
  "arguments": {
    "kb_id": "kb_123456",
    "url": "https://docs.example.com/api-guide",
    "enable_multimodel": true
  }
}

列出知识

{
  "tool": "list_knowledge",
  "arguments": {
    "kb_id": "kb_123456",
    "page": 1,
    "page_size": 20
  }
}

获取知识详情

{
  "tool": "get_knowledge",
  "arguments": {
    "knowledge_id": "know_789012"
  }
}

模型管理

创建模型

{
  "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
  }
}

列出模型

{
  "tool": "list_models",
  "arguments": {}
}

会话管理

创建聊天会话

{
  "tool": "create_session",
  "arguments": {
    "kb_id": "kb_123456",
    "max_rounds": 10,
    "enable_rewrite": true,
    "fallback_response": "抱歉，我无法回答这个问题。",
    "summary_model_id": "gpt-3.5-turbo"
  }
}

获取会话详情

{
  "tool": "get_session",
  "arguments": {
    "session_id": "sess_345678"
  }
}

列出会话

{
  "tool": "list_sessions",
  "arguments": {
    "page": 1,
    "page_size": 10
  }
}

聊天功能

发送聊天消息

{
  "tool": "chat",
  "arguments": {
    "session_id": "sess_345678",
    "query": "请介绍一下产品的主要功能"
  }
}

块管理

列出知识块

{
  "tool": "list_chunks",
  "arguments": {
    "knowledge_id": "know_789012",
    "page": 1,
    "page_size": 50
  }
}

删除知识块

{
  "tool": "delete_chunk",
  "arguments": {
    "knowledge_id": "know_789012",
    "chunk_id": "chunk_456789"
  }
}

完整工作流程示例

场景：创建一个完整的知识问答系统

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

# 2. 在 MCP 客户端中执行以下步骤：

步骤 1: 创建租户

{
  "tool": "create_tenant",
  "arguments": {
    "name": "技术文档中心",
    "description": "公司技术文档知识管理",
    "business": "technology"
  }
}

步骤 2: 创建知识库

{
  "tool": "create_knowledge_base",
  "arguments": {
    "name": "API文档库",
    "description": "所有API相关文档"
  }
}

步骤 3: 添加知识内容

{
  "tool": "create_knowledge_from_url",
  "arguments": {
    "kb_id": "返回的知识库ID",
    "url": "https://docs.company.com/api",
    "enable_multimodel": true
  }
}

步骤 4: 创建聊天会话

{
  "tool": "create_session",
  "arguments": {
    "kb_id": "知识库ID",
    "max_rounds": 5,
    "enable_rewrite": true
  }
}

步骤 5: 开始对话

{
  "tool": "chat",
  "arguments": {
    "session_id": "会话ID",
    "query": "如何使用用户认证API？"
  }
}

错误处理示例

常见错误和解决方案

1. 连接错误

{
  "error": "Connection refused",
  "solution": "检查 WEKNORA_BASE_URL 是否正确，确认服务正在运行"
}

2. 认证错误

{
  "error": "Unauthorized",
  "solution": "检查 WEKNORA_API_KEY 是否设置正确"
}

3. 资源不存在

{
  "error": "Knowledge base not found",
  "solution": "确认知识库ID是否正确，或先创建知识库"
}

高级配置示例

自定义检索配置

{
  "tool": "hybrid_search",
  "arguments": {
    "kb_id": "kb_123456",
    "query": "搜索查询",
    "vector_threshold": 0.8,
    "keyword_threshold": 0.6,
    "match_count": 15
  }
}

自定义会话策略

{
  "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 的配置文件中添加：

{
  "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. 验证网络连接和防火墙设置