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.

Related MCP server: ProposalCraft

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. 15 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, log_change_request, list_change_requests.

• 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).

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 (emails PDF + DOCX to the client when Brevo is configured) → export_document for a signed download link.

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

• Email: Brevo (approved document delivery)

• 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) — API only. Its UI lived in the removed web app; it is not exposed as MCP tools yet. See docs/v3-api-access.md for how to reach it today.

• MCP-first — this release: MCP server, API keys, OAuth for ChatGPT/Claude connectors, signed exports; web app removed, landing rewritten.

Docs

• docs/scope-to-profit.md — product concept, scope and architecture (source of truth)

• docs/mcp.md — MCP tools, auth and client setup

• docs/v3-api-access.md — how to reach the v3 quote, rate-card and maintenance endpoints without a UI

• docs/technical-plan.md — original v1 technical plan (historical; the web client it describes was removed)

• docs/production-launch-checklist.md — production checklist