使用说明

项目简介

WealthWise 的 MCP 服务是一个基于 MCP（Model Context Protocol）的后端服务，负责将应用中的资源、工具及提示模板以标准化的 JSON-RPC 形式暴露给 AI 代理。它允许 AI 客户端读取资源、执行工具、以及获取/渲染提示，从而在代理驱动的交互中提供丰富的上下文信息与外部能力调用。

主要功能点

资源管理与查询：定义并暴露 4 种资源，提供元数据与聚合数据，供 AI 代理读取。
工具注册与执行：集成 35 个 MCP 工具，覆盖账户、交易、预算、目标、类别、 recurring、分析等领域，代理可通过工具与应用后端进行操作并获取结果。
多传输支持：支持 SSE 与 stdio 两种传输模式，便于不同部署场景的集成。
会话与鉴权：通过 JWT 进行鉴权，stdio 模式支持 MCP_USER_ID 指定用户。
基于 MVC 的结构分层：将配置、模型、工具、资源、传输、鉴权、日志等职责分离，便于维护与扩展。
测试覆盖：包含大量单元测试，覆盖工具、资源、工具调用流程等。

安装步骤

安装依赖与环境准备
- 确保已安装 Node.js 18+ 与 MongoDB 7+，并启动数据库。
- 将代码仓库安装所需依赖（仓库为多包工作区，建议按工作区方式安装）。
配置依赖与环境
- 创建并编辑环境变量（示例变量见下方服务器配置段落）。
- 需要的最小变量包括数据库连接、JWT 秘钥、MCP 端口、传输模式等。
启动 MCP 服务
- 在支持 Turborepo 的工作区环境中启动 MCP 服务组件，或按项目文档提供的启动命令启动 MCP 服务模块。
- MCP 服务器默认端口为 5100，传输模式可通过 MCP_TRANSPORT 设置为 sse 或 stdio。
验证
- 通过 MCP 客户端连接并列出工具/资源、执行某些工具以验证功能是否正常。

服务器配置（给 MCP 客户端的连接信息）

以下为示例配置信息（以 JSON 形式给出，供 MCP 客户端参考：不包含代码，仅描述必要参数与含义，实际参数请根据部署环境填写）：

{ "server_name": "wealthwise-mcp", "command": "npm", "args": ["run", "dev:mcp"], "description": "WealthWise MCP 服务启动命令，开发环境推荐使用", "env": { "MONGODB_URI": "mongodb://localhost:27017/wealthwise", "JWT_SECRET": "your-secure-32-char-jwt-key-for-prod", "MCP_PORT": "5100", "MCP_TRANSPORT": "sse" }, "notes": "- 对应 MCP_TRANSPORT 为 sse 时，客户端应通过 SSE 传输接入；若选择 stdio，请在运行时通过标准输入输出进行通信。- 对 stdio 模式，需要设置 MCP_USER_ID 指定当前用户 ID，用于工具调用的授权。" }

说明

server_name：服务器对外名称，与 MCP 客户端识别一致。
command / args：启动 MCP 服务的命令及参数，必须能够在目标部署环境中执行。
env：运行时所需的必需环境变量，包含数据库连接、鉴权密钥及 MCP 配置。
transport 相关的选择，以及 stdio 模式下的用户标识要求，请根据实际部署选择合适模式。

基本使用方法

连接与通信
- 按照 MCP 客户端文档，通过服务器地址（如 http(s)://<host>:5100 或本地的 stdio 阵列）建立连接。
- 发送 JSON-RPC 请求以调用工具、读取资源或获取资源元数据，服务器返回标准的 JSON-RPC 响应。
安全与鉴权
- 使用 JWT 进行鉴权，stdio 模式下需设置 MCP_USER_ID，SSE/HTTP 模式下通过 Bearer Token 进行认证。
会话管理
- MCP 服务器在启动时初始化，随后对会话进行维护，支持多用户并发使用。
扩展与维护
- 工具/资源的注册点集中在 mcp/src/tools 与 mcp/src/resources 目录，新增工具或资源时需遵循已有的工具定义规范与 Zod 校验。

WealthWise MCP Server