mcp-skills

# MCP-Skills Project Summary **Project**: mcp-skills - Dynamic RAG-powered skills for code assistants via MCP **Created**: 2025-01-21 **Status**: ✅ Initialized - Ready for implementation **Version**: 0.1.0 ## Overview mcp-skills is a standalone Python PyPI package that provides intelligent, context-aware skills to code assistants via the Model Context Protocol (MCP). Unlike static skills loaded at startup, mcp-skills uses hybrid RAG (vector + knowledge graph) for runtime skill discovery, automatic recommendations, and dynamic loading. ## Project Statistics - **Total Python Files**: 29 - **Lines of Code**: ~1,785 (including tests and scripts) - **Test Files**: 4 - **Documentation Files**: 4 (README, CONTRIBUTING, architecture, resources) - **Git Commits**: 1 (initial structure) ## Complete Project Structure ``` /Users/masa/Projects/mcp-skills/ ├── README.md # Comprehensive project documentation ├── CONTRIBUTING.md # Development guidelines ├── LICENSE # MIT License ├── VERSION # 0.1.0 ├── pyproject.toml # Modern Python packaging config ├── setup.py # Backward compatibility ├── Makefile # Development commands ├── pytest.ini # Test configuration ├── mypy.ini # Type checking configuration ├── .gitignore # Git ignore patterns ├── .secrets.baseline # Secret detection baseline │ ├── src/mcp_skills/ │ ├── __init__.py # Package metadata │ ├── VERSION # Package version file │ ├── py.typed # PEP 561 type marker │ │ │ ├── cli/ │ │ ├── __init__.py │ │ └── main.py # Click CLI with all commands │ │ │ ├── services/ │ │ ├── __init__.py │ │ ├── toolchain_detector.py # Auto-detect project tech stack │ │ ├── repository_manager.py # Git operations for skill repos │ │ ├── skill_manager.py # Skill lifecycle management │ │ ├── indexing_engine.py # Hybrid RAG (vector + KG) │ │ └── mcp_server.py # MCP protocol server │ │ │ ├── models/ │ │ ├── __init__.py │ │ ├── skill.py # Pydantic skill models │ │ └── config.py # Configuration models │ │ │ └── utils/ │ ├── __init__.py │ └── logger.py # Logging setup │ ├── tests/ │ ├── __init__.py │ ├── conftest.py # Pytest fixtures │ ├── test_toolchain_detector.py # Toolchain tests │ ├── test_repository_manager.py # Repository tests │ └── test_cli.py # CLI tests │ ├── docs/ │ ├── architecture/ │ │ └── README.md # Architecture design document │ ├── research/ │ │ └── skills-research.md # Skills ecosystem research │ └── skills/ │ └── RESOURCES.md # Skill repository index │ └── scripts/ └── manage_version.py # Version management utility ``` ## Key Features Implemented ### 1. Python Package Setup ✅ - **Modern packaging**: pyproject.toml with setuptools backend - **Entry point**: `mcp-skills` CLI command - **Version management**: Dynamic version from VERSION file - **Type hints**: Full type coverage with mypy strict mode - **PEP 561 compliance**: py.typed marker for type distribution ### 2. CLI Framework ✅ - **Click-based CLI** with comprehensive commands: - `setup`: Interactive project configuration - `serve`: MCP server startup (stdio/http) - `search`: Natural language skill search - `list`, `info`: Skill browsing - `recommend`: Context-aware recommendations - `repo`: Repository management (add, list, update) - `index`: Index rebuilding - `health`, `stats`, `config`: Utilities ### 3. Service Layer (Stub Implementations) ✅ **ToolchainDetector**: - Pattern-based detection for Python, TypeScript, Rust, Go - Framework and build tool identification - Confidence scoring - Skill recommendations based on toolchain **RepositoryManager**: - Git repository cloning and updates - Multi-source repository support - Priority-based conflict resolution - Default repositories configured **SkillManager**: - Skill discovery from SKILL.md files - Metadata parsing (YAML frontmatter) - In-memory caching - Skill validation **IndexingEngine**: - Vector store using ChromaDB - Knowledge graph (NetworkX) - Hybrid RAG search combining vector + KG - Embedding generation with sentence-transformers **MCPServer**: - MCP protocol implementation stub - Tool and resource registration - stdio/HTTP transport support ### 4. Data Models ✅ - **Pydantic validation** for all data structures - **SkillModel**: Complete skill with validation - **SkillMetadataModel**: Lightweight metadata - **MCPSkillsConfig**: Configuration management with BaseSettings - **Component configs**: VectorStore, KnowledgeGraph, Server ### 5. Development Tooling ✅ **Makefile targets**: - `make install`: Development installation - `make lint-fix`: Auto-fix linting (ruff + black) - `make test`: Run tests with coverage - `make quality`: Comprehensive quality checks - `make pre-publish`: Quality + secret detection - `make safe-release-build`: Full release pipeline - `make clean`: Remove build artifacts **Quality gates**: - Ruff linting with auto-fix - Black code formatting - mypy type checking (strict mode) - pytest with 85% coverage requirement - detect-secrets scanning ### 6. Testing Infrastructure ✅ - **pytest configuration**: Markers, coverage, strict mode - **Fixtures**: Temporary projects, sample data - **Test suites**: CLI, toolchain detector, repository manager - **Coverage reporting**: HTML + terminal output ### 7. Documentation ✅ - **README.md**: Comprehensive installation and usage guide - **CONTRIBUTING.md**: Development workflow and guidelines - **Architecture design**: Complete system architecture - **Skills research**: Ecosystem analysis - **RESOURCES.md**: Skill repository index ## Installation and Usage ### Install Package ```bash cd /Users/masa/Projects/mcp-skills pip install -e ".[dev]" ``` ### Run CLI ```bash # Via Python module python -m mcp_skills.cli.main --help python -m mcp_skills.cli.main setup --auto # Once installed in PATH mcp-skills --version mcp-skills setup ``` ### Development Commands ```bash # Auto-fix linting make lint-fix # Run quality checks make quality # Run tests make test # Build distribution make safe-release-build ``` ### Version Management ```bash # Show current version python scripts/manage_version.py show # Bump version python scripts/manage_version.py bump patch # 0.1.0 -> 0.1.1 python scripts/manage_version.py bump minor # 0.1.0 -> 0.2.0 python scripts/manage_version.py bump major # 0.1.0 -> 1.0.0 # Set specific version python scripts/manage_version.py set 0.2.0 ``` ## Technology Stack ### Core Dependencies - **click**: CLI framework - **pydantic**: Data validation and settings - **rich**: Terminal formatting - **mcp**: Model Context Protocol SDK ### RAG Components - **chromadb**: Vector store for embeddings - **sentence-transformers**: Embedding generation - **networkx**: Knowledge graph ### Git and Storage - **gitpython**: Repository operations - **sqlalchemy**: Metadata storage - **python-frontmatter**: YAML frontmatter parsing ### Development - **pytest**: Testing framework - **pytest-cov**: Coverage reporting - **ruff**: Fast Python linter - **black**: Code formatter - **mypy**: Type checking - **detect-secrets**: Secret scanning ## Next Steps (Implementation Phases) ### Phase 1: MVP (Weeks 1-2) - [ ] Implement ToolchainDetector with pattern matching - [ ] Basic RepositoryManager with git clone/pull - [ ] SkillManager with SKILL.md parsing - [ ] Simple ChromaDB vector search - [ ] Basic MCP server (stdio transport) - [ ] SQLite metadata storage ### Phase 2: Core Features (Weeks 3-4) - [ ] Knowledge graph with NetworkX - [ ] Hybrid RAG search (vector + KG) - [ ] Repository priority system - [ ] Dynamic skill loading - [ ] MCP auto-configuration - [ ] Skill recommendations ### Phase 3: Polish (Weeks 5-6) - [ ] Usage analytics - [ ] Skill validation framework - [ ] Performance optimization - [ ] Comprehensive documentation - [ ] Integration tests - [ ] PyPI packaging and release ## Architecture Highlights **Hybrid RAG**: - Vector store for semantic similarity (ChromaDB) - Knowledge graph for relationships (NetworkX) - Combined scoring: 70% vector + 30% graph **Toolchain Detection**: - Pattern matching on marker files (pyproject.toml, package.json, etc.) - Confidence scoring based on file presence - Framework detection from dependency files **Dynamic Loading**: - On-demand skill loading (lazy evaluation) - LRU cache for frequently used skills - Unload unused skills after threshold **MCP Integration**: - stdio transport for Claude Code - HTTP transport for web clients - Tool exposure: search, get, recommend, list, update ## Git Repository ```bash git remote add origin <your-repository-url> git push -u origin main ``` ## License MIT License - See LICENSE file ## Acknowledgments - Architecture design based on [mcp-skills-architecture.md](/Users/masa/Projects/claude-mpm/docs/research/mcp-skills-architecture.md) - Skills research from [skills-research.md](/Users/masa/Projects/claude-mpm/docs/research/skills-research.md) - Inspired by [Claude Skills](https://github.com/anthropics/skills) - Built on [Model Context Protocol](https://modelcontextprotocol.io) --- **Status**: ✅ Project initialized and ready for implementation **Next**: Begin Phase 1 MVP implementation **Contact**: See CONTRIBUTING.md for contribution guidelines