mcp-skill 0.2.0__tar.gz

mcp_skill-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+# .github/workflows/release.yml
+#
+# Release workflow: automated changelog + PyPI publishing
+#
+# How it works:
+#   1. On every push to main, release-please checks for conventional commits
+#      and maintains a "Release PR" with updated CHANGELOG.md and version bump.
+#   2. When the Release PR is merged, release-please creates a GitHub release.
+#   3. The publish job then builds and publishes to PyPI using trusted publishing.
+#
+# Setup required (one-time, manual):
+#   - On PyPI: Settings → Publishing → Add trusted publisher
+#     Publisher: GitHub Actions
+#     Repository: manojbajaj95/mcp-skill
+#     Workflow: release.yml
+#     Environment: pypi
+#   - On GitHub: Settings → Environments → Create "pypi" environment
+#
+# Conventional commits required for release-please:
+#   feat:     → minor version bump (0.1.0 → 0.2.0)
+#   fix:      → patch version bump (0.1.0 → 0.1.1)
+#   feat!:    → major version bump (0.1.0 → 1.0.0)
+
+name: release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mcp-skill/
+    permissions:
+      id-token: write  # Required for PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

mcp_skill-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

mcp_skill-0.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [0.2.0](https://github.com/manojbajaj95/mcp-skill/compare/v0.1.0...v0.2.0) (2026-03-11)
+
+
+### Features
+
+* Add generated skills ([c9c81b9](https://github.com/manojbajaj95/mcp-skill/commit/c9c81b93344c1e45ce152e8a58ef264835f89f8d))
+* add persistent disk-backed token storage for all auth types ([531e402](https://github.com/manojbajaj95/mcp-skill/commit/531e40278268fb2997be012ef39e4b3ee0774078))
+* **auth:** add ClientCredentialsAuth stub (NotImplementedError placeholder) ([133ebcc](https://github.com/manojbajaj95/mcp-skill/commit/133ebcc50aad4b04d3c60ff5dfe064daca4abc87))
+* **auth:** extract auth classes into importable mcp_skill.auth module ([e0d0873](https://github.com/manojbajaj95/mcp-skill/commit/e0d0873d208100b05d40705108e78ecb47b48f0d))
+* **cli:** add interactive wizard and non-interactive CLI mode ([2e7e30c](https://github.com/manojbajaj95/mcp-skill/commit/2e7e30c8d38d654368ab23b36dd06249b1c4770e))
+* **core:** add introspector, app.py generator, and SKILL.md generator ([5256855](https://github.com/manojbajaj95/mcp-skill/commit/52568551306122451ef5cafcbe63103d22138b1a))
+* fix skill output, add deps/usage to SKILL.md, add post-gen validation ([516218b](https://github.com/manojbajaj95/mcp-skill/commit/516218bc74c4153b7b569bf9f7668cd04a9ec86a))
+* **scaffold:** initialize mcp-skill project with UV and pyproject.toml ([afcecd9](https://github.com/manojbajaj95/mcp-skill/commit/afcecd9f045a08c17a48bfd3973ac5b2d18a9ff3))
+* **templates:** unify __init__ signature to use auth=None across all auth types ([99bd4ef](https://github.com/manojbajaj95/mcp-skill/commit/99bd4ef5ff54cd1c681d3b44a9887ff4eef22058))
+* **types:** add JSON Schema to Python type mapper and name sanitizer ([6234fa1](https://github.com/manojbajaj95/mcp-skill/commit/6234fa1781963897c7b4407c923a1eb1b6d5d15f))
+
+
+### Bug Fixes
+
+* Fix parallel search name ([c5afbf6](https://github.com/manojbajaj95/mcp-skill/commit/c5afbf62d9c51346709c8fd7f87e0945138c35b5))
+* **generate:** use per-method client pattern and user-provided app name ([c65bb3e](https://github.com/manojbajaj95/mcp-skill/commit/c65bb3e2412f740706f155b4a243389003ea2f6f))
+* **generate:** use result.content for CallToolResult and filter None optional args ([48e4b56](https://github.com/manojbajaj95/mcp-skill/commit/48e4b566e3d2a88e0daaaaa6955c269ce944e764))
+* sanitize skill name to valid Python identifier for folder and imports ([afba3b6](https://github.com/manojbajaj95/mcp-skill/commit/afba3b683860c294ec28d7716eab5a553e1ff099))
+
+
+### Documentation
+
+* rewrite README with before/after, diagram, generated output, and audience section ([e341453](https://github.com/manojbajaj95/mcp-skill/commit/e341453e690ff8fa46422b270a70f8bf271426d8))

mcp_skill-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-skill contributors
+
+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_skill-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mcp-skill
+Version: 0.2.0
+Summary: Convert any MCP server into an Agent Skill
+Project-URL: Homepage, https://github.com/manojbajaj95/mcp-skill
+Project-URL: Repository, https://github.com/manojbajaj95/mcp-skill
+Project-URL: Issues, https://github.com/manojbajaj95/mcp-skill/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,code-generation,fastmcp,llm,mcp,skill
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: py-key-value-aio[disk]
+Requires-Dist: ruff>=0.15.4
+Requires-Dist: ty>=0.0.20
+Description-Content-Type: text/markdown
+
+# mcp-skill
+
+Turn any MCP server into a typed Python SDK.
+
+> **Compile MCP tools into code.**
+
+`mcp-skill` introspects an MCP server and generates a Python class where each tool becomes a typed async method.
+
+## Before and After
+
+### Before
+
+Agents call MCP tools through the model loop — one round-trip per tool call:
+
+```
+llm.call_tool("web_search_preview", {"query": "..."})
+# → model decides next step → calls another tool → model decides again → ...
+```
+
+### After
+
+Agents call tools directly in code:
+
+```python
+result = await app.web_search_preview(
+    objective="find latest news",
+    search_queries=["topic X 2026"]
+)
+# Agent processes result in code — no round-trip back to model
+```
+
+## How It Works
+
+```
+┌─────────────┐      ┌───────────────┐      ┌────────────────────┐
+│  MCP Server  │─────▶│  mcp-skill    │─────▶│  Generated Skill   │
+│  (any URL)   │      │  CLI          │      │                    │
+│              │      │               │      │  app.py            │
+│  Tools:      │      │  1. Connect   │      │  ├─ Typed class    │
+│  - search    │      │  2. Introspec │      │  ├─ Async methods  │
+│  - fetch     │      │  3. Map types │      │  ├─ Auth + storage │
+│  - ...       │      │  4. Generate  │      │  └─ JSON parsing   │
+│              │      │  5. Validate  │      │                    │
+└─────────────┘      └───────────────┘      │  SKILL.md          │
+                                             │  └─ Agent docs     │
+                                             └────────────────────┘
+```
+
+1. Connects to the MCP server using [fastmcp](https://github.com/jlowin/fastmcp)
+2. Introspects all available tools via `list_tools()`
+3. Converts each tool's JSON Schema into Python type annotations
+4. Generates a typed `App` class where each MCP tool becomes an `async` method
+5. Validates the output with `ast.parse` → `ruff` → `ty`
+6. Generates `SKILL.md` with tool documentation and usage examples for agents
+
+## Motivation
+
+MCP servers give agents access to tools, but every tool call round-trips through the model — request tool, execute, full result back into context, decide next step. For large payloads or sequential calls, this burns tokens and adds latency.
+
+[Programmatic Tool Calling](https://platform.claude.com/cookbook/tool-use-programmatic-tool-calling-ptc) fixes this: the agent writes code that calls tools directly, without model round-trips per invocation. Fetch, filter, aggregate — all in one code block.
+
+**mcp-skill** makes this possible by compiling any MCP server into a plain Python class. Each tool becomes a typed async method. The agent just writes Python.
+
+```python
+from parallel_search.app import ParallelApp
+
+app = ParallelApp(auth="sk-...")
+result = await app.web_search_preview(
+    objective="find latest news on topic X",
+    search_queries=["topic X 2026"]
+)
+```
+
+## Setup
+
+```bash
+# Install with uv
+uv pip install -e .
+
+# Or use directly
+uv run mcp-skill create --url https://your-mcp-server.com/mcp --auth api-key
+```
+
+Requires [uv](https://github.com/astral-sh/uv) and Python 3.10+.
+
+## Usage
+
+```bash
+# Interactive mode — prompts for URL, auth type, etc.
+mcp-skill create
+
+# Non-interactive mode
+mcp-skill create \
+  --url https://search-mcp.parallel.ai/mcp \
+  --auth api-key \
+  --api-key YOUR_KEY \
+  --name parallel-search \
+  --non-interactive
+```
+
+### Generated Output
+
+The skill lands in `.agents/skills/<name>/` as a Python package:
+
+```
+.agents/skills/parallel_search/
+├── __init__.py
+├── app.py          # Typed Python class wrapping the MCP server
+└── SKILL.md        # Agent-facing docs, dependencies, and usage
+```
+
+Here's what the generated `app.py` looks like:
+
+```python
+class ParallelApp:
+
+    def __init__(self, url: str = "https://...", auth=None) -> None:
+        ...
+
+    async def web_search_preview(
+        self,
+        objective: str,
+        search_queries: list[str],
+    ) -> dict[str, Any]:
+        """Search the web with multiple queries in parallel."""
+        ...
+
+    async def fetch_url(
+        self,
+        url: str,
+        max_length: int = None,
+    ) -> dict[str, Any]:
+        """Fetch and extract content from a URL."""
+        ...
+
+    def list_tools(self):
+        return [self.web_search_preview, self.fetch_url]
+```
+
+Each method connects to the MCP server, calls the underlying tool, and returns parsed JSON. Auth credentials are persisted to disk (`~/.mcp-skill/<name>/`) after first use — provide once, reuse automatically.
+
+## Who Is This For?
+
+Developers building:
+
+- **MCP-based agents** that need direct tool access without model round-trips
+- **Automation systems** using MCP tools as programmatic building blocks
+- **Code-execution agents** using [Programmatic Tool Calling](https://platform.claude.com/cookbook/tool-use-programmatic-tool-calling-ptc)
+
+## Current Limitations
+
+- **Auth**: Supports API key (Bearer or custom header), OAuth, and none — no mTLS or complex auth flows
+- **Runtime dependency**: Generated code depends on [fastmcp](https://github.com/jlowin/fastmcp) for MCP client connections
+- **Connection per call**: Each method creates a new MCP client connection (no pooling)
+- **Tools only**: MCP resources and prompts not yet supported
+
+## Task List
+
+Tracked improvements based on real-world usage:
+
+- [x] **Fix output directory path** — Changed from `.agents/skill/<name>` to `.agents/skills/<name>`
+- [x] **Add dependency info to SKILL.md** — Dependencies listed with `uv` and `pip` install commands
+- [x] **Generate `__init__.py`** — Skill directory is a proper Python package
+- [x] **Post-generation validation** — `ast.parse` → `ruff check` → `ty check` with `uvx` fallback
+- [x] **Package-style imports** — Moved `app.py` to skill root; import via `from <skill>.app import <Class>`
+- [x] **Persistent token storage** — Disk-backed credential storage at `~/.mcp-skill/<name>/`
+- [x] **Unified auth signature** — All auth types use `auth=None` in `__init__`
+- [x] **Sanitize skill names** — Hyphens/dots converted to underscores for valid Python identifiers
+- [ ] **Support MCP resources and prompts** — Currently only tools are introspected and generated

mcp_skill-0.2.0/README.md

@@ -0,0 +1,169 @@
+# mcp-skill
+
+Turn any MCP server into a typed Python SDK.
+
+> **Compile MCP tools into code.**
+
+`mcp-skill` introspects an MCP server and generates a Python class where each tool becomes a typed async method.
+
+## Before and After
+
+### Before
+
+Agents call MCP tools through the model loop — one round-trip per tool call:
+
+```
+llm.call_tool("web_search_preview", {"query": "..."})
+# → model decides next step → calls another tool → model decides again → ...
+```
+
+### After
+
+Agents call tools directly in code:
+
+```python
+result = await app.web_search_preview(
+    objective="find latest news",
+    search_queries=["topic X 2026"]
+)
+# Agent processes result in code — no round-trip back to model
+```
+
+## How It Works
+
+```
+┌─────────────┐      ┌───────────────┐      ┌────────────────────┐
+│  MCP Server  │─────▶│  mcp-skill    │─────▶│  Generated Skill   │
+│  (any URL)   │      │  CLI          │      │                    │
+│              │      │               │      │  app.py            │
+│  Tools:      │      │  1. Connect   │      │  ├─ Typed class    │
+│  - search    │      │  2. Introspec │      │  ├─ Async methods  │
+│  - fetch     │      │  3. Map types │      │  ├─ Auth + storage │
+│  - ...       │      │  4. Generate  │      │  └─ JSON parsing   │
+│              │      │  5. Validate  │      │                    │
+└─────────────┘      └───────────────┘      │  SKILL.md          │
+                                             │  └─ Agent docs     │
+                                             └────────────────────┘
+```
+
+1. Connects to the MCP server using [fastmcp](https://github.com/jlowin/fastmcp)
+2. Introspects all available tools via `list_tools()`
+3. Converts each tool's JSON Schema into Python type annotations
+4. Generates a typed `App` class where each MCP tool becomes an `async` method
+5. Validates the output with `ast.parse` → `ruff` → `ty`
+6. Generates `SKILL.md` with tool documentation and usage examples for agents
+
+## Motivation
+
+MCP servers give agents access to tools, but every tool call round-trips through the model — request tool, execute, full result back into context, decide next step. For large payloads or sequential calls, this burns tokens and adds latency.
+
+[Programmatic Tool Calling](https://platform.claude.com/cookbook/tool-use-programmatic-tool-calling-ptc) fixes this: the agent writes code that calls tools directly, without model round-trips per invocation. Fetch, filter, aggregate — all in one code block.
+
+**mcp-skill** makes this possible by compiling any MCP server into a plain Python class. Each tool becomes a typed async method. The agent just writes Python.
+
+```python
+from parallel_search.app import ParallelApp
+
+app = ParallelApp(auth="sk-...")
+result = await app.web_search_preview(
+    objective="find latest news on topic X",
+    search_queries=["topic X 2026"]
+)
+```
+
+## Setup
+
+```bash
+# Install with uv
+uv pip install -e .
+
+# Or use directly
+uv run mcp-skill create --url https://your-mcp-server.com/mcp --auth api-key
+```
+
+Requires [uv](https://github.com/astral-sh/uv) and Python 3.10+.
+
+## Usage
+
+```bash
+# Interactive mode — prompts for URL, auth type, etc.
+mcp-skill create
+
+# Non-interactive mode
+mcp-skill create \
+  --url https://search-mcp.parallel.ai/mcp \
+  --auth api-key \
+  --api-key YOUR_KEY \
+  --name parallel-search \
+  --non-interactive
+```
+
+### Generated Output
+
+The skill lands in `.agents/skills/<name>/` as a Python package:
+
+```
+.agents/skills/parallel_search/
+├── __init__.py
+├── app.py          # Typed Python class wrapping the MCP server
+└── SKILL.md        # Agent-facing docs, dependencies, and usage
+```
+
+Here's what the generated `app.py` looks like:
+
+```python
+class ParallelApp:
+
+    def __init__(self, url: str = "https://...", auth=None) -> None:
+        ...
+
+    async def web_search_preview(
+        self,
+        objective: str,
+        search_queries: list[str],
+    ) -> dict[str, Any]:
+        """Search the web with multiple queries in parallel."""
+        ...
+
+    async def fetch_url(
+        self,
+        url: str,
+        max_length: int = None,
+    ) -> dict[str, Any]:
+        """Fetch and extract content from a URL."""
+        ...
+
+    def list_tools(self):
+        return [self.web_search_preview, self.fetch_url]
+```
+
+Each method connects to the MCP server, calls the underlying tool, and returns parsed JSON. Auth credentials are persisted to disk (`~/.mcp-skill/<name>/`) after first use — provide once, reuse automatically.
+
+## Who Is This For?
+
+Developers building:
+
+- **MCP-based agents** that need direct tool access without model round-trips
+- **Automation systems** using MCP tools as programmatic building blocks
+- **Code-execution agents** using [Programmatic Tool Calling](https://platform.claude.com/cookbook/tool-use-programmatic-tool-calling-ptc)
+
+## Current Limitations
+
+- **Auth**: Supports API key (Bearer or custom header), OAuth, and none — no mTLS or complex auth flows
+- **Runtime dependency**: Generated code depends on [fastmcp](https://github.com/jlowin/fastmcp) for MCP client connections
+- **Connection per call**: Each method creates a new MCP client connection (no pooling)
+- **Tools only**: MCP resources and prompts not yet supported
+
+## Task List
+
+Tracked improvements based on real-world usage:
+
+- [x] **Fix output directory path** — Changed from `.agents/skill/<name>` to `.agents/skills/<name>`
+- [x] **Add dependency info to SKILL.md** — Dependencies listed with `uv` and `pip` install commands
+- [x] **Generate `__init__.py`** — Skill directory is a proper Python package
+- [x] **Post-generation validation** — `ast.parse` → `ruff check` → `ty check` with `uvx` fallback
+- [x] **Package-style imports** — Moved `app.py` to skill root; import via `from <skill>.app import <Class>`
+- [x] **Persistent token storage** — Disk-backed credential storage at `~/.mcp-skill/<name>/`
+- [x] **Unified auth signature** — All auth types use `auth=None` in `__init__`
+- [x] **Sanitize skill names** — Hyphens/dots converted to underscores for valid Python identifiers
+- [ ] **Support MCP resources and prompts** — Currently only tools are introspected and generated

mcp_skill-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-skill"
+version = "0.2.0"
+description = "Convert any MCP server into an Agent Skill"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["mcp", "agent", "skill", "code-generation", "fastmcp", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "fastmcp>=2.0",
+    "click>=8.0",
+    "jinja2>=3.1",
+    "ruff>=0.15.4",
+    "ty>=0.0.20",
+    "py-key-value-aio[disk]",
+]
+
+[project.urls]
+Homepage = "https://github.com/manojbajaj95/mcp-skill"
+Repository = "https://github.com/manojbajaj95/mcp-skill"
+Issues = "https://github.com/manojbajaj95/mcp-skill/issues"
+
+[project.scripts]
+mcp-skill = "mcp_skill.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_skill"]

mcp_skill-0.2.0/release-please-config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "mcp-skill",
+      "bump-minor-pre-major": true,
+      "changelog-path": "CHANGELOG.md",
+      "include-component-in-tag": false
+    }
+  }
+}