Fishbowl MCP Server

Fishbowl MCP Server

用于与 Fishbowl Inventory API 集成的中间件服务。

概述

此 MCP（消息控制程序）服务提供 RESTful API，可与您的 Fishbowl Inventory 软件通信。它负责身份验证和令牌管理，并将所有请求代理到 Fishbowl API。

功能

• 自动通过 Fishbowl API 进行身份验证
• 简化对 Fishbowl 功能的 API 访问
• 支持零件、库存、采购订单和制造订单
• 管理采购订单和制造订单的备注
• 提供供应商、计量单位、用户和产品端点

前提条件

• Node.js 18 或更高版本
• 可访问 API 的 Fishbowl Inventory 软件
• Fishbowl 访问凭据

本地开发设置

1. 克隆此代码库：

   git clone https://your-repo-url/fishbowl-mcp-server.git
   cd fishbowl-mcp-server
   

2. 安装依赖：

   npm install
   

3. 根据模板创建 .env 文件：

   cp .env.template .env
   

4. 编辑 .env 文件，填写您的 Fishbowl 凭据和 API URL。

5. 启动开发服务：

   npm run dev
   

部署到 Railway

1. 如果您还没有 Railway 账户，请前往 railway.app 创建一个。

2. 安装 Railway CLI：

   npm i -g @railway/cli
   

3. 登录 Railway：

   railway login
   

4. 初始化项目：

   railway init
   

5. 添加环境变量：

   railway variables set FISHBOWL_API_URL=http://your-fishbowl-server-address:port
   railway variables set FISHBOWL_APP_NAME="MCP Server"
   railway variables set FISHBOWL_APP_ID=101
   railway variables set FISHBOWL_USERNAME=your-username
   railway variables set FISHBOWL_PASSWORD=your-password
   

6. 部署应用：

   railway up
   

7. 打开已部署的应用：

   railway open
   

API 端点

身份验证

• POST /api/login - 登录 Fishbowl API
• POST /api/logout - 从 Fishbowl API 登出

零件与库存

• GET /api/parts - 搜索零件
• GET /api/parts/inventory - 获取零件库存
• GET /api/parts/:id/best-cost - 获取零件的最低成本
• POST /api/parts/:id/inventory/add - 为零件添加库存
• POST /api/parts/:id/inventory/cycle - 盘点库存
• POST /api/parts/:id/inventory/scrap - 报废库存

采购订单

• GET /api/purchase-orders - 列出采购订单
• GET /api/purchase-orders/:id - 按 ID 获取采购订单
• POST /api/purchase-orders - 创建采购订单
• POST /api/purchase-orders/:id - 更新采购订单
• POST /api/purchase-orders/:id/issue - 下达采购订单
• POST /api/purchase-orders/:id/unissue - 撤销下达采购订单
• POST /api/purchase-orders/:id/close-short - 缺量关闭采购订单
• POST /api/purchase-orders/:id/void - 作废采购订单
• DELETE /api/purchase-orders/:id - 删除采购订单

制造订单

• GET /api/manufacture-orders - 列出制造订单
• GET /api/manufacture-orders/:id - 按 ID 获取制造订单
• POST /api/manufacture-orders - 创建制造订单
• POST /api/manufacture-orders/:id/issue - 下达制造订单
• POST /api/manufacture-orders/:id/unissue - 撤销下达制造订单
• POST /api/manufacture-orders/:id/close-short - 缺量关闭制造订单
• DELETE /api/manufacture-orders/:id - 删除制造订单

备注

• GET /api/{type}/:id/memos - 获取采购订单或制造订单的备注
• GET /api/{type}/:id/memos/:memoId - 获取指定备注
• POST /api/{type}/:id/memos - 创建备注
• POST /api/{type}/:id/memos/:memoId - 更新备注
• DELETE /api/{type}/:id/memos/:memoId - 删除备注

其中，{type} 可以是 purchase-orders 或 manufacture-orders

其他端点

• GET /api/products/:id/best-price - 获取产品的最低价格
• GET /api/uoms - 列出计量单位
• GET /api/vendors - 列出供应商
• GET /api/users - 列出用户
• GET /api/health - 检查服务运行状况和身份验证状态

安全注意事项

• 使用环境变量安全地存储 Fishbowl 凭据
• 在生产环境中使用 HTTPS 加密传输中的数据
• 服务会自动处理身份验证令牌，但请注意令牌会过期
• 考虑在生产环境中为 MCP 服务添加额外的身份验证

故障排除

常见问题

1. 身份验证失败：

   • 检查 .env 文件中的 Fishbowl 凭据
   • 确保 Fishbowl API 已启用且可访问
   • 检查你的 Fishbowl 用户是否拥有相应权限

2. 连接错误：

   • 确认 FISHBOWL_API_URL 正确
   • 确保 Fishbowl 服务正在运行，且 MCP 服务可以访问它
   • 检查是否存在防火墙或网络限制

3. 在 Railway 上部署的问题：

   • 确认所有环境变量均已正确设置
   • 检查日志中是否有错误：railway logs
   • 确保你的 Railway 项目有足够的资源

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 ISC 许可证。