npm package: @junioralmeida/ciano-ds-mcp
Description: MCP server CLI for Ciano Design System
Latest version: 0.1.3

# Ciano Design System MCP CLI

MCP server for Ciano DS that can run in:

- `stdio` mode (Codex, Claude Desktop, local MCP clients)
- `http` mode (remote hosting for multiple clients/teams)

## Install as npm CLI

```bash
# global
npm i -g @junioralmeida/ciano-ds-mcp

# or run without install
npx @junioralmeida/ciano-ds-mcp start --stdio
```

## CLI

```bash
# stdio
ciano-ds-mcp start --stdio

# http (remote)
ciano-ds-mcp start --http --host 0.0.0.0 --port 3000
```

Direct usage:

```bash
node design-system-server-sdk.js start --stdio
node design-system-server-sdk.js start --http --host 0.0.0.0 --port 3000
```

## Exposed tools

- `list_components`
- `get_component_context`
- `search_design_system`

Resources:

- `ciano://catalog`
- `ciano://component/{name}`

## Environment variables

- `CIANO_DS_ROOT`: absolute path to DS source root (recommended)
- `CIANO_MCP_LOG_FILE`: file path for server logs
- `CIANO_MCP_SDK_BASE`: optional SDK base path (`.../@modelcontextprotocol/sdk/dist/cjs`) when package is not installed in local `node_modules`
- `MCP_ALLOWED_HOSTS`: optional comma-separated list for Host header allowlist (example: `localhost,127.0.0.1,my-app.trycloudflare.com`)

## Codex config (`stdio`)

```toml
[mcp_servers.ciano_design_system]
command = "ciano-ds-mcp"
args = ["start", "--stdio"]

[mcp_servers.ciano_design_system.env]
CIANO_DS_ROOT = "/Users/junioralmeida/Desktop/projetoscianolocal/arquitetura-ciano-lib-angular"
CIANO_MCP_LOG_FILE = "/tmp/ciano_codex_mcp.log"
```

## Claude Desktop config (`stdio`)

```json
{
  "mcpServers": {
    "ciano_design_system": {
      "command": "ciano-ds-mcp",
      "args": ["start", "--stdio"],
      "env": {
        "CIANO_DS_ROOT": "/Users/junioralmeida/Desktop/projetoscianolocal/arquitetura-ciano-lib-angular",
        "CIANO_MCP_LOG_FILE": "/tmp/ciano_claude_mcp.log"
      }
    }
  }
}
```

## Remote hosting baseline (`http`)

- Endpoint MCP: `POST/GET /mcp`
- Healthcheck: `GET /health`
- Default port: `3000`

Example:

```bash
CIANO_DS_ROOT=/path/to/arquitetura-ciano-lib-angular \
ciano-ds-mcp start --http --host 0.0.0.0 --port 3000
```

For Azure, deploy this process on App Service/Container Apps and expose `/mcp` over HTTPS.

## Production notes

- Use HTTPS only.
- Put authentication in front of `/mcp` (API Management, Front Door, Easy Auth or JWT middleware).
- Keep `CIANO_DS_ROOT` mounted/available in the runtime container.
- Monitor `GET /health` and server logs (`CIANO_MCP_LOG_FILE`).

## Quick MCP validation (HTTP)

```bash
curl -i -X POST http://127.0.0.1:3011/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual-test","version":"1.0.0"}}}'

curl -i -X POST http://127.0.0.1:3011/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

## Publish this package

From this folder (`mcp/`):

```bash
npm login
npm run check
npm run pack:dry
npm publish --access public
```