注册辅助MCP
SignupAssist MCP（模型上下文协议）是一个人工智能驱动的助手，用于以安全、对话的方式查找和完成活动注册。它专注于注册工作流程，不提供成人、约会或NSFW服务。 生产流程使用提供商HTTP API（Bookeo） 用于目录同步、表单发现和预订——在明确的用户授权、审计日志和范围检查下。SignupAssist旨在与ChatGPT的会话界面集成，强调清晰度、授权和安全性。
设计原则（ChatGPT原生用户体验和安全）
聊天原生流：所有交互都是通过自然的来回聊天进行的。助理首先解释或提问，然后在卡片上展示信息或选项，最后等待用户确认后再继续。这种对话模式（解释→ card → confirm）保持了直观的体验，避免了破坏性的模态或外部弹出窗口，符合ChatGPT对会话应用程序的指导方针。
SDK组件纯度：UI仅使用ChatGPT的内置界面组件，如消息气泡、用于选项的卡片/旋转木马、用于输入的短表单、确认对话框和状态芯片，没有外部web视图或自定义对话框。通过坚持ChatGPT SDK的原生元素，该应用程序仍然完全可访问、响应迅速，并符合ChatGPT app Store的要求。
“写入”的明确确认：在执行任何不可逆的操作（如安排注册或收取付款）之前，助手总是会显示一张总结操作的确认卡，并要求用户明确确认。这种“无意外行动”的保证是为了安全而强制要求的——用户必须明确同意任何外部影响，如提交表格或付款。
用户友好的语气和安全消息：助手以友好、令人放心的语气进行沟通，注意忙碌的用户（简洁、乐于助人、非技术性）。在每一个重要步骤中，它都强调安全性——例如，提醒用户他们的凭据和支付详细信息在受信任的提供商或Stripe处是安全的，并且SignupAssist从不存储敏感的卡号。这些保证有助于建立信任，满足隐私和合规标准。
审计跟踪和“责任委托”透明度：SignupAssist在责任委托模式下运作。它只在父母明确同意的情况下行事，并记录它代表用户采取的每一个行动。此审计跟踪意味着任何登录、表单填写或提交都会记录时间戳和详细信息，以便用户（和审阅者）可以准确地跟踪助手的操作。这种透明度是应用程序精神的核心，并通过温和的提醒向用户显示“所有操作都会记录下来供您查看”。
一致的视觉节奏和层次：流程中的每一步都遵循相同的可预测视觉结构，以便于理解。模式是：助理的解释文本，然后是一张卡片（带有详细信息、选项或表单输入），然后是明确的行动呼吁（例如确认按钮）。按钮样式和颜色等设计元素保持一致（主要动作与次要动作），以在整个应用程序中保持连贯的视觉层次结构。用户可以快速识别流程的各个阶段，从而提高可用性和信任度。
（这些设计原则确保应用程序感觉像是ChatGPT的自然扩展，并通过优先考虑清晰度、同意和用户控制来满足OpenAI的审查指南。）
技术特征和架构
API第一个提供程序： 程序目录和注册流通过记录的HTTP API（例如。 Bookeo 产品、可用性和预订）。Supabase边缘函数，如 sync-bookeo 保持 cached_provider_feed 按照时间表更新。
授权范围执行： 行动由已签署的授权书（范围、上限、到期）控制。MCP服务器和边缘功能记录工具使用情况，以实现可审计性。
A-A-P变窄： 编排器会提前按年龄、活动和提供者缩小范围，以便搜索保持专注。
缓存： 缓存提要行和发现提示，以保持聊天速度；过时的数据通过定时同步进行刷新。
遥测和记录： 工具调用、同步作业和编排器步骤会生成用于调试和操作的结构化日志。
安全和数据隐私： 敏感值位于Supabase/Stripe中，具有最低权限访问；UI避免收集超过当前步骤所需的数据。
未来： 随着API的成熟，更深入的提供商OAuth和可验证的委托仍然在路线图上。
入门（开发设置）
要设置SignupAssist MCP项目进行开发或测试，请执行以下步骤：
先决条件：确保你的系统上安装了Node.js 20.x和包管理器（npm或yarn） GitHub .您还需要访问Subabase实例（用于数据库和边缘函数）和所使用的任何外部服务的API密钥（详细信息如下）。
克隆存储库：将此存储库克隆到本地计算机并导航到项目目录。然后安装NPM依赖项：
克隆https://github.com/YourOrg/signupassist-mcp.git cd注册助理mcp npm 安装
配置环境变量：在项目根目录中复制或创建.env文件以提供必要的配置。至少，使用您的凭据设置以下变量：
OpenAI API密钥：OpenAI_API_Key（AI Orchestrator的语言模型调用所必需） GitHub
型号选择：OPENAI_Model（可选，默认为GPT-4等合适的型号） GitHub
Supabase连接：Supabase_URL和Supabase_SERVICE_ROLE_KEY（用于数据库和存储访问） GitHub .你应该建立一个Supabase项目；使用您的实例中的URL和服务角色API密钥。
Google Places API密钥：用于基于位置的提供商搜索回退的Google_Places_API_Key GitHub .（在Google Cloud中启用Google Places API并将您的密钥放在此处；如果提供商提要不包含位置查询，则使用此选项）。
其他密钥：如果您的部署使用任何其他服务（用于通知的电子邮件/短信、用于支付的Stripe等），请根据需要提供这些密钥。例如，用于支付处理的STRIPE_API_KEY（如果适用），以及用于支持OAuth的提供商集成的任何OAuth客户端机密。
有关所需变量及其描述的完整列表，请参阅铁路部署指南或环境文档 GitHub 。以上是入门的主要内容。
运行开发服务器：此项目涉及后端MCP服务器和前端接口：
启动MCP服务器：这将运行执行自动化任务的核心后端（Node/Express服务器）。用途：
npm运行mcp：服务器
这将构建并启动MCP服务器（默认情况下在端口8080上）。它连接到数据库并等待工具调用请求。
启动前端（测试工具）：对于开发，您可以运行Vite-dev服务器来使用提供的类似ChatGPT的测试工具UI。在单独的终端中，运行：
npm 运行开发
这将启动本地开发服务器（通常在http://localhost:5173).在该服务器上打开浏览器/聊天测试以访问聊天测试线束界面 GitHub 。测试工具模拟ChatGPT环境，并允许您在聊天UI中与SignupAssist交互以进行调试。（有关线束的详细用法、演示流程和故障排除，请参阅docs/CHAT_TEST_HARNES_USER_GUIDE.md。）
Supabase设置：部署必要的Supabase边缘功能和数据库架构：
存储库的suabase/目录包含任何自定义的Postgres函数或边缘函数（例如用于安全凭证检索的cred-get和用于cron维护的维护发现）。按照docs/PRODUCTION_BACKEND_SETUP.md和Supabase文档中的说明部署这些。对于本地开发，您可以使用Supabase CLI或将您的应用程序连接到远程Supabase项目。确保根据项目的迁移文件设置数据库表（例如，用于授权、审计日志、会话等）。
凭证存储：使用cred-get函数或类似的安全机制来存储和检索用户凭证（活动提供者的登录信息）。MCP服务器在需要登录时调用此函数，因此必须部署并可访问。它还会记录作为审计跟踪的一部分访问凭据的时间 GitHub .
验证：如果在本地运行而没有完整的Supabase设置，您可能会禁用某些功能或使用文档中描述的use_REAL_MCP=false模式（使用模拟数据） GitHub 然而，为了获得完整的功能，建议配置Supabase后端。
测试流程：在服务器和前端运行并配置环境的情况下，您可以模拟注册对话。例如，在聊天UI中，尝试“为我8岁的孩子查找AIM设计类”，然后按照提示进行操作。助理应按照配置完成提供商选择、程序搜索、先决条件和预订步骤。使用测试线束中的调试面板实时查看工具调用和响应 GitHub GitHub 这对于开发和验证每个步骤（登录、查找程序、检查请求等）是否按预期工作非常有用。
部署
当您准备在生产或测试环境中部署SignupAssist MCP时，该项目支持通过容器化或平台即服务进行云部署：
Docker/容器部署：提供了一个Dockerfile来将应用程序构建到生产容器映像中。它安装依赖项，编译TypeScript代码，构建前端，然后在端口8080上启动Node服务器。您可以使用此Dockerfile在任何基于容器的服务或您自己的基础设施上进行部署。例如：
docker build-t注册辅助mcp：最新版本。 docker run-p 8080:8080--env文件.env注册辅助mcp：最新
确保容器中配置了.env或环境变量（包括如上所述的数据库URL、键等）。
Railway.app（PaaS）：该项目旨在在Railway（或类似的Node托管平台）上轻松部署。该存储库包括一个铁路配置指南。总之：
将代码推送到您的存储库，并将Railway项目连接到它。Railway将检测到Node.js项目并使用指定的start命令（默认情况下，它运行npm run build，然后运行npm run mcp:start） GitHub .
在Railway仪表板中设置所需的环境变量（OpenAI键、Supabase键等） GitHub 。这与您在本地使用的匹配。
在您的Supabase实例上部署Supabase边缘函数（如果您还没有），并更新生产环境变量中的任何端点/键。例如，确保SUPABASE_URL和SUPABASE_SERVICE_ROLE_KEY与您的生产SUPABASE项目相对应，并且MCP_SERVER_URL（如果由前端或其他服务使用）指向您的Railway应用程序的URL GitHub GitHub .
部署后，您应该看到MCP服务器正在运行。前端（如果包括在内）将从同一服务器（dist/client中的静态文件）提供服务。然后，如果这是一个官方插件，您可以通过ChatGPT界面与实时应用程序进行交互，如果公开了它，您也可以通过web UI进行交互。
ChatGPT应用商店注意事项：如果部署为ChatGPT插件或应用程序，请确保仔细检查OpenAI插件清单（如果有的话），并确保您的OAuth回调、端点等配置正确。README强调确认、安全和数据处理，旨在简化审批过程。准备好向OpenAI提供测试证书或演示帐户以供任何审查，因为他们希望验证端到端流程。（所有的设计原则，如行动前明确的用户确认、无敏感数据保留和清晰的用户消息传递，对于通过审查至关重要。）
维护（发现数据维护）
随着时间的推移，提供者数据和学习表单提示可能会变得过时。SignupAssist包括一个自动维护例行程序，用于发现数据，以保持系统高效和最新 GitHub 此例程被实现为一个Supabase边缘函数（名为维护发现），该函数通过Postgres cron扩展按计划触发：
它的作用：每次维护运行都会对“发现学习”系统进行内务管理，该系统是缓存字段提示和程序发现结果的组件。具体来说，cron作业：
刷新“最佳提示”-更新表单字段提示或特定于提供程序的数据提取提示的缓存。（目前这是一个无操作占位符，意味着逻辑已经到位，但还没有主动更改提示。） GitHub 这是为了适应未来的改进，系统可能会随着时间的推移学习更好的表单填写策略。
修剪旧的发现运行-清理过去发现会话中存储的数据。它删除超过90天的发现运行记录，最多保留每个提供者/程序/阶段的最后200次运行以供参考 GitHub 这可以防止数据库随旧日志无限增长，并确保新运行具有优先级。
降低陈旧的信心分数——将过去45天内未使用的提示的信心分数降低10% GitHub 换句话说，如果系统推断出表单字段映射提示，但最近不需要使用它，则系统会逐渐降低对该提示的信心。这样，如果提供者更改了他们的形式，并且旧的提示已经过时，最终将被谨慎对待，或者被后来发现的新提示所取代。
安排Cron作业：我们建议将此维护功能安排在非高峰时段每天运行。如果您使用的是Supabase，则可以启用pg_cron扩展并按如下方式安排该功能（例如每天凌晨2点UTC）：
--（确保数据库中启用了pg_cron和pg_net扩展） 选择cron.schedule( “每日发现维护”， “0 2\*\*\*”，--每天02:00 UTC跑步 $$ 选择 net.http_post( url:='https://\.SUPABASE.co/functions/v1/维护发现'， headers:='{“内容类型”：“应用程序/json”，“授权”：“承载者\”}：：jsonb， body：=“｛｝”：：jsonb ); $$ );
这使用了Supabase按计划调用HTTP webhook（部署的边缘功能）的能力 GitHub GitHub .请确保将占位符URL替换为实际的Subabase项目URL，并提供anon API密钥（或服务角色密钥（如果适用））进行授权。一旦安排好，您可以通过选中SELECT\*FROM cron.job来验证它是否处于活动状态； GitHub .
手动触发器：您还可以通过直接调用端点来按需调用维护（例如，在对提示系统进行更改后）：
curl-X POST“https://\.SUPABASE.co/functions/v1/维护发现” \ -H“授权：持有人\” \ -H“内容类型：应用程序/json” \ d
HTTP响应将返回维护操作的JSON摘要，包括修剪或更新了多少项目，以及遇到的任何错误 GitHub GitHub .
定期维护可确保SignupAssist的发现机制保持快速准确。通过修剪和刷新数据，该系统避免了混乱，并在指导用户进行程序选择和表单填写时始终依赖最相关、最新的信息。
贡献
欢迎为SignupAssist MCP捐款！：握手：当这个项目将人工智能与网络自动化相结合时，我们要求贡献者保持上述高标准的安全性、清晰度和可靠性。以下是为那些希望扩展或改进该系统的人提供的一些指导方针：
与设计DNA保持一致：对于任何新的面向用户的功能，请遵循既定的用户体验模式（聊天原生卡和确认、家长友好语气等）。新的卡片或信息应与声音和风格保持一致（见设计原则部分）。例如，如果执行外部写入，任何新操作都必须包括一个确认步骤，错误消息应该是礼貌和有帮助的（没有原始异常）。
扩展提供者和表单：一个常见的贡献是添加对新活动提供者或新表单字段的支持。在这种情况下，更新相关模块（例如，mcp_server/providers/用于特定于提供者的逻辑，lib/formHelpers.ts用于表单填充逻辑） GitHub 。确保在发现提要中包含提供者的详细信息（如果适用），并添加所需的任何唯一表单字段提示或登录步骤。我们鼓励编写单元测试或使用聊天测试工具来模拟新提供商的完整流程。
增强提供程序集成：通过更清晰的错误处理、重试和测试，帮助扩展Bookeo（以及未来的API提供程序）。欢迎OAuth和其他提供者，只要他们遵循授权和审计模式。
遵循架构模式：在更改编排逻辑或添加新工具时，努力保持调用的确定性和幂等性，尽可能重用会话，并适当利用缓存层。这些模式（详见技术特性）对性能和可维护性至关重要。记录任何新工具或工艺的相关遥测数据，以便我们观察其对生产的影响。
测试和QA：在提交拉取请求之前，请使用聊天测试工具测试您的更改，如果可能的话，请在暂存环境中测试。确保所有现有流程（登录、搜索、注册）仍然有效，并且您的添加不会破坏视觉流程或确认步骤。如果你引入了一个新的依赖关系或环境变量，请在README或相关文档中清楚地记录下来。
我们使用GitHub问题和PR审查来跟踪变化。如果您计划进行重大更改，请随时提出问题，以便我们讨论方法。通过为这个项目做出贡献，你将通过改进一个让他们的生活更轻松的人工智能工具来帮助忙碌的父母，同时为负责任的人工智能代理设计设定标准。感谢您的合作！
通过遵守上述指导方针并利用现有的稳健架构，SignupAssist MCP旨在保持家庭活动领域安全、高效自动化的黄金标准。我们欢迎反馈和贡献，因为我们将继续朝着更安全、更无缝的代表注册体验发展。