# Fund MCP Server

一个基于 Model Context Protocol (MCP) 的基金知识库服务器，提供基金相关知识的查询和检索功能1。

## 服务介绍

Fund MCP Server 是一个专门为基金投资领域设计的 MCP 服务器，通过集成外部知识库 API，为用户提供基金知识查询服务。该服务器支持多种部署模式，包括标准 MCP 协议、HTTP REST API 和 Server-Sent Events (SSE) 模式。

### 主要功能

- **基金知识查询**: 通过关键词搜索基金相关知识库
- **多协议支持**: 支持 MCP 标准协议、HTTP REST API 和 SSE
- **灵活部署**: 支持本地部署、Docker 部署和生产环境部署
- **跨平台**: 支持 Windows、Linux 和 macOS

### 技术特性

- 基于 TypeScript 开发，类型安全
- 使用 Zod 进行参数验证
- 支持环境变量配置
- 提供健康检查和监控接口

## 服务配置

### MCP sever configuration

```json
{
    "mcpServers": {
        "fund-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "fund-mcp-server"
            ]
        }
    }
}

```

### HTTP REST API 配置

启动 HTTP 模式服务：

```bash
npm run start:http
```

服务将在 `http://localhost:3000` 启动，提供以下 API 端点：

- `GET /api/health` - 健康检查
- `GET /api/tools` - 获取可用工具列表
- `POST /api/tools/call` - 调用工具

### SSE 模式配置

启动 SSE 模式服务：

```bash
npm run start:sse
```

SSE 端点：`http://localhost:3000/sse`

## 环境变量配置

### 必需环境变量

创建 `llm-config.env` 文件或设置以下环境变量：

```env
# 知识库 API 配置
FUND_KB_API_URL=https://report.haiyu.datavita.com.cn/api/admin/knowledge/query

# 服务端口配置
PORT=3000

# 运行环境
NODE_ENV=production

# MCP 传输模式 (可选: sse, http)
MCP_TRANSPORT=http
```

### 环境变量说明


| 变量名            | 默认值                                                           | 说明                |
| ----------------- | ---------------------------------------------------------------- | ------------------- |
| `FUND_KB_API_URL` | `https://report.haiyu.datavita.com.cn/api/admin/knowledge/query` | 基金知识库 API 地址 |
| `PORT`            | `3000`                                                           | 服务监听端口        |
| `NODE_ENV`        | `development`                                                    | 运行环境            |
| `MCP_TRANSPORT`   | `stdio`                                                          | MCP 传输模式        |

## 快速开始

### 🚀 一键部署

#### Windows 用户

```cmd
# 双击运行或在命令行执行
deploy.bat
```

#### Linux/macOS 用户

```bash
# 给脚本执行权限并运行
chmod +x deploy.sh
./deploy.sh
```

### 📦 手动部署

1. **安装依赖**

   ```bash
   npm install
   ```
2. **构建项目**

   ```bash
   npm run build
   ```
3. **启动服务**

   ```bash
   # HTTP 模式
   npm run start:http

   # SSE 模式
   npm run start:sse

   # 标准 MCP 模式
   npm start
   ```

## 部署选项

### 1. 快速部署 (开发环境)

- **Windows**: `deploy.bat` 或 `scripts\deploy.bat`
- **Linux/macOS**: `./deploy.sh` 或 `./scripts/deploy.sh`

### 2. 生产环境部署

- **Linux**: `./scripts/deploy-production.sh deploy`
- **systemd 服务**: 参考 `scripts/DEPLOYMENT.md`

### 3. Docker 部署

```bash
cd scripts
docker-compose up -d
```

### 4. 查看详细部署说明

- 查看 `scripts/README.md` 获取脚本说明
- 查看 `scripts/DEPLOYMENT.md` 获取详细部署指南

## 项目结构

```
fund-mcp-server/
├── deploy.bat                    # Windows 部署入口
├── deploy.sh                     # Linux/macOS 部署入口
├── scripts/                      # 部署脚本文件夹
│   ├── README.md                # 脚本说明
│   ├── DEPLOYMENT.md            # 详细部署指南
│   ├── deploy.sh                # Linux 快速部署
│   ├── deploy.bat               # Windows 快速部署
│   ├── deploy-production.sh     # 生产环境部署
│   ├── fund-mcp-server.service  # systemd 服务配置
│   ├── Dockerfile               # Docker 镜像
│   └── docker-compose.yml       # Docker Compose
├── tool-registry/               # 工具注册表
├── tool-handlers/               # 工具处理器
├── common/                      # 公共模块
├── dist/                        # 构建输出
└── package.json                 # 项目配置
```

## 端口配置

默认端口：3000

- 环境变量：`PORT=8080`
- 命令行：`--port 8080`

## 开发

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run watch
```

### 构建

```bash
npm run build
```

### 测试

```bash
npm test
```

## 服务管理

### 生产环境

```bash
# 查看状态
./scripts/deploy-production.sh status

# 查看日志
./scripts/deploy-production.sh logs

# 重启服务
./scripts/deploy-production.sh restart
```

### Docker

```bash
# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 重启服务
docker-compose restart
```

## 故障排除

### 常见问题

1. **端口被占用**

   ```bash
   lsof -i :3000
   kill -9 <PID>
   ```
2. **权限问题**

   ```bash
   chmod +x scripts/*.sh
   ```
3. **依赖问题**

   ```bash
   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install
   ```

### 日志位置

- 应用日志：`logs/fund-mcp-server.log`
- 错误日志：`logs/fund-mcp-server-error.log`

## 贡献

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 许可证

Apache-2.0

## 支持

- 📖 部署文档：`scripts/DEPLOYMENT.md`
- 🐛 问题反馈：GitHub Issues
- 💬 讨论：GitHub Discussions

## 自动发布到 npm

当你推送版本标签（如 `v0.1.1`）时，仓库会使用 GitHub Actions 自动发布到 npm。

前置准备：

- 在 npm 创建 Automation Token，并在 GitHub 仓库 `Settings` → `Secrets and variables` → `Actions` 中添加：
  - 名称：`NPM_TOKEN`
  - 值：你的 npm Automation Token

使用方式：

```bash
npm version patch   # 或 minor/major
git push --follow-tags
# 或者显式推送标签
# git push origin v0.1.1
```

工作流位于 `.github/workflows/publish-on-tag.yml`，规则：

- 触发条件：推送 `v*.*.*` 标签
- 步骤：安装依赖 → 构建 → 将 `package.json` 版本对齐标签 → `npm publish --access public`