mcp_mother_skills: Instructions file for Codex

Mother MCP Skills - AI Coding Instructions

Startup

Only at the very start of a NEW conversation (when no context exists yet), call setup (for first-time use) or sync_skills (for ongoing updates) to ensure project-relevant skills are loaded. Do NOT call these repeatedly during the same conversation unless explicitly requested by the user.

Project Overview

This is an MCP (Model Context Protocol) server that dynamically provisions AI agent skills based on project tech stack detection. It supports both Claude and GitHub Copilot agents.

Core Architecture

index.ts               → MCP server entry, tool definitions, request routing
├── agent-detector.ts       → Detects Claude vs Copilot (env vars, client info, project structure)
├── project-detector.ts     → Scans files to detect tech stack (packages, configs, README)
├── enhanced-detector.ts    → Tiered detection: GitHub SBOM → Specfy → Local fallback
├── github-sbom-client.ts   → GitHub SBOM API client with PURL parsing
├── registry-client.ts      → Fetches skills from GitHub registries with caching
├── skill-installer.ts      → Downloads/installs skills to agent-specific paths
├── config-manager.ts       → YAML config handling (.mcp/mother/)
├── agent-profiles.ts       → Agent path configurations (claude → .claude/, copilot → .github/)
└── types.ts                → All shared TypeScript interfaces

Data Flow

1. sync_skills tool called → EnhancedProjectDetector uses 3-tier detection (GitHub SBOM → Specfy → Local) → matches against RegistryClient skills → SkillInstaller downloads to .github/skills or .claude/skills

Development Commands

npm run build      # TypeScript compilation to dist/
npm run dev        # Run with tsx (no compile step)
npm test           # Vitest test suite
npm run test:watch # Watch mode for TDD

Key Patterns

Module System

• ESM-only ("type": "module" in package.json)
• All imports must use .js extension: import { X } from './types.js'
• Target: ES2022 with NodeNext module resolution