refactor!: split CLI and MCP server into separate distributions (#56)

* refactor!: split CLI and MCP server into separate distributions

BREAKING CHANGE: CLI and MCP server are now separate packages.

This implements TASK-001 to separate concerns:
- `skillport` (CLI-only): SkillOps commands using filesystem as SSOT
- `skillport-mcp` (server-only): MCP server with indexed search
- `skillport-core` (library): shared logic, no console scripts

Key changes:
- CLI commands no longer depend on LanceDB indexes
- New filesystem-based catalog for CLI (list, show, doc, validate)
- Removed `search` and `serve` commands from CLI
- Added lazy imports to avoid loading indexing deps in CLI
- MCP server remains the sole index builder
- Dependency boundary tests to prevent regressions

Install separately:
- `pip install skillport` for CLI only
- `pip install skillport-mcp` for MCP server


* fix: resolve hatchling build issues for subpackages

- Remove relative readme paths that don't work with hatchling
- Add empty skillport_mcp package for wheel build requirement
- Update sdist include paths

* ci: update release workflow for 3-package publish

Build and publish all distributions in order:
1. skillport-core (dependency for others)
2. skillport (CLI)
3. skillport-mcp (MCP server)

Author: gotalab

.github/workflows/release.yml

@@ -42,13 +42,18 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
 
-      - name: Build distributions (sdist/wheel)
-        run: uv build
+      - name: Build all distributions (3 packages)
+        run: |
+          # Build order matters: skillport-core first (others depend on it)
+          uv build --package skillport-core --out-dir dist/
+          uv build --package skillport --out-dir dist/
+          uv build --package skillport-mcp --out-dir dist/
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           print-hash: true
+          # Publishes all packages in dist/
 
   # snapshot-docs:
   #   needs: release-please

AGENTS.md

@@ -14,8 +14,8 @@
 ## 2. Project Context
 ### Architecture
 *   **Brand**: SkillPort
-*   **Package & CLI**: `skillport` (legacy alias: `skillport-mcp`)
-*   **Type**: MCP Server (Model Context Protocol)
+*   **Packages**: `skillport` (CLI), `skillport-mcp` (MCP server), `skillport-core` (shared lib)
+*   **Type**: CLI + MCP Server (Model Context Protocol)
 *   **Stack**:
     *   **Runtime**: Python 3.10+
     *   **Package Manager**: `uv`
@@ -24,7 +24,7 @@
     *   **Config**: `pydantic-settings`
 
 ### Directory Structure
-*   `src/skillport/`: Source code (modular monolith)
+*   `packages/skillport-core/src/skillport/`: Source code (modular monolith)
     *   `interfaces/cli/`: Typer CLI adapter
     *   `interfaces/mcp/`: FastMCP server adapter
     *   `modules/skills/`: Skill management public/internal APIs
@@ -42,7 +42,7 @@ To act autonomously, always verify changes using these commands:
 *   **Install/Sync**: `uv sync`
 *   **Run Server (Manual)**:
     ```bash
-    SKILLPORT_SKILLS_DIR=.agent/skills SKILLPORT_EMBEDDING_PROVIDER=none uv run skillport
+    SKILLPORT_SKILLS_DIR=.agent/skills SKILLPORT_EMBEDDING_PROVIDER=none uv run python -m skillport.interfaces.mcp.cli
     ```
 *   **Verify Functionality (Critical)**:
     ```bash

README.md

@@ -68,9 +68,9 @@ Choose your setup:
 
 ### 1. Install
 
-> **Skip this step** if you only want to serve an existing skills directory via MCP.
+> **Note (CLI/MCP split):** The CLI (`skillport`) and MCP server (`skillport-mcp`) are separate install paths.
 
-Install to manage skills and use them without MCP:
+Install the lightweight CLI (SkillOps):
 
 ```bash
 uv tool install skillport
@@ -80,7 +80,16 @@ uv tool install skillport
 uv tool upgrade skillport
 ```
 
-Enables `add`, `update`, `remove`, `validate`, `search`, `show`, and `doc` (generate AGENTS.md for non-MCP agents).
+Enables `add`, `update`, `remove`, `validate`, `list`, `show`, and `doc` (generate AGENTS.md for non-MCP agents).
+
+Install the MCP server (indexing + search):
+
+```bash
+uv tool install skillport-mcp
+# or: pip install skillport-mcp
+
+uv tool upgrade skillport-mcp
+```
 
 ### 2. Add Skills
 
@@ -108,30 +117,30 @@ skillport --skills-dir ~/.codex/skills add anthropics/skills skills/frontend-des
 
 **Cursor** (one-click)
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=skillport&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJza2lsbHBvcnQiXSwiZW52Ijp7IlNLSUxMUE9SVF9TS0lMTFNfRElSIjoifi8uc2tpbGxwb3J0L3NraWxscyJ9fQ==)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=skillport&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJza2lsbHBvcnQtbWNwIl0sImVudiI6eyJTS0lMTFBPUlRfU0tJTExTX0RJUiI6In4vLnNraWxscG9ydC9za2lsbHMifX0=)
 
 **VS Code / GitHub Copilot** (one-click)
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-007ACC?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=skillport&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22skillport%22%5D%2C%22env%22%3A%7B%22SKILLPORT_SKILLS_DIR%22%3A%22~/.skillport/skills%22%7D%7D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-007ACC?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=skillport&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22skillport-mcp%22%5D%2C%22env%22%3A%7B%22SKILLPORT_SKILLS_DIR%22%3A%22~/.skillport/skills%22%7D%7D)
 
 **Kiro** (one-click)
 
-[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=skillport&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22skillport%22%5D%2C%22env%22%3A%7B%22SKILLPORT_SKILLS_DIR%22%3A%22~/.skillport/skills%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
+[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=skillport&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22skillport-mcp%22%5D%2C%22env%22%3A%7B%22SKILLPORT_SKILLS_DIR%22%3A%22~/.skillport/skills%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
 
 **CLI Agents**
 
 ```bash
 # Codex
-codex mcp add skillport -- uvx skillport
+codex mcp add skillport -- uvx skillport-mcp
 
 # With custom skills in the project directory
-codex mcp add skillport --env SKILLPORT_SKILLS_DIR=./.agent/skills -- uvx skillport
+codex mcp add skillport --env SKILLPORT_SKILLS_DIR=./.agent/skills -- uvx skillport-mcp
 
 # Claude Code
-claude mcp add skillport -- uvx skillport
+claude mcp add skillport -- uvx skillport-mcp
 
 # With custom skills directory
-claude mcp add skillport --env SKILLPORT_SKILLS_DIR=~/.claude/skills -- uvx skillport
+claude mcp add skillport --env SKILLPORT_SKILLS_DIR=~/.claude/skills -- uvx skillport-mcp
 ```
 
 **Other MCP Clients** (Windsurf, Cline, Roo Code, Antigravity, etc.)
@@ -143,7 +152,7 @@ Add to your client's MCP config file:
   "mcpServers": {
     "skillport": {
       "command": "uvx",
-      "args": ["skillport"],
+      "args": ["skillport-mcp"],
       "env": { "SKILLPORT_SKILLS_DIR": "~/.skillport/skills" }
     }
   }
@@ -166,7 +175,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
   "mcpServers": {
     "skillport": {
       "command": "uvx",
-      "args": ["skillport"],
+      "args": ["skillport-mcp"],
       "env": { "SKILLPORT_SKILLS_DIR": "~/.skillport/skills" }
     }
   }
@@ -256,9 +265,9 @@ skillport --skills-dir ./skills add hello-world
 **Search & Load:**
 
 ```bash
-skillport search <query>    # Find skills by description
 skillport show <id>         # View skill details and instructions
 ```
+For discovery/search, use MCP tools (`search_skills`, `load_skill`) via the MCP server.
 
 **Install from GitHub:**
 
@@ -318,7 +327,7 @@ Expose different skills to different AI agents:
   "mcpServers": {
     "skillport-development": {
       "command": "uvx",
-      "args": ["skillport"],
+      "args": ["skillport-mcp"],
       "env": { "SKILLPORT_ENABLED_CATEGORIES": "development,testing" }
     }
   }
@@ -331,7 +340,7 @@ Expose different skills to different AI agents:
   "mcpServers": {
     "writing-skills": {
       "command": "uvx",
-      "args": ["skillport"],
+      "args": ["skillport-mcp"],
       "env": { "SKILLPORT_ENABLED_CATEGORIES": "writing,research" }
     }
   }
@@ -446,7 +455,7 @@ Instructions for the AI agent.
 git clone https://github.com/gotalab/skillport.git
 cd skillport
 uv sync
-SKILLPORT_SKILLS_DIR=.agent/skills uv run skillport serve
+SKILLPORT_SKILLS_DIR=.agent/skills uv run skillport-mcp
 ```
 
 ## License

guide/cli.md

@@ -1,6 +1,8 @@
 # CLI Reference
 
-SkillPort provides a command-line interface for managing [Agent Skills](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview) and running the MCP server.
+SkillPort provides a command-line interface for managing [Agent Skills](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview).
+
+The MCP server (indexed search) is provided as a separate command/package: `skillport-mcp`.
 
 ## Table of Contents
 
@@ -10,12 +12,12 @@ SkillPort provides a command-line interface for managing [Agent Skills](https://
   - [add](#skillport-add) - Add skills
   - [update](#skillport-update) - Update skills
   - [list](#skillport-list) - List installed skills
-  - [search](#skillport-search) - Search skills
   - [show](#skillport-show) - Show skill details
   - [remove](#skillport-remove) - Remove skills
   - [validate](#skillport-validate) - Validate skills
-  - [serve](#skillport-serve) - Start MCP server
   - [doc](#skillport-doc) - Generate AGENTS.md
+- [MCP Server](#mcp-server)
+  - [skillport-mcp](#skillport-mcp) - Start MCP server
 - [Exit Codes](#exit-codes)
 - [Configuration](#configuration)
 
@@ -25,21 +27,20 @@ SkillPort provides a command-line interface for managing [Agent Skills](https://
 skillport <command> [options]
 
 # Global overrides (CLI > env > default)
-skillport --skills-dir ./skills --db-path ./index.lancedb add hello-world
+skillport --skills-dir ./skills add hello-world
 # Place global flags before the subcommand (e.g., skillport --skills-dir ... add ...)
 ```
 
-> **Note**: `skillport-mcp` is a legacy alias for `skillport`. Both work identically.
+> **Note:** `skillport` is CLI-only. Use `skillport-mcp` to run the MCP server.
 
 ### Global options (all commands)
 
 | Option | Description | Notes |
 |--------|-------------|-------|
 | `--skills-dir` | Override skills directory path | Applies to all commands in the invocation |
-| `--db-path` | Override LanceDB path | Use together with `--skills-dir` to keep index in sync |
-| `--auto-reindex/--no-auto-reindex` | Control automatic index rebuilding | Default: enabled; respects `SKILLPORT_AUTO_REINDEX` env var |
+| (none) | Index settings | Index settings are MCP-server-only (`skillport-mcp`) |
 
-Precedence: CLI flag > environment variable (`SKILLPORT_SKILLS_DIR` / `SKILLPORT_DB_PATH`) > default (`~/.skillport/skills`, `~/.skillport/indexes/default/skills.lancedb`).
+Precedence: CLI flag > environment variable (`SKILLPORT_SKILLS_DIR`) > default (`~/.skillport/skills`).
 
 ## Commands
 
@@ -55,8 +56,7 @@ skillport init [options]
 
 1. Creates `.skillportrc` configuration file
 2. Creates skills directory if it doesn't exist
-3. Builds the skill index
-4. Updates instruction files (AGENTS.md, etc.) with skills table
+3. Updates instruction files (AGENTS.md, etc.) with skills table
 
 #### Options
 
@@ -501,33 +501,15 @@ skillport list --json
 
 ---
 
-### skillport search
+### Search (MCP only)
 
-Search for skills.
+`skillport search` is not provided in the CLI.
 
-```bash
-skillport search <query> [options]
-```
+For discovery, run the MCP server (`skillport-mcp`) and use MCP tools:
+- `search_skills(query)`
+- `load_skill(skill_id)`
 
-#### Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--limit`, `-n` | Maximum results | `10` |
-| `--json` | Output as JSON | `false` |
-
-#### Examples
-
-```bash
-# Search by description
-skillport search "PDF text extraction"
-
-# Limit results
-skillport search "code review" --limit 5
-
-# JSON output
-skillport search "testing" --json
-```
+For local browsing without MCP, use `skillport list` + `skillport show <id>`.
 
 ---
 
@@ -604,8 +586,8 @@ skillport validate [target] [options]
 
 | Type | Example | Description |
 |------|---------|-------------|
-| (none) | `skillport validate` | Validate all skills in index |
-| Skill ID | `skillport validate hello-world` | Validate specific skill from index |
+| (none) | `skillport validate` | Validate all skills in skills directory |
+| Skill ID | `skillport validate hello-world` | Validate specific skill by ID |
 | Path (skill) | `skillport validate ./my-skill/` | Validate single skill directory |
 | Path (dir) | `skillport validate ./skills/` | Validate all skills in directory |
 
@@ -698,12 +680,14 @@ skillport validate
 
 ---
 
-### skillport serve
+## MCP Server
+
+### skillport-mcp
 
-Start the MCP server.
+Start the MCP server (indexed search).
 
 ```bash
-skillport serve [options]
+skillport-mcp [options]
 ```
 
 #### Options
@@ -720,40 +704,25 @@ skillport serve [options]
 
 | Mode | Command | Tools |
 |------|---------|-------|
-| **Local** (stdio) | `skillport serve` | `search_skills`, `load_skill` |
-| **Remote** (HTTP) | `skillport serve --http` | + `read_skill_file` |
+| **Local** (stdio) | `skillport-mcp` | `search_skills`, `load_skill` |
+| **Remote** (HTTP) | `skillport-mcp --http` | + `read_skill_file` |
 
 #### Examples
 
 ```bash
 # Local mode (stdio) - for Claude Code, Cursor
-skillport serve
+skillport-mcp
 
 # Remote mode (HTTP) - for network access
-skillport serve --http
+skillport-mcp --http
 
 # Remote mode with custom host/port
-skillport serve --http --host 0.0.0.0 --port 8000
+skillport-mcp --http --host 0.0.0.0 --port 8000
 
 # Start with forced reindex
-skillport serve --reindex
-```
-
-#### Local vs Remote Mode
-
-- **Local Mode (stdio)**: Agent has direct file access. `read_skill_file` is not needed.
-- **Remote Mode (HTTP)**: Agent accesses remotely. Use `read_skill_file` to fetch files.
-
-#### Legacy Mode
-
-```bash
-# The following are equivalent (backward compatible)
-skillport
-skillport serve
+skillport-mcp --reindex
 ```
 
-> **Note**: `skillport --reindex` is **not supported**. Always use `skillport serve --reindex`.
-
 ---
 
 ### skillport doc
@@ -906,10 +875,10 @@ For full configuration options, see [Configuration Guide](configuration.md).
 
 ### Quick Reference
 
-CLI commands resolve `skills_dir` / `db_path` in this order:
+CLI commands resolve `skills_dir` in this order:
 
-1. **CLI flags** — `--skills-dir`, `--db-path`
-2. **Environment variables** — `SKILLPORT_SKILLS_DIR`, `SKILLPORT_DB_PATH`
+1. **CLI flags** — `--skills-dir`
+2. **Environment variables** — `SKILLPORT_SKILLS_DIR`
 3. **Project config** — `.skillportrc` or `pyproject.toml [tool.skillport]`
 4. **Default** — `~/.skillport/skills`
 
@@ -918,7 +887,7 @@ CLI commands resolve `skills_dir` / `db_path` in this order:
 | Variable | Description |
 |----------|-------------|
 | `SKILLPORT_SKILLS_DIR` | Skills directory |
-| `SKILLPORT_AUTO_REINDEX` | Enable/disable automatic reindexing |
+| (MCP server) `SKILLPORT_DB_PATH` | Index location (used by `skillport-mcp`) |
 
 ### GitHub Authentication