Conventions MCP

🎯 Access coding conventions and best practices from community and enterprise repositories

A Model Context Protocol (MCP) server that provides AI assistants like Claude with access to coding conventions, best practices, and standards from both open-source community repositories and private enterprise sources.

Vision

Create the definitive platform for coding conventions that serves both open-source community collaboration and enterprise security needs, establishing a standard for how AI coding tools receive contextual guidance.

Architecture

Conventions MCP connects Claude to multiple convention sources (built-in, local directories, and Git repositories) through the Model Context Protocol, enabling dynamic access to coding conventions, agent definitions, workflows, and best practices.

Quick Start

Install with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "conventions": {
      "command": "npx",
      "args": ["@ablukis/conventions-mcp"]
    }
  }
}

Search for Conventions

You: "Search for fastapi patterns"

Claude: Found 2 conventions:

1. **FastAPI Architect** (100% match)
   Type: agent | Tokens: 767
   Tags: fastapi, python, api, async, backend
   Match: "Expert in building production FastAPI applications..."
   Path: agents/web-fastapi-architect.md

Configuration

Conventions MCP works out-of-the-box with built-in conventions. You can optionally configure additional sources.

Configuration File

Location: ~/.config/conventions-mcp/config.yaml (optional)

Create from template:

mkdir -p ~/.config/conventions-mcp
cp config.example.yaml ~/.config/conventions-mcp/config.yaml

Example:

# Local filesystem directories
localDirectories:
  - id: company-standards
    path: ~/company-conventions
    enabled: true
    priority: 1

# Git repositories
repositories:
  - id: awesome-subagents
    url: https://github.com/VoltAgent/awesome-claude-code-subagents.git
    type: public
    authMethod: none
    enabled: true
    autoSync: true
    cacheTTL: 3600

Configuration Fields

Common Fields:

• id - Unique identifier for the source
• enabled - Set to false to temporarily disable a source
• priority - Lower numbers = scanned first (built-in conventions are priority 0)
• description - Optional description of the source

Local Directories:

• path - Filesystem path to directory containing conventions

Git Repositories:

• url - Git repository URL (SSH or HTTPS)
• type - public or private
• authMethod - none, ssh, or https-token
• token - Personal Access Token for https-token auth (encrypted at rest with AES-256-CBC)
• autoSync - Automatically sync repository in background (default: true)
• cacheTTL - Seconds before auto-sync check (default: 3600 = 1 hour)
• customDirectories - Optional mapping for non-standard directory names (e.g., {agent: ['categories']})

Environment Variables

Configuration:

• CONVENTIONS_CONFIG_PATH - Custom config location (default: ~/.config/conventions-mcp/config.yaml)

Token Management:

• CONVENTIONS_MCP_CONTEXT_WINDOW - Context window size (default: 200000)
• CONVENTIONS_MCP_TOKEN_WARNING_THRESHOLD - Warning threshold (default: 10000)
• CONVENTIONS_MCP_MIN_RELEVANCE_SCORE - Minimum relevance 0.0-1.0 (default: 0.3)

Repository Sync:

• CONVENTIONS_MCP_SYNC_POLL_INTERVAL_MS - Background sync interval in milliseconds (default: 10800000 = 3 hours)

Adding Repositories

Public Repository

You: "Add repository id: awesome-conventions, url: https://github.com/org/repo.git, type: public, authMethod: none"

Claude: ✅ Repository 'awesome-conventions' added successfully.

Private Repository (SSH)

Prerequisites: SSH key added to your GitHub/GitLab account

You: "Add repository id: company-standards, url: [email protected]:company/private-repo.git, type: private, authMethod: ssh"

Claude: ✅ Repository 'company-standards' added successfully.

Private Repository (HTTPS Token)

Prerequisites: Personal Access Token (PAT) with repo access

You: "Add repository id: company-private, url: https://github.com/company/repo.git, type: private, authMethod: https-token, token: ghp_YourToken123"

Claude: ✅ Repository 'company-private' added successfully.

Security Note: Tokens are encrypted at rest using AES-256-CBC

Automatic Repository Syncing

Conventions MCP uses smart background syncing:

1. Startup Sync: Automatically clones/updates repositories when MCP server starts (non-blocking)
2. Background Polling: Checks for remote changes every 3 hours (configurable), only pulls when new commits detected
3. Zero-Impact Searches: Searches never wait for git operations
4. Auto-Index Refresh: Search index automatically updates after successful sync

Customize Poll Interval:

export CONVENTIONS_MCP_SYNC_POLL_INTERVAL_MS=86400000  # 24 hours

Manual Sync:

You: "Sync repository awesome-conventions"
Claude: ✅ Repository 'awesome-conventions' synced successfully

Features

Multi-Source Support

• Built-in conventions: 76 included conventions (agents, specs, workflows, skills, patterns, templates)
• Local directories: Configure additional filesystem directories
• Git repositories: Clone and sync public/private repositories
• Smart background sync: Zero-impact repository updates with auto-index refresh
• Authentication: SSH keys and HTTPS tokens with AES-256-CBC encryption

Smart Search

• Fuzzy matching: Typo-tolerant search ("nexjs" → "NextJS Specialist")
• Relevance scoring: Results ranked 0-100% by match quality
• Quality filtering: Automatically removes low-relevance matches (< 30% by default)
• Tag weighting: Prioritizes tags over descriptions
• Progressive disclosure: Lightweight metadata previews (~60 tokens) before full content (~1000+ tokens)

Token Management

• Accurate counting: Tiktoken-based (cl100k_base encoding) with ~18.5% accuracy
• Warnings: Automatic warnings when results exceed 10K tokens
• Context tracking: Shows percentage of Claude Sonnet 200K context window used
• Budget support: Token budget parameter with remaining token display
• Optimized responses: Complete workflow < 5000 tokens (scales to 20+ repositories)

Supported Repository Structures

Standard directories:

your-repo/
├── agents/       # AI agent definitions
├── specs/        # Specifications
├── workflows/    # Development workflows
├── commands/     # Scripts
├── skills/       # Skills
├── patterns/     # Design patterns
└── templates/    # Templates

Claude Code infrastructure (.claude/ prefix):

your-repo/
├── .claude/
│   ├── agents/
│   ├── skills/
│   └── hooks/

Nested plugins (wshobson/agents pattern):

your-repo/
├── plugins/
│   ├── plugin-1/
│   │   ├── agents/
│   │   └── skills/
│   └── plugin-2/
│       └── agents/

Root-level skill folders (anthropics/skills pattern):

your-repo/
├── skill-1/
│   ├── SKILL.md
│   └── patterns/
└── skill-2/
    └── SKILL.md

Custom directory mapping: For non-standard structures

You: "Add repository id: custom-repo, url: https://github.com/org/repo.git, type: public, authMethod: none, customDirectories: {agent: ['categories']}"

Type auto-detection works for all structures using SKILL.md detection, directory patterns, filename patterns, and content analysis.

Available MCP Tools

| Tool | Description | Typical Token Usage | |------|-------------|---------------------| | get_conventions_overview | Get compact hierarchical summary of all conventions | ~500 tokens | | find_conventions | Search with fuzzy matching and metadata previews | ~60 tokens/result | | list_conventions_by_type | List all conventions of a specific type (deterministic, paginated) | ~50 tokens/result | | read_convention | Retrieve full convention content by path | ~1000-2000 tokens | | add_repository | Add new Git repositories (public or private) | - | | list_repositories | Show all convention sources with status | - | | sync_repository | Manually sync repositories | - | | remove_repository | Remove repository and local files | - | | get_token_stats | Get token usage statistics | - |

Progressive Disclosure Workflow

For optimal token efficiency, use this 3-step workflow:

1. Start with overview (get_conventions_overview): Get compact summary of what's available (~500 tokens)
2. Search or list (find_conventions or list_conventions_by_type): Get metadata previews (~60 tokens/result)
3. Read specific content (read_convention): Get full convention content only when needed (~1500 tokens)

Complete workflow: < 5000 tokens (scales to 10-20 repositories)

Roadmap

✅ v1.1.1 - Token Optimization (Current)

• Progressive disclosure with compact overview (~500 tokens, down from 130,000)
• Auto-index refresh on repository sync
• Renamed tools for clarity (find_conventions, read_convention)
• New list_conventions_by_type tool for deterministic type listings
• Token budget compliance: complete workflow < 5000 tokens
• Scales to 10-20 repositories without context overflow

✅ v1.0.0 - Core Functionality

• Multi-repository management with SSH/HTTPS authentication
• Local directory configuration
• Smart search with fuzzy matching and relevance filtering
• Token management with accurate counting
• Support for 6 repository structure patterns

Next Up

• v1.2.0: GitLab and Bitbucket support, air-gapped mode optimization
• v1.3.0: Content expansion (more agents, workflows, framework-specific conventions)
• Future: Enterprise features (audit logging, access control, role-based permissions)

Contributing

We welcome contributions! Areas where you can help:

• Community Standards: Create and maintain open-source convention repositories
• Platform Development: Improve the MCP server and tools
• Documentation: Help others understand and use Conventions MCP
• Integration: Build connections with IDEs and AI tools

Local Development

Prerequisites

• Node.js 18 or higher
• npm or yarn

Setup

# Clone and install
git clone https://github.com/andisab/conventions-mcp.git
cd conventions-mcp
npm install

# Build
npm run build

# Test locally
npm run dev

Configure with Claude Desktop

For local development, use the built version:

{
  "mcpServers": {
    "conventions": {
      "command": "node",
      "args": ["/absolute/path/to/conventions-mcp/dist/index.js"]
    }
  }
}

See docs/DEV_GUIDE.md for detailed testing instructions.

License

MIT License - see LICENSE file for details.

Created by: Andis A. Blukis Repository: github.com/andisab/conventions-mcp NPM Package: @ablukis/conventions-mcp