Grail 📊

April 8, 2025 · View on GitHub

Bridgekeeper: Stop! Who would cross the Bridge of Code must answer me these questions three...
Sir Angelsen: Ask me the questions, Bridgekeeper. I am not afraid.
Bridgekeeper: What... is your name?
Sir Angelsen: My name is Sir Angelsen of Claude.
Bridgekeeper: What... is your quest?
Sir Angelsen: To seek the Holy Grail of Code Patterns!
Bridgekeeper: What... is your favorite search method?
Sir Angelsen: Semantic! No, wait-- AAAAAAAA!

AI-powered pattern management system for Claude Code, inspired by the quest for the perfect code patterns. A comprehensive system enabling efficient organization, discovery and application of patterns through semantic search and AI assistance.

Features

🧠 Semantic Pattern Search: Find patterns by meaning, not just keywords
🔄 MCP Server Integration: Seamless integration with Claude Code
🗄️ Vector Database Storage: Efficient pattern storage and retrieval
📈 Project Tracking: Monitor pattern usage across projects
⌨️ CLI Interface: Powerful command-line tools
🖥️ Reflex UI: Intuitive visual interface for pattern exploration

Why Grail?

Traditional pattern libraries rely on exact keyword matching, categories, or manual browsing. Grail revolutionizes this approach by:

Understanding the semantic intent of patterns through vector embeddings
Providing a unified interface between your codebase and AI assistants
Enabling powerful pattern discovery across languages and frameworks
Streamlining the pattern application process with Claude Code

Quick Start

# Install dependencies 
uv sync

# Option 1: Using .mcp.json (recommended for teams)
# The project includes a .mcp.json file ready for use
# Claude Code automatically detects and loads MCP servers on startup

# Option 2: Manual configuration
# Configure the Grail MCP server in Claude Code
claude mcp add grail uv -- run -m grail server

When you start Claude Code in a project with Grail configured, it automatically detects the MCP server:

╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code                          │
│                                                   │
│   /help for help                                  │
│                                                   │
│   cwd: /path/to/project                           │
╰───────────────────────────────────────────────────╯

 ✔ Found 1 MCP server • /mcp

You can check MCP server status anytime with the /mcp command:

> /mcp
  ⎿  MCP Server Status
  ⎿
  ⎿  • grail: connected

Usage With Claude Code

Claude automatically identifies and uses Grail tools as needed during conversation. Simply ask questions about patterns, and Claude will use the appropriate Grail tools:

Search Patterns Semantically

> use semantic search, do we have any formsnap patterns?

● Let me check for FormSnap patterns using semantic search.

● grail:search_patterns (MCP)(query: "formsnap", semantic: true)…
  ⎿  {
       "id": "6",
       "name": "Formsnap Form Styling",
       ...
       "score": 0.7523476481437683
     }
  ...

Retrieve Pattern Details

> get details for the login form pattern

● I'll retrieve the login form pattern.

● grail:get_pattern (MCP)(pattern_id: "7")…
  ⎿  {
       "id": "7",
       "name": "Formsnap Login Form",
       "type": "idiom",
       "languages": ["typescript", "svelte"],
       "frameworks": ["sveltekit", "formsnap"],
       "description": "Complete login form with email, password, and remember me fields",
       "content": { ... }
     }

Create a New Pattern

> create a pattern for react error boundary

● I'll help you create a pattern for React Error Boundary.

● grail:store_pattern (MCP)(pattern: {
    "name": "React Error Boundary",
    "type": "idiom",
    "languages": ["typescript", "javascript"],
    "frameworks": ["react"],
    "description": "Component for catching and handling errors in React components",
    "content": { ... }
  })…
  ⎿  {
       "id": "8",
       "name": "React Error Boundary"
     }

Architecture

graph TD
    %% Client nodes
    Claude[Claude Code] <--> GrailServer[Grail MCP Server]
    CLI[CLI Interface] --> GrailServer
    Reflex[Reflex UI] --> GrailServer
    
    %% Server components
    subgraph GrailServerComponents[Grail MCP Server Components]
        FastMCP[FastMCP]
        Tools[MCP Tools]
        Resources[MCP Resources]
        DB_Manager[Database Manager]
        Vector_Manager[Vector Search Manager]
    end
    
    GrailServer --> FastMCP
    FastMCP --> Tools
    FastMCP --> Resources
    Tools --> DB_Manager
    Tools --> Vector_Manager
    
    %% Data storage
    DB_Manager --> SQLite[(SQLite Database)]
    Vector_Manager --> ChromaDB[(ChromaDB Vector Store)]
    Vector_Manager <--> VoyageAI[VoyageAI API]
    
    %% Pattern flow
    Pattern_Creation[Pattern Creation] --> Tools
    Pattern_Search[Pattern Search] --> Tools
    Vector_Manager -- Semantic Search --> ChromaDB
    Vector_Manager -- Reranking --> VoyageAI
    
    %% Styling
    classDef clientNode fill:#86b2f5,stroke:#3874d6,stroke-width:2px;
    classDef serverNode fill:#f7be7f,stroke:#e67e22,stroke-width:2px;
    classDef dataNode fill:#a5dbb5,stroke:#41b35d,stroke-width:2px;
    classDef uiNode fill:#d9aaeb,stroke:#9c56b8,stroke-width:2px;
    classDef apiNode fill:#f794c8,stroke:#e84393,stroke-width:2px;
    classDef flowNode fill:#82cce2,stroke:#3498db,stroke-width:2px;
    
    class Claude,CLI,Reflex clientNode;
    class GrailServer,FastMCP,Tools,Resources,DB_Manager,Vector_Manager serverNode;
    class SQLite,ChromaDB dataNode;
    class VoyageAI apiNode;
    class Pattern_Creation,Pattern_Search flowNode;
    class GrailServerComponents serverNode;

Available MCP Tools

Grail provides the following MCP tools that Claude automatically uses during conversation:

store_pattern: Store a new code pattern
search_patterns: Find patterns by text or semantic similarity
get_pattern: Retrieve a pattern by ID
update_pattern: Modify an existing pattern
delete_pattern: Remove a pattern
apply_pattern: Generate code from a pattern
extract_pattern: Create a new pattern from code

Development

# Setup development environment
uv sync

# Start the Grail MCP server manually (if not using .mcp.json)
uv run -m grail server

# Run linting
uv run ruff check .

# Run type checking
uv run pyright

# Run tests
uv run pytest

MCP Server Configuration

Grail uses a .mcp.json file at the project root for team-wide MCP server configuration:

{
  "mcpServers": {
    "grail": {
      "command": "uv",
      "args": ["run", "-m", "grail", "server", "--debug"],
      "env": {}
    }
  }
}

Claude Code automatically detects and loads this configuration when launched in the project directory.

Project Timeline

gantt
    title Grail Development Timeline
    dateFormat  YYYY-MM-DD
    axisFormat %b
    
    section Core Implementation
    Project setup             :done, setup, 2024-01-15, 14d
    Configuration management  :done, config, after setup, 10d
    Data models               :done, models, after config, 14d
    Storage implementation    :done, storage, after models, 21d
    MCP server setup          :done, mcp, after config, 14d
    Pattern management tools  :done, tools, after mcp, 21d
    
    section Current Phase
    Resource implementation   :done, resources, after tools, 21d
    Semantic search enhancement :done, search, after resources, 14d
    Project linting & formatting :active, linting, after search, 7d
    
    section Upcoming Features
    Pattern application templates :templates, after linting, 14d
    CLI implementation        :cli, after templates, 14d
    Testing & documentation   :testing, after cli, 21d
    
    section UI Development
    Reflex UI setup           :ui_setup, after testing, 14d
    UI pattern management     :ui_patterns, after ui_setup, 14d
    UI project tracking       :ui_projects, after ui_patterns, 14d