raven-mcp 1.1.0 → 1.2.0

package/README.md

@@ -2,40 +2,46 @@
 
 **Odin's ravens brought back knowledge of the world — Raven brings back design intelligence.**
 
-A design knowledge MCP server that Claude can query when generating UI. Three layers: principles, patterns, and business strategy.
+A design knowledge MCP server that Claude can query when generating UI. Five layers: principles, patterns, content design systems, business strategy, and design tokens.
 
 ## What it does
 
 Raven gives Claude access to a comprehensive design knowledge base:
 
-- **Principles** — Nielsen's 10 Heuristics, all 21 Laws of UX, Gestalt principles, WCAG accessibility, typography rules, color theory, mobile UX, and D4D framework
-- **Patterns** — Proven UI patterns for signup flows, pricing pages, navigation, forms, landing pages, dashboards, modals, empty/error/loading states, CTAs, social proof, and mobile conversion
+- **Principles** — Nielsen's 10 Heuristics, all 21 Laws of UX, Gestalt principles, WCAG accessibility, typography rules, color theory, mobile UX, D4D framework, and UX writing principles
+- **Patterns** — Proven UI patterns for signup flows, pricing pages, navigation, forms, landing pages, dashboards, modals, empty/error/loading states, CTAs, social proof, mobile conversion — plus content patterns for error messages, empty-state copy, notifications, and form validation
+- **Content systems** — Voice & tone guides from real brands: Mailchimp, GOV.UK, Shopify Polaris, Atlassian, and Intuit
 - **Business** — Monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks
-- **Tokens** — Design system tokens for Stripe, Linear, and more (registry of 7 systems, 2 fully populated)
+- **Tokens** — Design system tokens for Stripe, Linear, and more
 
-## Setup
+## Install
 
+### Claude Code — one command
 ```bash
-cd raven-mcp
-npm install
-npm run build
+claude mcp add raven -- npx -y raven-mcp
 ```
 
-## Add to Claude Code
-
-Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):
-
+### Manual config (Claude Desktop or team `.mcp.json`)
 ```json
 {
   "mcpServers": {
     "raven": {
-      "command": "node",
-      "args": ["/path/to/raven-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "raven-mcp"]
     }
   }
 }
 ```
 
+### Claude Desktop — one-click extension
+Prefer not to edit JSON? Download [raven.mcpb](https://ravenmcp.ai/raven.mcpb) and double-click it. Claude Desktop installs Raven automatically — no Node, no terminal.
+
+### From source
+```bash
+git clone https://github.com/rhinocap/raven-mcp.git
+cd raven-mcp && npm install && npm run build
+```
+
 ## Tools
 
 | Tool | Description |
@@ -50,6 +56,27 @@ Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or pr
 | `list_design_systems` | Browse available design systems |
 | `get_design_system` | Get tokens for a specific design system |
 | `compose_system` | Mix tokens from different systems |
+| `get_brand_system` | Get a full system styled like a well-known brand |
+| `audit_page` | Audit HTML/CSS against Raven's quality standards |
+| `audit_layout` | Evaluate visual rhythm, alignment, and optical balance |
+| `generate_design_system` | Generate a custom design system from a brand color |
+| `list_content_systems` | Browse brand voice & tone systems (Mailchimp, GOV.UK, Shopify Polaris, Atlassian, Intuit) |
+| `get_content_system` | Get a brand's voice attributes, tone shifts, vocabulary, grammar, and content patterns |
+| `get_content_principles` | Get UX-writing principles — clarity, active voice, error anatomy, inclusive language |
+| `get_content_pattern` | Get copy recipes for error messages, empty-state copy, notifications, form validation |
+| `raven_reflect` | Summarize your local Raven usage log to find patterns + gaps |
+
+## Learning loop
+
+Raven keeps a small **local-only** log of how you use it so you (and Claude) can spot which patterns you build most often and which gaps show up again and again.
+
+- **Location:** `~/.raven/usage.jsonl` (override with `RAVEN_USAGE_LOG=/path`).
+- **What's written:** tool name, timestamp, elapsed ms, and a tiny insight object — audit score/warning rule names, pattern `type`, brand company name, search layer. **Never the HTML you audit, never prompt text, never brand copy.**
+- **What's never written:** raw page bodies, client content, your work product.
+- **Disable entirely:** `RAVEN_NO_USAGE_LOG=1`.
+- **Reflect:** ask Claude *"what have I been using Raven for?"* and it will call `raven_reflect`, which reads the log locally and summarizes the last N days — most-used tools, recurring audit warnings (likely knowledge gaps), patterns you request most, design systems you reach for.
+
+Nothing is sent to a remote server. If a recurring gap is worth turning into a new Raven principle or pattern, you file an issue by hand — the automated pipeline at [github.com/rhinocap/raven-mcp](https://github.com/rhinocap/raven-mcp) handles it from there.
 
 ## Development
 
@@ -68,5 +95,9 @@ src/data/
   principles/   # Nielsen, Laws of UX, Gestalt, accessibility, typography, color, mobile, D4D
   patterns/     # signup, pricing, nav, forms, landing, dashboard, modals, empty/error/loading, CTA, social proof, mobile
   business/     # monetization, retention, onboarding, growth, metrics
-  tokens/       # registry.json + systems/ (stripe.json, linear.json)
+  tokens/       # registry.json + systems/ (stripe, linear, vercel, …)
+  content/      # voice & tone: Mailchimp, GOV.UK, Shopify Polaris, Atlassian, Intuit
+    systems/    # registry.json + brand-voice JSONs
+    principles/ # UX-writing principles (clarity, active voice, error anatomy, …)
+    patterns/   # copy recipes for errors, empty states, notifications, form validation
 ```

package/SECURITY.md

@@ -0,0 +1,74 @@
+# Security Policy — Raven MCP
+
+## Data Flow
+
+Raven MCP runs entirely locally. Here is the complete data flow:
+
+```
+Claude (prompt) → MCP Protocol (stdio) → Raven MCP (local process) → Response (text)
+```
+
+### What Raven reads
+- User prompts passed via the MCP protocol from Claude Code or Claude Desktop
+- Static JSON files bundled in the package (design principles, patterns, tokens)
+
+### What Raven returns
+- Text responses (JSON) containing design principles, patterns, tokens, and evaluations
+- All responses are returned via stdio to the calling MCP client (Claude)
+
+### What Raven does NOT do
+- No network requests during tool execution — all data is local JSON loaded at startup
+- No file system reads beyond its own bundled data files
+- No logging of user prompts, code, or design artifacts
+- No collection of PII or customer data
+- No external API calls, database connections, or cloud service integrations
+- No access to environment variables, secrets, or credentials during tool execution
+
+### Optional telemetry (postinstall only)
+On `npm install`, an optional postinstall script sends a single HTTPS POST to `ravenmcp.ai/api/welcome` containing:
+- Node.js version
+- OS platform and architecture
+- Timestamp
+
+**No user data, prompts, code, or design artifacts are sent.** This telemetry is limited to install-time only and never runs during tool execution.
+
+**To disable:** Set `RAVEN_NO_TELEMETRY=1` before install:
+```bash
+RAVEN_NO_TELEMETRY=1 npm install raven-mcp
+```
+
+## Dependencies
+
+### Runtime
+| Package | Purpose | License |
+|---------|---------|---------|
+| `@modelcontextprotocol/sdk` | MCP protocol implementation | MIT |
+| `zod` | Input validation | MIT |
+
+### Dev-only (not shipped)
+| Package | Purpose | License |
+|---------|---------|---------|
+| `typescript` | Build | Apache-2.0 |
+| `tsx` | Dev server | MIT |
+| `@types/node` | Type definitions | MIT |
+| `resend` | Email (dev testing only) | MIT |
+
+Zero transitive runtime dependencies beyond the two listed above.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Reporting Vulnerabilities
+
+Email security concerns to andrew@ravenmcp.ai. Response within 48 hours.
+
+## Enterprise / Compliance Use
+
+For enterprise environments requiring:
+- Telemetry disabled: set `RAVEN_NO_TELEMETRY=1`
+- Version pinning: lock to a specific version in `package.json`
+- SBOM: generate with `npm sbom --sbom-format cyclonedx`
+- Audit: run `npm audit` — zero known vulnerabilities as of v1.1.0
+
+Raven MCP is designed for local-only, air-gapped use. No network access is required after installation.