decentproposal

Official CLI + MCP server for the Decent Proposal v2 Agent API.

What this is

The Decent Proposal v2 API lets any reasoning agent (Claude, Codex, Gemini, Kimi, custom) draft, edit, publish, and observe proposals on your behalf. This package gives you two ways to talk to it:

• CLI (npx decentproposal …) — humans + CI scripts.
• MCP server (npx decentproposal mcp) — connect to Claude Code, Cursor, Claude Desktop, or any other MCP-aware host so your agent can call tools directly.

Both share the same auth and the same 16 endpoints.

Requirements

• Node.js 18+
• A Decent Proposal agent key (Profile → Agent Keys → New Key)
• AGENT_API_BASE_URL is optional — the CLI defaults to https://kgcecdlyfyovcrnxeizb.supabase.co/functions/v1 (only override for a self-hosted fork).

One-time setup

npx decentproposal auth login --key dpak_xxx

(--base <url> is supported but rarely needed — the prod base URL is the default.)

Stores credentials in ~/.decentproposal/agent-cli.json. Sanity-check:

npx decentproposal whoami

Use it as a human

# Discover the API
npx decentproposal contract
npx decentproposal packages list --industry agencies

# Draft a proposal end-to-end
npx decentproposal create --title "Generali Brand Refresh" --client "Generali Central Life Insurance" --currency INR --industry agencies
# → returns proposalId + editorUrl

npx decentproposal section set --id <proposalId> --section execSummary --file ./execSummary.json
npx decentproposal section set --id <proposalId> --section scope --file ./scope.json
npx decentproposal section set --id <proposalId> --section costing --file ./costing.json

# Publish
npx decentproposal publish --id <proposalId>
# → returns shareUrl

# Check engagement
npx decentproposal analytics --id <proposalId>

section set is the universal editor — read npx decentproposal contract to learn the data shape for each section.

Use it from an MCP host

Auth is shared — set it up once with npx decentproposal auth login (above) and every host reads from the same ~/.decentproposal/agent-cli.json. Only the host registration differs.

Claude Code:

claude mcp add decentproposal -- npx -y decentproposal mcp

Gemini CLI:

gemini mcp add --scope user decentproposal npx -y decentproposal mcp

Cursor / Claude Desktop / Codex / other MCP hosts:

Add an mcpServers entry pointing at npx -y decentproposal mcp. JSON shape (Cursor, Claude Desktop):

{
  "mcpServers": {
    "decentproposal": {
      "command": "npx",
      "args": ["-y", "decentproposal", "mcp"]
    }
  }
}

TOML shape (Codex CLI's ~/.codex/config.toml):

[mcp_servers.decentproposal]
command = "npx"
args = ["-y", "decentproposal", "mcp"]

Then in your host:

Create a proposal for Generali Central Life Insurance in India. Client objective: brand refresh + GTM playbook for new term-life product. Add 3 scope sections, T&Cs, leave pricing blank — I'll fill it. Use INR.

The agent will call:

• proposals.create → gets proposalId + editorUrl
• proposals.section.set for execSummary, scope, timeline, terms, …
• Hands you the editorUrl

You open the URL, fill in rates, hit publish.

All commands

auth login --key <key> [--base <url>]
auth logout
whoami
contract
help

list [--status …] [--outcome …] [--limit 50] [--offset 0]
create --title … --client … [--currency] [--industry] [--style] [--scheme]
get --id <proposalId>
delete --id <proposalId>

section set --id <id> --section <name> --file <data.json>
section add --id <id> --target scope|costing.items|team --file <item.json>
style apply --id <id> [--style <id>] [--scheme <id>] [--cover <coverStyle.json>]
package apply --id <id> --package <package_id>

publish --id <id> [--rotate]
unpublish --id <id>
analytics --id <id>

snippets list [--category …]
packages list [--industry …]

mcp                              # run as MCP stdio server

Plans

• Free: contract, whoami, snippets list, packages list only (with daily caps).
• Pro: everything, with per-plan daily quotas and 25 active cloud proposals.

Security

• Treat your agent key like a password.
• Never commit it. Use env vars in CI.
• Revoke compromised keys in the web app (Profile → Agent Keys).

Contract

The canonical machine-readable contract is at https://www.thedecentproposal.com/llms.txt (human-readable) and https://www.thedecentproposal.com/openapi.json (OpenAPI 3.1). The agent-help endpoint returns the same shapes + enums + examples for runtime discovery.