aic-holdings/symmetra

Symmetra

Production-ready architectural patterns at the speed of thought

Symmetra is your AI coding assistant's expert architectural consultant, providing instant access to battle-tested patterns, complete implementations, and security-first best practices.

Instead of researching Stack Overflow and piecing together tutorials, your AI assistant gets complete, production-ready solutions with built-in security, error handling, and deployment guidance - accelerating development while reducing architectural risk.

🆕 NEW: Conversational Guidance Capture - Capture architectural patterns directly from your codebase through natural conversation with Claude Code. Say "This error handling pattern is clean - let's add it as guidance!" and Symmetra will help you capture, refine, and make it searchable for future use.

Symmetra integrated with Claude Code, providing real-time architectural guidance

✨ Key Features

• 🚀 Complete Implementations: Get entire auth systems, CRUD patterns, and integrations - not just code snippets
• 🔒 Security-First: Every pattern includes RLS policies, input validation, and vulnerability prevention
• ⚡ Instant Delivery: Vector-powered search returns comprehensive solutions in milliseconds
• 🎯 Context-Aware: Patterns adapt to your stack (Next.js, Supabase, Tailwind, ShadCN, etc.)
• 🤖 AI-Native Integration: Seamless integration with Claude Code and other MCP-compatible assistants
• 📝 Conversational Capture: Add new guidance through natural conversation - capture patterns as you discover them
• 📋 Project Checklists: Step-by-step guidance for building complete applications from scratch

🚀 Quick Start

Installation

Option 1: Direct execution with uvx (Recommended)

# Run without installation - perfect for trying Symmetra
uvx --from git+https://github.com/aic-holdings/symmetra symmetra --help

Option 2: Local development

# Clone and install with uv
git clone https://github.com/aic-holdings/symmetra
cd symmetra
uv run symmetra --help

# Or with pip
pip install -e .
symmetra --help

Option 3: Docker (Experimental)

docker run --rm -i --network host \
  -v "$(pwd)":/workspace \
  ghcr.io/aic-holdings/symmetra:latest \
  symmetra check

Integration with AI Coding Assistants

Claude Code Integration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "symmetra": {
      "command": "symmetra",
      "args": ["server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
      }
    }
  }
}

For project-specific configuration, create .symmetra.toml in your project root:

[project]
name = "my-project"

[api]
openai_api_key = "sk-your-api-key-here"

Claude Desktop Integration

Add to your Claude Desktop settings:

{
  "mcpServers": {
    "symmetra": {
      "command": "symmetra-server"
    }
  }
}

Basic Usage

Once integrated, ask your AI assistant:

• "Get guidance for implementing Supabase authentication" → Complete Next.js SSR auth system
• "Show me a ShadCN form with validation" → Full react-hook-form + zod + error handling
• "I need file upload with Supabase Storage" → Drag-drop, resize, security policies included
• "Help me build a documentation site" → Step-by-step Nextra setup checklist
• "Create a Stripe subscription flow" → Payment processing with webhooks and edge cases

📋 What You Get

Production-Ready Patterns

Symmetra provides complete implementations for:

• 🔐 Authentication Systems: Supabase Auth with SSR, email confirmation, RLS policies
• 📝 Form Handling: ShadCN + react-hook-form + Zod validation with error states
• 📁 File Management: Upload, resize, CDN delivery with security best practices
• 💳 Payment Processing: Stripe integration with webhooks and subscription management
• 📊 Data Tables: Server-side pagination, filtering, sorting with Supabase
• ✉️ Email Systems: Transactional emails with templates and delivery tracking
• 🔄 Real-time Features: Live chat, notifications with Supabase Realtime
• 📱 Image Optimization: Next.js Image with WebP conversion and responsive sizing

Example: Complete Auth Implementation

When you ask for "Supabase authentication guidance", you get:

• ✅ 2,700+ lines of production-ready code
• ✅ Server and client component setup
• ✅ Middleware for session management
• ✅ Email confirmation flow
• ✅ Protected route patterns
• ✅ RLS security policies
• ✅ Error handling and edge cases
• ✅ Testing examples and deployment checklist

🔧 Commands & Usage

Available Commands

# Start MCP server for AI integration
symmetra server

# Start HTTP server for production deployment  
symmetra http --host 0.0.0.0 --port 8080

# Initialize Symmetra in a new project
symmetra init

# Run architectural analysis on current project
symmetra check

# Validate specific files or directories
symmetra validate src/components/

# Show configuration
symmetra config show

Development Workflow

# Run tests before committing
pytest test/

# Check architectural compliance
symmetra check

# Start development server
uv run symmetra server

# Deploy to production
symmetra http --port 8080

🔗 Detailed Integration Guide

Project Setup & Configuration

If you are mostly working with the same project, you can configure to always activate it at startup by passing --project <path_or_name> to the Symmetra server command in your client's MCP config. This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code.

Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, in case the project was configured before, by its name. The default project name is the directory name.

• "Configure Symmetra for the project /path/to/my_project"
• "Activate Symmetra for my_project"

All projects that have been configured will be automatically added to your global Symmetra config, and for each project, the file .symmetra.toml will be generated. You can adjust the latter, e.g., by changing the name (which you refer to during activation) or other architectural rules. Make sure to not have two different projects with the same name.

ℹ️ For larger projects, we recommend that you analyze your project to accelerate Symmetra's guidance; otherwise the first analysis may be slower. To do so, run this from the project directory (or pass the path to the project as an argument):

uvx --from git+https://github.com/aic-holdings/symmetra symmetra check

Running the Symmetra MCP Server

There are several ways to run the Symmetra MCP server, depending on your setup:

Option 1: Direct execution with uvx (Recommended)

uvx --from git+https://github.com/aic-holdings/symmetra symmetra server

Option 2: Local development with uv

# From Symmetra source directory
uv run symmetra server

Option 3: After installation

# If you've installed Symmetra globally
symmetra server

Option 4: Docker

docker run --rm -i --network host \
  -v "$(pwd)":/workspace \
  ghcr.io/aic-holdings/symmetra:latest \
  symmetra server --transport stdio

Claude Code

Symmetra is a great way to make Claude Code both cheaper and more powerful with architectural guidance!

From your project directory, add Symmetra with a command like this:

claude mcp add symmetra -- <symmetra-mcp-server> --context ide-assistant --project $(pwd)

where <symmetra-mcp-server> is your way of running the Symmetra MCP server. For example, when using uvx, you would run:

claude mcp add symmetra -- uvx --from git+https://github.com/aic-holdings/symmetra symmetra server --context ide-assistant --project $(pwd)

ℹ️ Symmetra comes with architectural guidance instructions, and Claude needs to read them to properly use Symmetra's tools. As of version v1.0.52, Claude Code reads the instructions of the MCP server, so this is handled automatically. If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly to "read Symmetra's initial instructions" or access Symmetra's guidance resources directly. Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Symmetra's tools.

Other Terminal-Based Clients

There are many terminal-based coding assistants that support MCP servers, such as Codex, Gemini-CLI, Qwen3-Coder, rovodev, the OpenHands CLI and opencode.

They generally benefit from the architectural guidance tools provided by Symmetra. You might want to customize some aspects of Symmetra by writing your own rules or configuration to adjust it to your workflow, to other MCP servers you are using, and to the client's internal capabilities.

Claude Desktop

For Claude Desktop (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config, which will let you open the JSON file claude_desktop_config.json. Add the symmetra MCP server configuration, using a run command depending on your setup.

• local installation:

  {
      "mcpServers": {
          "symmetra": {
              "command": "/abs/path/to/uv",
              "args": ["run", "--directory", "/abs/path/to/symmetra", "symmetra", "server"]
          }
      }
  }
  

• uvx:

  {
      "mcpServers": {
          "symmetra": {
              "command": "/abs/path/to/uvx",
              "args": ["--from", "git+https://github.com/aic-holdings/symmetra", "symmetra", "server"]
          }
      }
  }
  

• docker:

   {
       "mcpServers": {
           "symmetra": {
               "command": "docker",
               "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/aic-holdings/symmetra:latest", "symmetra", "server", "--transport", "stdio"]
           }
       }
   }
  

If you are using paths containing backslashes for paths on Windows (note that you can also just use forward slashes), be sure to escape them correctly (\\).

That's it! Save the config and then restart Claude Desktop. You are ready for configuring your first project.

ℹ️ You can further customize the run command using additional arguments (see command-line arguments).

Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an open-source community version.

⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows.

⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. With Symmetra, you can activate the HTTP mode to prevent unnoted processes and also use the HTTP interface for monitoring Symmetra status.

After restarting, you should see Symmetra's tools in your chat interface (notice the small hammer icon).

For more information on MCP servers with Claude Desktop, see the official quick start guide.

MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.)

Being an MCP Server, Symmetra can be included in any MCP Client. The same configuration as above, perhaps with small client-specific modifications, should work. Most of the popular existing coding assistants (IDE extensions or VSCode-like IDEs) support connections to MCP Servers. It is recommended to use the ide-assistant context for these integrations by adding "--context", "ide-assistant" to the args in your MCP client's configuration. Including Symmetra generally boosts their performance by providing them tools for architectural guidance and code quality analysis.

In this case, the billing for the usage continues to be controlled by the client of your choice (unlike with the Claude Desktop client). But you may still want to use Symmetra through such an approach, e.g., for one of the following reasons:

1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more architecturally aware.
2. You are on Linux and don't want to use the community-created Claude Desktop.
3. You want tighter integration of Symmetra into your IDE and don't mind paying for that.

Command-Line Arguments

The Symmetra MCP server supports several command-line arguments for customization:

symmetra server [OPTIONS]

Options:
  --project PATH          Project path to activate automatically
  --context CONTEXT       Context mode (ide-assistant, terminal, etc.)
  --transport TRANSPORT   Transport mode (stdio, http)
  --port PORT            HTTP port (when using http transport)
  --log-level LEVEL      Logging level (DEBUG, INFO, WARNING, ERROR)
  --config PATH          Custom configuration file path
  --help                 Show this message and exit

Examples:

# Start with specific project
symmetra server --project /path/to/my/project

# Start in IDE assistant mode
symmetra server --context ide-assistant

# Start HTTP server on custom port
symmetra server --transport http --port 8080

# Debug mode with verbose logging
symmetra server --log-level DEBUG

⚙️ Configuration

Symmetra supports flexible, layered configuration:

Global Configuration

~/.config/symmetra/config.toml

[general]
default_complexity_threshold = "medium"
auto_format_suggestions = true

[rules]
max_file_lines = 300
max_function_lines = 50
enforce_type_hints = true

Project Configuration

.symmetra.toml (in project root)

[project]
name = "my-awesome-app"
architecture_style = "clean_architecture"

[rules]
max_file_lines = 500  # Override global setting
custom_patterns = [
    "no_god_objects",
    "single_responsibility"
]

[ignore]
paths = ["migrations/", "legacy/"]

🏗️ Architecture & Integration

MCP Protocol Integration

Symmetra implements the Model Context Protocol (MCP) specification:

• Tools: get_guidance(action, code) - Real-time architectural advice
• Resources: symmetra://rules - Access to governance rules and patterns
• Prompts: review_code(code) - Structured code review templates

Transport Modes

• Stdio (default): Optimal for local development and AI assistant integration
• HTTP: Production-ready with horizontal scaling support

Supported AI Platforms

• ✅ Claude Code
• ✅ Claude Desktop
• ✅ Any MCP-compatible client
• 🔄 Planned: Direct OpenAI integration
• 🔄 Planned: Local LLM support (Ollama)

📚 Documentation

• - Get up and running in 5 minutes
• - Complete configuration options
• - Writing custom architectural rules
• - MCP protocol implementation details
• - Platform-specific setup instructions
• - How to contribute to Symmetra

🎯 Design Philosophy

🤝 Advisory, Not Blocking: Symmetra provides intelligent suggestions without breaking your development flow. AI agents receive guidance but developers maintain full control.

🧠 AI-Native: Built specifically for AI-powered development workflows, ensuring seamless integration with modern coding assistants.

🔧 Extensible by Design: Plugin architecture allows teams to customize rules and integrations for their specific needs.

⚡ Performance First: Designed for real-time feedback with minimal overhead in your development environment.

🚀 Roadmap

v1.0 - ✅ Foundation Complete

• Core MCP protocol implementation
• Real-time architectural guidance via AI assistants
• Conversational guidance capture system
• Vector-powered search with OpenAI embeddings
• Project-aware configuration and rules
• Modern documentation site with MkDocs Material

v2.0 - Enhanced Intelligence

• Language Server Protocol (LSP) integration for semantic code understanding
• Advanced dependency analysis and visualization
• Custom rule development with Python plugins
• Integration with popular CI/CD platforms

v3.0 - Team Collaboration

• Team governance dashboards
• Architectural decision record (ADR) integration
• Slack/Discord notifications for violations
• Multi-repository governance

v4.0 - Enterprise Ready

• Advanced security analysis
• Performance impact prediction
• Compliance reporting (SOC2, HIPAA, etc.)
• Enterprise SSO integration

🤝 Contributing

We welcome contributions! Symmetra is built by developers, for developers.

• 🐛 Found a bug? Open an issue
• 💡 Have a feature idea? Start a discussion
• 📝 Want to contribute? Check our

Development Setup

# Clone the repository
git clone https://github.com/aic-holdings/symmetra
cd symmetra

# Install development dependencies
uv sync --dev

# Run tests
pytest

# Run the development server
uv run symmetra server

🌟 Community & Support

• 📖 Documentation: symmetra.dev
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 📧 Email: support@symmetra.dev

📄 License

This project is licensed under the - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the excellent FastMCP framework
• Inspired by the architectural guidance principles of Clean Architecture and Domain-Driven Design
• Special thanks to the Anthropic MCP team for the protocol specification

Symmetra v1.0 - Bringing architectural intelligence to AI-powered development.

Built with ❤️ by developers who care about code quality and team productivity.