zhenzp/fund-mcp-server

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

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

HTTP REST API 配置

启动 HTTP 模式服务：

npm run start:http

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

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

SSE 模式配置

启动 SSE 模式服务：

npm run start:sse

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

环境变量配置

必需环境变量

创建 llm-config.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

环境变量说明

快速开始

🚀 一键部署

Windows 用户

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

Linux/macOS 用户

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

📦 手动部署

1. 安装依赖

   npm install
   

2. 构建项目

   npm run build
   

3. 启动服务

   # 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 部署

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

开发

安装依赖

npm install

开发模式

npm run watch

构建

npm run build

测试

npm test

服务管理

生产环境

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

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

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

Docker

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 重启服务
docker-compose restart

故障排除

常见问题

1. 端口被占用

   lsof -i :3000
   kill -9 <PID>
   

2. 权限问题

   chmod +x scripts/*.sh
   

3. 依赖问题

   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

使用方式：

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