# AI Product Planner

AI Product Planner turns a product idea into an implementation-ready planning package: PRD, requirements, user flow, wireframes, data schema, API contracts, SDK boundaries, and an MCP handoff for coding agents.

The generation pipeline uses a supervisor stage followed by dependency-aware parallel workers. It calls any OpenAI-compatible Chat Completions API and keeps generated sessions on the local filesystem.

## Requirements

- Node.js 22 or newer
- An OpenAI-compatible LLM API key and model with structured JSON output support

## Quick Start

```bash
npm install
cp .env.example .env
# Set PLANNER_LLM_API_KEY and, if needed, the base URL and model.
npm run build
npm start
```

Open `http://127.0.0.1:8792`.

For frontend and backend development in separate terminals:

```bash
npm run dev:server
npm run dev
```

## LLM Providers

The default example targets NVIDIA's OpenAI-compatible endpoint with `z-ai/glm-5.2`. Other providers work when they implement `POST /chat/completions` with `messages`, `response_format`, and `choices[0].message.content`.

Set `PLANNER_LLM_STRUCTURED_OUTPUT=false` only when the selected provider does not support `response_format: { "type": "json_object" }`. The planner still validates the returned JSON and fails explicitly if the contract is invalid.

## Authentication

The default server binds only to `127.0.0.1` and allows unauthenticated local use. It refuses to start with `PLANNER_AUTH_MODE=none` on a non-loopback host.

For deployment behind an access proxy, use header mode:

```dotenv
HOST=0.0.0.0
PLANNER_AUTH_MODE=header
PLANNER_AUTH_HEADER=x-authenticated-user
PLANNER_AUTH_HEADER_VALUE=expected-proxy-value
```

Your proxy must strip incoming copies of that header and inject the trusted value after authentication. MCP clients can instead use `PLANNER_MCP_BEARER_TOKEN`.

## MCP

The JSON-RPC MCP endpoint is `/mcp`. It exposes planning sessions, generated contracts, active implementation goals, and run handoff resources.

```bash
curl http://127.0.0.1:8792/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

## Commands

```bash
npm test
npm run lint
npm run typecheck
npm run build
```

See [SERVER_START_HERE.md](SERVER_START_HERE.md), [SERVER_OPERATIONS.md](SERVER_OPERATIONS.md), and [APP_DATA_SCHEMA.md](APP_DATA_SCHEMA.md) for integration details.

## License

MIT