ai-core-mcp-server 1.0.0__tar.gz

ai_core_mcp_server-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
+
+### 新增
+- 初始版本发布
+- Ai-Core MCP Server 核心功能
+- 完整的 Ai-Core 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` - 删除知识块
+
+### 文件结构
+```
+ai-core-mcp-server/
+├── __init__.py              # 包初始化文件
+├── main.py                  # 主入口点 (推荐)
+├── run.py                   # 便捷启动脚本
+├── run_server.py           # 原始启动脚本
+├── ai_core_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 ai_core_mcp_server.py` - 直接运行
+5. `python -m ai_core_mcp_server` - 模块运行
+6. `ai-core-mcp-server` - 安装后命令行工具
+7. `ai-core-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 包管理工具

ai_core_mcp_server-1.0.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
+
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/pip pip install -e .
+
+ENV AI_CORE_HOST=0.0.0.0
+ENV AI_CORE_PORT=8000
+ENV AI_CORE_BASE_URL=http://app:8080/api/v1
+# Set AI_CORE_AUTH_TOKEN at runtime; HTTP transport refuses to start without it.
+
+EXPOSE 8000
+
+CMD ["ai-core-mcp-server", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

ai_core_mcp_server-1.0.0/EXAMPLES.md

@@ -0,0 +1,410 @@
+# Ai-Core MCP Server 使用示例
+
+本文档提供了 Ai-Core MCP Server 的详细使用示例。
+
+## 基本使用
+
+### 1. 启动服务器
+
+```bash
+# 推荐方式 - 使用主入口点
+python main.py
+
+# 检查环境配置
+python main.py --check-only
+
+# 启用详细日志
+python main.py --verbose
+```
+
+### 2. 环境配置示例
+
+```bash
+# 设置环境变量
+export AI_CORE_BASE_URL="http://localhost:8080/api/v1"
+export AI_CORE_API_KEY="your_api_key_here"
+
+# 或者在 .env 文件中设置
+echo "AI_CORE_BASE_URL=http://localhost:8080/api/v1" > .env
+echo "AI_CORE_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": "检查 AI_CORE_BASE_URL 是否正确，确认服务正在运行"
+}
+```
+
+#### 2. 认证错误
+```json
+{
+  "error": "Unauthorized",
+  "solution": "检查 AI_CORE_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": {
+    "ai-core": {
+      "command": "python",
+      "args": ["path/to/main.py"],
+      "env": {
+        "AI_CORE_BASE_URL": "http://localhost:8080/api/v1",
+        "AI_CORE_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+
+### 与其他 MCP 客户端集成
+参考各客户端的文档，配置服务器启动命令和环境变量。
+
+## 故障排除
+
+如果遇到问题：
+1. 运行 `python main.py --check-only` 检查环境
+2. 使用 `python main.py --verbose` 查看详细日志
+3. 检查 Ai-Core 服务是否正常运行
+4. 验证网络连接和防火墙设置

ai_core_mcp_server-1.0.0/INSTALL.md

@@ -0,0 +1,207 @@
+# Ai-Core MCP Server 安装和使用指南
+
+## 快速开始
+
+### 1. 安装依赖
+```bash
+pip install -r requirements.txt
+```
+
+### 2. 设置环境变量
+```bash
+# Linux/macOS
+export AI_CORE_BASE_URL="http://localhost:8080/api/v1"
+export AI_CORE_API_KEY="your_api_key_here"
+
+# Windows PowerShell
+$env:AI_CORE_BASE_URL="http://localhost:8080/api/v1"
+$env:AI_CORE_API_KEY="your_api_key_here"
+
+# Windows CMD
+set AI_CORE_BASE_URL=http://localhost:8080/api/v1
+set AI_CORE_API_KEY=your_api_key_here
+```
+
+### 3. 运行服务器
+
+有多种方式运行服务器：
+
+#### 方式 1: 使用主入口点 (推荐)
+```bash
+python main.py
+```
+
+#### 方式 2: 使用原始启动脚本
+```bash
+python run_server.py
+```
+
+#### 方式 3: 直接运行服务器模块
+```bash
+python ai_core_mcp_server.py
+```
+
+#### 方式 4: 作为 Python 模块运行
+```bash
+python -m ai_core_mcp_server
+```
+
+## 作为 Python 包安装
+
+### 开发模式安装
+```bash
+pip install -e .
+```
+
+安装后可以使用命令行工具：
+```bash
+ai-core-mcp-server
+# 或
+ai-core-server
+```
+
+### 生产模式安装
+```bash
+pip install .
+```
+
+### 构建分发包
+```bash
+# 构建源码分发包和轮子
+python setup.py sdist bdist_wheel
+
+# 或使用 build 工具
+pip install build
+python -m build
+```
+
+## 命令行选项
+
+主入口点 `main.py` 支持以下选项：
+
+```bash
+python main.py --help                 # 显示帮助信息
+python main.py --check-only           # 仅检查环境配置
+python main.py --verbose              # 启用详细日志
+python main.py --version              # 显示版本信息
+```
+
+## 环境检查
+
+运行以下命令检查环境配置：
+```bash
+python main.py --check-only
+```
+
+这将显示：
+- Ai-Core API 基础 URL 配置
+- API 密钥设置状态
+- 依赖包安装状态
+
+## 故障排除
+
+### 1. 导入错误
+如果遇到 `ImportError`，请确保：
+- 已安装所有依赖：`pip install -r requirements.txt`
+- Python 版本兼容（推荐 3.10+）
+- 没有文件名冲突
+
+### 2. 连接错误
+如果无法连接到 Ai-Core API：
+- 检查 `AI_CORE_BASE_URL` 是否正确
+- 确认 Ai-Core 服务正在运行
+- 验证网络连接
+
+### 3. 认证错误
+如果遇到认证问题：
+- 检查 `AI_CORE_API_KEY` 是否设置
+- 确认 API 密钥有效
+- 验证权限设置
+
+## 开发模式
+
+### 项目结构
+```
+ai-core-mcp-server/
+├── __init__.py              # 包初始化文件
+├── main.py                  # 主入口点
+├── run_server.py           # 原始启动脚本
+├── ai_core_mcp_server.py   # MCP 服务器实现
+├── requirements.txt        # 依赖列表
+├── setup.py               # 安装脚本
+├── MANIFEST.in            # 包含文件清单
+├── LICENSE                # 许可证
+├── README.md              # 项目说明
+└── INSTALL.md             # 安装指南
+```
+
+### 添加新功能
+1. 在 `AiCoreClient` 类中添加新的 API 方法
+2. 在 `handle_list_tools()` 中注册新工具
+3. 在 `handle_call_tool()` 中实现工具逻辑
+4. 更新文档和测试
+
+### 测试
+```bash
+# 运行基本测试
+python test_imports.py
+
+# 测试环境配置
+python main.py --check-only
+
+# 测试服务器启动
+python main.py --verbose
+```
+
+## 部署
+
+### Docker 部署
+创建 `Dockerfile`：
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+RUN pip install -e .
+
+ENV AI_CORE_BASE_URL=http://localhost:8080/api/v1
+EXPOSE 8000
+
+CMD ["ai-core-mcp-server"]
+```
+
+### 系统服务
+创建 systemd 服务文件 `/etc/systemd/system/ai-core-mcp.service`：
+```ini
+[Unit]
+Description=Ai-Core MCP Server
+After=network.target
+
+[Service]
+Type=simple
+User=ai-core
+WorkingDirectory=/opt/ai-core-mcp
+Environment=AI_CORE_BASE_URL=http://localhost:8080/api/v1
+Environment=AI_CORE_API_KEY=your_api_key
+ExecStart=/usr/local/bin/ai-core-mcp-server
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启用服务：
+```bash
+sudo systemctl enable ai-core-mcp
+sudo systemctl start ai-core-mcp
+```
+
+## 支持
+
+如果遇到问题，请：
+1. 查看日志输出
+2. 检查环境配置
+3. 参考故障排除部分