ScopeProfit

Scope-to-Profit

Scope copilot for freelancers and software agencies, exposed as an MCP server. It turns a client's messy idea (loose text, screenshots, "I want something simple but…") into a formal, versioned scope document that any AI agent can drive.

Source of truth: docs/scope-to-profit.md (product scope v1/v2 and the current MCP-first architecture). MCP setup and tool reference: docs/mcp.md.

What it produces

• requirements (functional / non-functional) with a verbatim source quote
• blocking questions
• risks with a traffic light
• scope (included / excluded / assumptions / acceptance criteria)
• hour-range estimate (no prices)
• next steps

All of it in the fixed template 7.1, exported to Markdown, PDF and editable DOCX.

Architecture (MCP-first)

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

• MCP server (primary interface) — POST /api/mcp (Streamable HTTP, stateless) and a stdio entrypoint for local hosts. 20 tools: create_project, add_client_input (text + image URLs), 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.
• Auth — Authorization: Bearer with a ScopeProfit API key, or OAuth 2.1 (dynamic client registration + PKCE) for ChatGPT-style connectors. See docs/mcp.md.
• Backend API — the only component with database and file-system access. Keeps the versioned Brief (PostgreSQL), renders template 7.1 and the PDF/DOCX artifacts, and runs the optional server-side scope agent.
• Landing (apps/landing) — static marketing page that explains the MCP-first product and how to connect each client. There is no web app anymore: the Next.js client chat (apps/app) was removed; the client conversation now happens in whatever agent uses the MCP server.

Quick start (local)

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

Then connect a client as described in docs/mcp.md (ChatGPT, Claude, Claude Code, Cursor, OpenAI Responses API, MCP Inspector, raw HTTP).

Self-hosting for ChatGPT

Use the opt-in HTTPS overlay and host-led drafting setup in docs/self-host-chatgpt.md. The MCP/OAuth server already exists; creating a custom ChatGPT connection still requires an eligible account/workspace and a verified live endpoint. A hosted public instance (above) and an official MCP Registry listing are available if you do not want to self-host.

Typical flow

1. create_project → add_client_input with the client's words and image URLs.
2. Either the host LLM drafts the scope with update_scope_section (every requirement must quote a stored message), or the server agent does it in the background (analyze: true, needs the owner's Gemini key).
3. get_tldr / list_pending_questions → answer_question until nothing blocks the estimate.
4. get_scope_document to review template 7.1 → approve_scope (locks the reviewed version; approval never emails the client) → export_document for a signed download link to share.

For developers (the product)

ScopeProfit is used through an MCP client, not a web UI. You talk to it from ChatGPT, Claude, Cursor, Claude Code or your own agent:

Fastest way (hosted, nothing to install): add https://scopeprofit-mcp.franutn23.workers.dev/api/mcp as a connector in ChatGPT or Claude and authorize it — the OAuth consent screen asks for your API key once. It is also listed in the official MCP Registry as io.github.FranprzDev/scopeprofit. To get an API key for the hosted instance, open an issue in this repo. Full connection guide with examples: scopeprofit.vercel.app/docs.

1. Get an API key from the installation operator: pnpm --filter @scopeprofit/api run mcp:keys create --email [email protected] --label <client>.
2. Connect your host — per-client recipes (ChatGPT OAuth, Claude connector, Claude Code header, local stdio for Claude Desktop/Cursor) are in docs/mcp.md.
3. Typical flow: create_project → add_client_input → answer list_pending_questions → draft with update_scope_section → approve_scope → export_document → save_quote → export_quote → decide_quote. Eight-call quickstart and the full error-code table: docs/mcp.md.

There is no client portal and no email delivery: you review the exported PDF/DOCX, share the signed link with your client yourself, and record their answer with decide_quote.

Stack

• API: NestJS 11 (Node 22, TypeScript), Prisma 6 + PostgreSQL 17
• MCP: xmcp 1.9 (file-based tools, Streamable HTTP + stdio) with the existing OAuth 2.1 authorization server
• Agent (optional): LangGraph + LangChain JS with Gemini; clarification gate via Vercel AI Gateway
• Documents: structured Brief → Markdown, pdfkit → PDF, docx → DOCX
• Bot: grammY webhook with secret_token
• Quality: unit, integration, MCP (SDK client over xmcp HTTP) and e2e (HTTP, OAuth, stdio) tests on real PostgreSQL; separate backend and landing CI pipelines
• Deploy: Docker Compose with PostgreSQL and persistent volumes

Commands

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

Version status

• v1 — delivered: projects, structured versioned Brief, AI agent, template 7.1, PDF/DOCX, approval and delivery.
• v2 — delivered: Brief diff, change-request log and classification, strict domain types.
• v3 (pricing, quotes, maintenance) — delivered: quotes and rate cards are MCP tools (save_quote, get_quote, export_quote, decide_quote); maintenance records stay internal.
• MCP-first — this release: MCP server, API keys, OAuth for ChatGPT/Claude connectors, signed exports; web app removed, landing rewritten.

Docs

• scopeprofit.vercel.app/docs — live developer docs (connect, 20 tools with examples, flow, limits); /llms.txt on the same site for AI agents
• docs/scope-to-profit.md — product concept, scope and architecture (source of truth)
• docs/mcp.md — MCP tools, auth and client setup
• docs/technical-plan.md — original v1 technical plan (historical; the web client it describes was removed)
• docs/production-launch-checklist.md — production checklist