尧图网页设计 
PanWatch 手写轻量 JSON-RPC 的设计取舍为什么不用 MCP SDK【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatchPanWatch 是一款覆盖 A股、港股、美股的 AI 盯盘工具提供持仓分析、实时提醒与自动报告。除了前端界面它还内置了一个 MCPModel Context ProtocolServer让任意 AI 客户端都能通过标准的 JSON-RPC 2.0 协议调用 PanWatch 的只读工具。有意思的是这个 JSON-RPC 端点没有使用官方的 mcp SDK而是手写了不到 300 行代码。本文将拆解这一取舍背后的原因。MCP 端点能做什么PanWatch 把 5 个只读工具暴露为 MCP 端点get_portfolio持仓、get_stock_quote实时行情、get_technical_analysis技术面、get_stock_suggestionsAI 建议、get_watchlist自选股。你只需要在 MCP 客户端里填入{base}/mcp地址和一个 PAT 令牌就可以在自己的 AI 助手里问我的持仓健康吗AI 会自动调用get_portfolio拿到真实数据后作答。端点实现位于 src/modules/administration/api/mcp.py路由挂载见 src/bootstrap/application.py。为什么手写 JSON-RPC而不是引入 mcp SDK这是整个设计中最值得推敲的取舍。答案其实藏在那 5 个只读工具里。协议表面极小只需要 4 个方法PanWatch 的 MCP Server 是只读的它不需要 SDK 提供的会话管理、资源订阅、Prompt 模板、日志传输等一整套能力。实际用到的方法只有 4 个方法作用initialize协议握手返回协议版本与服务信息ping心跳tools/list工具发现tools/call执行工具对应代码就是 mcp_endpoint 里的几个if分支外加两个构造 JSON-RPC 响应的小函数_rpc_result/_rpc_error。协议表面越小攻击面和排查成本就越小——这是够用就好哲学的典型例子。顶层 /mcp 挂载绕开响应包装项目内所有/api/路由都会被ResponseWrapperMiddleware包装成{code, data, message}的统一结构。这对业务 API 是好事但会破坏 JSON-RPC 报文客户端期望的顶层字段是jsonrpc、id、result/error。因此 MCP 路由直接挂在顶层/mcp保证报文原样进出——这也是选 FastAPI 原生JSONResponse而非 SDK 高层封装的原因之一。鉴权用独立 PAT 体系与登录 JWT 分流MCP 端点不走登录态而是使用独立的个人访问令牌PAT体系实现见 src/modules/administration/pat.py令牌以pwmcp_为前缀32 字节随机熵约 256bit明文只在创建时返回一次库里只存 sha256 摘要校验使用hmac.compare_digest常数时间比较防时序攻击刻意不用bcrypt/PBKDF2——高熵随机令牌不像密码那样需要抗暴破而每次tools/call都要校验轻量更快scope 固定为mcp:read工具全只读天然安全边界普通 API 拒绝 PATMCP 端点拒绝 JWT两套凭证物理隔离互不渗透。每次调用都有审计日志每次tools/call都会落一条MCPCallLog审计记录工具名、状态、脱敏后的参数摘要字符串截断到 40 字符、总长 200 字符、耗时毫秒数、客户端 IP。日志保留 30 天由 server.py 注册的每日调度任务清理。审计写入走独立 session失败静默绝不影响主流程——这种防御式细节恰恰是手写代码才能精细控制的体现。工具不重写复用助手的同一套 schemaMCP 端点没有复制粘贴任何业务逻辑。工具定义与执行函数直接复用了 AI 助手使用的公开适配器 src/modules/assistant/tool_adapters.pyASSISTANT_TOOLS是 OpenAI function schemaexecute_tool是统一分发器。_mcp_tools()只做一次 schema 转换parameters→inputSchema白名单READ_TOOL_NAMES也从工具清单自动生成——新增工具自动纳入 MCP不会遗漏。这个传输层与工具层分离的结构意味着未来换一个宿主协议比如 WebSocket 或 stdio复用成本极低。测试自包含不触网的完整验证SDK 的另一个隐性成本是黑盒握手细节、错误码映射都由库内部处理出问题时排查链路长。PanWatch 的测试 tests/test_mcp_server.py 用内存 SQLite TestClient 覆盖了完整行为面initialize握手返回protocolVersion/capabilities/serverInfo缺少 Authorization → 401拿 JWT 进 MCP → 403隔离生效无效 / 已吊销的 PAT → 401 立即失效tools/call执行成功并落审计日志调用白名单外的工具 → 标准 JSON-RPC 参数错误码-32602通知类消息无id→ 202 无响应。另外还实现了一个容易被忽略的兼容细节MCP 客户端握手前会按 RFC 9728 探测/.well-known/oauth-protected-resource元数据。PanWatch 用的是静态 PAT 而非 OAuth server但仍提供该端点并返回authorization_servers: []明确告知客户端直接用 Bearer Header 即可否则客户端拿到 404 会因 schema 不匹配直接报错。见 src/bootstrap/application.py。小结好的取舍 最小依赖 × 可验证回顾一下这次手写 JSON-RPC的账本维度引入 mcp SDKPanWatch 手写方案依赖额外包及传递依赖零新增依赖代码量配置 适配层约 300 行协议表面全量能力仅 4 个方法可测试性依赖库内部行为自包含逐条可断言演进方向跟随 SDK 版本场景变了再升级核心结论当需求收敛到只读 4 个方法时SDK 带来的能力冗余大于其便利。PanWatch 的做法是把协议层JSON-RPC 报文与工具层schema dispatcher清晰分离——协议层手写保持最小可控工具层与 AI 助手共享保证不重复。模块全景可参考 src/ARCHITECTURE.mdPAT 管理 API 见 src/modules/administration/api/pats.py。这套取舍对所有自建 AI 数据接口的开发者都有参考价值先问我的协议表面有多小再决定要不要上 SDK。【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PanWatch 手写轻量 JSON-RPC 的设计取舍：为什么不用 MCP SDK
PanWatch 手写轻量 JSON-RPC 的设计取舍为什么不用 MCP SDK【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatchPanWatch 是一款覆盖 A股、港股、美股的 AI 盯盘工具提供持仓分析、实时提醒与自动报告。除了前端界面它还内置了一个 MCPModel Context ProtocolServer让任意 AI 客户端都能通过标准的 JSON-RPC 2.0 协议调用 PanWatch 的只读工具。有意思的是这个 JSON-RPC 端点没有使用官方的 mcp SDK而是手写了不到 300 行代码。本文将拆解这一取舍背后的原因。MCP 端点能做什么PanWatch 把 5 个只读工具暴露为 MCP 端点get_portfolio持仓、get_stock_quote实时行情、get_technical_analysis技术面、get_stock_suggestionsAI 建议、get_watchlist自选股。你只需要在 MCP 客户端里填入{base}/mcp地址和一个 PAT 令牌就可以在自己的 AI 助手里问我的持仓健康吗AI 会自动调用get_portfolio拿到真实数据后作答。端点实现位于 src/modules/administration/api/mcp.py路由挂载见 src/bootstrap/application.py。为什么手写 JSON-RPC而不是引入 mcp SDK这是整个设计中最值得推敲的取舍。答案其实藏在那 5 个只读工具里。协议表面极小只需要 4 个方法PanWatch 的 MCP Server 是只读的它不需要 SDK 提供的会话管理、资源订阅、Prompt 模板、日志传输等一整套能力。实际用到的方法只有 4 个方法作用initialize协议握手返回协议版本与服务信息ping心跳tools/list工具发现tools/call执行工具对应代码就是 mcp_endpoint 里的几个if分支外加两个构造 JSON-RPC 响应的小函数_rpc_result/_rpc_error。协议表面越小攻击面和排查成本就越小——这是够用就好哲学的典型例子。顶层 /mcp 挂载绕开响应包装项目内所有/api/路由都会被ResponseWrapperMiddleware包装成{code, data, message}的统一结构。这对业务 API 是好事但会破坏 JSON-RPC 报文客户端期望的顶层字段是jsonrpc、id、result/error。因此 MCP 路由直接挂在顶层/mcp保证报文原样进出——这也是选 FastAPI 原生JSONResponse而非 SDK 高层封装的原因之一。鉴权用独立 PAT 体系与登录 JWT 分流MCP 端点不走登录态而是使用独立的个人访问令牌PAT体系实现见 src/modules/administration/pat.py令牌以pwmcp_为前缀32 字节随机熵约 256bit明文只在创建时返回一次库里只存 sha256 摘要校验使用hmac.compare_digest常数时间比较防时序攻击刻意不用bcrypt/PBKDF2——高熵随机令牌不像密码那样需要抗暴破而每次tools/call都要校验轻量更快scope 固定为mcp:read工具全只读天然安全边界普通 API 拒绝 PATMCP 端点拒绝 JWT两套凭证物理隔离互不渗透。每次调用都有审计日志每次tools/call都会落一条MCPCallLog审计记录工具名、状态、脱敏后的参数摘要字符串截断到 40 字符、总长 200 字符、耗时毫秒数、客户端 IP。日志保留 30 天由 server.py 注册的每日调度任务清理。审计写入走独立 session失败静默绝不影响主流程——这种防御式细节恰恰是手写代码才能精细控制的体现。工具不重写复用助手的同一套 schemaMCP 端点没有复制粘贴任何业务逻辑。工具定义与执行函数直接复用了 AI 助手使用的公开适配器 src/modules/assistant/tool_adapters.pyASSISTANT_TOOLS是 OpenAI function schemaexecute_tool是统一分发器。_mcp_tools()只做一次 schema 转换parameters→inputSchema白名单READ_TOOL_NAMES也从工具清单自动生成——新增工具自动纳入 MCP不会遗漏。这个传输层与工具层分离的结构意味着未来换一个宿主协议比如 WebSocket 或 stdio复用成本极低。测试自包含不触网的完整验证SDK 的另一个隐性成本是黑盒握手细节、错误码映射都由库内部处理出问题时排查链路长。PanWatch 的测试 tests/test_mcp_server.py 用内存 SQLite TestClient 覆盖了完整行为面initialize握手返回protocolVersion/capabilities/serverInfo缺少 Authorization → 401拿 JWT 进 MCP → 403隔离生效无效 / 已吊销的 PAT → 401 立即失效tools/call执行成功并落审计日志调用白名单外的工具 → 标准 JSON-RPC 参数错误码-32602通知类消息无id→ 202 无响应。另外还实现了一个容易被忽略的兼容细节MCP 客户端握手前会按 RFC 9728 探测/.well-known/oauth-protected-resource元数据。PanWatch 用的是静态 PAT 而非 OAuth server但仍提供该端点并返回authorization_servers: []明确告知客户端直接用 Bearer Header 即可否则客户端拿到 404 会因 schema 不匹配直接报错。见 src/bootstrap/application.py。小结好的取舍 最小依赖 × 可验证回顾一下这次手写 JSON-RPC的账本维度引入 mcp SDKPanWatch 手写方案依赖额外包及传递依赖零新增依赖代码量配置 适配层约 300 行协议表面全量能力仅 4 个方法可测试性依赖库内部行为自包含逐条可断言演进方向跟随 SDK 版本场景变了再升级核心结论当需求收敛到只读 4 个方法时SDK 带来的能力冗余大于其便利。PanWatch 的做法是把协议层JSON-RPC 报文与工具层schema dispatcher清晰分离——协议层手写保持最小可控工具层与 AI 助手共享保证不重复。模块全景可参考 src/ARCHITECTURE.mdPAT 管理 API 见 src/modules/administration/api/pats.py。这套取舍对所有自建 AI 数据接口的开发者都有参考价值先问我的协议表面有多小再决定要不要上 SDK。【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考