@skilljack/mcp 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP server that jacks [Agent Skills](https://agentskills.io) directly into your LLM's brain.
 
-> **Recommended:** For best results, use an MCP client that supports `tools/listChanged` notifications (e.g., Claude Code). This enables dynamic skill discovery - when skills are added or modified, the client automatically refreshes its understanding of available skills.
+> **Recommended:** For best results, use an MCP client that supports `tools/listChanged` notifications (e.g., Claude Code). This enables dynamic skill discovery - when skills are added or modified, the client automatically refreshes its understanding of available skills. Alternatively, use `--static` mode for predictable behavior with a fixed skill set.
 
 ## Features
 
@@ -12,6 +12,7 @@ An MCP server that jacks [Agent Skills](https://agentskills.io) directly into yo
 - **MCP Prompts** - Load skills via `/skill` prompt with auto-completion or per-skill prompts
 - **MCP Resources** - Access skills via `skill://` URIs with batch collection support
 - **Resource Subscriptions** - Real-time file watching with `notifications/resources/updated`
+- **Configuration UI** - Manage skill directories through an [interactive UI](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/) in supported clients
 
 ## Motivation
 
@@ -65,11 +66,66 @@ SKILLS_DIR=/path/to/skills,/path/to/more/skills skilljack-mcp
 
 Each directory is scanned along with its `.claude/skills/` and `skills/` subdirectories for skills. Duplicate skill names are handled by keeping the first occurrence.
 
+### Static Mode
+
+By default, Skilljack MCP watches skill directories for changes and notifies clients when skills are added, modified, or removed.
+
+Enable **static mode** to freeze the skills list at startup:
+
+```bash
+skilljack-mcp --static /path/to/skills
+# or
+SKILLJACK_STATIC=true skilljack-mcp /path/to/skills
+```
+
+In static mode:
+- Skills are discovered once at startup and never refreshed
+- No file watchers are set up for skill directories
+- `tools.listChanged` and `prompts.listChanged` capabilities are `false`
+- Resource subscriptions remain fully dynamic (individual skill files can still be watched)
+
+Use static mode when you need predictable behavior or have a fixed set of skills that won't change during the session.
+
 **Windows note**: Use forward slashes in paths when using with MCP Inspector:
 ```bash
 skilljack-mcp "C:/Users/you/skills"
 ```
 
+## Configuration UI
+
+In MCP clients that support [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/) (like Claude Desktop), you can manage skill directories through an interactive UI.
+
+**To open the configuration UI**, ask your assistant to show the skilljack config:
+
+> "show me the skilljack config"
+
+The UI displays:
+- Current skill directories with skill counts
+- Status indicators showing which directories are from config vs command-line
+- Options to add new directories or remove existing ones
+
+![Skills Configuration UI](docs/images/skills-config-ui.png)
+
+Changes made through the UI are persisted to the server's configuration. Clients that support `tools/listChanged` notifications will see updates immediately; others may require reconnection.
+
+## Skill Display UI
+
+View all available skills and customize their invocation settings through the skill display UI.
+
+**To open the skill display UI**, ask your assistant:
+
+> "what skills are configured in skilljack?"
+
+The UI displays:
+- All discovered skills with name, description, and file path
+- **Source indicators** showing whether each skill is from a local directory or GitHub repository
+- **Invocation toggles** to enable/disable Assistant (model auto-invoke) and User (prompts menu) visibility
+- **Customized badge** when settings differ from frontmatter defaults
+
+![Skill Display UI](docs/images/skill-display-ui.png)
+
+Skills from GitHub repositories show the org/repo name (e.g., `modelcontextprotocol/ext-apps`), making it easy to identify where each skill originates.
+
 ## How It Works
 
 The server implements the [Agent Skills](https://agentskills.io) progressive disclosure pattern with dynamic updates:
@@ -321,16 +377,73 @@ Skills are discovered at startup from the configured directories. For each direc
 
 Each skill subdirectory must contain a `SKILL.md` file with YAML frontmatter including `name` and `description` fields.
 
+## Skill Visibility Control
+
+Control which skills appear in tools vs prompts using optional frontmatter fields:
+
+| Frontmatter | In Tool Description | In Prompts Menu | Use Case |
+|-------------|---------------------|-----------------|----------|
+| (default) | Yes | Yes | Normal skills |
+| `disable-model-invocation: true` | No | Yes | User-triggered workflows (deploy, commit) |
+| `user-invocable: false` | Yes | No | Background context (model auto-loads when relevant) |
+
+### Example: User-Only Skill
+
+Hide from model auto-discovery, require explicit user invocation via `/skill-name` prompt:
+
+```yaml
+---
+name: deploy
+description: Deploy to production
+disable-model-invocation: true
+---
+```
+
+### Example: Model-Only Skill
+
+Hide from prompts menu, model uses automatically when relevant:
+
+```yaml
+---
+name: codebase-context
+description: Background information about this codebase
+user-invocable: false
+---
+```
+
+Note: Resources (`skill://` URIs) always include all skills regardless of these settings, allowing explicit access when needed.
+
 ## Testing
 
+### Manual Testing with MCP Inspector
+
 ```bash
-# Build first
 npm run build
+npm run inspector -- /path/to/skills
+```
+
+### Automated Evals (Development Only)
+
+The `evals/` directory contains an evaluation framework for testing skill activation across different delivery modes. Evals are only available when developing from source (not included in the npm package).
 
-# Test with MCP Inspector
-npx @modelcontextprotocol/inspector@latest node dist/index.js /path/to/skills
+```bash
+# Clone the repo first
+git clone https://github.com/olaservo/skilljack-mcp.git
+cd skilljack-mcp
+
+# Install dev dependencies (includes claude-agent-sdk for evals)
+npm install
+
+# Build and run evals
+npm run build
+npm run eval                              # Default: greeting task, MCP mode
+npm run eval -- --task=xlsx-openpyxl      # Specific task
+npm run eval -- --mode=native             # Native skill mode
+npm run eval -- --mode=mcp+native         # Both MCP and native enabled
 ```
 
+See [evals/README.md](evals/README.md) for details on available tasks, modes, and findings about activation behavior differences.
+
 ## Related
 
 - [Agent Skills Specification](https://agentskills.io)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilljack/mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server that discovers and serves Agent Skills. I know kung fu.",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "dist/ui",
     "README.md",
     "LICENSE"
   ],
@@ -35,7 +36,9 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:ui && npm run build:ui:display && tsc",
+    "build:ui": "vite build",
+    "build:ui:display": "cross-env INPUT=skill-display.html vite build --emptyOutDir false",
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",
     "inspector": "npx @modelcontextprotocol/inspector@latest node dist/index.js",
@@ -49,15 +52,20 @@
     "eval:xlsx-verify": "tsx evals/eval.ts --task=xlsx-verify"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@modelcontextprotocol/ext-apps": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.25.3",
     "chokidar": "^5.0.0",
+    "simple-git": "^3.27.0",
     "yaml": "^2.7.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.42",
     "@types/node": "^22.10.0",
+    "cross-env": "^7.0.3",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.0.0"
   }
 }