npm package: @haoming06/knowledge-base-mcp-server
Description: MCP server for Knowledge Base system - Node.js implementation
Latest version: 0.1.2

# Knowledge Base MCP Server (Node.js)

这是一个基于 MCP (Model Context Protocol) 的知识库服务器 Node.js 实现，提供知识库管理、文档上传、检索等功能。

## 快速开始

### 方式一：使用 npx（最推荐，无需安装）

这是最简单的方式，无需全局或本地安装，直接通过 npx 运行：

#### Cursor 配置

在 Cursor 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "npx",
      "args": ["-y", "@wyseos/knowledge-base-mcp-server"],
      "env": {
        "AUTHORIZATION_TOKEN": "your-token-here",
        "SERVICE_BASE_URL": "http://localhost:4001"
      }
    }
  }
}
```

**优势：**
- ✅ 无需安装，npx 会自动下载并运行
- ✅ 自动使用最新版本
- ✅ 配置简单，一行命令即可

### 方式二：通过 npm 全局安装

#### 1. 安装包

```bash
npm install -g @wyseos/knowledge-base-mcp-server
```

#### 2. Cursor 配置

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "knowledge-base-mcp-server",
      "env": {
        "AUTHORIZATION_TOKEN": "your-token-here",
        "SERVICE_BASE_URL": "http://localhost:4001"
      }
    }
  }
}
```

### 方式三：作为项目依赖安装

#### 1. 安装包

```bash
npm install @wyseos/knowledge-base-mcp-server
```

#### 2. Cursor 配置

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": [
        "./node_modules/@wyseos/knowledge-base-mcp-server/server.js"
      ],
      "env": {
        "AUTHORIZATION_TOKEN": "your-token-here",
        "SERVICE_BASE_URL": "http://localhost:4001"
      }
    }
  }
}
```

### 环境变量说明

环境变量可以通过 Cursor 配置的 `env` 字段直接设置，也可以创建 `.env` 文件（如果从源码运行）：

```bash
# 知识库服务地址（可选，默认: http://localhost:4001）
SERVICE_BASE_URL=http://localhost:4001

# 授权令牌（必填）
AUTHORIZATION_TOKEN=your-token-here
```

### 方式二：从源码运行

#### 1. 克隆或下载项目

```bash
git clone <repository-url>
cd knowledge-base/mcp/node
```

#### 2. 安装依赖

```bash
npm install
```

#### 3. 配置环境变量

创建 `.env` 文件：

```bash
cp .env.example .env
# 编辑 .env 文件，设置 AUTHORIZATION_TOKEN 和 SERVICE_BASE_URL
```

#### 4. Cursor 配置

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": [
        "${workspaceFolder}/mcp/node/server.js"
      ],
      "env": {
        "AUTHORIZATION_TOKEN": "your-token-here",
        "SERVICE_BASE_URL": "http://localhost:4001"
      }
    }
  }
}
```

## 直接运行方式

### stdio 模式（默认，用于 Cursor 集成）

```bash
node server.js
# 或
npm start
```

### SSE 模式

```bash
node server.js --mode sse --host 127.0.0.1 --port 8000
```

### 环境变量配置

可以通过环境变量或 `.env` 文件配置：

- `SERVICE_BASE_URL`: 知识库服务地址（默认: `http://localhost:4001`）
- `AUTHORIZATION_TOKEN`: 授权令牌（必填）

## 注意事项

- 确保知识库服务（Go 服务）在 `http://localhost:4001` 运行（或配置的 `SERVICE_BASE_URL`）
- 确保 `AUTHORIZATION_TOKEN` 已正确配置
- Node.js 版本要求：>=18.0.0

## 故障排查

### 常见问题

1. **找不到模块**
   ```bash
   # 确保已安装依赖
   npm install
   ```

2. **授权失败**
   ```bash
   # 检查环境变量是否正确配置
   echo $AUTHORIZATION_TOKEN
   # 或检查 .env 文件
   cat .env
   ```

3. **连接失败**
   ```bash
   # 确保 Go 服务正在运行
   curl http://localhost:4001/health
   ```

4. **命令未找到**
   ```bash
   # 如果全局安装后仍找不到命令，检查 npm 全局路径
   npm config get prefix
   # 确保该路径在 PATH 环境变量中
   ```

## 与 Python 版本的对比

本 Node.js 版本与 Python 版本功能完全一致，所有工具函数和 API 接口保持一致。

## 发布到 npm

如果你想发布自己的版本：

```bash
# 1. 登录 npm
npm login

# 2. 更新版本号（可选）
npm version patch  # 或 minor, major

# 3. 发布
npm publish
```