stylemcp 0.1.0

package/README.md

@@ -0,0 +1,261 @@
+# StyleMCP
+
+Executable brand rules for AI models and agents. Keep every AI-generated message on-brand.
+
+## What is StyleMCP?
+
+StyleMCP validates and rewrites AI-generated text to match your brand voice. Use it as:
+
+- **REST API** - Validate text from any application
+- **MCP Server** - Direct integration with Claude and other AI agents
+- **CLI** - Check copy in your terminal or CI/CD
+- **GitHub Action** - Catch off-brand copy in pull requests
+
+## Quick Start
+
+### API
+
+```bash
+curl -X POST https://stylemcp.com/api/validate \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Click here to learn more!"}'
+```
+
+Response:
+
+```json
+{
+  "valid": false,
+  "score": 65,
+  "issues": [
+    {
+      "rule": "no-click-here",
+      "message": "Avoid 'click here' - describe the destination instead",
+      "suggestion": "Learn more about our features"
+    }
+  ]
+}
+```
+
+### CLI
+
+```bash
+# Install
+npm install -g stylemcp
+
+# Validate text
+stylemcp validate "Click here to learn more"
+
+# Validate file
+stylemcp validate src/copy/homepage.json --pack saas
+
+# Rewrite text
+stylemcp rewrite "Please utilize our product" --mode aggressive
+```
+
+### MCP (Claude Desktop)
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stylemcp": {
+      "command": "npx",
+      "args": ["stylemcp"]
+    }
+  }
+}
+```
+
+Now Claude can validate and rewrite text using your brand rules.
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/validate` | Validate text against brand rules |
+| POST | `/api/rewrite` | Rewrite text to match brand voice |
+| POST | `/api/validate/batch` | Validate multiple texts |
+| GET | `/api/packs` | List available style packs |
+| GET | `/api/packs/{pack}/voice` | Get voice guidelines |
+| GET | `/api/packs/{pack}/ctas` | Get CTA rules |
+| GET | `/api/mcp/sse` | MCP SSE endpoint |
+| POST | `/api/mcp/call` | MCP tool calls |
+
+## Style Packs
+
+StyleMCP uses **style packs** - YAML files that define your brand rules.
+
+### Default Pack: `saas`
+
+The included `saas` pack is designed for B2B SaaS products:
+
+- **Vocabulary**: Prefer "use" over "utilize", "help" over "assist"
+- **Forbidden words**: "synergy", "leverage", "cutting-edge", "game-changing"
+- **Patterns to avoid**: "click here", "we're sorry for any inconvenience"
+- **CTA rules**: Avoid "Submit", "Click here", "OK" - prefer "Save", "Create", "Sign up"
+
+### Pack Structure
+
+```
+packs/
+  my-brand/
+    manifest.yaml      # Pack metadata
+    voice.yaml         # Tone, vocabulary, forbidden words
+    copy_patterns.yaml # Reusable copy templates
+    cta_rules.yaml     # Button/CTA guidelines
+    tokens.json        # Design tokens (optional)
+```
+
+### Create Your Own Pack
+
+```bash
+# Copy the default pack
+cp -r packs/saas packs/my-brand
+
+# Edit the rules
+nano packs/my-brand/voice.yaml
+
+# Use your pack
+curl -X POST https://stylemcp.com/api/validate \
+  -d '{"text": "Your text", "pack": "my-brand"}'
+```
+
+### voice.yaml Example
+
+```yaml
+tone:
+  summary: "Friendly, clear, and helpful"
+  attributes:
+    - name: friendly
+      weight: 0.8
+    - name: professional
+      weight: 0.7
+
+vocabulary:
+  rules:
+    - preferred: "use"
+      avoid: ["utilize", "leverage"]
+    - preferred: "help"
+      avoid: ["assist", "facilitate"]
+
+  forbidden:
+    - "synergy"
+    - "paradigm shift"
+    - "game-changing"
+
+doNot:
+  - pattern: "click here"
+    reason: "Poor accessibility"
+    suggestion: "Describe the destination"
+    severity: error
+
+  - pattern: "\\b(obviously|simply|just)\\b"
+    isRegex: true
+    reason: "Can make users feel stupid"
+    severity: warning
+```
+
+## Self-Hosting
+
+### Docker
+
+```bash
+# Clone the repo
+git clone https://github.com/stylemcp/stylemcp.git
+cd stylemcp
+
+# Set up environment
+echo "STYLEMCP_API_KEY=$(openssl rand -hex 32)" > .env
+
+# Run with Docker
+docker compose up -d
+
+# Check health
+curl http://localhost:3000/health
+```
+
+### Manual
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Start server
+npm start
+```
+
+## GitHub Actions
+
+```yaml
+name: Brand Check
+on: [pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate copy
+        run: |
+          npx stylemcp validate src/copy/*.json \
+            --min-score 80 \
+            --format github
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | 3000 |
+| `STYLEMCP_API_KEY` | API key for authentication | (none) |
+| `GITHUB_WEBHOOK_SECRET` | GitHub webhook secret | (none) |
+
+## MCP Tools
+
+When used as an MCP server, StyleMCP provides these tools:
+
+| Tool | Description |
+|------|-------------|
+| `validate_text` | Validate text against brand rules |
+| `rewrite_to_style` | Rewrite text to match brand voice |
+| `get_voice_rules` | Get voice and tone guidelines |
+| `get_copy_patterns` | Get approved copy patterns |
+| `get_cta_rules` | Get CTA guidelines |
+| `get_tokens` | Get design tokens |
+| `list_packs` | List available style packs |
+
+## What Gets Validated?
+
+The `saas` pack checks for:
+
+### Vocabulary
+- Use simple words: "use" not "utilize", "help" not "assist"
+- Avoid jargon: "synergy", "leverage", "paradigm shift"
+- Avoid weak intensifiers: "very", "really", "extremely"
+
+### Patterns
+- No "click here" (accessibility issue)
+- No "we're sorry for any inconvenience" (corporate non-apology)
+- No double "please" (sounds desperate)
+- No starting with "Sorry" (lead with solutions)
+
+### CTAs
+- Avoid generic: "Submit", "OK", "Yes/No", "Click here"
+- Use specific actions: "Save", "Create", "Sign up", "Export"
+- Max 4 words
+
+### Constraints
+- Max 25 words per sentence
+- No exclamation marks (in most contexts)
+- First-person plural ("we", "our")
+- Oxford comma
+
+## License
+
+MIT

package/action/action.yml

@@ -0,0 +1,59 @@
+name: 'StyleMCP'
+description: 'Validate text and copy against brand/voice rules. Brand CI for AI output.'
+author: 'StyleMCP'
+
+branding:
+  icon: 'check-circle'
+  color: 'blue'
+
+inputs:
+  pack:
+    description: 'Style pack to use (built-in: saas, or path to custom pack)'
+    required: false
+    default: 'saas'
+  files:
+    description: 'Glob pattern for files to validate (e.g., "src/**/*.tsx", "docs/**/*.md")'
+    required: false
+    default: ''
+  text:
+    description: 'Direct text to validate (alternative to files)'
+    required: false
+    default: ''
+  min-score:
+    description: 'Minimum passing score (0-100)'
+    required: false
+    default: '70'
+  strict:
+    description: 'Fail on any violation, regardless of score'
+    required: false
+    default: 'false'
+  fail-on-warning:
+    description: 'Treat warnings as failures'
+    required: false
+    default: 'false'
+  content-type:
+    description: 'Content type hint (ui-copy, marketing, docs, support, general)'
+    required: false
+    default: 'general'
+  comment-on-pr:
+    description: 'Post validation results as a PR comment'
+    required: false
+    default: 'true'
+  github-token:
+    description: 'GitHub token for PR comments (defaults to GITHUB_TOKEN)'
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  score:
+    description: 'Overall validation score (0-100)'
+  valid:
+    description: 'Whether validation passed'
+  violations:
+    description: 'Number of violations found'
+  report:
+    description: 'Full validation report as JSON'
+
+runs:
+  using: 'node20'
+  main: 'dist/index.js'

package/action/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "stylemcp-action",
+  "version": "0.1.0",
+  "private": true,
+  "description": "GitHub Action for StyleMCP validation",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "ncc build src/index.ts -o dist --source-map --license licenses.txt",
+    "package": "npm run build"
+  },
+  "dependencies": {
+    "@actions/core": "^1.10.1",
+    "@actions/github": "^6.0.0",
+    "glob": "^10.4.1",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.0",
+    "@vercel/ncc": "^0.38.1",
+    "typescript": "^5.5.0"
+  }
+}