ScopeProfit MCP server
Commit Nov 15, 2026Converts client requests into formal scope documents, requirements, and quotes with PDF and DOCX export capabilities.
Also known as FranprzDev/ScopeProfit
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is ScopeProfit MCP?
ScopeProfit converts client requests into formal scope documents, requirements, and quotes with PDF and DOCX export capabilities.
Summary generated from the project's README
About ScopeProfit MCP server
Freelancers and software agencies can transform messy client ideas into formal project documentation using ScopeProfit. Instead of using a traditional web interface, you interact with this service through MCP clients like Claude, ChatGPT, Cursor, or Claude Code. It processes text and image URLs to generate structured requirements, risk assessments with traffic light indicators, and hour-range estimates using a specific template 7.1.
The system operates via a NestJS backend that manages persistent storage in PostgreSQL. You can connect locally using a stdio entrypoint or remotely via Streamable HTTP. Authentication is handled through Bearer API keys or OAuth 2.1 for ChatGPT-style connectors. Once a scope is reviewed and approved, the server provides tools to export the final document as a Markdown, PDF, or editable DOCX file.
This tool focuses on maintaining a versioned source of truth for project briefs. It includes specialized functions for managing change requests, saving quotes, and tracking pending questions to ensure no blocking issues remain before an estimate is finalized.
What you can do with it
- 1Convert client messages into requirementsTurn loose text and screenshots from a client into a formal functional and non-functional requirements list.
Written from the project's README. Every use case is checked against a quote from it.
How to install ScopeProfit MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ScopeProfit MCP in Claude Code
$ claude mcp add --transport http scopeprofit https://scopeprofit-mcp.franutn23.workers.dev/api/mcpInstall ScopeProfit MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"scopeprofit": {
"url": "https://scopeprofit-mcp.franutn23.workers.dev/api/mcp"
}
}
}Install ScopeProfit MCP in VS Code
.vscode/mcp.json
{
"servers": {
"scopeprofit": {
"type": "http",
"url": "https://scopeprofit-mcp.franutn23.workers.dev/api/mcp"
}
}
}Install ScopeProfit MCP in VS Code CLI
$ code --add-mcp '{"name":"scopeprofit","type":"http","url":"https://scopeprofit-mcp.franutn23.workers.dev/api/mcp"}'Install ScopeProfit MCP in Codex
$ codex mcp add scopeprofit --url https://scopeprofit-mcp.franutn23.workers.dev/api/mcpInstall ScopeProfit MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.scopeprofit] url = "https://scopeprofit-mcp.franutn23.workers.dev/api/mcp"
Install ScopeProfit MCP in Gemini CLI
$ gemini mcp add -s user --transport http scopeprofit https://scopeprofit-mcp.franutn23.workers.dev/api/mcpInstall ScopeProfit MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"scopeprofit": {
"url": "https://scopeprofit-mcp.franutn23.workers.dev/api/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefranprzdev/scopeprofit is public and reachablegithub.com/franprzdev/scopeprofit ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/franprzdev/scopeprofit ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubScope-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: Bearerwith a ScopeProfit API key, or OAuth 2.1 (dynamic client registration + PKCE) for ChatGPT-style connectors. Seedocs/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
create_project→add_client_inputwith the client's words and image URLs.- 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). get_tldr/list_pending_questions→answer_questionuntil nothing blocks the estimate.get_scope_documentto review template 7.1 →approve_scope(locks the reviewed version; approval never emails the client) →export_documentfor 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:
Install it yourself (self-hosted, ~5 minutes, nothing to request): clone the repo, pnpm install, point .env at any PostgreSQL, run the migrations and create your own API key with mcp:keys create — then connect over stdio (mcp:stdio) or local HTTP. Any agent that can run shell commands can do the whole setup from the guide at scopeprofit.vercel.app/docs. ScopeProfit is also listed in the official MCP Registry as io.github.FranprzDev/scopeprofit.
- Get an API key from the installation operator:
pnpm --filter @scopeprofit/api run mcp:keys create --email you@example.com --label <client>. - Connect your host — per-client recipes (ChatGPT OAuth, Claude connector, Claude Code header, local stdio for Claude Desktop/Cursor) are in docs/mcp.md.
- Typical flow:
create_project→add_client_input→ answerlist_pending_questions→ draft withupdate_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.txton 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 setupdocs/technical-plan.md— original v1 technical plan (historical; the web client it describes was removed)docs/production-launch-checklist.md— production checklist
ScopeProfit MCP questions
How do I add ScopeProfit MCP to Claude Code?
Run claude mcp add --transport http scopeprofit https://scopeprofit-mcp.franutn23.workers.dev/api/mcp in your terminal. Add --scope user to make it available in every project.
How do I add ScopeProfit MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I connect ScopeProfit to my AI client?
You can connect via ChatGPT OAuth, Claude connector, Claude Code header, or local stdio for Claude Desktop and Cursor.
Does ScopeProfit have a web interface for clients?
No, there is no client portal or web app; the client conversation happens within the AI agent using the MCP server.