weknora-mcp 1.0.0__tar.gz

weknora_mcp-1.0.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# 更新日志
+
+所有重要的项目更改都将记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
+并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [1.0.0] - 2024-01-XX
+
+### 新增
+- 初始版本发布
+- WeKnora MCP Server 核心功能
+- 完整的 WeKnora API 集成
+- 空间管理工具
+- 知识库管理工具
+- 知识管理工具
+- 模型管理工具
+- 会话管理工具
+- 聊天功能工具
+- 块管理工具
+- 多种启动方式支持
+- 命令行参数支持
+- 环境变量配置
+- 完整的包安装支持
+- 开发和生产模式
+- 详细的文档和安装指南
+
+### 工具列表
+- `create_tenant` - 创建新空间
+- `list_tenants` - 列出所有空间
+- `create_knowledge_base` - 创建知识库
+- `list_knowledge_bases` - 列出知识库
+- `get_knowledge_base` - 获取知识库详情
+- `delete_knowledge_base` - 删除知识库
+- `hybrid_search` - 混合搜索
+- `create_knowledge_from_url` - 从 URL 创建知识
+- `list_knowledge` - 列出知识
+- `get_knowledge` - 获取知识详情
+- `delete_knowledge` - 删除知识
+- `create_model` - 创建模型
+- `list_models` - 列出模型
+- `get_model` - 获取模型详情
+- `create_session` - 创建聊天会话
+- `get_session` - 获取会话详情
+- `list_sessions` - 列出会话
+- `delete_session` - 删除会话
+- `chat` - 发送聊天消息
+- `list_chunks` - 列出知识块
+- `delete_chunk` - 删除知识块
+
+### 文件结构
+```
+WeKnoraMCP/
+├── __init__.py              # 包初始化文件
+├── main.py                  # 主入口点 (推荐)
+├── run.py                   # 便捷启动脚本
+├── run_server.py           # 原始启动脚本
+├── weknora_mcp_server.py   # MCP 服务器实现
+├── test_module.py          # 模组测试脚本
+├── requirements.txt        # 依赖列表
+├── setup.py               # 安装脚本 (传统)
+├── pyproject.toml         # 现代项目配置
+├── MANIFEST.in            # 包含文件清单
+├── LICENSE                # MIT 许可证
+├── README.md              # 项目说明
+├── INSTALL.md             # 详细安装指南
+└── CHANGELOG.md           # 更新日志
+```
+
+### 启动方式
+1. `python main.py` - 主入口点 (推荐)
+2. `python run_server.py` - 原始启动脚本
+3. `python run.py` - 便捷启动脚本
+4. `python weknora_mcp_server.py` - 直接运行
+5. `python -m weknora_mcp_server` - 模块运行
+6. `weknora-mcp-server` - 安装后命令行工具
+7. `weknora-server` - 安装后命令行工具 (别名)
+
+### 技术特性
+- 基于 Model Context Protocol (MCP) 1.0.0+
+- 异步 I/O 支持
+- 完整的错误处理
+- 详细的日志记录
+- 环境变量配置
+- 命令行参数支持
+- 多种安装方式
+- 开发和生产模式
+- 完整的测试覆盖
+
+### 依赖
+- Python 3.10+
+- mcp >= 1.0.0
+- requests >= 2.31.0
+
+### 兼容性
+- 支持 Windows、macOS、Linux
+- 支持 Python 3.10-3.12
+- 兼容现代 Python 包管理工具

weknora_mcp-1.0.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+RUN pip install --no-cache-dir -e .
+
+ENV MCP_HOST=0.0.0.0
+ENV MCP_PORT=8000
+ENV WEKNORA_BASE_URL=http://app:8080/api/v1
+# Set MCP_SERVER_AUTH_TOKEN at runtime; HTTP transport refuses to start without it.
+
+EXPOSE 8000
+
+CMD ["weknora-mcp-server", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

weknora_mcp-1.0.0/EXAMPLES.md

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