# Design Brief Generator Provider

An independent, local-first TypeScript provider that generates a structured design brief from a website URL and/or brand details. Output is deterministic, available in English (`en`) and Spanish (`es`), and exposed through both a direct function and an MCP-shaped JSON-RPC 2.0 handler.

This is a standalone provider. It does not connect to or modify Stellar Bazaar, and it does not require secrets, payment credentials, or wallets.

## Requirements

- Node.js 22.6 or newer (Node 24 recommended)
- No runtime dependencies

## Quick start

```bash
npm test
npm run build
npm run audit:files
npm run example
```

On Windows PowerShell with script execution disabled, use `npm.cmd test`. Compiled output is written to ignored `dist/` and is never committed or uploaded to Vercel.

```ts
import { generateDesignBrief } from "./src/index.ts";

const result = generateDesignBrief({
  url: "https://example.com",
  locale: "es",
  brand: {
    name: "Marca Ejemplo",
    industry: "tecnología",
    audience: ["Equipos de producto"],
    values: ["Claridad", "Confianza"],
    colors: ["#101828", "#7F56D9"]
  }
});
```

At least one of `url` or `brand.name` is required. A URL supplies a humanized hostname when the brand name is absent. The provider does not fetch the URL; it uses it only as local input, which keeps fixture behavior safe and reproducible.

## Contract

`generateDesignBrief(input)` returns `ProviderResult<DesignBrief>`: either `{ ok: true, data }` or `{ ok: false, error }`. The design brief includes project objectives and constraints, brand strategy and visual direction, experience principles, page recommendations, deliverables, metrics, and explicit assumptions.

The MCP-shaped handler supports:

- `initialize`
- `tools/list`
- `tools/call` with `generate_design_brief`

```ts
import { handleMcpRequest } from "./src/index.ts";

const response = handleMcpRequest({
  jsonrpc: "2.0",
  id: 1,
  method: "tools/call",
  params: {
    name: "generate_design_brief",
    arguments: { url: "https://example.com", locale: "en" }
  }
});
```

This is an in-process protocol adapter, not a network server. A host can map it to stdio or HTTP without changing the generation contract. Provider metadata is also available in `service-card.json` and as the exported `serviceCard` constant.

## HTTP API

The Vercel deployment exposes the same local contract:

**Production:** <https://design-brief-provider.vercel.app>

- `GET /` — service discovery and Tool schema
- `GET /health` — health and version response
- `POST /api` — direct `GenerateBriefInput`, returning `ProviderResult<DesignBrief>`
- `POST /api` — JSON-RPC 2.0 request for the MCP-shaped adapter

```bash
curl -X POST https://design-brief-provider.vercel.app/api \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com","locale":"es"}'
```

The URL is treated as metadata only; the provider performs no outbound website fetch.

## Deploying to Vercel

Import this repository as a new Vercel project with the default framework preset. No environment variables, database, build output, payments, or wallet configuration are required. The `api/` handlers and `vercel.json` rewrites are deployment-ready.

## Development

```bash
npm test
npm run build
npm run audit:files
npm run example
```

The test suite covers deterministic URL input, Spanish brand input, validation failures, discovery, and MCP-shaped invocation.
The committed `fixtures/stellar-brief.es.json` file is a stable, local sample output and is checked by the test suite.

## License

Apache License 2.0. See [LICENSE](./LICENSE).