MCP Standards

# MCP Standards - Personal Memory for Claude > **⚠️ ARCHIVED PROJECT**: This repository is archived and provided for reference only. The project was experimental and served as a proof-of-concept for automatic preference learning with AgentDB vector memory. See [ARCHIVE.md](ARCHIVE.md) for complete details. **Make Claude remember YOUR preferences automatically. Zero config, zero manual steps.** [](LICENSE) [](https://www.python.org/downloads/) [](ARCHIVE.md) --- ## 🎯 What This Does Stop repeating yourself to Claude. This MCP server learns your preferences automatically: ``` You: "Install pytest" Claude: pip install pytest You: "Actually, use uv not pip" Claude: ✓ Remembered Next session: You: "Install requests" Claude: uv pip install requests [automatic] ``` **One correction. Forever remembered.** --- ## ⚡ Quick Start (5 Minutes) ### 1. Install ```bash git clone https://github.com/airmcp-com/mcp-standards.git cd mcp-standards # Install dependencies npm install # Setup AgentDB npm run setup ``` ### 2. Configure Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "mcp-standards": { "command": "uv", "args": [ "run", "--directory", "/ABSOLUTE/PATH/TO/mcp-standards", "python", "-m", "mcp_standards.server_simple" ] } } } ``` **⚠️ Replace `/ABSOLUTE/PATH/TO/` with your actual path!** ### 3. Restart Claude Desktop Quit and relaunch Claude Desktop. ### 4. Test It! ``` You: "Remember: use uv not pip" Claude: ✓ Remembered: 'use uv not pip' (python) You: "What do you remember?" Claude: I remember you prefer: - Use uv not pip for Python projects ``` **That's it! You're done.** 🎉 --- ## 🧠 How It Works ### Automatic Learning Just correct Claude naturally - it learns automatically: ``` Session 1: You: "Use uv not pip" → Auto-detected and stored in AgentDB Session 2+: You: "Install anything" → Claude uses uv automatically ``` ### What Gets Remembered ✅ **Tool preferences**: "use uv not pip", "prefer yarn over npm" ✅ **Workflow patterns**: "run tests before commit" ✅ **Code style**: "use TypeScript for new files" ✅ **Project conventions**: "follow PEP 8" ### Categories (Auto-Detected) - `python` - Python/pip/uv preferences - `javascript` - npm/yarn/pnpm preferences - `git` - Git workflow preferences - `docker` - Docker/container preferences - `testing` - Test framework preferences - `general` - Everything else --- ## 📊 Features | Feature | Status | |---------|--------| | **Auto-detection** | ✅ Detects "use X not Y" automatically | | **Semantic search** | ✅ <1ms with AgentDB (150x faster than SQLite) | | **Cross-session** | ✅ Preferences persist forever | | **Zero config** | ✅ Works out of the box | | **100% local** | ✅ No cloud, all private | | **Simple** | ✅ 5-minute setup | --- ## 📖 Documentation - **[Quick Start Guide](docs/QUICKSTART_SIMPLE.md)** - Detailed setup instructions - **[Validation Checklist](docs/VALIDATION_CHECKLIST.md)** - Testing & troubleshooting - **[Implementation Plan](docs/SIMPLE_V2_PLAN.md)** - Technical details - **[Skills Guide](.claude/skills/remember-preferences.md)** - How to use in Claude --- ## 🛠️ MCP Tools Available ### Personal Memory (Simple Version) ```javascript // Store preference remember({ content: "use uv not pip", category: "python" }) // Search preferences recall({ query: "package manager", top_k: 5 }) // List all categories list_categories() // Get statistics memory_stats() ``` ### Config Standards (Bonus) ```javascript // Generate minimal CLAUDE.md from project config files generate_ai_standards({ project_path: ".", formats: ["claude"] }) ``` --- ## 🚀 Architecture ### Simple & Fast ``` User corrects Claude ↓ Auto-detection hook triggers ↓ Stores in AgentDB (semantic vector memory) ↓ Next session: Claude queries AgentDB automatically ↓ Uses remembered preference ``` ### Technologies - **AgentDB** - Ultra-fast vector memory (<1ms search) - **Python** - MCP server (async) - **SQLite** - Fallback storage - **MCP Protocol** - Claude Desktop integration - **100% Local** - No cloud dependencies --- ## 📁 Project Structure ``` mcp-standards/ ├── src/mcp_standards/ │ ├── agentdb_client.py # AgentDB wrapper │ ├── hooks/auto_memory.py # Auto-detection │ └── server_simple.py # Simple MCP server ├── tests/ │ └── test_simple_setup.py # Validation tests ├── docs/ │ ├── QUICKSTART_SIMPLE.md # Setup guide │ ├── VALIDATION_CHECKLIST.md # Testing guide │ └── SIMPLE_V2_PLAN.md # Technical details ├── scripts/ │ └── setup-agentdb.js # Setup script ├── .claude/skills/ │ └── remember-preferences.md # Claude skill └── README.md # This file ``` **Clean. Simple. Works.** --- ## 🧪 Testing Run automated validation: ```bash python3 tests/test_simple_setup.py ``` **Expected output**: ``` ✓ PASS: Directory Structure ✓ PASS: Required Files ✓ PASS: Module Imports ✓ PASS: AgentDB Client Init ✓ PASS: Auto Memory Patterns Results: 5/5 tests passed Status: Ready for dev testing 🚀 ``` --- ## 🐛 Troubleshooting ### Setup fails ```bash # Check Node.js version node --version # Need v18+ # Install AgentDB manually npm install -g agentdb npx agentdb --version ``` ### Claude Desktop doesn't connect ```bash # Check logs tail -f ~/Library/Logs/Claude/mcp*.log # Look for initialization messages # Should see: "MCP Standards (Simple) initialized" ``` ### Preferences not remembered Check that: 1. Server is running (check Claude Desktop MCP status) 2. Corrections use clear phrases ("use X not Y") 3. AgentDB path exists: `~/.mcp-standards/agentdb` **More help**: See [Validation Checklist](docs/VALIDATION_CHECKLIST.md) --- ## 🎯 Performance | Metric | Value | |--------|-------| | **Setup time** | <5 minutes | | **Server startup** | <2 seconds | | **Search speed** | <1ms (AgentDB HNSW) | | **Detection** | Real-time (async) | | **Storage** | <10ms | | **Memory usage** | ~50MB (embedding model) | **150x faster than SQLite. Zero lag.** --- ## 🔒 Privacy - ✅ **100% local** - Everything stored in `~/.mcp-standards/` - ✅ **No cloud** - No external API calls - ✅ **No telemetry** - No data collection - ✅ **Your data** - You control everything --- ## 📝 What Changed (v2 Simple) We removed all the complexity: | v1 (Old) | v2 Simple (New) | |----------|-----------------| | Manual MCP calls (4-5 steps) | ✅ Automatic (zero steps) | | SQLite keyword search (50ms+) | ✅ AgentDB vector search (<1ms) | | No semantic matching | ✅ Semantic understanding | | Complex setup | ✅ 5-minute setup | | 6,000+ LOC | ✅ ~950 LOC | **Result**: 80% less code, 100x better UX --- ## 🤝 Contributing This is a personal side project. If you want to contribute: 1. Try it yourself first 2. Open an issue describing what you want to add 3. Wait for feedback before writing code **Please don't**: Submit large PRs without discussion first. --- ## 📜 License MIT License - See [LICENSE](LICENSE) file --- ## 🙏 Credits Built with inspiration from: - **[AgentDB](https://agentdb.ruv.io)** - Ultra-fast vector memory - **[Context Engineering Guide](https://github.com/coleam00/context-engineering-intro)** - Minimal CLAUDE.md principles - **Gunnar's approach** - Simple side projects that solve personal problems --- ## 💬 Questions? **Q: Why not just use v1?** A: v1 requires 4-5 manual MCP calls per correction. v2 is zero-touch. **Q: Do I need AgentDB?** A: Yes, but it's installed automatically via `npm run setup`. **Q: Is my data private?** A: 100% local. Everything stored in `~/.mcp-standards/`. No cloud. **Q: What if I want the old version?** A: Use `src/mcp_standards/server.py` instead of `server_simple.py`. --- ## 🚀 Next Steps ```bash # Try it now git clone https://github.com/airmcp-com/mcp-standards.git cd mcp-standards npm run setup # See: docs/QUICKSTART_SIMPLE.md ``` **Stop repeating yourself. Start remembering automatically.** 🎯 --- ## 📦 Archive Status **This project is archived.** See [ARCHIVE.md](docs/ARCHIVE.md) for: - Complete project status and achievements - Security audit results - Full documentation index - Lessons learned and technical insights - How to use this repository as reference --- **Made with ❤️ by keeping it simple**