使用说明（Markdown 版本）

项目简介

Jarvis 是一个基于模型上下文协议（MCP）的后端服务集，旨在为大型语言模型客户端提供标准化的上下文信息、工具执行能力和提示模板渲染。它通过 JSON-RPC 与客户端通信，支持资源管理、工具注册与调用，以及提示模板渲染等功能。后端数据源以 Notion 数据库为主，提供灵活的数据存储与查询能力。系统还包含一个独立的 Agent 服务，用于将自然语言输入解析为 MCP 工具调用。

主要功能点

MCP 服务器：核心与协调单元，注册并暴露工具（如 add_transaction、split_paycheck、get_categories 等），通过 /mcp 接口以 JSON-RPC 2.0 协议处理请求。
Agent 服务：提供 /chat 端点，接收自然语言输入，借助 Gemini LLM 将输入转换为结构化的 MCP 调用请求，并通过 MCP 客工具执行。
工具与服务分层：transactions、payments、categories、budgets 等服务层实现具体业务逻辑，所有操作通过 MCP 工具注册暴露。
Notion 集成：Notion API 作为底层数据源，管理 Expenses、Income、Payments、Accounts、Categories、Budget Rules 等数据库，提供数据缓存、字段提取和实体关系处理。
传输与接口：MCP 服务器通过 HTTP JSON-RPC（/mcp）暴露工具调用，Agent 通过 HTTP（/chat）实现自然语言到工具调用的转换；支持 SSE 等未来扩展与多传输协议。
安全与健壮性：包含重复交易检测、清晰的错误处理、断路与优雅关闭逻辑，以及环境变量配置以分离开发与生产环境。

安装与运行

依赖环境
- Node.js 18+（用于运行 TypeScript/Node 服务）
- Notion 账号及 API Key
- Gemini API Key（用于 Agent 的自然语言理解/解析）
安装与编译
- 依赖项安装：npm install
- 运行 MCP 服务器：npm run mcp
- 运行 Agent 服务器：npm run agent
环境变量与数据源
- Notion API Key、各数据库 (Expenses, Income, Payments, Accounts, Categories, Budget Rules) 的数据库 ID
- Gemini API Key
- 可选：信用卡末四位等用于 LLM 匹配的额外变量
- 端口与 base URL（默认 MCP 3000、Agent 4000，MCP_BASE_URL 指向 MCP 服务器地址）
关键端点
- MCP 服务器：POST /mcp，JSON-RPC 请求格式用于调用注册的工具
- Agent 服务器：POST /chat，接收自然语言消息，返回解析结果与执行信息
- 健康/状态接口（如需要在实际环境中暴露健康状态）

服务器配置（给 MCP 客户端的连接配置说明，JSON 格式，非代码块，便于理解）

基本使用方法

启动顺序
1. MCP 服务器：运行命令 npm run mcp，按需配置环境变量后启动，监听端口通常为 3000。
2. Agent 服务器：在单独终端运行 npm run agent，端口通常为 4000，提供 /chat 接口来将自然语言转换为 MCP 调用。
客户端使用思路
- MCP 客户端直接通过 JSON-RPC 调用 /mcp 接口，执行已注册的工具（如 add_transaction、set_budget_rule 等）。
- 当需要对 natural language 进行解析时，客户端可以通过 Agent 的 /chat 端点提交自然语言文本，Agent 将返回一个带有 action 与 args 的 MCP 调用结构以及执行结果摘要。
本仓库实现的核心价值
- 为 LLM 客户端提供统一、可扩展的后端服务，用于资源管理、工具执行与提示渲染，帮助实现对话式商业场景中的自动化财务操作。

注意事项

Jarvis MCP 服务端 + Agent