mcp-standards 0.1.0a1

Self-learning AI standards system - learns from corrections and auto-updates CLAUDE.md

MCP Standards - Self-Learning AI Standards System

Stop repeating yourself. MCP Standards learns from your corrections automatically and updates your AI configuration.

---

The Problem

You keep telling your AI assistant the same things:

• "Use uv not pip"
• "Use uv not pip"
• "Use uv not pip"

What if it learned after the 3rd time?

---

The Solution

MCP Standards learns from your corrections automatically:

1. You correct Claude 3 times: "use uv not pip"
2. MCP Standards detects the pattern
3. Preference promoted (80% confidence)
4. CLAUDE.md updated automatically
5. Claude never makes that mistake again

Before MCP Standards

You: "Use uv not pip"
Claude: *ignores, uses pip again*
You: "USE UV NOT PIP"
Claude: *ignores again*
You: "I TOLD YOU 10 TIMES, USE UV!!!"

After MCP Standards

You: "Use uv not pip" (correction #1)
You: "Use uv not pip" (correction #2)
You: "Use uv not pip" (correction #3)
MCP Standards: ✅ Pattern learned! Added to CLAUDE.md
Claude: *uses uv from now on, forever*

---

Features

✨ Self-Learning (THE Killer Feature)

Automatic Pattern Detection:

• Learns from corrections (3+ occurrences)
• Detects workflow patterns
• Promotes to preferences automatically
• Updates CLAUDE.md without manual work

5 Types of Learning:

1. Explicit corrections: "use X not Y"
2. Implicit rejections: User edits within 2 minutes
3. Rule violations: Compare vs config files
4. Workflow patterns: Always run tests after code
5. Tool preferences: Prefer certain tools for tasks

Confidence-Based Promotion:

• 3 occurrences = 30% confidence (detected)
• 5 occurrences = 70% confidence (high)
• 10 occurrences = 90% confidence (very high)
• 95%+ = auto-apply to CLAUDE.md

🎯 Automatic Standards Extraction

Reads your existing config files:

• .editorconfig → Indentation, line endings
• .prettierrc → Formatting, quotes
• .eslintrc → Linting rules
• pyproject.toml → Python config
• package.json → JavaScript dependencies
• Cargo.toml → Rust config

Auto-detects:

• Project type (Python, JavaScript, Rust, Go, etc.)
• Package manager (uv, npm, yarn, cargo, etc.)
• Test framework (pytest, jest, vitest, etc.)
• Build commands

Generates instruction files for:

• Claude Desktop/Code (CLAUDE.md)
• GitHub Copilot (.github/copilot-instructions.md)
• Cursor (.cursor/rules/standards.mdc)

🔒 Production-Grade Security

Built with defense-in-depth:

• ✅ Path whitelist - Only allowed directories
• ✅ Input sanitization - No log injection
• ✅ Rate limiting - 100 patterns/min max
• ✅ Audit logging - Complete modification trail
• ✅ 100% local - No cloud, no tracking

🧠 Persistent Memory

• Local SQLite database with FTS5
• Full-text search (<50ms on 1M+ episodes)
• Export to markdown
• Project-specific vs global preferences

---

Quick Start

Install

# 1. Clone repository
git clone https://github.com/airmcp-com/mcp-standards.git
cd mcp-standards

# 2. Install dependencies
uv sync

# 3. Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "mcp-standards": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-standards",
        "python",
        "run_server.py"
      ]
    }
  }
}
# Replace /ABSOLUTE/PATH/TO/ with your actual path!
# Example: /Users/yourname/Projects/mcp-standards/run_server.py

# 4. Restart Claude Desktop - you're done!

Option B: From PyPI (Coming Soon)

# Install from PyPI
uv pip install mcp-standards

# Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "mcp-standards": {
      "command": "mcp-standards",
      "args": []
    }
  }
}

# Restart Claude Desktop

🚀 60-Second Quickstart

Once Claude Desktop restarts, try this:

// 1. Store a preference right now
add_episode(
    name="My First Preference",
    content="I prefer using TypeScript over JavaScript for new projects",
    source="user"
)

// 2. Search for it
search_episodes(query="TypeScript", limit=5)

// 3. Generate AI standards from your current project
generate_ai_standards(project_path=".")

What just happened?

• ✅ Your preference is stored in local SQLite database
• ✅ Searchable in all future conversations
• ✅ AI standards file generated from your project config

Next: Start correcting Claude when it makes mistakes. After 3 similar corrections, run:

get_learned_preferences(min_confidence=0.3)

You'll see MCP Standards has learned the pattern automatically!

---

Optional: Add Cost Optimization (99.5% Savings)

Want to save on AI costs? Add agentic-flow to route simple operations to cheaper models:

# Get free Gemini API key: https://aistudio.google.com/app/apikey

# Add to your claude_desktop_config.json (alongside mcp-standards):
{
  "mcpServers": {
    "mcp-standards": { ... },
    "agentic-flow": {
      "command": "npx",
      "args": ["-y", "agentic-flow", "mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "DEFAULT_MODEL": "gemini-1.5-flash",
        "SHOW_MODEL_USAGE": "true",
        "SHOW_COST_SAVINGS": "true",
        "LOG_LEVEL": "info"
      }
    }
  }
}

What agentic-flow does:

• Routes simple operations (memory, search) → Gemini Flash ($0.075/1M tokens)
• Keeps complex operations (code gen) → Claude Sonnet ($15/1M tokens)
• Shows which model was used for each operation
• Displays cost savings in real-time
• Saves ~$389/month on typical usage
• 100% optional - MCP Standards works perfectly without it

📖 Quick Start Guide

MCP Standards has two complementary systems for building your AI assistant's knowledge:

System 1: Episodes (Manual Knowledge - Immediate)

Store facts, preferences, and instructions right now:

// ✅ Store a preference immediately
add_episode(
    name="Package Manager Preference",
    content="Always use uv instead of pip for Python. Example: uv pip install pytest",
    source="user"
)

// 🔍 Search your stored knowledge
search_episodes(query="package manager", limit=5)
// Returns: Your uv preference with full context

// 📋 List recent additions
list_recent(limit=10)
// Returns: Last 10 episodes you added

When to use Episodes:

• ✅ Store a preference immediately
• ✅ Document project-specific facts
• ✅ Save code examples and snippets
• ✅ Build a searchable knowledge base

System 2: Learned Preferences (Auto Pattern Detection - Over Time)

The system automatically learns from repeated corrections:

// 🤖 You DON'T call these - they happen automatically!
// Example: You correct Claude 3+ times: "Use uv instead of pip"
// → System detects pattern
// → Creates learned preference with confidence score

// 📊 Check what patterns were detected automatically
get_learned_preferences(min_confidence=0.3)
// Returns: Preferences learned from corrections with confidence scores
// Example: { preference: "use uv over pip", confidence: 0.85, occurrences: 5 }

// 💡 Get AI-suggested CLAUDE.md updates
suggest_claudemd_update(
    project_path="./my-project",
    min_confidence=0.7
)
// Returns: "Add rule: Use uv for package management (confidence: 0.85)"

// ✍️ Apply learned patterns to your CLAUDE.md
update_claudemd(
    file_path="./CLAUDE.md",
    min_confidence=0.7
)
// Automatically updates CLAUDE.md with high-confidence learned patterns

Learned preferences build automatically when:

• 🔄 You correct the same thing 3+ times
• 🔄 Patterns emerge across different projects
• 🔄 Confidence scores reach thresholds:
  • 0.3 = Emerging pattern (2-3 corrections)
  • 0.7 = Strong preference (5-7 corrections)
  • 0.9 = Very confident (10+ corrections)

🎯 Practical Example: Teaching Claude to Use uv

Scenario: You want Claude to always use uv instead of pip

Option A: Store Immediately (Recommended for new preferences)

add_episode(
    name="Python Package Manager",
    content="User prefers uv over pip. Always use: uv pip install <package>",
    source="user"
)

✅ Available immediately in search ✅ Works in current session ✅ Manual but fast

Option B: Let System Learn (Automatic over time)

1. Day 1: Correct Claude: "Use uv instead of pip" → Pattern #1 detected
2. Day 3: Correct again on different project → Pattern #2 detected
3. Day 7: Correct third time → Learned preference created (confidence: 0.3)
4. Day 14: Fourth correction → Confidence increases to 0.7
5. Run get_learned_preferences() → See the pattern
6. Run suggest_claudemd_update() → Get suggestion to add to CLAUDE.md
7. Run update_claudemd() → Automatically updates your config file

✅ Builds confidence scores ✅ Suggests CLAUDE.md updates ✅ Automatic but slower

🚀 Best Practice: Use Both!

1. Store critical preferences immediately with add_episode()
2. Let the system learn patterns over time from corrections
3. Review learned preferences monthly with get_learned_preferences()
4. Update CLAUDE.md when confidence scores are high (0.7+)

🔧 Generate Standards from Existing Project

// Auto-generate CLAUDE.md from existing config files
generate_ai_standards(project_path=".")
// Analyzes: .editorconfig, .prettierrc, eslint.config.js, pyproject.toml
// Generates: CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/

---

How It Works

Pattern Learning Pipeline

User Correction → Pattern Extraction → Frequency Tracking → Confidence Scoring → Preference Promotion → CLAUDE.md Update

Example Flow:

1. User says: "Actually, use uv not pip"
2. Pattern extractor detects: "use uv instead of pip"
3. Frequency tracker increments: occurrence #1
4. Repeat 2 more times → occurrence #3
5. Promotion engine creates preference (confidence 0.3)
6. User approves → CLAUDE.md updated
7. Future sessions → Claude sees preference in context

Database Schema

-- Pattern frequency (tracks occurrences)
CREATE TABLE pattern_frequency (
    pattern_key TEXT UNIQUE,
    occurrence_count INTEGER,
    confidence REAL,
    promoted_to_preference BOOLEAN
);

-- Tool preferences (learned rules)
CREATE TABLE tool_preferences (
    category TEXT,
    preference TEXT,
    confidence REAL,
    apply_count INTEGER,
    project_specific BOOLEAN
);

-- Audit log (security trail)
CREATE TABLE audit_log (
    action TEXT,
    target_path TEXT,
    details TEXT,
    success BOOLEAN,
    timestamp TIMESTAMP
);

---

What Makes MCP Standards Different?

Feature	MCP Standards	Tabnine	Copilot	Other MCPs
Learns from corrections	✅ Auto	❌ No	❌ No	❌ No
Updates CLAUDE.md	✅ Auto	N/A	N/A	❌ Manual
Pattern detection	✅ 5 types	❌ No	❌ No	❌ No
100% local	✅ Yes	❌ Cloud	❌ Cloud	✅ Varies
Open source	✅ MIT	❌ No	❌ No	✅ Varies
Security features	✅ 4 layers	⚠️ Basic	⚠️ Basic	⚠️ Varies

Unique Value Proposition: MCP Standards is the ONLY system that learns from your corrections and automatically updates your AI configuration.

---

Documentation

Guides

• Quick Start - 5-minute setup
• Self-Learning Guide - How pattern learning works
• Security Guide - Security features explained
• Integration Guide - Setup for all AI assistants
• Config Standards - Universal config reference

Technical

• Architecture - System design
• Self-Learning PRD - Product requirements document

---

MCP Tools

Core Memory

• add_episode(name, content) - Save knowledge
• search_episodes(query, limit) - Full-text search
• list_recent(limit) - Recent episodes

Pattern Learning

• get_learned_preferences(category, min_confidence) - View learned patterns
• suggest_claudemd_update(project_path) - Get suggestions
• update_claudemd(file_path, min_confidence) - Apply updates

Standards Generation

• generate_ai_standards(project_path, formats) - Auto-generate from config files
• export_to_markdown(export_path) - Export knowledge base

---

Requirements

• Python 3.10 or higher
• Claude Desktop or Claude Code
• MCP 1.0+

Supported Config Files

Formatting:

• .editorconfig
• .prettierrc / .prettierrc.json
• .eslintrc / .eslintrc.json

Languages:

• pyproject.toml (Python - Black, Ruff, Poetry, uv)
• package.json (JavaScript/TypeScript)
• Cargo.toml (Rust)
• go.mod (Go)

More coming: Ruby, PHP, Java, C#

---

Cost Optimization (Optional)

By default, MCP Standards uses Claude Sonnet for all operations. You can optionally configure it to use 99.5% cheaper models for simple operations:

Setup Gemini Flash (Recommended)

1. Get free API key: https://aistudio.google.com/app/apikey
2. Add to your environment:

   export GEMINI_API_KEY="your_key_here"
   # Or add to ~/.bashrc or ~/.zshrc
   

3. Automatic routing:
   • Simple operations (memory CRUD, searches) → Gemini 1.5 Flash ($0.075/1M tokens)
   • Complex operations (code generation, pattern analysis) → Claude Sonnet ($15/1M tokens)
   • 99.5% cost savings on routine operations

Powered by Agentic Flow

MCP Standards uses agentic-flow for intelligent model routing and cost optimization.

Features:

• Automatic model selection based on task complexity
• Support for 20+ AI providers (Anthropic, Google, OpenRouter, Groq, etc.)
• Fallback chains for reliability
• Token usage tracking

Learn more: agentic-flow documentation

---

Roadmap

✅ v0.1.0 (October 2025 - Current)

• Self-learning pattern detection
• CLAUDE.md auto-generation
• Config file parsing
• Security enhancements (whitelist, sanitization, rate limiting, audit logs)
• 100% local with SQLite + FTS5

🔄 v0.2.0 (Q1 2026)

• Implicit rejection detection (user edits within 2 min)
• Rule violation detection (compare vs config files)
• Workflow pattern learning (test after code changes)
• Cross-project promotion (project → global)
• MCP notifications for pattern promotions

🔮 v0.3.0 (Q2 2026)

• Team sync (share learned preferences)
• Analytics dashboard (trends, common corrections)
• Cloud backup (optional)
• Multi-project management
• Priority support

---

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• How to report bugs
• How to request features
• Development setup
• Code standards

---

License

MIT License - see LICENSE for details

---

Support

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions or share ideas
• Email: [e-mail]

---

Built With

• Python 3.10+
• SQLite with FTS5 (full-text search)
• MCP (Model Context Protocol)
• uv (fast Python package manager)

---

Acknowledgments

• Anthropic for Claude and MCP
• agentic-flow for intelligent model routing and cost optimization
• The open source community
• Everyone who tested early versions

---

Made with ❤️ by Matt Strautmann

Stop repeating yourself. Start using MCP Standards.

⭐ Star us on GitHub if this helps you!