mcp-to-cli 0.1.0__tar.gz

mcp_to_cli-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+
+# Distribution
+*.tar.gz
+*.whl
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Design Doc
+design/

mcp_to_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+## Design Document Rules
+
+1. **After modifying any sub-design MD file under `design/`, you must also update `design/0.0-design-overview.md`** to keep the overview consistent with the sub-documents. Design documents are written in Chinese.
+
+## Language Rules
+
+1. **Everything outside the `design/` folder must be written in English**, including code comments, examples, commit messages, etc.

mcp_to_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mengxiangyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_to_cli-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mcp-to-cli
+Version: 0.1.0
+Summary: Convert MCP server tools into hierarchical CLI commands and agent Skills
+Project-URL: Homepage, https://github.com/makabakaxy/mcp2skill
+Project-URL: Repository, https://github.com/makabakaxy/mcp2skill
+Project-URL: Issues, https://github.com/makabakaxy/mcp2skill/issues
+Author: oliver.mengxy@gmail.com
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai-tools,cli,llm,mcp,model-context-protocol,skill
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+<!-- Keywords: mcp2cli mcp2skill mcp-to-skill mcp-to-cli mcpcli mcp to skill mcp to cli mcp 2 cli mcp 2 skill -->
+
+# mcp2cli
+
+> Also known as: **mcp2skill** · **mcp-to-cli** · **mcp-to-skill** · **mcpcli**
+
+Convert MCP servers into CLI commands and compact AI agent skills.
+
+## Why
+
+For example, install [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) — it exposes **122 tools** across 14 categories (merge requests, issues, pipelines, wikis, etc.). Every tool schema gets injected into your AI conversation context on every request. We measured this directly against the Claude API:
+
+| Per-request input tokens | Before (raw MCP) | After (mcp2cli) |
+|---|---|---|
+| Your message | 20 | 20 |
+| Tool definitions (122 tools) | 27,969 | — |
+| Skill file (1 file) | — | ~800 |
+| **Total** | **27,989** | **~820** |
+| **Reduction** | | **~97%** |
+
+After `mcp2cli convert`, your AI agent stops seeing 122 tool definitions. Instead, it reads one small skill file, and calls CLI commands like `mcp2cli gitlab mr create --project-id 123 --title "Fix bug"` to get the job done.
+
+Beyond token savings, some projects maintain both a CLI and an MCP server in parallel (e.g. the GitLab MCP server vs. the `glab` CLI). Keeping two interfaces in sync is a maintenance burden and inevitably leads to feature drift. mcp2cli eliminates the need — one MCP server, one generated CLI, always consistent.
+
+## Quick Start
+
+```bash
+pip install mcp2skill
+```
+
+If you already have an MCP server configured in Claude, Cursor, or Codex:
+
+```bash
+mcp2cli list              # See which MCP servers are available
+mcp2cli convert gitlab-mcp
+```
+
+That's it. Your MCP server is now a CLI, and the compressed skill files are synced to your AI clients.
+
+## How It Works
+
+`mcp2cli convert gitlab-mcp` runs a 3-phase pipeline:
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│  1. Extract  │─────>│  2. Generate │─────>│   3. Sync    │
+│              │      │              │      │              │
+│  Read config │      │ AI-generate  │      │ Copy skills, │
+│  from Claude,│      │ CLI + skill  │      │ disable MCP  │
+│  Cursor,Codex│      │              │      │              │
+└──────┬───────┘      └──────┬───────┘      └──────┬───────┘
+       v                     v                     v
+ mcp_servers.json    cli.yaml + SKILL.md    ~/.claude/skills/
+```
+
+1. **Extract** — Reads your MCP server config from Claude (`~/.claude.json`) / Cursor (`~/.cursor/mcp.json`) / Codex (`~/.codex/config.toml`)
+2. **Generate** — Connects to the MCP server, discovers all tools, and uses AI to generate a CLI command tree (`cli.yaml`) and a compressed skill file (`SKILL.md`)
+3. **Sync** — Copies skill files to your AI clients and disables the raw MCP server
+
+Each skill directory contains a `users/` subdirectory where you can add your own notes and workflows. This directory is never overwritten by `mcp2cli`.
+
+At runtime, the generated CLI resolves commands to MCP tool calls through a lightweight daemon:
+
+```
+mcp2cli gitlab mr list --project-id 123
+        │
+        │  resolve via cli.yaml
+        v
+  tool: gitlab_list_merge_requests(project_id=123)
+        │
+        v
+  ┌─────────┐     MCP protocol     ┌────────────┐
+  │ mcp2cli │ ──────────────────>  │ MCP Server │
+  │ daemon  │ <──────────────────  │ (gitlab)   │
+  └─────────┘     JSON result      └────────────┘
+```
+
+The daemon starts automatically on first use and stops when idle.
+
+## Presets — Pre-built Skills, Download in Seconds
+
+Don't want to wait for AI generation (~2-3 min)? Use **presets** — pre-built CLI mappings + skill files shared by the community. Downloads in ~10 seconds.
+
+```bash
+mcp2cli preset list                       # Browse available presets
+mcp2cli preset pull mcp-atlassian         # Download + sync to AI clients
+mcp2cli preset pull mcp-atlassian@1.2.3   # Pin a specific version
+mcp2cli preset push gitlab-mcp            # Share your result with others
+```
+
+During `convert` and `install`, presets are checked automatically — if one exists, you can skip AI generation entirely:
+
+```
+mcp2cli convert/install
+        |
+   preset-check ─── found? ─── yes ──→ download preset (~10s)
+        |                                      |
+        no                                     |
+        |                                      |
+   scan → generate cli → generate skill        |
+        (~2-3 min)                             |
+        |                                      |
+        └──────────────→ skill sync ←──────────┘
+```
+
+Custom registry for private/team use:
+
+```bash
+mcp2cli preset registry set https://github.com/your-org/mcp2cli-presets
+```
+
+## Install — Add New MCP Servers
+
+`convert` works with servers already configured in your AI clients. For MCP servers you haven't set up yet, use `install` — it searches the internet for installation info, prompts for env vars, then runs the full conversion pipeline:
+
+```bash
+mcp2cli install mcp-atlassian
+```
+
+## Usage Examples
+
+```bash
+# List all configured local MCP servers
+mcp2cli list
+
+# Convert a server (auto-detects config from all clients)
+mcp2cli convert gitlab-mcp
+
+# Use the generated CLI
+mcp2cli gitlab mr list --project-id 123
+mcp2cli gitlab issue create --title "Fix login bug" --project-id 123
+
+# Update when the MCP server adds new tools
+mcp2cli update gitlab-mcp
+
+# Remove everything (CLI, skills, config)
+mcp2cli remove gitlab-mcp
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `convert <server>` | Convert an MCP server to skill-based usage |
+| `install <server>` | Install a new MCP server and generate skills |
+| `update <server>` | Update tools and regenerate CLI + skills |
+| `remove <server>` | Remove a server and all generated artifacts |
+| `list` | List all configured MCP servers |
+| `scan <server>` | Discover all tools from an MCP server |
+| `tools <server>` | List tools or show tool details |
+| `call <server> <tool>` | Call an MCP tool directly |
+| `generate cli <server>` | (Re)generate the CLI command tree |
+| `generate skill <server>` | (Re)generate skill files |
+| `skill sync <server>` | Sync skill files to AI clients |
+| `skill unsync <server>` | Remove synced skills and re-enable MCP server |
+| `preset list [server]` | Browse available presets (local + remote) |
+| `preset pull <name[@ver]>` | Download a preset, skip AI generation |
+| `preset export <server>` | Export a preset bundle to a local directory |
+| `preset push <server>` | Push local preset to community registry |
+| `validate <server>` | Validate CLI mapping and skill files |
+
+## License
+
+MIT

mcp_to_cli-0.1.0/README.md

@@ -0,0 +1,164 @@
+<!-- Keywords: mcp2cli mcp2skill mcp-to-skill mcp-to-cli mcpcli mcp to skill mcp to cli mcp 2 cli mcp 2 skill -->
+
+# mcp2cli
+
+> Also known as: **mcp2skill** · **mcp-to-cli** · **mcp-to-skill** · **mcpcli**
+
+Convert MCP servers into CLI commands and compact AI agent skills.
+
+## Why
+
+For example, install [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) — it exposes **122 tools** across 14 categories (merge requests, issues, pipelines, wikis, etc.). Every tool schema gets injected into your AI conversation context on every request. We measured this directly against the Claude API:
+
+| Per-request input tokens | Before (raw MCP) | After (mcp2cli) |
+|---|---|---|
+| Your message | 20 | 20 |
+| Tool definitions (122 tools) | 27,969 | — |
+| Skill file (1 file) | — | ~800 |
+| **Total** | **27,989** | **~820** |
+| **Reduction** | | **~97%** |
+
+After `mcp2cli convert`, your AI agent stops seeing 122 tool definitions. Instead, it reads one small skill file, and calls CLI commands like `mcp2cli gitlab mr create --project-id 123 --title "Fix bug"` to get the job done.
+
+Beyond token savings, some projects maintain both a CLI and an MCP server in parallel (e.g. the GitLab MCP server vs. the `glab` CLI). Keeping two interfaces in sync is a maintenance burden and inevitably leads to feature drift. mcp2cli eliminates the need — one MCP server, one generated CLI, always consistent.
+
+## Quick Start
+
+```bash
+pip install mcp2skill
+```
+
+If you already have an MCP server configured in Claude, Cursor, or Codex:
+
+```bash
+mcp2cli list              # See which MCP servers are available
+mcp2cli convert gitlab-mcp
+```
+
+That's it. Your MCP server is now a CLI, and the compressed skill files are synced to your AI clients.
+
+## How It Works
+
+`mcp2cli convert gitlab-mcp` runs a 3-phase pipeline:
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│  1. Extract  │─────>│  2. Generate │─────>│   3. Sync    │
+│              │      │              │      │              │
+│  Read config │      │ AI-generate  │      │ Copy skills, │
+│  from Claude,│      │ CLI + skill  │      │ disable MCP  │
+│  Cursor,Codex│      │              │      │              │
+└──────┬───────┘      └──────┬───────┘      └──────┬───────┘
+       v                     v                     v
+ mcp_servers.json    cli.yaml + SKILL.md    ~/.claude/skills/
+```
+
+1. **Extract** — Reads your MCP server config from Claude (`~/.claude.json`) / Cursor (`~/.cursor/mcp.json`) / Codex (`~/.codex/config.toml`)
+2. **Generate** — Connects to the MCP server, discovers all tools, and uses AI to generate a CLI command tree (`cli.yaml`) and a compressed skill file (`SKILL.md`)
+3. **Sync** — Copies skill files to your AI clients and disables the raw MCP server
+
+Each skill directory contains a `users/` subdirectory where you can add your own notes and workflows. This directory is never overwritten by `mcp2cli`.
+
+At runtime, the generated CLI resolves commands to MCP tool calls through a lightweight daemon:
+
+```
+mcp2cli gitlab mr list --project-id 123
+        │
+        │  resolve via cli.yaml
+        v
+  tool: gitlab_list_merge_requests(project_id=123)
+        │
+        v
+  ┌─────────┐     MCP protocol     ┌────────────┐
+  │ mcp2cli │ ──────────────────>  │ MCP Server │
+  │ daemon  │ <──────────────────  │ (gitlab)   │
+  └─────────┘     JSON result      └────────────┘
+```
+
+The daemon starts automatically on first use and stops when idle.
+
+## Presets — Pre-built Skills, Download in Seconds
+
+Don't want to wait for AI generation (~2-3 min)? Use **presets** — pre-built CLI mappings + skill files shared by the community. Downloads in ~10 seconds.
+
+```bash
+mcp2cli preset list                       # Browse available presets
+mcp2cli preset pull mcp-atlassian         # Download + sync to AI clients
+mcp2cli preset pull mcp-atlassian@1.2.3   # Pin a specific version
+mcp2cli preset push gitlab-mcp            # Share your result with others
+```
+
+During `convert` and `install`, presets are checked automatically — if one exists, you can skip AI generation entirely:
+
+```
+mcp2cli convert/install
+        |
+   preset-check ─── found? ─── yes ──→ download preset (~10s)
+        |                                      |
+        no                                     |
+        |                                      |
+   scan → generate cli → generate skill        |
+        (~2-3 min)                             |
+        |                                      |
+        └──────────────→ skill sync ←──────────┘
+```
+
+Custom registry for private/team use:
+
+```bash
+mcp2cli preset registry set https://github.com/your-org/mcp2cli-presets
+```
+
+## Install — Add New MCP Servers
+
+`convert` works with servers already configured in your AI clients. For MCP servers you haven't set up yet, use `install` — it searches the internet for installation info, prompts for env vars, then runs the full conversion pipeline:
+
+```bash
+mcp2cli install mcp-atlassian
+```
+
+## Usage Examples
+
+```bash
+# List all configured local MCP servers
+mcp2cli list
+
+# Convert a server (auto-detects config from all clients)
+mcp2cli convert gitlab-mcp
+
+# Use the generated CLI
+mcp2cli gitlab mr list --project-id 123
+mcp2cli gitlab issue create --title "Fix login bug" --project-id 123
+
+# Update when the MCP server adds new tools
+mcp2cli update gitlab-mcp
+
+# Remove everything (CLI, skills, config)
+mcp2cli remove gitlab-mcp
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `convert <server>` | Convert an MCP server to skill-based usage |
+| `install <server>` | Install a new MCP server and generate skills |
+| `update <server>` | Update tools and regenerate CLI + skills |
+| `remove <server>` | Remove a server and all generated artifacts |
+| `list` | List all configured MCP servers |
+| `scan <server>` | Discover all tools from an MCP server |
+| `tools <server>` | List tools or show tool details |
+| `call <server> <tool>` | Call an MCP tool directly |
+| `generate cli <server>` | (Re)generate the CLI command tree |
+| `generate skill <server>` | (Re)generate skill files |
+| `skill sync <server>` | Sync skill files to AI clients |
+| `skill unsync <server>` | Remove synced skills and re-enable MCP server |
+| `preset list [server]` | Browse available presets (local + remote) |
+| `preset pull <name[@ver]>` | Download a preset, skip AI generation |
+| `preset export <server>` | Export a preset bundle to a local directory |
+| `preset push <server>` | Push local preset to community registry |
+| `validate <server>` | Validate CLI mapping and skill files |
+
+## License
+
+MIT

mcp_to_cli-0.1.0/mcp2cli/__init__.py

@@ -0,0 +1,3 @@
+"""mcp2cli - Convert MCP server tools into hierarchical CLI commands and agent Skills."""
+
+__version__ = "0.1.0"

mcp_to_cli-0.1.0/mcp2cli/cli/mapping.py

@@ -0,0 +1,82 @@
+"""Read and write CLI mapping YAML files."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import yaml
+
+from mcp2cli.constants import CLI_DIR
+from mcp2cli.utils import safe_filename
+
+
+def cli_path(server_name: str) -> Path:
+    return CLI_DIR / f"{safe_filename(server_name)}.yaml"
+
+
+def load_cli_yaml(server_name: str) -> dict | None:
+    path = cli_path(server_name)
+    if not path.exists():
+        return None
+    try:
+        return yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError:
+        return None
+
+
+def save_cli_yaml(server_name: str, data: dict) -> Path:
+    CLI_DIR.mkdir(parents=True, exist_ok=True)
+    path = cli_path(server_name)
+    path.write_text(yaml.dump(data, allow_unicode=True, default_flow_style=False, sort_keys=False), encoding="utf-8")
+    return path
+
+
+def cli_yaml_hash(server_name: str) -> str | None:
+    """Compute SHA-256 first 8 hex chars of cli/<server>.yaml content."""
+    path = cli_path(server_name)
+    if not path.exists():
+        return None
+    content = path.read_bytes()
+    return hashlib.sha256(content).hexdigest()[:8]
+
+
+def extract_tools_from_yaml(data: dict) -> set[str]:
+    """Extract all _tool values from a CLI YAML dict."""
+    tools: set[str] = set()
+
+    def _walk(node: dict) -> None:
+        for key, value in node.items():
+            if key.startswith("_"):
+                if key == "_tool" and isinstance(value, str):
+                    tools.add(value)
+                continue
+            if isinstance(value, dict):
+                _walk(value)
+
+    commands = data.get("commands", {})
+    if isinstance(commands, dict):
+        _walk(commands)
+    return tools
+
+
+def print_command_tree(data: dict, server_name: str) -> None:
+    """Print a visual command tree."""
+    commands = data.get("commands", {})
+
+    def _print_node(node: dict, prefix: str = "", is_last: bool = True, parent_prefix: str = "") -> None:
+        items = [(k, v) for k, v in node.items() if not k.startswith("_") and isinstance(v, dict)]
+        for i, (key, value) in enumerate(items):
+            last = i == len(items) - 1
+            connector = "└── " if last else "├── "
+            child_prefix = parent_prefix + ("    " if last else "│   ")
+
+            tool = value.get("_tool")
+            if tool:
+                print(f"{parent_prefix}{connector}{key:<15} → {tool}")
+            else:
+                print(f"{parent_prefix}{connector}{key}")
+                _print_node(value, prefix=key, is_last=last, parent_prefix=child_prefix)
+
+    print(server_name)
+    _print_node(commands)