# Enterprise Knowledge MCP

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的企业知识管理服务。

为大语言模型提供三个核心能力：

| 工具 | 功能 |
|------|------|
| `search_knowledge` | 语义搜索企业知识库 |
| `get_document` | 根据文档 ID 获取完整文档 |
| `search_cases` | 搜索企业项目案例 |

## 项目结构

```
enterprise-knowledge-mcp/
├── src/
│   └── enterprise_knowledge_mcp/
│       ├── __init__.py          # 包入口
│       ├── server.py            # MCP 工具注册（协议层）
│       └── retriever.py         # 检索逻辑（业务层）
├── tests/
│   ├── test_server.py           # 单元测试
│   └── test_e2e.py              # MCP Client 端到端测试
├── scripts/
│   ├── seed_data.py             # 导入示例数据到 ChromaDB
│   └── download_model.py        # 下载嵌入模型（离线环境用）
├── pyproject.toml
├── server.json                  # MCP 服务描述清单
├── README.md
└── LICENSE
```

## 架构设计

```
┌─────────────────────────────────────────┐
│  server.py  (协议层)                     │
│  - 注册 MCP Tool                        │
│  - 参数校验 & 输出格式化                  │
└──────────────┬──────────────────────────┘
               │ 调用
┌──────────────▼──────────────────────────┐
│  retriever.py  (业务层)                  │
│  - KnowledgeRetriever  知识库检索        │
│  - DocumentRetriever   文档检索          │
│  - CaseRetriever       案例检索          │
└──────────────┬──────────────────────────┘
               │ 替换实现
┌──────────────▼──────────────────────────┐
│  数据层（可插拔）                         │
│  - MockRetriever     开发/测试用          │
│  - ChromaRetriever   ChromaDB 向量检索   │
│  - 自定义 Retriever   ES / 数据库 / ...   │
└─────────────────────────────────────────┘
```

检索器采用**基类 + 实现**的可插拔设计。`server.py` 中只更换实例化对象即可切换后端，工具注册代码无需改动。

## 快速开始

### 安装

```bash
# 克隆仓库
git clone https://github.com/your-username/enterprise-knowledge-mcp.git
cd enterprise-knowledge-mcp

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/macOS

# 安装（开发模式）
pip install -e ".[dev]"
```

### 初始化 ChromaDB 数据

```bash
# 导入示例企业知识数据（知识库 5 条、文档 3 篇、案例 4 个）
python scripts/seed_data.py
```

### 运行服务

```bash
# Mock 模式（无需 ChromaDB 数据）
python -m enterprise_knowledge_mcp.server

# ChromaDB 模式（需先执行 seed_data.py）
RETRIEVER_BACKEND=chroma python -m enterprise_knowledge_mcp.server
```

### 运行测试

```bash
pytest tests/ -v
```

## 接入 MCP 客户端

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "enterprise-knowledge": {
      "command": "python",
      "args": ["-m", "enterprise_knowledge_mcp.server"],
      "cwd": "C:/path/to/enterprise-knowledge-mcp"
    }
  }
}
```

### Python SDK

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="python",
    args=["-m", "enterprise_knowledge_mcp.server"],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "search_knowledge", {"query": "人工智能"}
        )
        print(result.content[0].text)
```

## 自定义检索器

继承基类并实现 `retrieve` / `get_document` / `search_cases` 方法：

```python
from enterprise_knowledge_mcp.retriever import (
    KnowledgeRetriever,
    SearchResult,
)

class MyRetriever(KnowledgeRetriever):
    def retrieve(self, query: str, top_k: int = 5) -> list[SearchResult]:
        # 你的检索逻辑
        return [SearchResult(text="...", source="...", score=0.9)]
```

然后在 `server.py` 中替换：

```python
from .retriever import MyRetriever

knowledge_retriever = MyRetriever()
```

## 许可证

[MIT](LICENSE)