claude-mpm 5.6.1__py3-none-any.whl → 5.6.76__py3-none-any.whl

claude_mpm/services/mcp_service_registry.py

@@ -0,0 +1,294 @@
+"""MCP Service Registry for claude-mpm.
+
+This module provides a registry of known MCP services with their
+installation, configuration, and runtime requirements.
+
+WHY: Centralizes MCP service definitions to enable enable/disable/list
+operations with automatic configuration generation.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import ClassVar
+
+
+class InstallMethod(str, Enum):
+    """Installation method for MCP services."""
+
+    UVX = "uvx"
+    PIPX = "pipx"
+    NPX = "npx"
+    PIP = "pip"
+
+
+@dataclass(frozen=True)
+class MCPServiceDefinition:
+    """Definition of an MCP service with all configuration requirements.
+
+    Attributes:
+        name: Unique service identifier (e.g., "kuzu-memory")
+        package: PyPI/npm package name for installation
+        install_method: How to install (uvx, pipx, npx, pip)
+        command: Command to run the service
+        args: Default command arguments
+        required_env: Environment variables that must be set
+        optional_env: Environment variables that may be set
+        description: Human-readable description
+        env_defaults: Default values for optional env vars
+        enabled_by_default: Whether service is enabled by default
+    """
+
+    name: str
+    package: str
+    install_method: InstallMethod
+    command: str
+    args: list[str] = field(default_factory=list)
+    required_env: list[str] = field(default_factory=list)
+    optional_env: list[str] = field(default_factory=list)
+    description: str = ""
+    env_defaults: dict[str, str] = field(default_factory=dict)
+    enabled_by_default: bool = False
+    oauth_provider: str | None = None  # "google", "microsoft", etc.
+    oauth_scopes: list[str] = field(default_factory=list)  # OAuth scopes if applicable
+
+
+class MCPServiceRegistry:
+    """Registry of known MCP services.
+
+    Provides service lookup, configuration generation, and
+    enable/disable state management.
+    """
+
+    # Registry of all known MCP services
+    SERVICES: ClassVar[dict[str, MCPServiceDefinition]] = {}
+
+    @classmethod
+    def register(cls, service: MCPServiceDefinition) -> None:
+        """Register a service definition."""
+        cls.SERVICES[service.name] = service
+
+    @classmethod
+    def get(cls, name: str) -> MCPServiceDefinition | None:
+        """Get a service definition by name."""
+        return cls.SERVICES.get(name)
+
+    @classmethod
+    def list_all(cls) -> list[MCPServiceDefinition]:
+        """List all registered services."""
+        return list(cls.SERVICES.values())
+
+    @classmethod
+    def list_names(cls) -> list[str]:
+        """List all registered service names."""
+        return list(cls.SERVICES.keys())
+
+    @classmethod
+    def exists(cls, name: str) -> bool:
+        """Check if a service exists in the registry."""
+        return name in cls.SERVICES
+
+    @classmethod
+    def get_default_enabled(cls) -> list[MCPServiceDefinition]:
+        """Get services that are enabled by default."""
+        return [s for s in cls.SERVICES.values() if s.enabled_by_default]
+
+    @classmethod
+    def generate_config(
+        cls,
+        service: MCPServiceDefinition,
+        env_overrides: dict[str, str] | None = None,
+    ) -> dict:
+        """Generate MCP configuration for a service.
+
+        Args:
+            service: The service definition
+            env_overrides: Environment variable overrides
+
+        Returns:
+            Configuration dict suitable for .mcp.json or ~/.claude.json
+        """
+        env = {}
+
+        # Add required env vars (must be provided or have defaults)
+        for var in service.required_env:
+            if env_overrides and var in env_overrides:
+                env[var] = env_overrides[var]
+            elif var in service.env_defaults:
+                env[var] = service.env_defaults[var]
+            # If required and not provided, leave it out - caller should validate
+
+        # Add optional env vars if provided or have defaults
+        for var in service.optional_env:
+            if env_overrides and var in env_overrides:
+                env[var] = env_overrides[var]
+            elif var in service.env_defaults:
+                env[var] = service.env_defaults[var]
+
+        config: dict = {
+            "command": service.command,
+            "args": service.args.copy(),
+        }
+
+        if env:
+            config["env"] = env
+
+        return config
+
+    @classmethod
+    def validate_env(
+        cls, service: MCPServiceDefinition, env: dict[str, str]
+    ) -> tuple[bool, list[str]]:
+        """Validate that all required env vars are provided.
+
+        Args:
+            service: The service definition
+            env: Environment variables to validate
+
+        Returns:
+            Tuple of (is_valid, list of missing required vars)
+        """
+        missing = []
+        for var in service.required_env:
+            if var not in env and var not in service.env_defaults:
+                missing.append(var)
+        return len(missing) == 0, missing
+
+
+# ============================================================================
+# Service Definitions
+# ============================================================================
+
+# KuzuMemory - Project memory and context management
+KUZU_MEMORY = MCPServiceDefinition(
+    name="kuzu-memory",
+    package="kuzu-memory",
+    install_method=InstallMethod.UVX,
+    command="uvx",
+    args=["kuzu-memory"],
+    required_env=[],
+    optional_env=["KUZU_DB_PATH", "KUZU_LOG_LEVEL"],
+    description="Project memory and context management with graph database",
+    env_defaults={},
+    enabled_by_default=True,
+)
+
+# MCP Ticketer - Ticket and project management
+MCP_TICKETER = MCPServiceDefinition(
+    name="mcp-ticketer",
+    package="mcp-ticketer",
+    install_method=InstallMethod.UVX,
+    command="uvx",
+    args=["mcp-ticketer"],
+    required_env=[],
+    optional_env=["TICKETER_BACKEND", "GITHUB_TOKEN", "LINEAR_API_KEY"],
+    description="Ticket and project management integration",
+    env_defaults={},
+    enabled_by_default=True,
+)
+
+# MCP Vector Search - Code semantic search
+MCP_VECTOR_SEARCH = MCPServiceDefinition(
+    name="mcp-vector-search",
+    package="mcp-vector-search",
+    install_method=InstallMethod.UVX,
+    command="uvx",
+    args=["mcp-vector-search"],
+    required_env=[],
+    optional_env=["VECTOR_SEARCH_INDEX_PATH"],
+    description="Semantic code search with vector embeddings",
+    env_defaults={},
+    enabled_by_default=True,
+)
+
+# Google Workspace MCP - Google Drive, Docs, Sheets integration
+# Package: https://pypi.org/project/workspace-mcp/
+GOOGLE_WORKSPACE_MCP = MCPServiceDefinition(
+    name="workspace-mcp",
+    package="workspace-mcp",
+    install_method=InstallMethod.UVX,
+    command="uvx",
+    args=["workspace-mcp", "--tool-tier", "core"],
+    required_env=["GOOGLE_OAUTH_CLIENT_ID", "GOOGLE_OAUTH_CLIENT_SECRET"],
+    optional_env=[
+        "OAUTHLIB_INSECURE_TRANSPORT",
+        "USER_GOOGLE_EMAIL",
+        "GOOGLE_PSE_API_KEY",
+        "GOOGLE_PSE_ENGINE_ID",
+    ],
+    description="Google Workspace integration (Gmail, Calendar, Drive, Docs, Sheets, Slides)",
+    env_defaults={"OAUTHLIB_INSECURE_TRANSPORT": "1"},
+    enabled_by_default=False,
+    oauth_provider="google",
+    oauth_scopes=[
+        "openid",
+        "email",
+        "profile",
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://www.googleapis.com/auth/calendar",
+        "https://www.googleapis.com/auth/drive",
+        "https://www.googleapis.com/auth/documents",
+        "https://www.googleapis.com/auth/spreadsheets",
+    ],
+)
+
+# MCP GitHub - GitHub repository integration (future)
+MCP_GITHUB = MCPServiceDefinition(
+    name="mcp-github",
+    package="@modelcontextprotocol/server-github",
+    install_method=InstallMethod.NPX,
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-github"],
+    required_env=["GITHUB_PERSONAL_ACCESS_TOKEN"],
+    optional_env=[],
+    description="GitHub repository integration",
+    env_defaults={},
+    enabled_by_default=False,
+)
+
+# MCP Filesystem - Local filesystem access (future)
+MCP_FILESYSTEM = MCPServiceDefinition(
+    name="mcp-filesystem",
+    package="@modelcontextprotocol/server-filesystem",
+    install_method=InstallMethod.NPX,
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-filesystem"],
+    required_env=[],
+    optional_env=["FILESYSTEM_ROOT_PATH"],
+    description="Local filesystem access and management",
+    env_defaults={},
+    enabled_by_default=False,
+)
+
+# MCP Skillset - Skills and knowledge management
+MCP_SKILLSET = MCPServiceDefinition(
+    name="mcp-skillset",
+    package="mcp-skillset",
+    install_method=InstallMethod.UVX,
+    command="uvx",
+    args=["mcp-skillset"],
+    required_env=[],
+    optional_env=["SKILLSET_PATH", "SKILLSET_LOG_LEVEL"],
+    description="Skills and knowledge management for Claude",
+    env_defaults={},
+    enabled_by_default=True,
+)
+
+
+# Register all services
+def _register_builtin_services() -> None:
+    """Register all built-in service definitions."""
+    services = [
+        KUZU_MEMORY,
+        MCP_TICKETER,
+        MCP_VECTOR_SEARCH,
+        GOOGLE_WORKSPACE_MCP,
+        MCP_GITHUB,
+        MCP_FILESYSTEM,
+        MCP_SKILLSET,
+    ]
+    for service in services:
+        MCPServiceRegistry.register(service)
+
+
+# Auto-register on module import
+_register_builtin_services()

claude_mpm/services/monitor/server.py

@@ -576,8 +576,13 @@ class UnifiedMonitorServer:
                     event = data.get("event", "claude_event")
                     event_data = data.get("data", {})
 
+                    # Extract actual event name from subtype or type within data
+                    actual_event = (
+                        event_data.get("subtype") or event_data.get("type") or event
+                    )
+
                     # Categorize event and wrap in expected format
-                    event_type = self._categorize_event(event)
+                    event_type = self._categorize_event(actual_event)
                     wrapped_event = {
                         "type": event_type,
                         "subtype": event,

claude_mpm/services/pm_skills_deployer.py

@@ -71,6 +71,8 @@ REQUIRED_PM_SKILLS = [
     "mpm-circuit-breaker-enforcement",
     "mpm-tool-usage-guide",
     "mpm-session-management",
+    "mpm-session-pause",
+    "mpm-session-resume",
 ]
 
 # Tier 2: Recommended skills (deployed with standard install)
@@ -78,7 +80,6 @@ REQUIRED_PM_SKILLS = [
 RECOMMENDED_PM_SKILLS = [
     "mpm-config",
     "mpm-ticket-view",
-    "mpm-session-resume",
     "mpm-postmortem",
 ]
 
@@ -389,8 +390,9 @@ class PMSkillsDeployerService(LoggerMixin):
             if not skill_dir.is_dir() or skill_dir.name.startswith("."):
                 continue
 
-            # Only process mpm-* skills (framework management)
-            if not skill_dir.name.startswith("mpm-"):
+            # Only process mpm* skills (framework management)
+            # Note: Includes both 'mpm' (core skill) and 'mpm-*' (other PM skills)
+            if not skill_dir.name.startswith("mpm"):
                 self.logger.debug(f"Skipping non-mpm skill: {skill_dir.name}")
                 continue
 

claude_mpm/services/skills/git_skill_source_manager.py

@@ -16,6 +16,7 @@ Trade-offs:
 - Flexibility: Easy to extend with skills-specific features
 """
 
+import os
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timezone
 from pathlib import Path
@@ -32,6 +33,46 @@ from claude_mpm.services.skills.skill_discovery_service import SkillDiscoverySer
 logger = get_logger(__name__)
 
 
+def _get_github_token(source: Optional[SkillSource] = None) -> Optional[str]:
+    """Get GitHub token with source-specific override support.
+
+    Priority: source.token > GITHUB_TOKEN > GH_TOKEN
+
+    Args:
+        source: Optional SkillSource to check for per-source token
+
+    Returns:
+        GitHub token if found, None otherwise
+
+    Token Resolution:
+        1. If source has token starting with "$", resolve as env var
+        2. If source has direct token, use it (not recommended for security)
+        3. Fall back to GITHUB_TOKEN env var
+        4. Fall back to GH_TOKEN env var
+        5. Return None if no token found
+
+    Security Note:
+        Token is never logged or printed to avoid exposure.
+        Direct tokens in config are discouraged - use env var refs ($VAR_NAME).
+
+    Example:
+        >>> source = SkillSource(..., token="$PRIVATE_TOKEN")
+        >>> token = _get_github_token(source)  # Resolves $PRIVATE_TOKEN from env
+        >>> token = _get_github_token()  # Falls back to GITHUB_TOKEN
+    """
+    # Priority 1: Per-source token (env var reference or direct)
+    if source and source.token:
+        if source.token.startswith("$"):
+            # Env var reference: $VAR_NAME -> os.environ.get("VAR_NAME")
+            env_var_name = source.token[1:]
+            return os.environ.get(env_var_name)
+        # Direct token (not recommended but supported)
+        return source.token
+
+    # Priority 2-3: Global environment variables
+    return os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
 class GitSkillSourceManager:
     """Manages multiple Git-based skill sources with priority resolution.
 
@@ -217,9 +258,21 @@ class GitSkillSourceManager:
             )
 
             # Discover skills in cache
+            self.logger.debug(f"Scanning cache path for skills: {cache_path}")
             discovery_service = SkillDiscoveryService(cache_path)
             discovered_skills = discovery_service.discover_skills()
 
+            # Log discovery results
+            if len(discovered_skills) == 0:
+                self.logger.info(
+                    f"No SKILL.md files found in {cache_path}. "
+                    "Ensure your skill source has SKILL.md files with valid frontmatter."
+                )
+            else:
+                self.logger.debug(
+                    f"Successfully parsed {len(discovered_skills)} skills from {cache_path}"
+                )
+
             # Build result
             result = {
                 "synced": True,
@@ -469,7 +522,7 @@ class GitSkillSourceManager:
         # Step 1: Discover all files via GitHub Tree API (single request)
         # This discovers the COMPLETE repository structure (272 files for skills)
         all_files = self._discover_repository_files_via_tree_api(
-            owner_repo, source.branch
+            owner_repo, source.branch, source
         )
 
         if not all_files:
@@ -504,7 +557,7 @@ class GitSkillSourceManager:
                 raw_url = f"https://raw.githubusercontent.com/{owner_repo}/{source.branch}/{file_path}"
                 cache_file = cache_path / file_path
                 future = executor.submit(
-                    self._download_file_with_etag, raw_url, cache_file, force
+                    self._download_file_with_etag, raw_url, cache_file, force, source
                 )
                 future_to_file[future] = file_path
 
@@ -533,7 +586,7 @@ class GitSkillSourceManager:
         return files_updated, files_cached
 
     def _discover_repository_files_via_tree_api(
-        self, owner_repo: str, branch: str
+        self, owner_repo: str, branch: str, source: Optional[SkillSource] = None
     ) -> List[str]:
         """Discover all files in repository using GitHub Git Tree API.
 
@@ -596,9 +649,17 @@ class GitSkillSourceManager:
             )
             self.logger.debug(f"Fetching commit SHA from {refs_url}")
 
-            refs_response = requests.get(
-                refs_url, headers={"Accept": "application/vnd.github+json"}, timeout=30
-            )
+            # Build headers with authentication if token available
+            headers = {"Accept": "application/vnd.github+json"}
+            token = _get_github_token(source)
+            if token:
+                headers["Authorization"] = f"token {token}"
+                if source and source.token:
+                    self.logger.debug(f"Using source-specific token for {source.id}")
+                else:
+                    self.logger.debug("Using GitHub token for authentication")
+
+            refs_response = requests.get(refs_url, headers=headers, timeout=30)
 
             # Check for rate limiting
             if refs_response.status_code == 403:
@@ -621,7 +682,7 @@ class GitSkillSourceManager:
             self.logger.debug(f"Fetching recursive tree from {tree_url}")
             tree_response = requests.get(
                 tree_url,
-                headers={"Accept": "application/vnd.github+json"},
+                headers=headers,  # Reuse headers with auth from Step 1
                 params=params,
                 timeout=30,
             )
@@ -652,7 +713,11 @@ class GitSkillSourceManager:
         return all_files
 
     def _download_file_with_etag(
-        self, url: str, local_path: Path, force: bool = False
+        self,
+        url: str,
+        local_path: Path,
+        force: bool = False,
+        source: Optional[SkillSource] = None,
     ) -> bool:
         """Download file from URL with ETag caching (thread-safe).
 
@@ -660,6 +725,7 @@ class GitSkillSourceManager:
             url: Raw GitHub URL
             local_path: Local file path to save to
             force: Force download even if cached
+            source: Optional SkillSource for token resolution
 
         Returns:
             True if file was updated, False if cached
@@ -692,6 +758,11 @@ class GitSkillSourceManager:
         if cached_etag and not force:
             headers["If-None-Match"] = cached_etag
 
+        # Add GitHub authentication if token available
+        token = _get_github_token(source)
+        if token:
+            headers["Authorization"] = f"token {token}"
+
         try:
             response = requests.get(url, headers=headers, timeout=30)
 

claude_mpm/services/skills/selective_skill_deployer.py

@@ -50,6 +50,22 @@ logger = get_logger(__name__)
 # Deployment tracking index file
 DEPLOYED_INDEX_FILE = ".mpm-deployed-skills.json"
 
+# Core PM skills that should always be deployed
+# These are referenced in PM_INSTRUCTIONS.md with [SKILL: name] markers
+# Without these skills, PM only sees placeholders, not actual content
+PM_CORE_SKILLS = {
+    "mpm-delegation-patterns",
+    "mpm-verification-protocols",
+    "mpm-tool-usage-guide",
+    "mpm-git-file-tracking",
+    "mpm-pr-workflow",
+    "mpm-ticketing-integration",
+    "mpm-teaching-mode",
+    "mpm-bug-reporting",
+    "mpm-circuit-breaker-enforcement",
+    "mpm-session-management",
+}
+
 # Core skills that are universally useful across all projects
 # These are deployed when skill mapping returns too many skills (>60)
 # Target: ~25-30 core skills for balanced functionality
@@ -376,6 +392,18 @@ def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
             "(converted slashes to dashes)"
         )
 
+    # Always include PM core skills to ensure PM_INSTRUCTIONS.md markers are resolved
+    # These skills are referenced in PM_INSTRUCTIONS.md and must be deployed
+    # for PM to see actual content instead of [SKILL: name] placeholders
+    before_pm_skills = len(normalized_skills)
+    normalized_skills = normalized_skills | PM_CORE_SKILLS
+    pm_skills_added = len(normalized_skills) - before_pm_skills
+
+    if pm_skills_added > 0:
+        logger.info(
+            f"Added {pm_skills_added} PM core skills to ensure PM_INSTRUCTIONS.md markers resolve"
+        )
+
     return normalized_skills
 
 

claude_mpm/services/skills/skill_discovery_service.py

@@ -188,6 +188,15 @@ class SkillDiscoveryService:
             f"and {len(legacy_md_files)} legacy .md files in {self.skills_dir}"
         )
 
+        # Log first few file paths for debugging
+        if all_skill_files:
+            sample_files = [
+                str(f.relative_to(self.skills_dir)) for f in all_skill_files[:5]
+            ]
+            self.logger.debug(f"Sample skill files: {sample_files}")
+        else:
+            self.logger.debug(f"No SKILL.md or .md files found in {self.skills_dir}")
+
         # Track deployment names to detect collisions
         deployment_names = {}
 
@@ -226,7 +235,14 @@ class SkillDiscoveryService:
             except Exception as e:
                 self.logger.warning(f"Failed to parse skill {skill_file}: {e}")
 
-        self.logger.info(f"Discovered {len(skills)} skills from {self.skills_dir.name}")
+        # Summary logging
+        parsed_count = len(skills)
+        failed_count = len(all_skill_files) - parsed_count
+        self.logger.info(
+            f"Discovered {parsed_count} skills from {self.skills_dir.name} "
+            f"({len(all_skill_files)} files found, {failed_count} failed to parse)"
+        )
+
         return skills
 
     def _parse_skill_file(self, skill_file: Path) -> Optional[Dict[str, Any]]:

claude_mpm/services/skills_deployer.py

@@ -28,7 +28,7 @@ References:
 import json
 import platform
 import shutil
-import subprocess
+import subprocess  # nosec B404 - subprocess needed for safe git operations
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -653,7 +653,7 @@ class SkillsDeployerService(LoggerMixin):
                     f"Updating existing collection '{collection_name}' at {target_dir}"
                 )
                 try:
-                    result = subprocess.run(
+                    result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded git command
                         ["git", "pull"],
                         cwd=target_dir,
                         capture_output=True,
@@ -684,7 +684,7 @@ class SkillsDeployerService(LoggerMixin):
                 f"Installing new collection '{collection_name}' to {target_dir}"
             )
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded git command
                     ["git", "clone", repo_url, str(target_dir)],
                     capture_output=True,
                     text=True,
@@ -773,6 +773,32 @@ class SkillsDeployerService(LoggerMixin):
         if isinstance(skills_data, dict):
             flat_skills = []
 
+            # Define valid top-level categories
+            VALID_CATEGORIES = {"universal", "toolchains"}
+
+            # Check for unknown categories and warn user
+            unknown_categories = set(skills_data.keys()) - VALID_CATEGORIES
+            if unknown_categories:
+                # Count skills in unknown categories
+                skipped_count = 0
+                for cat in unknown_categories:
+                    cat_data = skills_data.get(cat, [])
+                    if isinstance(cat_data, list):
+                        skipped_count += len(cat_data)
+                    elif isinstance(cat_data, dict):
+                        # If it's a dict like toolchains, count nested skills
+                        for skills_list in cat_data.values():
+                            if isinstance(skills_list, list):
+                                skipped_count += len(skills_list)
+
+                self.logger.warning(
+                    f"Unknown categories in manifest will be skipped: "
+                    f"{', '.join(sorted(unknown_categories))} ({skipped_count} skills)"
+                )
+                self.logger.info(
+                    f"Valid top-level categories: {', '.join(sorted(VALID_CATEGORIES))}"
+                )
+
             # Add universal skills
             universal_skills = skills_data.get("universal", [])
             if isinstance(universal_skills, list):
@@ -1022,12 +1048,12 @@ class SkillsDeployerService(LoggerMixin):
         """
         try:
             if platform.system() == "Windows":
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded tasklist command
                     ["tasklist"], check=False, capture_output=True, text=True, timeout=5
                 )
                 return "claude" in result.stdout.lower()
             # macOS and Linux
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded ps command
                 ["ps", "aux"], check=False, capture_output=True, text=True, timeout=5
             )
             # Look for "Claude Code" or "claude-code" process

claude_mpm/skills/__init__.py

@@ -24,7 +24,7 @@ Legacy System (maintained for compatibility):
 from .agent_skills_injector import AgentSkillsInjector
 
 # Legacy System (maintained for compatibility)
-from .registry import Skill, SkillsRegistry, get_registry
+from .registry import Skill, SkillsRegistry, get_registry, validate_agentskills_spec
 from .skill_manager import SkillManager
 from .skills_registry import SkillsRegistry as SkillsRegistryHelper
 from .skills_service import SkillsService
@@ -39,4 +39,5 @@ __all__ = [
     # New Skills Integration System
     "SkillsService",
     "get_registry",
+    "validate_agentskills_spec",
 ]