Cursor与Figma通信协议中的JSON解析问题分析与解决方案

问题背景

在sonnylazuardi开发的cursor-talk-to-figma-mcp项目中，多个用户报告了类似的错误现象：系统在尝试建立与Figma的通信连接时，控制台输出了"Unexpected token"错误信息。虽然部分功能(如加入频道)能够正常工作，但其他关键操作却无法执行。

错误现象分析

从用户报告的错误日志中可以观察到几个关键点：

1. 控制台显示"Unexpected token 'C'"错误，提示"Connecting"不是有效的JSON格式
2. 错误发生在JSON.parse解析过程中
3. 虽然报错，但部分基础功能(如加入频道)仍能工作
4. 错误导致后续操作无法正常执行

根本原因

经过技术分析，问题的根本原因在于：

1. 控制台输出干扰：服务器端代码中的console.log/console.error等调试输出被误认为是协议响应的一部分
2. 协议解析冲突：MCP(模型上下文协议)期望接收纯JSON格式的通信，但控制台输出混入了通信流
3. 非标准响应处理：当非JSON内容被当作响应解析时，会触发JSON.parse异常

解决方案

项目维护者通过以下方式解决了该问题：

1. 移除干扰性输出：清理了server.ts文件中所有不必要的console输出
2. 规范化协议通信：确保所有通信内容严格遵循JSON格式标准
3. 错误处理增强：增加了对非预期输入的容错处理

技术启示

这个案例为我们提供了几个重要的技术启示：

1. 调试输出需谨慎：在生产级通信协议实现中，控制台输出应谨慎使用或完全移除
2. 协议边界清晰：通信协议实现应严格区分调试信息和实际协议内容
3. 错误处理完整性：对于可能接收非预期输入的场景，应实现完善的错误处理机制

最佳实践建议

基于此问题的解决经验，建议开发类似通信协议时：

1. 使用专门的日志系统而非console输出
2. 实现协议内容的严格验证机制
3. 在开发和生产环境采用不同的输出策略
4. 对输入内容进行预处理和净化

这个问题虽然看似简单，但揭示了在实现通信协议时容易忽视的一个重要方面——协议纯净性。通过这次修复，项目不仅解决了当前问题，也为后续的协议扩展奠定了更坚实的基础。