Wealth Management MCP

财富管理MCP

一个独立的模型上下文协议（MCP）服务器 财富管理：投资组合健康分析、再平衡模拟和交易执行。建于 NitroStack 因此，您可以独立运行此模块，也可以将其集成到更大的人工智能辅助工作流程中。

______________________________________________________________________

总结

该服务器公开单个MCP工具， wealth_management，采取四项行动： 列表_客户 （样本客户的仪表板）， 健康分析, 模拟平衡，以及 execute_rebalance它连接到MongoDB（本地或Atlas）以获取投资组合数据，支持对投资组合集合进行可选的JSON模式验证，并演示了保护、缓存、速率限制和事件处理。非常适合需要投资组合见解和重新平衡工作流程的顾问、仪表板或人工智能代理。

______________________________________________________________________

技术栈

______________________________________________________________________

商业痛点

顾问和运营团队需要：

• 快速评估投资组合的健康状况，并偏离目标配置。
• 执行前模拟再平衡交易。
• 通过适当的控制（间隙、速率限制）执行重新平衡。

手动工作流程和分散的工具使这一过程缓慢且容易出错。该模块提供了一个单一的、有利于人工智能的API，因此助手和仪表板可以驱动从分析到执行的整个流程。

______________________________________________________________________

为什么选择NitroStack

• 一个工具，多个动作 --单身 wealth_management 工具与 action 参数；客户表面积较小，画布有限。
• 防护和限速 --经理权限和限制开启 execute_rebalance；健康/模拟保持自我服务。
• 缓存 --缓存健康结果，以避免重复数据库点击。
• 事件 — trade.executed 下游系统的排放（如审计、通知）。
• 最小样板 --专注于领域逻辑；NitroStack处理MCP协议、验证和接线。

______________________________________________________________________

解决方案架构

┌─────────────────┐     stdio / MCP      ┌──────────────────┐
│  Client (Studio, │ ◄──────────────────► │  Wealth Mgmt MCP │
│  AI, Dashboard)  │                      │  (this server)   │
└─────────────────┘                      └────────┬─────────┘
                                                  │
                      ┌───────────────────────────┼───────────────────────────┐
                      │                           │                           │
                      ▼                           ▼                           ▼
              wealth_management             DatabaseService              Events
              (health_analysis,             (MongoDB: local              (trade.executed)
               simulate_rebalance,           or Atlas)
               execute_rebalance)

• 工具： wealth_management --操作： list_customers, search_customers （MongoDB全文）， health_analysis, simulate_rebalance, execute_rebalance; clientId 需要最后三个。
• 数据： MongoDB；连接偏好 MONGODB_ATLAS_URI 当设置时，否则 MONGODB_URI.
• 播种： npm run seed:portfolios 创建 portfolios, governing_rules，以及 search_synonyms 收藏和a 文本索引 上 portfolios 搜索。

MongoDB搜索（客户仪表板）

客户仪表板使用MongoDB的 全文和聚合 功能通过 search_customers 动作：

拼写纠正（例如模糊匹配）可通过以下方式实现 MongoDB Atlas搜索；此模块使用核心服务器文本索引和同义词扩展。跑 npm run seed:portfolios 创建文本索引和种子同义词。

管理规则（HNI政策）

建议和再平衡建议如下 组织管理规则 存储在 governing_rules 收藏。这些政策确保财富分析人员在HNI的严格保护范围内：

健康分析和再平衡模拟都使用这些规则：建议文本引用了政策（例如，“根据政策，平衡客户的股权在40-60%以内”），只有当漂移超过阈值且交易规模达到最小值时，才会提出模拟交易。可以在MongoDB中编辑规则，以匹配您组织的合规性和风险偏好。

______________________________________________________________________

先决条件

• Node.js 18岁或以后

______________________________________________________________________

设置

npm install
cp .env.example .env

编辑 .env:

• 本地/Docker： 集 MONGODB_URI=mongodb://127.0.0.1:27018/mcp_wealth.离开 MONGODB_ATLAS_URI 空的。
• 阿特拉斯： 集 `MONGODB_ATLAS_URI=mongodb+srv://:

@.mongodb.net/mcp_wealth?retryWrites=true&w=majority`.

为数据库添加种子（创建 portfolios 和 governing_rules 包含样本数据的集合）：

npm run seed:portfolios

______________________________________________________________________

跑

发展

npm run dev

生产

npm run build
npm start

______________________________________________________________________

环境

______________________________________________________________________

如何部署

1. 构建： npm run build （输出单位： dist/).
2. 配置： 集 PORT, MONGODB_ATLAS_URI 或 MONGODB_URI 在环境中（或 .env).
3. 种子（一次）： 跑 npm run seed:portfolios 针对目标数据库。
4. 运行： node dist/index.js 或 npm start对于流程管理器（例如systemd、PM2），使用相同的命令并确保工作目录是项目根目录，以便 .env 并且路径正确解析。
5. 连接： 将您的MCP客户端（例如NitroStack Studio）指向此项目目录，使其使用相同的配置和依赖关系。

______________________________________________________________________

故障排除

连接失败/管道破裂（Nitro Studio）

如果Nitro Studio显示 “连接失败” 或 “5次尝试后初始化MCP连接失败：刷新stdin失败：管道破裂”，使用此检查表。

1. Nitro Studio中的项目路径必须是此模块文件夹

- 在Studio中，设置 项目路径 到包含以下内容的文件夹 package.json 和 src/ 对于这台服务器。 - 示例（财富管理）：\ .../NitroStack/module-repos/wealth-management - 做 不 指向父母 NitroStack 或 module-repos 文件夹；工作室必须运行 npm run dev （或等效物）从内部 wealth-management.

1. 检查引导错误日志

- 打开终端并运行（从此模块文件夹）：

     cd path/to/module-repos/wealth-management
     cat .mcp-bootstrap-error.log

- 如果文件存在，则它包含导致服务器退出的错误。先修复（例如缺失 .env，错误的MongoDB URI，正在使用的端口）。

1. 在终端中运行服务器 要查看stderr的实时状态：

   cd path/to/module-repos/wealth-management
   npm run dev

- 如果进程退出，则stderr上的最后一行是原因。 - 常见原因： - 缺失或不正确 .env --复制自 .env.example，set MONGODB_URI 或 MONGODB_ATLAS_URI. - 无法访问MongoDB——如果使用Colima run colima start那么 docker compose up -d 来自此文件夹；或修复Atlas URI/网络。 - 正在使用的端口--已设置 PORT 在 .env 连接到另一个端口（例如3001）。

1. 代码更改后重建

- 如果你改变了 src/，跑 npm run build （或依赖 npm run dev 其构建和监视）。然后尝试从Studio重新连接。

小部件显示无资产/“运行wealth_management…”或后端错误

如果 投资组合健康状况 小部件不显示资产列表（当前值、目标、手动调整），该工具通常返回错误而不是投资组合数据。

1. 检查刀具输出 在工作室：如果你看到 "status": "ERROR" 或 "message": "Database fetch failed..."，服务器无法从MongoDB读取。
2. 启动MongoDB （如果是本地的）：如果您使用Colima，请运行 colima start 第一。然后从该模块文件夹运行 docker compose up -d.
3. 为数据库添加种子： npm run seed:portfolios （创建 portfolios 收集和样本客户 client-IND-001, client-US-001, client-TECH-001).
4. 检查 .env: 集 MONGODB_URI 或 MONGODB_ATLAS_URI 正确并重新启动服务器。
5. 再次运行该工具 和 action: "health_analysis" 和 clientId: "client-IND-001"。然后，小部件应显示资产列表，包括当前值、推荐目标和手动覆盖的“您的目标”。

MongoDB/种子

• Docker（本地）： 从该模块文件夹运行 docker compose up -dMongoDB监听端口27018；集 MONGODB_URI 因此。

- 使用大肠杆菌： 先启动运行时(colima start)，然后运行 docker compose up -d 在这个文件夹中。

• 阿特拉斯： 在中使用完整的SRV字符串 MONGODB_ATLAS_URI它优先于 MONGODB_URI.

______________________________________________________________________

测试

有关分步测试计划（安装、种子、构建、运行、调用工具），请参阅 测试.md.

______________________________________________________________________

工具参考

______________________________________________________________________

许可证

MIT。看 许可证 在这个存储库中。

______________________________________________________________________

下一个增强功能

• 投资组合健康小部件 --添加a widgets/ 应用程序和构建 portfolio-health UI可以重新启用（例如从monorepo备份）。工具在没有它的情况下运行；Studio显示JSON输出。
• 真正的经纪人/OMS集成 execute_rebalance.
• 多租户和基于角色的访问（超出经理权限）。
• 可选REST/HTTP传输以及stdio。
• 再平衡模拟中的更多资产类别和约束。

______________________________________________________________________

贡献

欢迎捐款。请打开一个问题来讨论更大的更改，并确保测试和文档保持更新。提交更改时，保持相同的结构：1 wealth_management 带有操作的工具、用于持久化的MongoDB和NitroStack模式（保护、缓存、事件）。

______________________________________________________________________

结论

该模块提供了一个生产式财富管理MCP服务器，将分析、模拟和执行明确分离。您可以独立运行它，将其部署在现有堆栈旁边，或将其用作构建其他基于NitroStack的MCP服务器的参考。

有关NitroStack的更多信息： nitrostack.cn | 文档.