IMPORTANT: Before modifying this file, please update CHANGELOG.md with a summary of your changes. Also, make clear comments about every change in this file and what it was replacing so that we don't end up trying the same fixes repeatedly.

Opichi Style MCP

An MCP server for discovering, documenting, comparing, and applying styles across projects with strict per-project isolation. Distributed via npm. Designed to:

• Discover existing styles (tokens, utilities, component archetypes) and generate a project-local style reference.
• Compare live code against the reference and surface drift and gaps.
• Apply consistent styles to pages/components across CSS/SCSS/LESS, React, Vue, HTML, and Tailwind.
• Assist feature planning by outputting a style spec aligned with the reference.
• Edit the reference safely (soft-delete by default, optional hard-delete).

Status

Fully implemented with all features working. The server can discover styles across multiple frameworks, maintain style references, compare actual usage against references, and safely apply style modifications with backup support.

Key Concepts

• Per-project isolation: stores data under .opichi/ inside the detected project root.
• Non-destructive operations by default (soft delete, backups for writes).
• Stdio transport only; no stdout logging (stderr for logs).

Install

npm i -g opichi-style-mcp

Run (as an MCP server)

This server runs over stdio. Configure it in your MCP host (e.g., Claude Desktop) to invoke:

node /ABSOLUTE/PATH/TO/opichi-style-mcp/build/index.js

Claude Desktop example

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "opichi-style-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/opichi-style-mcp/build/index.js"]
    }
  }
}

Tool Contracts (AI-facing)

All tools accept an optional rootPath which, if omitted, is auto-detected as the project root.

• discover_styles

  • purpose: scan target scope and build/update the style reference.
  • params: { scope: "app" | "page" | "component" | "glob", target?: string, includeFrameworks?: string[], write: boolean, rootPath?: string }
  • behavior: merges non-destructively when write=true; previews otherwise.

• get_style_reference

  • purpose: return current style reference (optionally create an empty shell).
  • params: { createIfMissing?: boolean, rootPath?: string }

• compare_styles

  • purpose: compare live code vs reference; report drift and suggested patches.
  • params: { scope: "app" | "page" | "component" | "glob", target?: string, strict?: boolean, rootPath?: string }

• apply_styles

  • purpose: align provided files to the reference.
  • params: { files: string[], strategy: "utility" | "semantic" | "component" | "hybrid", dryRun?: boolean, allowAdditions?: boolean, rootPath?: string }

• plan_feature_styles

  • purpose: produce a style spec for a new feature consistent with the reference.
  • params: { featureDescription: string, outputFormat?: "markdown" | "json", rootPath?: string }

• update_style_reference

  • purpose: edit reference safely.
  • params: { operations: Array<{ op: "add" | "replace" | "remove", path: string, value?: any, soft?: boolean, force?: boolean }>, rootPath?: string }

• list_frameworks_detected

  • purpose: enumerate detected frameworks/utilities for the project.
  • params: { rootPath?: string }

Resources

• style://reference — current reference JSON
• style://report/{timestamp} — last discovery/compare report
• style://diff/{timestamp} — last apply diff plan

Development

• Build: npm run build
• Logging: use console.error only. Never write to stdout in stdio mode.

Contributing

• Follow the CHANGELOG protocol.
• Keep files modular and under 400 lines when possible.