skillforge-mcp 0.1.0__tar.gz

skillforge_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: 📦 Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  build:
+    name: 🔨 Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: 🚀 Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/skillforge-mcp
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

skillforge_mcp-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+.python-version
+
+# SkillForge runtime data
+.skillforge/

skillforge_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CatVinci Studio
+
+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.

skillforge_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: skillforge-mcp
+Version: 0.1.0
+Summary: An MCP server that makes your AI agent learn and evolve — one skill at a time.
+Project-URL: Homepage, https://github.com/CatVinci-Studio/skillForge
+Project-URL: Repository, https://github.com/CatVinci-Studio/skillForge
+Project-URL: Issues, https://github.com/CatVinci-Studio/skillForge/issues
+Author-email: CatVinci Studio <catvinci.studio@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,llm,mcp,model-context-protocol,skills
+Classifier: Development Status :: 4 - Beta
+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 :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/badge/MCP-Server-blueviolet?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJMMiA3bDEwIDUgMTAtNS0xMC01ek0yIDE3bDEwIDUgMTAtNS0xMC01LTEwIDV6TTIgMTJsMTAgNSAxMC01LTEwLTUtMTAgNXoiLz48L3N2Zz4=" alt="MCP Server"/>
+  <img src="https://img.shields.io/badge/python-≥3.10-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
+  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/>
+  <img src="https://img.shields.io/badge/status-beta-orange?style=for-the-badge" alt="Status"/>
+</p>
+
+<h1 align="center">🛠️ SkillForge</h1>
+
+<p align="center">
+  <strong>An MCP server that makes your AI agent learn and evolve — one skill at a time.</strong>
+</p>
+
+<p align="center">
+  <em>Skills are reusable instructions that get better with every conversation.</em>
+</p>
+
+---
+
+## ✨ What is SkillForge?
+
+SkillForge is a **Model Context Protocol (MCP) server** that gives your AI agent a persistent, evolving skill library. Instead of repeating the same corrections and preferences every session, SkillForge captures them as **skills** — structured instructions that the agent loads and follows automatically.
+
+> 💡 Think of it as **muscle memory for your AI** — it learns your conventions once and applies them forever.
+
+### 🔄 The Feedback Loop
+
+```
+  👤 User gives feedback
+        │
+        ▼
+  🔍 Agent detects improvement signal
+        │
+        ▼
+  🤖 Sub-agent optimizes the skill
+        │
+        ▼
+  💾 Skill saved (auto-backed up)
+        │
+        ▼
+  ✅ Next task uses improved skill
+```
+
+---
+
+## 🚀 Quick Start
+
+### 📦 Installation
+
+```bash
+# Install from PyPI (recommended)
+pip install skillforge-mcp
+
+# Or with uv
+uv pip install skillforge-mcp
+```
+
+### ⚡ Run the Server
+
+```bash
+# Run directly
+skillforge
+
+# Or run without installing via uvx
+uvx skillforge-mcp
+```
+
+### 🔌 Connect to Claude Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "skillforge": {
+      "command": "uvx",
+      "args": ["skillforge-mcp"]
+    }
+  }
+}
+```
+
+<details>
+<summary>💡 Alternative: install from source</summary>
+
+```bash
+git clone https://github.com/CatVinci-Studio/skillForge.git
+cd skillForge
+pip install -e .
+```
+
+</details>
+
+---
+
+## 🧩 Architecture
+
+```
+src/skillforge/
+├── 🏠 server.py              # MCP server definition & prompts
+├── 📨 response.py            # Response formatting & feedback monitor
+├── 📁 skill_manager.py       # Core CRUD, backup, restore logic
+├── 🔧 tools/
+│   ├── 🔍 discovery.py       # list_skills, get_skill
+│   ├── ✏️  crud.py            # save_skill, delete_skill
+│   ├── 💾 backup.py          # list_backups, restore_skill
+│   └── 🧠 optimization.py    # get_skill_guide, request_skill_optimization
+└── 📖 guide/
+    └── skill_writing_guide.md # Best practices for skill authoring
+```
+
+### 📂 Runtime Data
+
+SkillForge stores its data in `~/.skillforge/`:
+
+| Directory | Purpose |
+|-----------|---------|
+| `~/.skillforge/skills/` | 📚 Active skill library |
+| `~/.skillforge/backups/` | 🗄️ Automatic version history |
+
+> 🔒 Override with `SKILLFORGE_SKILLS_DIR` and `SKILLFORGE_BACKUP_DIR` environment variables.
+
+---
+
+## 🔧 Available Tools
+
+| Tool | Description | Who Calls It |
+|------|-------------|--------------|
+| 🔍 `list_skills` | List all skills (mandatory first call!) | 🤖 Agent |
+| 📖 `get_skill` | Load full skill instructions | 🤖 Agent |
+| ✏️ `save_skill` | Create or update a skill | 🤖 Sub-agent |
+| 🗑️ `delete_skill` | Remove a skill (with confirmation) | 🤖 Sub-agent |
+| 📋 `list_backups` | View version history for a skill | 🤖 Agent |
+| ⏪ `restore_skill` | Roll back to a previous version | 🤖 Agent |
+| 📖 `get_skill_guide` | Load the skill writing guide | 🤖 Sub-agent |
+| 🧠 `request_skill_optimization` | Trigger skill improvement | 🤖 Agent |
+| 📊 `get_optimization_history` | View optimization log | 🤖 Agent |
+
+---
+
+## 📝 Skill Format
+
+Each skill lives in its own directory as a `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: my-skill
+description: >
+  What this skill does and when to trigger it.
+  Be specific about trigger contexts.
+---
+
+# Skill Instructions
+
+Your markdown instructions here...
+```
+
+### 🏷️ Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | ✅ | Identifier (`lowercase-with-hyphens`, max 64 chars) |
+| `description` | ✅ | Trigger conditions — WHAT it does + WHEN to use it |
+| `disable-model-invocation` | ❌ | `true` = only user can invoke |
+| `user-invocable` | ❌ | `false` = only LLM can invoke |
+| `allowed-tools` | ❌ | Tools allowed without per-use approval |
+| `context` | ❌ | `fork` = run in isolated sub-agent |
+
+---
+
+## 🧠 How Optimization Works
+
+SkillForge continuously monitors conversations for improvement signals:
+
+| Signal | Example | Action |
+|--------|---------|--------|
+| 🔴 **Correction** | "No, don't mock the database" | Update relevant skill |
+| 🟡 **Preference** | "Always use snake_case" | Create or update skill |
+| 🔵 **Pattern** | Same structure used 3+ times | Bundle into new skill |
+| 🟢 **Explicit** | "Add this to the review skill" | Direct skill edit |
+
+### 🔒 Safety Guarantees
+
+- ✅ **Auto-backup** before every save and delete
+- ✅ **One-click restore** from any backup timestamp
+- ✅ **Path traversal protection** on all file operations
+- ✅ **Atomic writes** with file locking for optimization logs
+- ✅ **Sub-agent isolation** — skill edits don't interrupt your main task
+
+---
+
+## 🌟 Why SkillForge?
+
+| Without SkillForge | With SkillForge |
+|---------------------|-----------------|
+| 😤 Repeat the same corrections every session | 🧠 Agent remembers and applies automatically |
+| 📋 Conventions scattered across docs | 📦 Single source of truth per topic |
+| 🎲 Inconsistent agent behavior | ✅ Deterministic, skill-guided responses |
+| 🔄 No learning from feedback | 📈 Skills evolve with every interaction |
+
+---
+
+## 🛣️ Roadmap
+
+- [ ] 🌐 Skill sharing & import from remote repositories
+- [ ] 📊 Analytics dashboard for skill usage & effectiveness
+- [ ] 🔗 Cross-skill dependency management
+- [ ] 🧪 Skill testing framework with evaluation harness
+- [ ] 🏪 Community skill marketplace
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  <strong>Built with ❤️ by <a href="https://github.com/CatVinci-Studio">CatVinci Studio</a></strong>
+</p>
+
+<p align="center">
+  <em>Forging better AI, one skill at a time. 🔨</em>
+</p>

skillforge_mcp-0.1.0/README.md

@@ -0,0 +1,231 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/MCP-Server-blueviolet?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJMMiA3bDEwIDUgMTAtNS0xMC01ek0yIDE3bDEwIDUgMTAtNS0xMC01LTEwIDV6TTIgMTJsMTAgNSAxMC01LTEwLTUtMTAgNXoiLz48L3N2Zz4=" alt="MCP Server"/>
+  <img src="https://img.shields.io/badge/python-≥3.10-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
+  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/>
+  <img src="https://img.shields.io/badge/status-beta-orange?style=for-the-badge" alt="Status"/>
+</p>
+
+<h1 align="center">🛠️ SkillForge</h1>
+
+<p align="center">
+  <strong>An MCP server that makes your AI agent learn and evolve — one skill at a time.</strong>
+</p>
+
+<p align="center">
+  <em>Skills are reusable instructions that get better with every conversation.</em>
+</p>
+
+---
+
+## ✨ What is SkillForge?
+
+SkillForge is a **Model Context Protocol (MCP) server** that gives your AI agent a persistent, evolving skill library. Instead of repeating the same corrections and preferences every session, SkillForge captures them as **skills** — structured instructions that the agent loads and follows automatically.
+
+> 💡 Think of it as **muscle memory for your AI** — it learns your conventions once and applies them forever.
+
+### 🔄 The Feedback Loop
+
+```
+  👤 User gives feedback
+        │
+        ▼
+  🔍 Agent detects improvement signal
+        │
+        ▼
+  🤖 Sub-agent optimizes the skill
+        │
+        ▼
+  💾 Skill saved (auto-backed up)
+        │
+        ▼
+  ✅ Next task uses improved skill
+```
+
+---
+
+## 🚀 Quick Start
+
+### 📦 Installation
+
+```bash
+# Install from PyPI (recommended)
+pip install skillforge-mcp
+
+# Or with uv
+uv pip install skillforge-mcp
+```
+
+### ⚡ Run the Server
+
+```bash
+# Run directly
+skillforge
+
+# Or run without installing via uvx
+uvx skillforge-mcp
+```
+
+### 🔌 Connect to Claude Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "skillforge": {
+      "command": "uvx",
+      "args": ["skillforge-mcp"]
+    }
+  }
+}
+```
+
+<details>
+<summary>💡 Alternative: install from source</summary>
+
+```bash
+git clone https://github.com/CatVinci-Studio/skillForge.git
+cd skillForge
+pip install -e .
+```
+
+</details>
+
+---
+
+## 🧩 Architecture
+
+```
+src/skillforge/
+├── 🏠 server.py              # MCP server definition & prompts
+├── 📨 response.py            # Response formatting & feedback monitor
+├── 📁 skill_manager.py       # Core CRUD, backup, restore logic
+├── 🔧 tools/
+│   ├── 🔍 discovery.py       # list_skills, get_skill
+│   ├── ✏️  crud.py            # save_skill, delete_skill
+│   ├── 💾 backup.py          # list_backups, restore_skill
+│   └── 🧠 optimization.py    # get_skill_guide, request_skill_optimization
+└── 📖 guide/
+    └── skill_writing_guide.md # Best practices for skill authoring
+```
+
+### 📂 Runtime Data
+
+SkillForge stores its data in `~/.skillforge/`:
+
+| Directory | Purpose |
+|-----------|---------|
+| `~/.skillforge/skills/` | 📚 Active skill library |
+| `~/.skillforge/backups/` | 🗄️ Automatic version history |
+
+> 🔒 Override with `SKILLFORGE_SKILLS_DIR` and `SKILLFORGE_BACKUP_DIR` environment variables.
+
+---
+
+## 🔧 Available Tools
+
+| Tool | Description | Who Calls It |
+|------|-------------|--------------|
+| 🔍 `list_skills` | List all skills (mandatory first call!) | 🤖 Agent |
+| 📖 `get_skill` | Load full skill instructions | 🤖 Agent |
+| ✏️ `save_skill` | Create or update a skill | 🤖 Sub-agent |
+| 🗑️ `delete_skill` | Remove a skill (with confirmation) | 🤖 Sub-agent |
+| 📋 `list_backups` | View version history for a skill | 🤖 Agent |
+| ⏪ `restore_skill` | Roll back to a previous version | 🤖 Agent |
+| 📖 `get_skill_guide` | Load the skill writing guide | 🤖 Sub-agent |
+| 🧠 `request_skill_optimization` | Trigger skill improvement | 🤖 Agent |
+| 📊 `get_optimization_history` | View optimization log | 🤖 Agent |
+
+---
+
+## 📝 Skill Format
+
+Each skill lives in its own directory as a `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: my-skill
+description: >
+  What this skill does and when to trigger it.
+  Be specific about trigger contexts.
+---
+
+# Skill Instructions
+
+Your markdown instructions here...
+```
+
+### 🏷️ Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | ✅ | Identifier (`lowercase-with-hyphens`, max 64 chars) |
+| `description` | ✅ | Trigger conditions — WHAT it does + WHEN to use it |
+| `disable-model-invocation` | ❌ | `true` = only user can invoke |
+| `user-invocable` | ❌ | `false` = only LLM can invoke |
+| `allowed-tools` | ❌ | Tools allowed without per-use approval |
+| `context` | ❌ | `fork` = run in isolated sub-agent |
+
+---
+
+## 🧠 How Optimization Works
+
+SkillForge continuously monitors conversations for improvement signals:
+
+| Signal | Example | Action |
+|--------|---------|--------|
+| 🔴 **Correction** | "No, don't mock the database" | Update relevant skill |
+| 🟡 **Preference** | "Always use snake_case" | Create or update skill |
+| 🔵 **Pattern** | Same structure used 3+ times | Bundle into new skill |
+| 🟢 **Explicit** | "Add this to the review skill" | Direct skill edit |
+
+### 🔒 Safety Guarantees
+
+- ✅ **Auto-backup** before every save and delete
+- ✅ **One-click restore** from any backup timestamp
+- ✅ **Path traversal protection** on all file operations
+- ✅ **Atomic writes** with file locking for optimization logs
+- ✅ **Sub-agent isolation** — skill edits don't interrupt your main task
+
+---
+
+## 🌟 Why SkillForge?
+
+| Without SkillForge | With SkillForge |
+|---------------------|-----------------|
+| 😤 Repeat the same corrections every session | 🧠 Agent remembers and applies automatically |
+| 📋 Conventions scattered across docs | 📦 Single source of truth per topic |
+| 🎲 Inconsistent agent behavior | ✅ Deterministic, skill-guided responses |
+| 🔄 No learning from feedback | 📈 Skills evolve with every interaction |
+
+---
+
+## 🛣️ Roadmap
+
+- [ ] 🌐 Skill sharing & import from remote repositories
+- [ ] 📊 Analytics dashboard for skill usage & effectiveness
+- [ ] 🔗 Cross-skill dependency management
+- [ ] 🧪 Skill testing framework with evaluation harness
+- [ ] 🏪 Community skill marketplace
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  <strong>Built with ❤️ by <a href="https://github.com/CatVinci-Studio">CatVinci Studio</a></strong>
+</p>
+
+<p align="center">
+  <em>Forging better AI, one skill at a time. 🔨</em>
+</p>

skillforge_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "skillforge-mcp"
+version = "0.1.0"
+description = "An MCP server that makes your AI agent learn and evolve — one skill at a time."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "CatVinci Studio", email = "catvinci.studio@gmail.com"},
+]
+keywords = ["mcp", "skills", "ai", "agent", "claude", "llm", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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 :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CatVinci-Studio/skillForge"
+Repository = "https://github.com/CatVinci-Studio/skillForge"
+Issues = "https://github.com/CatVinci-Studio/skillForge/issues"
+
+[project.scripts]
+skillforge = "skillforge.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skillforge"]

skillforge_mcp-0.1.0/src/skillforge/__init__.py

@@ -0,0 +1,3 @@
+"""SkillForge: MCP server for managing and iteratively optimizing Skills."""
+
+__version__ = "0.1.0"