# Sharp SIR Charts MCP Server

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Local, privacy-preserving Chart.js rendering for MCP-compatible agents.

`sharpsir-charts-mcp-server` turns structured data into PNG, SVG, PDF, or JSON chart
outputs. It runs entirely on your machine, returns an inline preview, and
defaults to a restrained Sotheby's International Realty-inspired editorial
design. The active design can be configured by the calling agent for the
current MCP session.

Use it when an AI agent needs beautiful, deterministic, server-side charts for
real-estate reporting, executive dashboards, financial analysis, market
comparisons, presentations, or print collateral without sending data to a
third-party chart service.

## Quick start

Clone the repository and build it locally:

```bash
git clone https://github.com/gca-ltd/sharpsir-charts-mcp-server.git
cd sharpsir-charts-mcp-server
npm install
npm run build
CHARTS_TRANSPORT=stdio node dist/index.js
```

The server has no data connector. The caller supplies the data, which keeps
rendering private and deterministic.

## Features

- Server-side Chart.js rendering with deterministic PNG, SVG, PDF and JSON output.
- Luxury editorial defaults inspired by Sotheby's International Realty, plus
  Sharp Matrix, mono-print and neutral references.
- Session-scoped design configuration with strict schemas, OKLCH palette ramps,
  contrast warnings and bundled OFL fonts.
- Inline PNG previews, full-resolution files, configurable public URLs and
  retention cleanup.
- Local stdio transport or authenticated Streamable HTTP with rate limiting,
  request limits and concurrency guards.

## MCP client configuration

For Cursor, Claude Desktop or another stdio MCP client:

```json
{
  "mcpServers": {
    "sharpsir-charts": {
      "command": "node",
      "args": ["/home/bitnami/sharpsir-charts-mcp-server/dist/index.js"],
      "env": {
        "CHARTS_TRANSPORT": "stdio"
      }
    }
  }
}
```

For the hosted Streamable HTTP deployment, use the MCP URL
`https://intranet.sharpsir.group/charts/mcp` and send
`Authorization: Bearer <CHARTS_API_TOKEN>`. Never commit the token.

## Gallery

### Sotheby's-inspired series chart

![Sotheby's-inspired series chart](examples/sothebys-series.png)

### Editorial KPI card

![Editorial KPI card](examples/sothebys-kpi.png)

### Sharp Matrix reference

![Sharp Matrix series chart](examples/sharp-matrix-series.png)

## Agent workflow

1. Call a render tool with no design to get a SIR-styled chart immediately.
2. Call `get_design` to inspect the active design.
3. Call `describe_design_schema` or `get_design_reference` when changing the look.
4. Call `configure_design`, then `preview_design` to review the result.
5. Render production charts and read the returned warnings.

The design is held in memory per MCP session. It is never written to disk or
shared with another caller. The default is `sothebys`; `neutral` is available
only when an agent explicitly asks for unbranded output.

## Tools

| Tool | Use |
|---|---|
| `render_series_chart` | Bar, line, area, dot, lollipop, dumbbell and slope charts |
| `render_part_to_whole` | Small part-to-whole comparisons (pie / doughnut / polar) |
| `render_waterfall` | Variance bridges with floating bars |
| `render_bullet` | Actual versus target with qualitative bands |
| `render_funnel` | Conversion stages with drop-off percentages |
| `render_scatter` | Numeric correlation and outliers |
| `render_small_multiples` | Shared-scale panels across cuts |
| `render_chart` | Advanced Chart.js configurations not covered above |
| `render_kpi_card` | Editorial typographic KPI with optional sparkline |
| `render_kpi_row` | Two to four KPI cells with hairline dividers |
| `configure_design` | Session-wide design configuration |
| `preview_design` | Specimen render for visual QA |
| `describe_design_schema` | Strict annotated design contract |
| `get_design_reference` | SIR, Sharp Matrix, mono-print and neutral references |
| `get_design` | Current resolved design |
| `list_fonts` | Fonts actually available to the renderer |

Every tool has detailed WHAT / WHEN TO USE / INPUTS / RETURNS / CONSTRAINTS /
EXAMPLES guidance. Styling belongs in the design system, not in chart data.
JavaScript callbacks are not accepted.

## Output

PNG is the default and returns a downscaled inline preview plus a full output
path or hosted URL. SVG and PDF are vector outputs. JSON returns the resolved
Chart.js configuration without an image.

## Development

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

See [docs/DESIGN-SYSTEM.md](docs/DESIGN-SYSTEM.md),
[docs/USER_GUIDE.md](docs/USER_GUIDE.md), and
[docs/INSTALL.md](docs/INSTALL.md).

## Licence and brand notice

The software is MIT licensed. The `sothebys` design reference reproduces
publicly published affiliate guidance for Sharp SIR; it does not grant rights
to Sotheby's International Realty marks. See [NOTICE.md](NOTICE.md).