Canon

Universal MCP knowledge server for LLM agents, powered by local RAG.

Use Canon to provide domain-specific best practices and playbooks across software engineering, marketing, video editing, and other knowledge areas.

Typical workflows:

• Find the most suitable guide for a task
• Retrieve concise best-practice snippets
• Read full guides for deeper execution context

Quick Start

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"]
    }
  }
}

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"],
      "env": {
        "CANON_DB_PATH": "/path/to/my-db"
      }
    }
  }
}

{
  "mcpServers": {
    "canon": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

claude mcp add --scope user canon -- uvx mcp-canon

claude mcp add --scope user -e CANON_DB_PATH=/path/to/my-db canon -- uvx mcp-canon

claude mcp add --scope user --transport http canon http://localhost:8080/mcp

{
  "mcp": {
    "canon": {
      "type": "local",
      "command": ["uvx", "mcp-canon"],
      "enabled": true
    }
  }
}

{
  "mcp": {
    "canon": {
      "type": "local",
      "command": ["uvx", "mcp-canon"],
      "enabled": true,
      "environment": {
        "CANON_DB_PATH": "/path/to/my-db"
      }
    }
  }
}

"mcp": {
  "context7": {
    "type": "remote",
    "url": "http://localhost:8080/mcp",
    "enabled": true
  }
}

gemini mcp add --scope user canon uvx mcp-canon

gemini mcp add --scope user -e CANON_DB_PATH=/path/to/my-db canon uvx mcp-canon

gemini mcp add --scope user --transport http canon http://localhost:8080/mcp

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"]
    }
  }
}

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"],
      "env": {
        "CANON_DB_PATH": "/path/to/my-db"
      }
    }
  }
}

Create and index your own guides

Complete workflow from installation to running with your own domain guides.

Step 1: Install with indexing support

pip install "mcp-canon[indexing]"

Step 2: Create library structure

my-library/
├── engineering/
│   └── python-fastapi-guide/
│       ├── INDEX.md      # Required: metadata
│       └── GUIDE.md      # Content
├── marketing/
│   └── launch-playbook/
│       ├── INDEX.md
│       └── GUIDE.md
└── video-editing/
    └── shorts-workflow/
        └── INDEX.md      # Can reference external URL

Step 3: Create guides

Step 4: Index your library

# Index to custom location
canon index --library ./my-library --output /path/to/my-db

# Validate frontmatter before indexing (optional)
canon validate --library ./my-library

Running as HTTP server

For remote access or multi-client scenarios, run Canon as an HTTP server. This is useful when multiple agents or teams share one cross-domain knowledge base.

Step 1: Install with HTTP support

pip install "mcp-canon[http]"

Step 2: Start the server

# Default port 8080
canon serve

# Custom port and host
canon serve --port 3000 --host 0.0.0.0

# With custom database
CANON_DB_PATH=/path/to/db canon serve --port 8080

Step 3: Configure MCP client

{
  "mcpServers": {
    "canon": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Environment Variables

Note: Changing CANON_EMBEDDING_MODEL or CANON_EMBEDDING_DIM requires a full reindex: canon index --library ./library

Change embedding model and dimensions

Internal constants EMBEDDING_MODEL_NAME and EMBEDDING_DIM are configured via:

• CANON_EMBEDDING_MODEL
• CANON_EMBEDDING_DIM

Example (using BAAI/bge-small-en-v1.5, 384 dims):

CANON_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5 \
CANON_EMBEDDING_DIM=384 \
canon index --library ./library --output ./my-db

Where to find available models:

• FastEmbed supported models: https://qdrant.github.io/fastembed/examples/Supported_Models/
• FastEmbed model card and usage notes: https://qdrant.github.io/fastembed/

Important:

• CANON_EMBEDDING_DIM must match the selected model output size.
• After changing model or dimension, rebuild the index before running search/server commands.

MCP Tools

CLI Commands

# Indexing
canon index --library ./library           # Index guides from any domain (creates new DB)
canon index --library ./lib --append      # Add to existing database
canon validate --library ./library        # Validate frontmatter

# Server
canon serve --port 8080                   # Start HTTP server (requires [http])

# Info
canon list                                # List indexed guides
canon info                                # Show database info

License

MIT