ScopeProfit

Scope-to-Profit

**面向自由职业者和软件代理机构的范围界定副驾，以 MCP 服务形式提供。**它能将客户杂乱的想法（零散文字、截图、“我想要个简单的东西，不过……”）转化为正式的版本化范围说明文档，供任意 AI Agent 使用。

事实来源：docs/scope-to-profit.md（产品范围 v1/v2 和当前以 MCP 为先的架构）。MCP 设置和工具参考：docs/mcp.md。

产出内容

• 需求（功能性 / 非功能性），附逐字引用的来源内容
• 阻塞性问题
• 带红黄绿灯标识的风险
• 范围（包含 / 排除 / 假设 / 验收标准）
• 工时范围估算（不含价格）
• 后续步骤

所有内容均采用固定的 template 7.1，并导出为 Markdown、PDF 和可编辑的 DOCX。

架构（MCP 优先）

ChatGPT · Claude · Cursor · Grok bots · custom agents
                │  MCP (Streamable HTTP / stdio)
                ▼
        Backend API (NestJS) ── scope tools ── LangGraph agent (optional) ── PostgreSQL + persistent storage

• MCP 服务（主要接口） — POST /api/mcp（无状态的 Streamable HTTP）和面向本地主机的 stdio 入口。共 20 个工具：create_project、add_client_input（文本 + 图片 URL）、get_tldr、get_scope_document、list_pending_questions、answer_question、update_scope_section、approve_scope、export_document、list_projects、archive_project、get_project、get_conversation、get_input_image、log_change_request、list_change_requests、get_quote、save_quote、export_quote、decide_quote。
• 身份验证 — 使用 ScopeProfit API 密钥进行 Authorization: Bearer 身份验证，或使用 OAuth 2.1（动态客户端注册 + PKCE），以连接 ChatGPT 风格的客户端。详见 docs/mcp.md。
• 后端 API — 唯一可以访问数据库和文件系统的组件。它会保存版本化的 Brief（PostgreSQL）、渲染 template 7.1 和 PDF/DOCX 文件，并运行可选的服务端范围界定 Agent。
• 落地页（apps/landing） — 静态营销页面，介绍 MCP 优先的产品，以及如何连接各个客户端。现在已不再提供 Web 应用：Next.js 客户端聊天界面（apps/app）已移除；客户对话现在由使用 MCP 服务的 Agent 负责。

快速开始（本地）

pnpm install
cp .env.example .env              # fill DATABASE_URL, ENCRYPTION_KEY, PUBLIC_API_URL
pnpm --filter @scopeprofit/contracts run build
pnpm run db:migrate
pnpm --filter @scopeprofit/api run build
pnpm --filter @scopeprofit/api run mcp:keys create --email <your-email> --label local
pnpm run dev:api                  # MCP endpoint at http://localhost:3001/api/mcp
pnpm run dev:landing              # landing at http://localhost:3000

然后按照 docs/mcp.md 中的说明连接客户端（ChatGPT、Claude、Claude Code、Cursor、OpenAI Responses API、MCP Inspector、原始 HTTP）。

为 ChatGPT 自托管

按照 docs/self-host-chatgpt.md 中的说明，使用可选的 HTTPS 覆盖层和由主机引导的起草设置。MCP/OAuth 服务已就绪；但要创建自定义 ChatGPT 连接，仍需符合条件的账户 / 工作区，以及经过验证的在线端点。如果不想自托管，也可以使用上文所述的托管公共实例和官方 MCP Registry 列表。

典型工作流

1. create_project → add_client_input，传入客户的原话和图片 URL。
2. 由主机端大模型使用 update_scope_section 起草范围说明（每项需求都必须引用已存储的消息）；或者由服务端 Agent 在后台起草（analyze: true，需要所有者的 Gemini 密钥）。
3. 使用 get_tldr / list_pending_questions → answer_question，直到没有问题会阻碍估算。
4. 使用 get_scope_document 查看 template 7.1 → approve_scope（锁定已审阅的版本；批准后绝不会向客户发送邮件）→ export_document，获取可分享的签名下载链接。

面向开发者（产品）

ScopeProfit 通过 MCP 客户端使用，而不是通过 Web UI。你可以在 ChatGPT、Claude、Cursor、Claude Code 或自己的 Agent 中与它交互：

**最快方式（托管版，无需安装）：**在 ChatGPT 或 Claude 中添加 https://scopeprofit-mcp.franutn23.workers.dev/api/mcp 作为连接器并授权——OAuth 同意屏幕会提示你输入一次 API 密钥。它也已列入官方 MCP Registry，名称为 io.github.FranprzDev/scopeprofit。如需获取托管实例的 API 密钥，请在此仓库中提交 issue。完整连接指南及示例请见：scopeprofit.vercel.app/docs。

1. 从安装服务的运营方获取 API 密钥：pnpm --filter @scopeprofit/api run mcp:keys create --email [email protected] --label <client>。
2. 连接你的宿主端——按客户端分类的配置指南（ChatGPT OAuth、Claude 连接器、Claude Code 请求头、Claude Desktop/Cursor 的本地 stdio）见 docs/mcp.md。
3. 典型工作流：create_project → add_client_input → 回答 list_pending_questions → 使用 update_scope_section 起草 → approve_scope → export_document → save_quote → export_quote → decide_quote。八次调用的快速入门及完整错误代码表见：docs/mcp.md。

没有客户端门户，也不支持通过电子邮件发送：你需要查看导出的 PDF/DOCX，自行将签名链接分享给客户端，并使用 decide_quote 记录对方的答复。

技术栈

• **API：**NestJS 11（Node 22、TypeScript）、Prisma 6 + PostgreSQL 17
• **MCP：**xmcp 1.9（基于文件的工具，Streamable HTTP + stdio），以及现有的 OAuth 2.1 授权服务器
• **Agent（可选）：**LangGraph + LangChain JS 与 Gemini；通过 Vercel AI Gateway 实现澄清关卡
• **文档：**结构化 Brief → Markdown，pdfkit → PDF，docx → DOCX
• **机器人：**带有 secret_token 的 grammY webhook
• **质量：**在真实 PostgreSQL 上进行单元、集成、MCP（通过 xmcp HTTP 的 SDK 客户端）和端到端（HTTP、OAuth、stdio）测试；后端和落地页使用独立的 CI 流水线
• **部署：**使用 PostgreSQL 和持久卷的 Docker Compose

命令

pnpm --filter @scopeprofit/api run lint
pnpm --filter @scopeprofit/api run typecheck
pnpm --filter @scopeprofit/api run test        # unit + integration + mcp + e2e (needs DATABASE_URL)
pnpm --filter @scopeprofit/api run build
pnpm --filter @scopeprofit/api run mcp:stdio   # local stdio server (needs SCOPEPROFIT_API_KEY)
pnpm run production:preflight

版本状态

• **v1 — 已交付：**项目、结构化且有版本控制的 Brief、AI Agent、模板 7.1、PDF/DOCX、审批和交付。
• **v2 — 已交付：**Brief 差异、变更请求日志及分类、严格的领域类型。
• **v3（定价、报价、维护）— 已交付：**报价和费率卡是 MCP 工具（save_quote、get_quote、export_quote、decide_quote）；维护记录仅供内部使用。
• **MCP 优先 — 本次发布：**MCP 服务、API 密钥、适用于 ChatGPT/Claude 连接器的 OAuth、签名导出文件；移除 Web 应用并重写落地页。

文档

• scopeprofit.vercel.app/docs — 在线开发者文档（连接、带示例的 20 个工具、工作流、限制）；同一网站上的 /llms.txt 供 AI Agent 使用
• docs/scope-to-profit.md — 产品理念、范围和架构（唯一可信来源）
• docs/mcp.md — MCP 工具、身份验证和客户端设置
• docs/technical-plan.md — 最初的 v1 技术计划（历史文档；其中描述的 Web 客户端已移除）
• docs/production-launch-checklist.md — 生产环境检查清单